![](/images/clear.gif) |
|
| |
OPENXPKIADM(1) |
User Contributed Perl Documentation |
OPENXPKIADM(1) |
openxpkiadm - tool for management operations of OpenXPKI instances
openxpkiadm COMMAND [SUBCOMMAND] [OPTIONS]
Global options:
--config DIR Location of the configuration repository
optional, defaults to /usr/local/etc/openxpki/config.d
--instance|i NAME Shortcut to set the config path to
/usr/local/etc/openxpki/<instance>/config.d
Commands:
help brief help message
man full documentation
version print program version and exit
key Manage keys
certificate Manage certificates
hashpwd Create the (salted) hash / argon2 kcv for a password
alias Manage the token alias table
lintconfig Parse config and shows errors from Config::Merge
buildconfig Create (signed) config blob from config tree
Available commands:
Command was removed, use provided sql schema dumps to create database.
Key management for OpenXPKI Tokens (including issuing CAs and subsystems).
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'
Starts a certificate management command and allows to list, install, delete and
connect certificates for the configured PKI Realms.
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'
An alias is a symbolic name for a certificate in a specific realm. OpenXPKI uses
aliases to manage the crypto tokens for signer and helper tokens. Several
configs options and commands are able to process aliases, too.
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
Create the hash of a given password to be used with the internal user database.
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.
Validate that the config tree is parseable, shows errors from underlying
Config::Merge such as YAML ident or quoting errors.
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
Serializes the config tree into a single transportable file that can be signed.
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
openxpkiadm is the administrative frontend for controlling the OpenXPKI
installation.
The openxpkiadm script returns a 0 exit value on success,
and >0 if an error occurs.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|