[B<-cmd> I<ir|cr|kur|p10cr|rr|genm>]
[B<-infotype> I<name>]
-[B<-geninfo> I<OID:int:N>]
+[B<-profile> I<name>]
+[B<-geninfo> I<values>]
Certificate enrollment options:
[B<-newkey> I<filename>|I<uri>]
[B<-newkeypass> I<arg>]
[B<-subject> I<name>]
-[B<-issuer> I<name>]
[B<-days> I<number>]
[B<-reqexts> I<name>]
[B<-sans> I<spec>]
Certificate enrollment and revocation options:
[B<-oldcert> I<filename>|I<uri>]
+[B<-issuer> I<name>]
+[B<-serial> I<number>]
[B<-revreason> I<number>]
Message transfer options:
[B<-server> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>]
-[B<-path> I<remote_path>]
[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>]
[B<-no_proxy> I<addresses>]
[B<-recipient> I<name>]
+[B<-path> I<remote_path>]
[B<-keep_alive> I<value>]
[B<-msg_timeout> I<seconds>]
[B<-total_timeout> I<seconds>]
[B<-expect_sender> I<name>]
[B<-ignore_keyusage>]
[B<-unprotected_errors>]
+[B<-no_cache_extracerts>]
+[B<-srvcertout> I<filename>]
[B<-extracertsout> I<filename>]
[B<-cacertsout> I<filename>]
+[B<-oldwithold> I<filename>]
+[B<-newwithnew> I<filename>]
+[B<-newwithold> I<filename>]
+[B<-oldwithnew> I<filename>]
Client authentication and protection options:
[B<-reqin> I<filenames>]
[B<-reqin_new_tid>]
[B<-reqout> I<filenames>]
+[B<-reqout_only> I<filename>]
[B<-rspin> I<filenames>]
[B<-rspout> I<filenames>]
[B<-use_mock_srv>]
[B<-srv_keypass> I<arg>]
[B<-srv_trusted> I<filenames>|I<uris>]
[B<-srv_untrusted> I<filenames>|I<uris>]
+[B<-ref_cert> I<filename>|I<uri>]
[B<-rsp_cert> I<filename>|I<uri>]
[B<-rsp_extracerts> I<filenames>|I<uris>]
[B<-rsp_capubs> I<filenames>|I<uris>]
+[B<-rsp_newwithnew> I<filename>|I<uri>]
+[B<-rsp_newwithold> I<filename>|I<uri>]
+[B<-rsp_oldwithnew> I<filename>|I<uri>]
[B<-poll_count> I<number>]
[B<-check_after> I<number>]
[B<-grant_implicitconf>]
{- $OpenSSL::safe::opt_v_synopsis -}
-=for openssl ifdef engine
-
=head1 DESCRIPTION
The B<cmp> command is a client implementation for the Certificate
Set InfoType name to use for requesting specific info in B<genm>,
e.g., C<signKeyPairTypes>.
+So far, there is specific support for C<caCerts> and C<rootCaCert>.
+
+=item B<-profile> I<name>
-=item B<-geninfo> I<OID:int:N>
+Name of a certificate profile to place in
+the PKIHeader generalInfo field of request messages.
-generalInfo integer values to place in request PKIHeader with given OID,
-e.g., C<1.2.3.4:int:56789>.
+=item B<-geninfo> I<values>
+
+A comma-separated list of InfoTypeAndValue to place in
+the generalInfo field of the PKIHeader of requests messages.
+Each InfoTypeAndValue gives an OID and an integer or string value
+of the form I<OID>:int:I<number> or I<OID>:str:I<text>,
+e.g., C<'1.2.3.4:int:56789, id-kp:str:name'>.
=back
=item B<-newkey> I<filename>|I<uri>
-The source of the private or public key for the certificate requested
-in Initialization Request (IR), Certification Request(CR), or
-Key Update Request (KUR).
-Default is the public key in the PKCS#10 CSR given with the B<-csr> option,
-if any, or else the current client key, if given.
+The source of the private or public key for the certificate being requested.
+Defaults to the public key in the PKCS#10 CSR given with the B<-csr> option,
+the public key of the reference certificate, or the current client key.
+
+The public portion of the key is placed in the certification request.
+
+Unless B<-cmd> I<p10cr>, B<-popo> I<-1>, or B<-popo> I<0> is given, the
+private key will be needed as well to provide the proof of possession (POPO),
+where the B<-key> option may provide a fallback.
=item B<-newkeypass> I<arg>
=item B<-subject> I<name>
-X509 Distinguished Name (DN) of subject to use in the requested certificate
-template.
-For KUR, it defaults to the public key
-in the PKCS#10 CSR given with the B<-csr> option, if provided,
-or of the reference certificate (see B<-oldcert>) if provided.
-This default is used for IR and CR only if no SANs are set.
-If the NULL-DN (C<"/">) is given then no subject is placed in the template.
+X.509 Distinguished Name (DN) to use as subject field
+in the requested certificate template in IR/CR/KUR messages.
+If the NULL-DN (C</>) is given then no subject is placed in the template.
+Default is the subject DN of any PKCS#10 CSR given with the B<-csr> option.
+For KUR, a further fallback is the subject DN
+of the reference certificate (see B<-oldcert>) if provided.
+This fallback is used for IR and CR only if no SANs are set.
-If provided and neither B<-cert> nor B<-oldcert> is given,
+If provided and neither of B<-cert>, B<-oldcert>, or B<-csr> is given,
the subject DN is used as fallback sender of outgoing CMP messages.
The argument must be formatted as I</type0=value0/type1=value1/type2=...>.
C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
-=item B<-issuer> I<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 (C<"/">) is given then no issuer is placed in the template.
-
-If provided and neither B<-recipient> nor B<-srvcert> is given,
-the issuer DN is used as fallback recipient of outgoing CMP messages.
-
-The argument must be formatted as I</type0=value0/type1=value1/type2=...>.
-For details see the description of the B<-subject> option.
-
=item B<-days> I<number>
Number of days the new certificate is requested to be valid for, counting from
=item B<-sans> I<spec>
-One or more IP addresses, DNS names, or URIs separated by commas or whitespace
+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.
=item B<-popo> I<number>
-Proof-of-Possession (POPO) method to use for IR/CR/KUR; values: C<-1>..<2> where
+Proof-of-possession (POPO) method to use for IR/CR/KUR; values: C<-1>..<2> where
C<-1> = NONE, C<0> = RAVERIFIED, C<1> = SIGNATURE (default), C<2> = KEYENC.
Note that a signature-based POPO can only be produced if a private key
PKCS#10 CSR in PEM or DER format containing a certificate request.
With B<-cmd> I<p10cr> it is used directly in a legacy P10CR message.
-When used with B<-cmd> I<ir>, I<cr>, or I<kur>, it is transformed into the
-respective regular CMP request.
-It may also be used with B<-cmd> I<rr> to specify the certificate to be revoked
+
+When used with B<-cmd> I<ir>, I<cr>, or I<kur>,
+it is transformed into the respective regular CMP request.
+In this case, a private key must be provided (with B<-newkey> or B<-key>)
+for the proof of possession (unless B<-popo> I<-1> or B<-popo> I<0> is used)
+and the respective public key is placed in the certification request
+(rather than taking over the public key contained in the PKCS#10 CSR).
+
+PKCS#10 CSR input may also be used with B<-cmd> I<rr>
+to specify the certificate to be revoked
via the included subject name and public key.
+Its subject is used as fallback sender in CMP message headers
+if B<-cert> and B<-oldcert> are not given.
=item B<-out_trusted> I<filenames>|I<uris>
Trusted certificate(s) to use for validating the newly enrolled certificate.
+During this verification, any certificate status checking is disabled.
Multiple sources may be given, separated by commas and/or whitespace
(where in the latter case the whole argument must be enclosed in "...").
=item B<-certout> I<filename>
-The file where the newly enrolled certificate should be saved.
+The file where any newly enrolled certificate should be saved.
=item B<-chainout> I<filename>
-The file where the chain of the newly enrolled certificate should be saved.
+The file where the chain of any newly enrolled certificate should be saved.
=back
For KUR the certificate to be updated defaults to B<-cert>,
and the resulting certificate is called I<reference certificate>.
For RR the certificate to be revoked can also be specified using B<-csr>.
+B<-oldcert> and B<-csr> is ignored if B<-issuer> and B<-serial> is provided.
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 public key is used as a fallback in the template of certification requests.
Its subject is used as sender of outgoing messages if B<-cert> is not given.
Its issuer is used as default recipient in CMP message headers
if neither B<-recipient>, B<-srvcert>, nor B<-issuer> is given.
+=item B<-issuer> I<name>
+
+X.509 Distinguished Name (DN) use as issuer field
+in the requested certificate template in IR/CR/KUR/RR messages.
+If the NULL-DN (C</>) is given then no issuer is placed in the template.
+
+If provided and neither B<-recipient> nor B<-srvcert> is given,
+the issuer DN is used as fallback recipient of outgoing CMP messages.
+
+The argument must be formatted as I</type0=value0/type1=value1/type2=...>.
+For details see the description of the B<-subject> option.
+
+=item B<-serial> I<number>
+
+Specify the Serial number of certificate to be revoked in revocation request.
+The serial number can be decimal or hex (if preceded by C<0x>)
+
=item B<-revreason> I<number>
Set CRLReason to be included in revocation request (RR); values: C<0>..C<10>
=item B<-server> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>
-The IP address or DNS hostname and optionally port
-of the CMP server to connect to using HTTP(S) transport.
-The scheme C<https> may be given only if the B<-tls_used> option is used.
-In this case the default port is 443, else 80.
+The I<host> domain name or IP address and optionally I<port>
+of the CMP server to connect to using HTTP(S).
+IP address may be for v4 or v6, such as C<127.0.0.1> or C<[::1]> for localhost.
+
+This option excludes I<-port> and I<-use_mock_srv>.
+It is ignored if I<-rspin> is given with enough filename arguments.
+
+If the scheme C<https> is given, the B<-tls_used> option is implied.
+When TLS is used, the default port is 443, otherwise 80.
The optional userinfo and fragment components are ignored.
Any given query component is handled as part of the path component.
If a path is included it provides the default value for the B<-path> option.
-=item B<-path> I<remote_path>
-
-HTTP path at the CMP server (aka CMP alias) to use for POST requests.
-Defaults to any path given with B<-server>, else C<"/">.
-
=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>
The HTTP(S) proxy server to use for reaching the CMP server unless B<-no_proxy>
applies, see below.
The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that
-the optional C<http://> or C<https://> prefix is ignored (note that TLS may be
-selected by B<-tls_used>), as well as any path, userinfo, and query, and fragment
-components.
+the optional C<http://> or C<https://> prefix is ignored (note that using TLS
+may be required by B<-tls_used> or B<-server> with the prefix C<https>),
+as well as any path, userinfo, and query, and fragment components.
Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY>
in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>.
+This option is ignored if I<-server> is not given.
=item B<-no_proxy> I<addresses>
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 C<no_proxy> if set, else C<NO_PROXY>.
+This option is ignored if I<-server> is not given.
=item B<-recipient> I<name>
The argument must be formatted as I</type0=value0/type1=value1/type2=...>.
For details see the description of the B<-subject> option.
+=item B<-path> I<remote_path>
+
+HTTP path at the CMP server (aka CMP alias) to use for POST requests.
+Defaults to any path given with B<-server>, else C<"/">.
+
=item B<-keep_alive> I<value>
-If the given value is 0 then HTTP connections are not kept open
-after receiving a response, which is the default behavior for HTTP 1.0.
-If the value is 1 or 2 then persistent connections 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.
+If the given value is 0 then HTTP connections are closed after each response
+(which would be the default behavior of HTTP 1.0)
+even if a CMP transaction needs more than one round trip.
+If the value is 1 or 2
+then for each transaction a persistent connection is requested.
+If the value is 2 then a persistent connection is required,
+i.e., an error occurs if the server does not grant it.
The default value is 1, which means preferring to keep the connection open.
=item B<-msg_timeout> I<seconds>
-Number of seconds (or 0 for infinite) a CMP request-response message round trip
+Number of seconds a CMP request-response message round trip
is allowed to take before a timeout error is returned.
+A value <= 0 means no limitation (waiting indefinitely).
Default is to use the B<-total_timeout> setting.
=item B<-total_timeout> I<seconds>
-Maximum number seconds an overall enrollment transaction may take,
-including attempts polling for certificates on C<waiting> PKIStatus.
-Default is 0 (infinite).
+Maximum total number of seconds a transaction may take,
+including polling etc.
+A value <= 0 means no limitation (waiting indefinitely).
+Default is 0.
=back
=item B<-trusted> I<filenames>|I<uris>
-When validating signature-based protection of CMP response messages,
-these are the CA certificate(s) to trust while checking certificate chains
-during CMP server authentication.
-This option gives more flexibility than the B<-srvcert> option because the
-server-side CMP signer certificate is not pinned but may be any certificate
-for which a chain to one of the given trusted certificates can be constructed.
+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 B<-srvcert> option is given as well.
+It provides more flexibility than B<-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 no B<-trusted>, B<-srvcert>, and B<-secret> option is given
-then protected response messages from the server are not authenticated.
+If none of B<-trusted>, B<-srvcert>, and B<-secret> is given, message validation
+errors will be thrown unless B<-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 "...").
Non-trusted intermediate CA certificate(s).
Any extra certificates given with the B<-cert> option are appended to it.
All these certificates may be useful for cert path construction
-for the CMP client certificate (to include in the extraCerts field of outgoing
-messages) and for the TLS client certificate (if TLS is enabled)
+for the own CMP signer certificate (to include in the extraCerts field of
+request messages) and for the TLS client certificate (if TLS is used)
as well as for chain building
-when validating the CMP server certificate (checking signature-based
+when validating server certificates (checking signature-based
CMP message protection) and when validating newly enrolled certificates.
-Multiple sources may be given, separated by commas and/or whitespace.
-Each file may contain multiple certificates.
+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.
=item B<-srvcert> I<filename>|I<uri>
The specific CMP server certificate to expect and directly trust (even if it is
-expired) when validating signature-based protection of CMP response messages.
-May be set alternatively to the B<-trusted> option to pin the accepted server.
+expired) when verifying signature-based protection of CMP response messages.
+This pins the accepted server and results in ignoring the B<-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 incoming CMP messages.
+and as default value for the expected sender of CMP responses.
=item B<-expect_sender> I<name>
=item B<-ignore_keyusage>
Ignore key usage restrictions in CMP signer certificates when validating
-signature-based protection of incoming CMP messages,
-else C<digitalSignature> must be allowed for signer certificate.
+signature-based protection of incoming CMP messages.
+By default, C<digitalSignature> must be allowed by CMP signer certificates.
+This option applies to both CMP clients and the mock server.
=item B<-unprotected_errors>
=back
+=item B<-no_cache_extracerts>
+
+Do not cache certificates in the extraCerts field of CMP messages received.
+By default, they are kept as they may be helful for validating further messages.
+This option applies to both CMP clients and the mock server.
+
+=item B<-srvcertout> I<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).
+
=item B<-extracertsout> I<filename>
-The file where to save all certificates contained in the extraCerts field
-of the last received response message (except for pollRep and PKIConf).
+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.
=item B<-cacertsout> I<filename>
-The file where to save any CA certificates contained in the caPubs field of
-the last received certificate response (i.e., IP, CP, or KUP) message.
+The file where to save the list of CA certificates contained in the caPubs field
+if a positive certificate response (i.e., IP, CP, or KUP) message was received
+or contained in a general response (genp) message with infoType C<caCerts>.
+
+=item B<-oldwithold> I<filename>
+
+The root CA certificate to include in a genm request of infoType C<rootCaCert>.
+If present and the optional oldWithNew certificate is received,
+it is verified using the newWithNew certificate as the (only) trust anchor.
+
+=item B<-newwithnew> I<filename>
+
+This option must be provided when B<-infotype> I<rootCaCert> is given.
+It specifies the file to save the newWithNew certificate
+received in a genp message of type C<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 B<-oldwithold> as the (only) trust anchor,
+or if not provided, using the certificates given with the B<-trusted> option.
+
+B<WARNING:>
+The newWithNew certificate is meant to be a certificate that will be trusted.
+The trust placed in it cannot be stronger than the trust placed in
+the B<-oldwithold> certificate if present, otherwise it cannot be stronger than
+the weakest trust placed in any of the B<-trusted> certificates.
+
+=item B<-newwithold> I<filename>
+
+The file to save any newWithOld certificate
+received in a genp message of infoType C<rootCaKeyUpdate>.
+If on success no such cert was received, this is indicated by deleting the file.
+
+=item B<-oldwithnew> I<filename>
+
+The file to save any oldWithNew certificate
+received in a genp message of infoType C<rootCaKeyUpdate>.
+If on success no such cert was received, this is indicated by deleting the file.
=back
=item B<-secret> I<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 validating PBM-based protection of incoming messages.
-PBM stands for Password-Based Message Authentication Code.
+Provides the source of a secret value to use with MAC-based message protection.
This takes precedence over the B<-cert> and B<-key> options.
+The secret is used for creating MAC-based protection of outgoing messages
+and for validating incoming messages that have MAC-based protection.
+The algorithm used by default is Password-Based Message Authentication Code (PBM)
+as defined in RFC 4210 section 5.1.3.1.
For more information about the format of I<arg> see
L<openssl-passphrase-options(1)>.
The client's current CMP signer certificate.
Requires the corresponding key to be given with B<-key>.
+
+The subject and the public key contained in this certificate
+serve as fallback values in the certificate template of IR/CR/KUR messages.
+
The subject of this certificate will be used as sender of outgoing CMP messages,
while the subject of B<-oldcert> or B<-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/KUR.
-When using signature-based message protection, this "protection certificate"
+and as fallback issuer entry in the certificate template of IR/CR/KUR messages.
+
+When performing signature-based message protection,
+this "protection certificate", also called "signer 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.
+
For Key Update Request (KUR) messages this is also used as
the certificate to be updated if the B<-oldcert> option is not given.
+
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.
The corresponding private key file for the client's current certificate given in
the B<-cert> option.
-This will be used for signature-based message protection unless
-the B<-secret> option indicating PBM or B<-unprotected_requests> is given.
+This will be used for signature-based message protection unless the B<-secret>
+option indicating MAC-based protection or B<-unprotected_requests> is given.
+
+It is also used as a fallback for the B<-newkey> option with IR/CR/KUR messages.
=item B<-keypass> I<arg>
=item B<-digest> I<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.
+and as the one-way function (OWF) in C<MSG_MAC_ALG>.
If applicable, this is used for message protection and
-Proof-of-Possession (POPO) signatures.
+proof-of-possession (POPO) signatures.
To see the list of supported digests, use C<openssl list -digest-commands>.
Defaults to C<sha256>.
=item B<-mac> I<name>
-Specifies the name of the MAC algorithm in MSG_MAC_ALG.
+Specifies the name of the MAC algorithm in C<MSG_MAC_ALG>.
To get the names of supported MAC algorithms use C<openssl list -mac-algorithms>
and possibly combine such a name with the name of a supported digest algorithm,
e.g., hmacWithSHA256.
=item B<-unprotected_requests>
-Send messages without CMP-level protection.
+Send request messages without CMP-level protection.
=back
Pass phrase source for certificate given with the B<-trusted>, B<-untrusted>,
B<-own_trusted>, B<-srvcert>, B<-out_trusted>, B<-extracerts>,
-B<-srv_trusted>, B<-srv_untrusted>, B<-rsp_extracerts>, B<-rsp_capubs>,
+B<-srv_trusted>, B<-srv_untrusted>, B<-ref_cert>, B<-rsp_cert>,
+B<-rsp_extracerts>, B<-rsp_capubs>,
+B<-rsp_newwithnew>, B<-rsp_newwithold>, B<-rsp_oldwithnew>,
B<-tls_extra>, and B<-tls_trusted> options.
If not given here, the password will be prompted for if needed.
=item B<-tls_used>
-Enable using TLS (even when other TLS_related options are not set)
-when connecting to CMP server.
+Make the CMP client use TLS (regardless if other TLS-related options are set)
+for message exchange with the server via HTTP.
+This option is not supported with the I<-port> option.
+It is implied if the B<-server> option is given with the scheme C<https>.
+It is ignored if the B<-server> option is not given or B<-use_mock_srv> is given
+or B<-rspin> is given with enough filename arguments.
+
+The following TLS-related options are ignored if TLS is not used.
=item B<-tls_cert> I<filename>|I<uri>
-Client's TLS certificate.
+Client's TLS certificate to use for authenticating to the TLS server.
If the source includes further certs they are used (along with B<-untrusted>
certs) for constructing the client cert chain provided to the TLS server.
=item B<-tls_extra> I<filenames>|I<uris>
-Extra certificates to provide to TLS server during TLS handshake
+Extra certificates to provide to the TLS server during handshake.
=item B<-tls_trusted> I<filenames>|I<uris>
=item B<-tls_host> I<name>
-Address to be checked during hostname validation.
+Address to be checked during hostname validation.
This may be a DNS name or an IP address.
If not given it defaults to the B<-server> address.
=back
-=head2 Client-side debugging options
+=head2 Client-side options for debugging and offline scenarios
=over 4
=item B<-reqin> I<filenames>
-Take sequence of CMP requests from file(s).
+Take the sequence of CMP requests to send to the server from the given file(s)
+rather than from the sequence of requests produced internally.
+
+This option is useful for supporting offline scenarios where the certificate
+request (or any other CMP request) is produced beforehand and sent out later.
+
+This option is ignored if the B<-rspin> option is given
+because in the latter case no requests are actually sent.
+
+Note that in any case the client produces internally its sequence
+of CMP request messages. Thus, all options required for doing this
+(such as B<-cmd> and all options providing the required parameters)
+need to be given also when the B<-reqin> option is present.
+
+If the B<-reqin> option is given for a certificate request
+and no B<-newkey>, B<-key>, B<-oldcert>, or B<-csr> option is given,
+a fallback public key is taken from the request message file
+(if it is included in the certificate template).
+
+Hint: In case the B<-reqin> option is given for a certificate request, there are
+situations where the client has access to the public key to be certified but
+not to the private key that by default will be needed for proof of possession.
+In this case the POPO is not actually needed (because the internally produced
+certificate request message will not be sent), and its generation
+can be disabled using the options B<-popo> I<-1> or B<-popo> I<0>.
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.
+
+The files are read as far as needed to complete the transaction
+and filenames have been provided. If more requests are needed,
+the remaining ones are taken from the items at the respective position
+in the sequence of requests produced internally.
+
+The client needs to update the recipNonce field in the given requests (except
+for the first one) in order to satisfy the checks to be performed by the server.
+This causes re-protection (if protecting requests is required).
=item B<-reqin_new_tid>
Use a fresh transactionID for CMP request messages read using B<-reqin>,
-which requires re-protecting them as far as they were protected before.
+which causes their reprotection (if protecting requests is required).
This may be needed in case the sequence of requests is reused
and the CMP server complains that the transaction ID has already been used.
=item B<-reqout> I<filenames>
-Save sequence of CMP requests to file(s).
+Save the sequence of CMP requests created by the client to the given file(s).
+These requests are not sent to the server if the B<-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.
+
+Files are written as far as needed to save the transaction
+and filenames have been provided.
+If the transaction contains more requests, the remaining ones are not saved.
+
+=item B<-reqout_only> I<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.
=item B<-rspin> I<filenames>
-Process sequence of CMP responses provided in file(s), skipping server.
+Process the sequence of CMP responses provided in the given file(s),
+not contacting any given server,
+as long as enough filenames are provided to complete the transaction.
Multiple filenames may be given, separated by commas and/or whitespace.
-As many files are read as needed for the complete transaction.
+
+Any server specified via the I<-server> or I<-use_mock_srv> options is contacted
+only if more responses are needed to complete the transaction.
+In this case the transaction will fail
+unless the server has been prepared to continue the already started transaction.
=item B<-rspout> I<filenames>
-Save sequence of CMP responses to file(s).
+Save the sequence of actually used CMP responses to the given file(s).
+These have been received from the server unless B<-rspin> takes effect.
Multiple filenames may be given, separated by commas and/or whitespace.
-As many files are written as needed to store the complete transaction.
+
+Files are written as far as needed to save the responses
+contained in the transaction and filenames have been provided.
+If the transaction contains more responses, the remaining ones are not saved.
=item B<-use_mock_srv>
-Use the internal mock server for testing the client.
-This works at API level, bypassing HTTP transport.
+Test the client using the internal CMP server mock-up at API level,
+bypassing socket-based transfer via HTTP.
+This excludes the B<-server> and B<-port> options.
=back
=item B<-port> I<number>
-Act as CMP HTTP server mock-up listening on the given port.
+Act as HTTP-based CMP server mock-up listening on the given local port.
+The client may address the server via, e.g., C<127.0.0.1> or C<[::1]>.
+This option excludes the B<-server> and B<-use_mock_srv> options.
+The B<-rspin>, B<-rspout>, B<-reqin>, and B<-reqout> options
+so far are not supported in this mode.
=item B<-max_msgs> I<number>
Intermediate CA certs that may be useful when validating client certificates.
+=item B<-ref_cert> I<filename>|I<uri>
+
+Certificate to be expected for RR messages and any oldCertID in KUR messages.
+
=item B<-rsp_cert> I<filename>|I<uri>
Certificate to be returned as mock enrollment result.
CA certificates to be included in mock Initialization Response (IP) message.
+=item B<-rsp_newwithnew> I<filename>|I<uri>
+
+Certificate to be returned in newWithNew field of genp of type rootCaKeyUpdate.
+
+=item B<-rsp_newwithold> I<filename>|I<uri>
+
+Certificate to be returned in newWithOld field of genp of type rootCaKeyUpdate.
+
+=item B<-rsp_oldwithnew> I<filename>|I<uri>
+
+Certificate to be returned in oldWithNew field of genp of type rootCaKeyUpdate.
+
=item B<-poll_count> I<number>
Number of times the client must poll before receiving a certificate.
=item B<-accept_unprot_err>
Accept unprotected error messages from client.
+So far this has no effect because the server does not accept any error messages.
=item B<-accept_raverified>
-Accept RAVERIFED as proof-of-possession (POPO).
+Accept RAVERIFED as proof of possession (POPO).
=back
=head1 NOTES
+When a client obtains, from a CMP server, CA certificates that it is going to
+trust, for instance via the C<caPubs> field of a certificate response
+or using general messages with infoType C<caCerts> or C<rootCaCert>,
+authentication of the CMP server is particularly critical.
+So special care must be taken setting up server authentication
+using B<-trusted> and related options for certificate-based authentication
+or B<-secret> for MAC-based protection.
+If authentication is certificate-based, the B<-srvcertout> option
+should be used to obtain the validated server certificate
+and perform an authorization check based on it.
+
When setting up CMP configurations and experimenting with enrollment options
typically various errors occur until the configuration is correct and complete.
When the CMP server reports an error the client will by default
For assisting in such cases the CMP client offers a workaround via the
B<-unprotected_errors> option, which allows accepting such negative messages.
+If OpenSSL was built with trace support enabled (e.g., C<./config enable-trace>)
+and the environment variable B<OPENSSL_TRACE> includes B<HTTP>,
+the requests and the response headers transferred via HTTP are printed.
+
=head1 EXAMPLES
=head2 Simple examples using the default OpenSSL configuration file
openssl cmp -section insta,kur
-using with PBM-based protection or
+using MAC-based protection with PBM or
openssl cmp -section insta,kur,signature
-newkey cl_key_new.pem -certout cl_cert.pem
cp cl_key_new.pem cl_key.pem
-This command sequence can be repated as often as needed.
+This command sequence can be repeated as often as needed.
=head2 Requesting information from CMP server
The B<cmp> application was added in OpenSSL 3.0.
-The B<-engine option> was deprecated in OpenSSL 3.0.
+The B<-engine> option was deprecated in OpenSSL 3.0.
+
+The B<-profile> option was added in OpenSSL 3.3.
=head1 COPYRIGHT
-Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
projects / thirdparty / openssl.git / blobdiff