initdb

key

Command options:

   --realm               PKI Realm to operate on

key management subcommands

list

Shows token key information for the specified realm, including key algorithm, key length and secret splitting information. TODO: Key info not implemented yet!

Lists keys together with a status flag, which can be one of the following:

  c - token not defined in crypto.token
  + - key exists and file is non-empty
  0 - key exists but file is empty
  ! - key files does not exist (yet)
    

Example:

  openxpkiadm key list --realm 'Root CA'
    

certificate

  openxpkiadm certificate <subcommand> <options>

certificate management subcommands

list

Subcommand options (optional):

   --realm                  PKI realm to operate on
   --all                    Show all certificates
   -v                       Show subject and issuer DN as well
   -v -v                    Show chain as well
   -v -v -v                 Show (nearly complete) database entry
   -v -v -v -v              Show pubkey and certificate data, too
    

Lists certificates present in the database for the specified realm. If --all is not specified, only certificates that have an alias defined for them are listed. --all lists all certificates, regardless of whether they have an alias or not. If --realm is left out, the certificates in all realms are listed The number of -v's increases the verbosity (see above for what is listed in which case).

import

Subcommand options:

Mandatory: --file the PEM file to import from

Optional: --revoked import with status "revoked" --issuer the identifier of the issuer --realm PKI realm to import certificate to

Force options (use only if you exactly now what you are doing!): --force-no-chain (only without issuer) Import even if the chain is incomplete, set NULL as issuer --force-issuer Force the issuer setting even if the chain validation fails --force-certificate-already-exists Force update for an existing certificate --force-certificate-ignore-existing Exit without error if the certificate exists --force-no-verify Build the chain but skip cryptographic verification

Once again, only use these options if you actually have to (the occasions where this happens should be really, really rare). Note that force-no-chain might result in a wrong issuers assignment if key identifiers or subjects are ambiguous. Consider using explicit issuer in that cases if possible.

Adds a certificate to the database. The issuer is usually auto-detected and needs to be given only in rare cases. By default the certificates are imported into the global realm, if you want to add them to a specific one, you need to specify it. Note that a certificate always inherits the realm of its issuer!

The command outputs the subject's DN, issuer's DN and the imported realm for you to verify that you imported the correct certificate as well as a unique identifier which can be used to globally reference the certificate (i.e. for configuration or as an issuer). If you don't want to remember the identifier, look into openxpkiadm certificate alias to find out how to create a symbolic name for an identifier.

Examples:

  openxpkiadm certificate import --file cacert.pem
    

Import a certificate which issuer is not known in the "ServerCA" realm:

  openxpkiadm certificate import --file cacert.pem \
      --force-no-chain --realm ServerCA
    

If alias, generation/group or token is given it is used to add an alias after import - this option is deprecated and will be removed, use the alias command with --file instead.

remove

Subcommand options:

Mandatory: --name The alias or identifier of the certificate

Optional: --realm The PKI realm in which the alias is defined

Force options (use only if you now what you are doing!): --force-is-issuer Delete certificate even though it is the issuer of another certificate in the database

Removes a certificate from the database.

Example:

  openxpkiadm certificate remove --realm 'Root CA' \
        --name 'Root CA 1'
    

chain

Subcommand options:

 Mandatory:
  --realm               The PKI realm to operate in
  --name                The alias or identifier of the child
  --issuer              The alias or identifier of the parent
    

Optional: --issuer-realm The realm in which the issuer alias is defined

Force options (use only if you now what you are doing!): --force-certificate-not-found Ignore that the certificate of the child was not found in the DB --force-issuer-certificate-not-found Ignore that the certificate of the parent was not found in the DB

Once again, only use these options if you actually have to (the occasions where this happens should be really, really rare).

Specifies subject/issuer relationship in order to set up certificate chains. The certificates to be connected must already be present in the database (see import). As those connections are already set up during --import, this command exists for changing the issuer if you made an error. It also allows to specify an issuer that does not agree with the information contained in the certificate (but outputs a warning)

 Example:
    

openxpkiadm certificate chain --realm 'Root CA' \ --name 'Subordinate CA 1' --issuer 'root1'

alias

The selection of functional tokens is done based on the notbefore/ notafter date. To force certain behaviour (e.g time of a ca rollover), you can force a custom notbefore/notafter date on the aliases.

Common options: --realm PKI realm for the alias --identifier The identifier of the certificate --notbefore custom notbefore date to set --notafter custom notafter date to set accepted formats are epoch or yyyy-mm-dd hh:mm:ss a literal 0 restores the certificates validity.

There are different ways to deal with aliases:

list tokens

If you pass a realm but no identifier, you will receive the list of active tokens for all token groups, the current root certificate and, if set, the upcoming root certificate as used by scep GetNexCACert.

For items with custom notbefore/notafter settings, the certificate's value is shown in brackets:

    upcoming root ca:
        Alias     : root-2
        Identifier: xGBSVo6N-9gpjB8UFll4TS-u-Eo
        NotBefore : 2014-01-01 00:00:00 (2013-06-17 13:54:34)
        NotAfter  : 2016-12-31 23:59:59 (2020-06-17 13:54:34)
    

To show the certificates subject besides the identifier, add --subject.

To show a list of all or all active tokens, you can add the filter parameter:

  --filter all or --filter active
    

You can also filter by a certain group name with --group <groupname>.

Specify --nogroup to list tokens that do not belong to a group.

