Skip to content

Latest commit

 

History

History
1279 lines (913 loc) · 44.6 KB

cmpClient.pod

File metadata and controls

1279 lines (913 loc) · 44.6 KB
Raw

NAME

cmpClient - genCMPClient CLI for the Certificate Management Protocol (RFC4210)

SYNOPSIS

cmpClient (imprint|bootstrap|pkcs10|update|revoke) [-section server]

In this simple style of invocation, the first argument of the application, e.g., bootstrap, is mapped to using a section in config/demo.cnf. The optional server argument may be used to reference a CMP server to be used, where the default is EJBCA. This is also used as config section name.

cmpClient validate options

In this form of invocation, no CMP command is performed but a certificate is validated, optionally including revocation status checks. The target is given by the -tls_cert option if present, otherwise -cert. In the former case -tls_trusted must be given, otherwise -own_trusted.

Further verification options like -untrusted may be given, and also the -config and -section options may used as detailed below. By default, the sections EJBCA,validate of config/demo.cnf are used.

cmpClient options

[-help] [-config filename] [-section names] [-verbosity level]

Generic message options:

[-cmd ir|cr|kur|p10cr|rr|genm] [-infotype name] [-profile name] [-geninfo OID:int:N] [-template filename]

Certificate enrollment options:

[-newkeytype EC:curve|RSA-len] [-centralkeygen] [-newkey filename] [-newkeypass arg] [-subject name] [-issuer name] [-days number] [-reqexts name] [-sans spec] [-san_nodefault] [-policies name] [-policy_oids names] [-policy_oids_critical] [-popo number] [-csr filename] [-out_trusted filenames] [-verify_hostname cn] [-verify_ip ip] [-verify_email email] [-implicit_confirm] [-disable_confirm] [-certout filename] [-chainout filename]

Certificate enrollment and revocation options:

[-oldcert filename] [-revreason number]

Message transfer options:

