Skip to content

Latest commit

 

History

History
155 lines (109 loc) · 7.06 KB

cli.md

File metadata and controls

155 lines (109 loc) · 7.06 KB
Raw

Certomancer CLI

Note: Certomancer's CLI was built with Click. As such, it comes with a built-in help function that can be accessed by certomancer --help.

Role of the CLI in Certomancer

In principle, you can spin up a Certomancer instance on a server running nginx and uWSGI without ever needing to touch its CLI. That being said, the CLI provides a number of useful shortcuts that'll make testing your code less cumbersome. It can be used to

  • launch a Certomancer Animator instance locally, behind a development server;
  • generate certificates & CRLs without requiring an operational Animator instance at all.

In particular, the CLI allows you to use Certomancer as a certificate generation tool without actually deploying any of its 'live' components.

The certomancer script currently has five subcommands:

  • animate: run the Certomancer Animator behind a development server
  • summon: create and output a single certificate for a Certomancer PKI architecture
  • mass-summon: create and output all certificates for a Certomancer PKI architecture
  • necronomicon: create and output a CRL
  • seance: generate OCSP responses

Core config flags

The following flags should be passed before any subcommands.

Flag Argument Use
--version none Show the version and exit.
--config filename YAML file to load the configuration from. The default is certomancer.yml
--key-root dirname Root folder for paths to keys. The default is the folder containing the configuration file.
--extra-config-root dirname Folder to look for external PKI architecture files. The default is the folder containing the configuration file.
--no-external-config none Disable external PKI architecture files altogether.

Running the Animator locally

Running certomancer animate will launch a local instance of Certomancer Animator with a bare-bones development web server supplied by Werkzeug. It takes the following arguments.

Flag Argument Use
--port number Set the port number to listen on. The default is 9000.
--no-web-ui none Disable the web UI and only expose the "core" API.
--no-time-override none Disable per-request time override functionality.

About the last flag: by default, a test client making requests to an Animator instance can include the X-Certomancer-Fake-Time header with an ISO 8601 datetime to tell Certomancer to simulate a particular point in time when preparing a response for the request. If left out, the current time will be used. Passing the --no-time-override flag turns off this feature.

Generating single certificates

Extracting a single certificate from a Certomancer PKI architecture is done through the certomancer summon command. Its general structure is

certomancer summon PKI_ARCH CERT_LABEL [OUTPUT]

Here PKI_ARCH refers to a PKI architecture defined in the configuration file, CERT_LABEL to the label of a certificate that is part of said PKI architecture, and OUTPUT is the (optional) name of the file to write the output to. If not specified, data will be written to standard output.

The summon subcommand takes the following flags and options.

Flag Argument Use
--ignore-tty none Never try to prevent binary data from being written to stdout, even if stdout appears to be a tty.
--as-pfx none Output a PFX (PKCS #12) file that bundles the certificate with the corresponding chain of issuance and private key, if available.
--pfx-pass string Set the passphrase for the PFX file.
--no-pem none Do not PEM-armour the certificate, just output its raw DER encoding.

Note: PKCS#12 support requires the cryptography library to be installed.

Generating many certificates

Extracting all certificates from a Certomancer PKI architecture can be done through the certomancer mass-summon command. Its general structure is

certomancer mass-summon PKI_ARCH OUTPUT

Here PKI_ARCH refers to a PKI architecture defined in the configuration file, and OUTPUT is the name of the file or directory to write the output to. If the cryptography library is available, Certomancer will also create PKCS #12 (PFX) files for each certificate.

The mass-summon subcommand takes the following flags and options.

Flag Argument Use
--flat none Do not group certificates by issuer.
--archive none Write the certificates to a .zip archive instead of a directory.
--no-pfx string Do not attempt to generate PKCS#12 files.
--pfx-pass string Set the passphrase for the PFX files to be generated.
--no-pem none Do not PEM-armour the certificates, just output their raw DER encoding.

Generating CRLs

To generate a CRL from the CLI, use the certomancer necronomicon subcommand. Its general structure is

certomancer necronomicon PKI_ARCH CRL_REPO [OUTPUT]

Here PKI_ARCH refers to a PKI architecture defined in the configuration file, CRL_REPO to the label of a CRL endpoint defined in the services.crl-repo section of said PKI architecture, and OUTPUT is the (optional) name of the file to write the output to. If not specified, data will be written to standard output.

Flag Argument Use
--ignore-tty none Never try to prevent binary data from being written to stdout, even if stdout appears to be a tty.
--no-pem none Do not PEM-armour the CRL, just output its raw DER encoding.
--at-time ISO 8601 datetime Generate the latest CRL at the point in time specified (default: now)

Note: the --at-time flag takes the (simulated) publication schedule of the CRL into account. For example, if the nth CRL was published on 2021-01-01, the next one is scheduled for 2021-01-31 and a certificate is revoked on 2021-01-02, then telling Certomancer to generate a CRL on 2021-01-03 will not cause the recently revoked certificate to be included.

Generating OCSP responses

To generate an OCSP response from the CLI, use the certomancer seance subcommand. Its general structure is

certomancer seance PKI_ARCH CERT_LABEL OCSP_RESPONDER

Here PKI_ARCH refers to a PKI architecture defined in the configuration file, OCSP_RESPONDER to the label of an OCSP responder defined in the services.ocsp section of said PKI architecture, and CERT_LABEL to the label of a certificate (or attribute certificate) defined in the PKI architecture. An OCSP response that applies to that certificate will be generated. Finally, OUTPUT specifies the (optional) name of the file to write the output to. If not specified, data will be written to standard output.

Flag Argument Use
--ignore-tty none Never try to prevent binary data from being written to stdout, even if stdout appears to be a tty.
--at-time ISO 8601 datetime Generate the OCSP response at the point in time specified (default: now)