show/export a single alias

Show the details of a single alias and export the linked certificate to a file.

  --alias    The full alias (e.g. ca-signer-1)
  --subject  Print the subject of the certificate
  --export   Write PEM encoded certificate to <target>.
             If target is a directory the alias is used as filename.
             If target is "-" the certificate is printed to the terminal
             including its textual representation
    

add functional token with automatic group discovery

Looks up the name of the associated group and finds the next generation index by looking up the present aliases in the group. Recommended.

  --token  The name of the token type you want to add,
           e.g. certsign or datasafe.
  --file   The filename of the PEM encoded certificate, can be given
           instead  of --identifier. If the certificate does not exists
           in the database it is imported.
    

Example:

    openxpkiadm alias --realm server-realm \
        --identifier rzg0GhTx81ioYGXADfuuIxFd9fw \
        --token certsign
    

add functional token with manual group configuration

The alias is automatically set to <group>-<generation>, e.g. server-ca-1. The generation identifier is increased by one from the latest one found in the same group.

  --group   The name of the group (e.g. server-ca)
    

Example:

    openxpkiadm alias --realm server-realm \
        --identifier rzg0GhTx81ioYGXADfuuIxFd9fw \
        --group server-ca
    

explicit generation

If you need to force a certain generation identifier, you can skip the autodetection and provide the wanted index:

    --generation  The numeric index to use for this alias
    

This works with both methods above, token and group.

Example:

    openxpkiadm alias --realm server-realm \
        --identifier rzg0GhTx81ioYGXADfuuIxFd9fw \
        --group server-ca --generation 42
    

add non-functional alias

Adds the alias leaving group and generation empty.

  --alias               The symbolic name for the certificate
    

Example:

    openxpkiadm alias --realm server-realm \
        --identifier rzg0GhTx81ioYGXADfuuIxFd9fw \
        --alias my-very-important-certificate
    

alias key import

This applies as an extended functionality for all commands that create an alias.

  --key    The filename of a PEM encoded private key.
    

When provided, the system tries to copy the key data contained in the given file to the location defined in the token configuration. The token configuration is read from the OpenXPKI server process via the socket using the System stack to authenticate. Therefore this requires that the daemon is up and allows access to the get_token_info call for the default System user (this configuration is currently hardcoded and can not be changed).

For storage type "OPENXPKI" (file based) the key data is written into the given key file, the file is set to 0400 permissions, owned by the user the daemon runs with. The parent folder for the file must exist.

For storage type "DATAPOOL" the key blob is loaded into the datapool, encrypted with the current DataVault token. This therefore requires that the DataVault token is already set up and available for encryption.

force option

All alias create commands will fail if the given certificate already exists in the given group. There are two options to ignore existing items.

  --force-ignore-existing  return and ignore extra settings
  --force-update-existing  update validity and key for existing alias
    

This will silently return if an alias for the given identifier exists in the given group and no explicit generation was given. If an explicit name or generation was given this only return if the existing alias matches the given name.

With --force-ignore-existing any given additional options will not be processed.

The command will fail if a key to import is specified but the target already exists. To force overwrite of an existing key use

    --force-update-key
    

Please note that this will overwrite the existing file in place!

update alias

Update notebefore/notafter date or set key of an existing alias.

    --update        Indicates that you want to update an existing entry
    --alias         You can select the alias by name rather than passing
                    the identifier.
    

Example:

     openxpkiadm alias --update --realm democa \
         --alias ca-signer-1
         --notbefore "2014-01-01:00:00:00"
    

This updates notbefore, notafter is not changed.

Example:

     openxpkiadm alias --update --realm democa \
         --file ca-issuer-1.crt
         --key ca-issuer-1.pem
    

Assign the key found in ca-issuer-1.pem to the alias matching the certfificate ca-issuer-1.crt. The command will die if no alias is found for the given certificate or if there is already a key found. In case you want "create or update" use --force-update-existing instead --update.

remove alias

Remove the entry from the alias table.

  --remove          Indicates that the alias should be removed.
  --alias           You can select the alias by name rather than passing
                    the identifier.
    

Example:

    openxpkiadm alias --remove --realm server-realm \
        --identifier rzg0GhTx81ioYGXADfuuIxFd9fw \

    openxpkiadm alias --remove --realm server-realm \
        --alias server-ca-1
    

hashpwd

Command options:

  --scheme   The hashing scheme to use, allowed values are
             sshaXXX|shaXXX|smd5|md5|crypt|argon2, default is ssha256
             see also OpenXPKI::Server::Authentication::Password

  --plain    do not hide the password on enter, no retype required
             should work with passwords piped to STDIN

Prompts for the password and prints the hashed value including the used scheme as defined in RFC2307.

Also offers calculation of a token based on the Argon2 KDF.

lintconfig

Path to the config is read from environment OPENXPKI_CONF_PATH or --config switch on commandline. If both are not set, the default location /usr/local/etc/openxpki/config.d is used.

Command options:

  -- module  Specify extra modules to apply on the config object for
             additional checks.

  --debug               Dump the full config tree as YAML structure
  --debug path.to.node  Dump the tree below this node as YAML structure

buildconfig

Command options:

    --output  Name of the output file, default is config.oxi
    --key     Filename of the key to use for signing
    --cert    Filename of the certificate (together with key)
    --chain   Filename holding additonal certificates added as chain
    --force   Force overwrite of existing file