[-server [http://]address[:port]][/path] [-proxy [http://]address[:port][/path]] [-no_proxy addresses] [-recipient name] [-path remote_path] [-keep_alive value] [-msg_timeout seconds] [-total_timeout seconds]

Server authentication options:

[-trusted filenames] [-untrusted sources] [-srvcert filename] [-expect_sender name] [-ignore_keyusage] [-unprotected_errors] [-no_cache_extracerts] [-srvcertout filename] [-extracertsout filename] [-extracerts_dir dirname] [-extracerts_dir_format <PEM|DER|P12|extension] [-cacertsout filename] [-cacerts_dir dirname] [-cacerts_dir_format <PEM|DER|P12|extension] [-oldwithold filename] [-newwithnew filename] [-newwithold filename] [-oldwithnew filename] [-crlcert filename] [-oldcrl filename] [-crlout filename] [-otherpass arg]

Client authentication and protection options:

[-ref value] [-secret arg] [-cert filename] [-own_trusted filenames] [-key filename] [-keypass arg] [-digest name] [-mac name] [-extracerts sources] [-unprotected_requests]

TLS connection options:

[-tls_used] [-tls_cert filename] [-tls_key filename] [-tls_keypass arg] [-tls_extra filenames] [-tls_trusted filenames] [-tls_host name]

Debugging options:

[-reqin] filenames [-reqin_new_tid] [-reqout] filenames [-rspin] filenames [-rspout] filenames

Certificate status checking options, for both CMP and TLS:

[-check_all] [-check_any] [-crls URLs] [-use_cdp] [-cdps URLs] [-cdp_proxy url] [-crl_cache_dir dirname] [-crls_timeout seconds] [-crl_maxdownload_size bytes] [-use_aia] [-ocsp URLs] [-ocsp_timeout seconds] [-ocsp_last] [-stapling]

Certificate verification options, for both CMP and TLS:

[-policy arg] [-purpose purpose] [-verify_name name] [-verify_depth num] [-auth_level level] [-attime timestamp] [-ignore_critical] [-issuer_checks] [-policy_check] [-explicit_policy] [-inhibit_any] [-inhibit_map] [-x509_strict] [-extended_crl] [-use_deltas] [-policy_print] [-check_ss_sig] [-trusted_first] [-suiteB_128_only] [-suiteB_128] [-suiteB_192] [-partial_chain] [-no_alt_chains] [-no_check_time] [-allow_proxy_certs]

DESCRIPTION

The cmpClient command is a demo and test client implementation of the Certificate Management Protocol (CMP) as defined in RFC 4210. It can be used to request certificates from a CA via a CMP server, to update or revoke them, and to perform other CMP requests.

USAGE

imprint|bootstrap|pkcs10|update|revoke|genm

Select demo use_case of the cmpClient application. The corresponding CMP request will be executed with default settings. These settings could be adapted via the file 'config/demo.cnf'.

List of options available for the cmpClient application:

OPTIONS

-help

Display a summary of all options

-config filename

Configuration file to use. An empty string "" means none. Default filename is config/demo.cnf.

-section names

Section(s) to use within config file defining CMP options. An empty string "" means no specific section. Default is default.

Multiple section names may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Contents of sections named later may override contents of sections named before. In any case, as usual, the [default] section and finally the unnamed section (as far as present) can provide per-option fallback values.

-verbosity level

Level of verbosity for logging, error output, etc. 0 = EMERG, 1 = ALERT, 2 = CRIT, 3 = ERR, 4 = WARN, 5 = NOTE, 6 = INFO, 7 = DEBUG, 8 = TRACE. Defaults to 6 = INFO. The levels DEBUG and TRACE are most useful for certificate status check issues.

Generic message options

-cmd ir|cr|kur|p10cr|rr|genm

CMP command to execute. Overrides use_case if present. Currently implemented commands are:

ir   - Initialization Request
cr   - Certificate Request
p10cr - PKCS#10 Certification Request (for legacy support)
kur   - Key Update Request
rr   - Revocation Request
genm - General Message

ir requests initialization of an end entity into a PKI hierarchy by issuing a first certificate.

cr requests issuing an additional certificate for an end entity already initialized to the PKI hierarchy.

p10cr requests issuing an additional certificate similarly to cr but using legacy PKCS#10 CSR format.

kur requests a (key) update for an existing certificate.

rr requests revocation of an existing certificate.

genm requests information using a General Message, where optionally included InfoTypeAndValues may be used to state which info is of interest. Upon receipt of the General Response, information about all received ITAV infoTypes is printed to stdout.

-infotype name

InfoType name to use for requesting specific info in a genm request, e.g., signKeyPairTypes.

There is specific support for caCerts, rootCaCert, certReqTemplate, and crlStatusList (CRL update retrieval).

-profile name

Name of a certificate profile to place in the generalInfo field of the PKIHeader of request messages.

-geninfo values

A comma-separated list of InfoTypeAndValue to place in the generalInfo field of the PKIHeader of request messages. Each InfoTypeAndValue gives an OID and an integer or string value of the form OID:int:number or OID:str:text, e.g., '1.2.3.4:int:56789, id-kp:str:name'.

-template filename

The file to save any CRMF certTemplate in DER format received in a genp message with id-it-certReqTemplate.

Note: any keySpec field contents received are logged as INFO.

Certificate enrollment options

-newkeytype spec

In case of IR, CR, or KUR, generate or request a new key of the given type for the requested certificate. The spec may be of the form EC:curve or RSA-length. The key will be saved in the file specified with the -newkey option.

-centralkeygen

Request central (server-side) key generation. This implies -popo -1 = NONE. All other -popo values are not consistent with this option. Default is local key generation.

-newkey filename

The file to save the newly generated key in case -newkeytype or -centralkeygen is given. Otherwise the file to read the private or public key from for the certificate requested in IR, CR or KUR. Defaults to the public key in the PKCS#10 CSR given with the -csr option, the public key of the reference certificate, or the current client key.

-newkeypass arg

Pass phrase source for the key file given with the -newkey option. If not given here, the password will be prompted for if needed.

This may be a plain password, which should be preceded by 'pass:', a key identifier preceded by 'engine:' to use with a crypto engine, the name of a environment variable preceded by 'env:' to read from, the name of a file preceded by 'file:' to read from, the numeric descriptor of a file preceded by 'fd:' to read from, or 'stdin' to indicate that the password input is to be read from STDIN.

-subject name

X509 Distinguished Name (DN) of subject to use in the requested certificate template. If the NULL-DN (/) is given then no subject is placed in the template. Default is the subject DN of any PKCS#10 CSR given with the -csr option. For KUR, a further fallback is the subject DN of the reference certificate (see -oldcert) if provided. This fallback is used for IR and CR only if no SANs are set.

If provided and neither of -cert, -oldcert, or -csr is given, the subject DN is used as fallback sender of outgoing CMP messages.

Special characters may be escaped by \ (backslash); whitespace is retained. Empty values are permitted, but the corresponding type will not be included. Giving a single / will lead to an empty sequence of RDNs (a NULL-DN). Multi-valued RDNs can be formed by placing a + character instead of a / between the AttributeValueAssertions (AVAs) that specify the members of the set. Example:

/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe The argument must be formatted as /type0=value0/type1=value1/type2=.... For details see the description of the -recipient option.

-issuer name

X509 issuer Distinguished Name (DN) of the CA server to place in the requested certificate template in IR/CR/KUR. If the NULL-DN (/) is given then no issuer is placed in the template.

If provided and neither -recipient nor -srvcert is given, the issuer DN is used as fallback recipient of outgoing CMP messages.

The argument must be formatted as /type0=value0/type1=value1/type2=.... For details see the description of the -subject option.

-days number

Number of days the new certificate is requested to be valid for, counting from the current time of the host. Also triggers the explicit request that the validity period starts from the current time (as seen by the host).

-reqexts name

Name of section in OpenSSL config file defining certificate request extensions. If the -csr option is present, these extensions augment the extensions contained the given PKCS#10 CSR, overriding any extensions with same OIDs.

-sans spec

One or more IP addresses, email addresses, DNS names, or URIs separated by commas or whitespace (where in the latter case the whole argument must be enclosed in "...") to add as Subject Alternative Name(s) (SAN) certificate request extension. If the special element critical is given the SANs are flagged as critical. Cannot be used if any Subject Alternative Name extension is set via -reqexts.

-san_nodefault

When Subject Alternative Names are not given via -sans nor defined via -reqexts, they are copied by default from the reference certificate (see -oldcert). This can be disabled by giving the -san_nodefault option.

-policies name

Name of section in OpenSSL config file defining policies to be set as certificate request extension. This option cannot be used together with -policy_oids.

-policy_oids names

One or more OID(s), separated by commas and/or whitespace, to add as certificate policies request extension. This option cannot be used together with -policies.

-policy_oids_critical

Flag the policies given with -policy_oids as critical.

-popo number

Proof-of-Possession (POPO) method to use for IR/CR/KUR; values: -1..<2> where -1 = NONE, which implies central key generation, 0 = RAVERIFIED, 1 = SIGNATURE (default), 2 = KEYENC.

Note that a signature-based POPO can only produced if a private key is provided via the -newkey option.

-csr filename

PKCS#10 CSR in PEM or DER format containing a certificate request. With -cmd p10cr it is used directly in a legacy P10CR message. When used with -cmd ir, cr, or kur, it is transformed into the respective regular CMP request, while its public key is ignored if -newkey is given. It may also be used with -cmd rr to specify the certificate to be revoked via the included subject and public key. Its subject is used as fallback sender in CMP message headers if -cert and -oldcert are not given.

-out_trusted filenames

Trusted certificate(s) to use for verifying the newly enrolled certificate.

Multiple filenames may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Each source may contain multiple certificates.

The certificate verification options -verify_hostname, -verify_ip, and -verify_email only affect the certificate verification enabled via this option.

-verify_hostname name

When verification of the newly enrolled certificate is enabled (with the -out_trusted option), check if any DNS Subject Alternative Name (or if no DNS SAN is included, the Common Name in the subject) equals the given name.

-verify_ip ip

When verification of the newly enrolled certificate is enabled (with the -out_trusted option), check if there is an IP address Subject Alternative Name matching the given IP address.

-verify_email email

When verification of the newly enrolled certificate is enabled (with the -out_trusted option), check if there is an email address Subject Alternative Name matching the given email address.

-implicit_confirm

Request implicit confirmation of newly enrolled certificates.

-disable_confirm

Do not send certificate confirmation message for newly enrolled certificate without requesting implicit confirmation to cope with broken servers not supporting implicit confirmation correctly. WARNING: This leads to behavior violating RFC 4210.

-certout filename

The file where any newly enrolled certificate should be saved.

If -newkey and -newkeytype or -centralkeygen are given and -cmd is not p10cr then the related chain and key are stored in this file as well, else if -chainout is not given or is the same as -certout the related chain is stored in this file as well.

-chainout filename

The file where the chain of any newly enrolled certificate should be saved. If -newkey and -newkeytype or -centralkeygen are given and -cmd is not p10cr then this option is ignored.

Certificate enrollment and revocation options

-oldcert filename

The certificate to be updated (i.e., renewed or re-keyed) in Key Update Request (KUR) messages or to be revoked in Revocation Request (RR) messages. For KUR the certificate to be updated defaults to -cert, and the resulting certificate is called reference certificate. For RR the certificate to be revoked can also be specified using -csr.

The reference certificate, if any, is also used for deriving default subject DN and Subject Alternative Names and the default issuer entry in the requested certificate template of an IR/CR/KUR. Its subject is used as sender in CMP message headers if -cert is not given. Its issuer is used as default recipient in CMP message headers if neither -recipient, -srvcert, nor -issuer is given.

This option is also used as a fallback to determine CRL source data in a general message (genm) request of infoType crlStatusList if neither the -crlcert nor the -oldcrl option is provided.

-revreason number

Set CRLReason to be included in revocation request (RR); values: 0..10 or -1 for none (which is the default).

Reason numbers defined in RFC 5280 are:

CRLReason ::= ENUMERATED {
     unspecified             (0),
     keyCompromise           (1),
     cACompromise            (2),
     affiliationChanged      (3),
     superseded              (4),
     cessationOfOperation    (5),
     certificateHold         (6),
     -- value 7 is not used
     removeFromCRL           (8),
     privilegeWithdrawn      (9),
     aACompromise           (10)
 }

Message transfer options

-server [http[s]://]address[:port][/path]

The IP address or DNS hostname and optionally port of the CMP server to connect to using HTTP(S) transport. This option excludes -rspin. The port defaults to 80 or 443 if the scheme is https. If a path is included it provides the default value for the -path option.

-proxy [http[s]://]address[:port][/path]

The HTTP(S) proxy server to use for reaching the CMP server unless -no_proxy applies, see below. The proxy port defaults to 80 or 443 if the scheme is https; apart from that the optional http:// or https://prefix and any trailing path are ignored. Defaults to the environment variable http_proxy if set, else HTTP_PROXY in case no TLS is used, otherwise https_proxy if set, else HTTPS_PROXY.

-no_proxy addresses List of IP addresses and/or DNS names of servers not to use an HTTP(S) proxy for, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Default is from the environment variable no_proxy if set, else NO_PROXY.
-recipient name

Distinguished Name (DN) to use in the recipient field of CMP request messages, i.e., the CMP server (usually the addressed CA).

The recipient field in the header of a CMP message is mandatory. If not given explicitly the recipient is determined in the following order: the subject of the CMP server certificate given with the -srvcert option, the -issuer option, the issuer of the certificate given with the -oldcert option, the issuer of the CMP client certificate (-cert option), the subject of the first certificate given with the -untrusted option, as far as any of those is present, else the NULL-DN as last resort.

The argument must be formatted as /type0=value0/type1=value1/type2=.... For details see the description of the -subject option.

-path remote_path

HTTP path at the CMP server (aka CMP alias) to use for POST requests. Defaults to any path given with -server, else "/".

-keep_alive value

If the given value is 0 then HTTP connections are closed after each response, which is the default behavior for HTTP 1.0. If the value is 1 or 2 then persistent connections within a transaction are requested. If the value is 2 then persistent connections are required, i.e., in case the server does not grant them an error occurs. The default value is 1, which means preferring to keep the connection open.

-msg_timeout seconds

Number of seconds (or 0 for infinite) a CMP message round trip is allowed to take before a timeout error is returned. Default is 120.

-total_timeout seconds

Maximum number seconds an enrollment may take, including attempts polling for certificates on waiting PKIStatus. Default is 0 (infinite).

Server authentication options

-trusted sources

The certificate(s), typically of root CAs, the client shall use as trust anchors when validating signature-based protection of CMP response messages. This option is ignored if the -srvcert option is given as well. It provides more flexibility than -srvcert because the CMP protection certificate of the server is not pinned but may be any certificate from which a chain to one of the given trust anchors can be constructed.

If none of -trusted, -srvcert, and -secret is given, message validation errors will be thrown unless -unprotected_errors permits an exception.

Multiple sources may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Each source may contain multiple certificates.

The certificate verification options -verify_hostname, -verify_ip, and -verify_email have no effect on the certificate verification enabled via this option.

-untrusted sources

Non-trusted intermediate CA certificate(s). Any extra certificates given with the -cert option are appended to it. All these certificates may be useful for cert path construction for the own CMP signer certificate (to include in the extraCerts field of request messages) and for the TLS client certificate (if TLS is enabled) as well as for chain building when validating server certificates (checking signature-based CMP message protection), when verifying stapled OCSP responses (while establishing TLS connections), and when validating newly enrolled certificates.

Multiple filenames or URLs may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Each source may contain multiple certificates.

-srvcert filename

The specific CMP server certificate to expect and directly trust (even if it is expired) when verifying signature-based protection of CMP response messages. This pins the accepted server and results in ignoring the -trusted option.

If set, the subject of the certificate is also used as default value for the recipient of CMP requests and as default value for the expected sender of CMP responses.

-expect_sender name

Distinguished Name (DN) expected in the sender field of incoming CMP messages. Defaults to the subject DN of the pinned -srvcert, if any.

This can be used to make sure that only a particular entity is accepted as CMP message signer, and attackers are not able to use arbitrary certificates of a trusted PKI hierarchy to fraudulently pose as CMP server. Note that this option gives slightly more freedom than setting the -srvcert, which pins the server to the holder of a particular certificate, while the expected sender name will continue to match after updates of the server cert.

The argument must be formatted as /type0=value0/type1=value1/type2=.... For details see the description of the -recipient option.

-ignore_keyusage

Ignore key usage restrictions in CMP signer certificates when validating signature-based protection of incoming CMP messages, By default, digitalSignature must be allowed by CMP signer certificates.

-unprotected_errors

Accept missing or invalid protection of negative responses from the server. This applies to the following message types and contents:

-no_cache_extracerts

Do not cache certificates in the extraCerts field of CMP messages received. By default, they are kept as they may be helpful for validating further messages.

  • error messages

  • negative certificate responses (IP/CP/KUP)

  • negative revocation responses (RP)

  • negative PKIConf messages

WARNING: This setting leads to unspecified behavior and it is meant exclusively to allow interoperability with server implementations violating RFC 4210, e.g.:

  • section 5.1.3.1 allows exceptions from protecting only for special cases: "There MAY be cases in which the PKIProtection BIT STRING is deliberately not used to protect a message [...] because other protection, external to PKIX, will be applied instead."

  • section 5.3.21 is clear on ErrMsgContent: "The CA MUST always sign it with a signature key."

  • appendix D.4 shows PKIConf having protection

-srvcertout filename

The file where to save the successfully validated certificate, if any, that the CMP server used for signature-based response message protection. If there is no such certificate, typically because the protection was MAC-based, this is indicated by deleting the file (if it existed).

-extracertsout filename

The file where to save the list of certificates contained in the extraCerts field of the last received response message that is not a pollRep nor PKIConf.

-extracerts_dir dirname

Directory to save extra certificates received in the extraCerts field that are not self-issued. The dirname does not need to end with the path name separator.

-extracerts_dir_format <PEM|DER|P12|extension

Certificate file format to use when when the -extracerts_dir option is given. It may be given in the form of a file name extension, e.g., crt. Default is pem.

-cacertsout filename

The file where to save CA certificates received. On a successful certificate request the list of CA certificates in the caPubs field of the response (i.e., IP, CP, or KUP) is stored in the given file. When receiving a genp message of infoType caCerts upon a genm request of the same infoType, the list of received certificates, which may be empty, is also stored in this file.

-cacerts_dir dirname

Directory to save self-issued (root CA) certificates received in the caPubs field. The dirname does not need to end with the path name separator.

-cacerts_dir_format <PEM|DER|P12|extension

Certificate file format to use when when the -cacerts_dir option is given. It may be given in the form of a file name extension, e.g., crt. Default is pem.

-oldwithold filename

The root CA certificate to include in a genm request of infoType rootCaCert. If present and the optional oldWithNew certificate is received, it is verified using the newWithNew certificate as the (only) trust anchor.

-newwithnew filename

This option must be provided when -infotype rootCaCert is given. It specifies the file to save the newWithNew certificate received in a genp message of type rootCaKeyUpdate. If on success no such cert was received, this file (if present) is deleted to indicate that the requested root CA certificate update is not available.

Any received newWithNew certificate is verified using any received newWithOld certificate as untrusted intermediate certificate and the certificate provided with -oldwithold as the (only) trust anchor, or if not provided, using the certificates given with the -trusted option.

WARNING: The newWithNew certificate is meant to be certificate that will be trusted. The trust placed in it cannot be stronger than the trust placed in the -oldwithold certificate if present, otherwise it cannot be stronger than the weakest trust placed in any of the -trusted certificates.

-newwithold filename

The file to save any newWithOld certificate received in a genp message of infoType rootCaKeyUpdate. If on success no such cert was received, this is indicated by deleting the file.

-oldwithnew filename

The file to save any oldWithNew certificate received in a genp message of infoType rootCaKeyUpdate. If on success no such cert was received, this is indicated by deleting the file.

-crlcert filename

Certificate to derive CRL issuer data for the source field when requesting a CRL in a genm message with infoType crlStatusList. Any available distribution point name is preferred over issuer names. If neither the -crlcert nor the -oldcrl option is provided, any certificate given with the -oldcert option is taken as a fallback.

-oldcrl filename

Unless the -crlcert option is provided as well, the given CRL is used for deriving CRL issuer data for the source field when requesting a CRL in a genm message with infoType crlStatusList. Any available distribution point name is preferred over issuer names. If the CRL contains a thisUpdate field, its value is copied to the request.

-crlout filename

The file to save any CRL in DER format received in a genp message of infoType crls. If on success no such CRL was received, this is indicated by deleting the file.

-otherpass arg

Pass phrase source for certificate given with the <!-- -trusted, -untrusted, -own_trusted, --> -srvcert and -crlcert <!-- , -out_trusted, -extracerts, -tls_extra, and -tls_trusted --> options. If not given here, the password will be prompted for if needed.

Client authentication options

-ref value

Reference number/string/value to use as fallback senderKID; this is required if no sender name can be determined from the -cert or <-subject> options and is typically used when authenticating with pre-shared key (password-based MAC).

-secret arg

Prefer PBM-based message protection with given source of a secret value. The secret is used for creating PBM-based protection of outgoing messages and (as far as needed) for verifying PBM-based protection of incoming messages. PBM stands for Password-Based Message Authentication Code. This takes precedence over the -cert and -key options.

Supports plain passwords preceded by pass: and others, see -newkeypass.

-cert filename

The client's current CMP signer certificate. Requires for the corresponding key to be given with -key. The subject of this certificate will be used as sender of outgoing CMP messages, while the subject of -oldcert or -subjectName may provide fallback values. The issuer of this certificate is used as one of the recipient fallback values and as fallback issuer entry in the certificate template of IR, CR, and KUR. When using signature-based message protection, this "protection certificate" will be included first in the extraCerts field of outgoing messages and the signature is done with the corresponding key. In Initialization Request (IR) messages this can be used for authenticating using an external entity certificate as defined in appendix E.7 of RFC 4210. If the file includes further certs, they are appended to the untrusted certs because they typically constitute the chain of the client certificate, which is included in the extraCerts field in signature-protected request messages.

-own_trusted filenames

If this list of certificates are provided they are used as trust anchors to verify the chain building for the own CMP signer certificate.

Multiple filenames may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Each source may contain multiple certificates.

The certificate verification options -verify_hostname, -verify_ip, and -verify_email have no effect on the certificate verification enabled via this option.

-key filename

The corresponding private key file for the client's certificate given in the -cert option. This will be used for signature-based message protection unless the -secret option indicating PBM or -unprotected_requests is given.

-keypass arg

Pass phrase source for the private key given with the -key option. Also used for -cert and -oldcert in case it is an encrypted PKCS#12 file. If not given here, the password will be prompted for if needed.

Supports plain passwords preceded by pass: and others, see -newkeypass.

-digest name

Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG and as the one-way function (OWF) in MSG_MAC_ALG. If applicable, this is used for message protection and Proof-of-Possession (POPO) signatures. To see the list of supported digests, use openssl list -digest-commands. Defaults to sha256.

-mac name

Specifies name of supported digest to use as the MAC algorithm in MSG_MAC_ALG. To get the names of supported MAC algorithms use openssl list -mac-algorithms and possibly combine such a name with the name of a supported digest algorithm, e.g., hmacWithSHA256. https://raw.githubusercontent.com/openssl/openssl/master/include/openssl/obj_mac.h contains the complete set of supported combinations of MAC and digest algorithm names. Defaults to hmac-sha1 as per RFC 4210.

-extracerts sources

Certificates to append in the extraCerts field when sending messages. They can be used as the default CMP signer certificate chain to include.

Multiple filenames or URLs may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Each source may contain multiple certificates.

-unprotected_requests

Send request messages without CMP-level protection.

TLS connection options

-tls_used

Enable using TLS (even when other TLS_related options are not set) for message exchange with CMP server. The following TLS-related options are ignored if -tls_used is not given.

-tls_cert filename

Client's TLS certificate to use for authenticating to the TLS server. If the file includes further certificates, they are used for constructing the client cert chain provided to the TLS server.

-tls_key filename

Private key for the client's TLS certificate.

-tls_keypass arg

Pass phrase source for client's private TLS key -tls_key. Also used for -tls_cert in case it is an encrypted PKCS#12 file. If not given here, the password will be prompted for if needed.

Supports plain passwords preceded by pass: and others, see -newkeypass.

-tls_extra filenames

Extra certificates to provide to the TLS server during handshake.

-tls_trusted filenames

Trusted certificate(s) to use for verifying the TLS server certificate. This implies hostname validation.

Multiple filenames may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Each source may contain multiple certificates.

The certificate verification options -verify_hostname, -verify_ip, and -verify_email have no effect on the certificate verification enabled via this option.

-tls_host name

Address to be checked (rather than -server address) during TLS hostname validation. This may be a Common Name, a DNS name, or an IP address.

Debugging options

-reqin filenames

Take the sequence of CMP requests to send to the server from file(s). This option is ignored if the -rspin option is given because in the latter case no requests are actually sent. Except for first request, the client needs to update the recipNonce field in any further request in order to satisfy the checks to be performed by the server. This causes re-protection (if protecting requests is required).

Multiple filenames may be given, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). As many files are read as needed for a complete transaction.

-reqin_new_tid

Use a fresh transactionID for CMP request messages read using -reqin, which causes their reprotection (if protecting requests is required). A fresh transactionID may be needed if an earlier sequence of requests is reused and the CMP server would complain that the transaction ID has already been used.

-reqout filenames

Save sequence of CMP requests created by the client to file(s). These requests are not sent to the server if the -reqin option is used, too.

Multiple filenames may be given, separated by commas and/or whitespace. As many files are written as needed to store the complete transaction.

-reqout_only filename

Save the first CMP requests created by the client to the given file and exit. Any options related to CMP servers and their reponses are ignored.

This option is useful for supporting offline scenarios where the certificate request (or any other CMP request) is produced beforehand and sent out later.

-rspin filenames

Process the sequence of CMP responses provided in file(s), skipping server. This option excludes -server.

Multiple filenames may be given, separated by commas and/or whitespace. As many files are read as needed for the complete transaction.

-rspout filenames

Save the sequence of CMP responses to file(s).

Multiple filenames may be given, separated by commas and/or whitespace. As many files are written as needed to store the complete transaction.

Certificate status checking options, for both CMP and TLS

The following set of options determine various parameters of certificate revocation status checking to be performed by the client on setting up any TLS connection and on checking any signature-based protection of CMP messages received, but not when verifying newly enrolled certificates.

By default no certificate status checks are performed. Status checking is demanded if any of the below status checking options are set, but only as far as a trust store is provided for TLS or at CMP level. Then by default only the leaf certificates of a chain are checked, i.e., the certificates of CMP servers and of TLS servers (as far as TLS is used). The options -check_all and -check_any may be used to change the extent of the checks to further elements in the CA chain of these certificates.

For each certificate for which the status check is demanded the certification verification procedure will try to obtain the revocation status first via OCSP stapling if enabled, then from any locally available CRLs, then from any Online Certificate Status Protocol (OCSP) responders if enabled, and finally from CRLs downloaded from certificate distribution points (CDPs) if enabled. With the -ocsp_last option CDPs are tried before trying OCSP. Verification fails if no valid and current revocation status can be found or the status indicates that the certificate has been revoked.

-check_all

Check certificate status not only for leaf certificates of a chain but for all certificates (except root, i.e., self-issued certificates).

-check_any

Check certificate status for those certificates (except root certificates) that contain a CDP or AIA entry (or for which OCSP stapling for TLS is enabled). This option is overridden by -check_all if set.

-crls URLs

Enable CRL-based status checking and use given CRL(s) as primary source of certificate revocation information. The URLs argument may contain a single element or a comma- or whitespace-separated list, each element starting with http: or file: or being a filename or pathname.

-use_cdp

Enable CRL-based status checking and enable using CRL Distribution Points (CDP) extension entries in certificates.

-cdps URLs

Enable CRL-based status checking and use the given URL(s) as fallback certificate distribution points (CDP).

-cdp_proxy url

URL of the proxy server to send CDP URLs to in the form url?url=CDP_URL or to send issuer Distinguished Names (DNs) to in the form url?issuer=DN.

-crl_cache_dir dirname

Directory where to cache CRLs downloaded during verification. The dirname does not need to end with the path name separator. Then downloaded CRLs will be stored at the given location using files names uniquely derived from the URL of the CRL distribution point.

-crls_timeout seconds

Number of seconds fetching a CRL may take, or 0 for infinite. A negative value implies the default: 10 seconds.

-crl_maxdownload_size bytes

Maximum size of a CRL to be downloaded. A value of 0 indicates the OpenSSL default, which is 100 kiB.

-use_aia

Enable OCSP-based status checking and enable using Authority Information Access (AIA) OCSP responder entries in certificates.

-ocsp URLs

Enable OCSP-based status checking and use given OCSP responder URL(s) as fallback.

-ocsp_timeout seconds

Number of seconds getting an OCSP response may take, or 0 for infinite. A negative value implies the default: 10 seconds.

-ocsp_last

This option can be used only when OCSP-based checks are enabled using -ocsp or -use_aia. If checks downloading CRLs from CDPs are also enabled then do OCSP-based checks last (else before using CRLs downloaded from CDPs).

-stapling

Enable the TLS certificate status request extension ("OCSP stapling"), which is tried first before any other methods of certificate status checking. This makes sense only if -tls_used is given. So far OCSP multi-stapling is not supported, so status information can be obtained in this way only for the leaf certificate (i.e., the TLS server certificate).

Certificate verification options, for both CMP and TLS

-policy, -purpose, -verify_name, -verify_depth, -auth_level, -attime, -ignore_critical, -issuer_checks], -policy_check, -explicit_policy, -inhibit_any, -inhibit_map, -x509_strict, -extended_crl, -use_deltas, -policy_print, -check_ss_sig, -trusted_first, -suiteB_128_only, -suiteB_128, -suiteB_192, -partial_chain, -no_check_time, -allow_proxy_certs

Set various options of certificate chain verification. See the openssl-verify(1) manual page or "Verification Options" in openssl(1) for details.

HISTORY

For an overview of CMP features relevant in industrial use cases see [LCMPP section 7.1](https://datatracker.ietf.org/doc/html/rfc9483#section-7.1). CMP client (EE) features are supported by the genCMPClient as follows.

The features newly defined with CMPv3 in [RFC 9480 (CMP Updates)](https://www.rfc-editor.org/rfc/rfc9480) are fully covered when using the [intermediate CMP library `libcmp`]( https://github.com/mpeylo/cmpossl) or when using at least OpenSSL 3.5.

* CMPv2 features defined in [RFC 4210](https://www.rfc-editor.org/rfc/rfc4210) are sufficiently covered by using OpenSSL 3.0.\ This includes most of the "Generic Aspects of PKI Messages and PKI Management Operations", IR, CR, KUR, P10CR, MAC, RR, and polling for certification responses. * In OpenSSL 3.2, "Get CA Certificates" and "Get Root CA Certificate Update" were added, as well as the -srvcertout option for saving the validated server certificate and the -serial option for the serial number of certificates to be revoked. Since then, the -issuer may be used also for certificates to be revoked. * In OpenSSL 3.3, support for certificate profiles with the -profile option and generalized polling ("Handling Delayed Delivery") were added, as well as the -no_cache_extracerts option for not reusing extraCerts received. * In OpenSSL 3.4, "Get Certificate Request Template" and "CRL Update Retrieval" were added, as well as the related -template, -crlcert, -oldcrl, and -crlout options. * In OpenSSL 3.5, support for central key generation is added.

COPYRIGHT

Copyright (c) 2021-2024 Siemens AG.

Licensed under the Apache License, Version 2.0 SPDX-License-Identifier: Apache-2.0