2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
6 openssl-cmp - Certificate Management Protocol (CMP, RFC 4210) application
12 [B<-config> I<filename>]
13 [B<-section> I<names>]
14 [B<-verbosity> I<level>]
16 Generic message options:
18 [B<-cmd> I<i r|cr|kur|p10cr|rr|genm>]
19 [B<-infotype> I<name>]
20 [B<-geninfo> I<OID:int:N>]
22 Certificate enrollment options:
24 [B<-newkey> I<filename>|I<uri>]
25 [B<-newkeypass> I<arg>]
32 [B<-policies> I<name>]
33 [B<-policy_oids> I<names>]
34 [B<-policy_oids_critical>]
37 [B<-out_trusted> I<filenames>|I<uris>]
38 [B<-implicit_confirm>]
40 [B<-certout> I<filename>]
41 [B<-chainout> I<filename>]
43 Certificate enrollment and revocation options:
45 [B<-oldcert> I<filename>|I<uri>]
46 [B<-revreason> I<number>]
48 Message transfer options:
50 [B<-server> I<[http[s]://]address[:port][/path]>]
51 [B<-path> I<remote_path>]
52 [B<-proxy> I<[http[s]://]address[:port][/path]>]
53 [B<-no_proxy> I<addresses>]
54 [B<-msg_timeout> I<seconds>]
55 [B<-total_timeout> I<seconds>]
57 Server authentication options:
59 [B<-trusted> I<filenames>|I<uris>]
60 [B<-untrusted> I<sources>]
61 [B<-srvcert> I<filename>|I<uri>]
62 [B<-recipient> I<name>]
63 [B<-expect_sender> I<name>]
65 [B<-unprotected_errors>]
66 [B<-extracertsout> I<filename>]
67 [B<-cacertsout> I<filename>]
69 Client authentication options:
73 [B<-cert> I<filename>|I<uri>]
74 [B<-own_trusted> I<filenames>|I<uris>]
75 [B<-key> I<filename>|I<uri>]
79 [B<-extracerts> I<sources>]
80 [B<-unprotected_requests>]
82 Credentials format options:
84 [B<-certform> I<PEM|DER>]
85 [B<-keyform> I<PEM|DER|P12|ENGINE>]
86 [B<-otherpass> I<arg>]
87 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
89 TLS connection options:
92 [B<-tls_cert> I<filename>|I<uri>]
93 [B<-tls_key> I<filename>|I<uri>]
94 [B<-tls_keypass> I<arg>]
95 [B<-tls_extra> I<filenames>|I<uris>]
96 [B<-tls_trusted> I<filenames>|I<uris>]
97 [B<-tls_host> I<name>]
99 Client-side debugging options:
102 [B<-repeat> I<number>]
103 [B<-reqin>] I<filenames>
105 [B<-reqout>] I<filenames>
106 [B<-rspin>] I<filenames>
107 [B<-rspout>] I<filenames>
113 [B<-max_msgs> I<number>]
114 [B<-srv_ref> I<value>]
115 [B<-srv_secret> I<arg>]
116 [B<-srv_cert> I<filename>|I<uri>]
117 [B<-srv_key> I<filename>|I<uri>]
118 [B<-srv_keypass> I<arg>]
119 [B<-srv_trusted> I<filenames>|I<uris>]
120 [B<-srv_untrusted> I<filenames>|I<uris>]
121 [B<-rsp_cert> I<filename>|I<uri>]
122 [B<-rsp_extracerts> I<filenames>|I<uris>]
123 [B<-rsp_capubs> I<filenames>|I<uris>]
124 [B<-poll_count> I<number>]
125 [B<-check_after> I<number>]
126 [B<-grant_implicitconf>]
127 [B<-pkistatus> I<number>]
128 [B<-failure> I<number>]
129 [B<-failurebits> I<number>]
130 [B<-statusstring> I<arg>]
132 [B<-send_unprotected>]
133 [B<-send_unprot_err>]
134 [B<-accept_unprotected>]
135 [B<-accept_unprot_err>]
136 [B<-accept_raverified>]
138 Certificate verification options, for both CMP and TLS:
140 {- $OpenSSL::safe::opt_v_synopsis -}
142 =for openssl ifdef engine
146 The B<cmp> command is a client implementation for the Certificate
147 Management Protocol (CMP) as defined in RFC4210.
148 It can be used to request certificates from a CA server,
149 update their certificates,
150 request certificates to be revoked, and perform other types of CMP requests.
158 Display a summary of all options
160 =item B<-config> I<filename>
162 Configuration file to use.
163 An empty string C<""> means none.
164 Default filename is from the environment variable C<OPENSSL_CONF>.
166 =item B<-section> I<names>
168 Section(s) to use within config file defining CMP options.
169 An empty string C<""> means no specific section.
172 Multiple section names may be given, separated by commas and/or whitespace
173 (where in the latter case the whole argument must be enclosed in "...").
174 Contents of sections named later may override contents of sections named before.
175 In any case, as usual, the C<[default]> section and finally the unnamed
176 section (as far as present) can provide per-option fallback values.
178 =item B<-verbosity> I<level>
180 Level of verbosity for logging, error output, etc.
181 0 = EMERG, 1 = ALERT, 2 = CRIT, 3 = ERR, 4 = WARN, 5 = NOTE,
182 6 = INFO, 7 = DEBUG, 8 = TRACE.
183 Defaults to 6 = INFO.
187 =head2 Generic message options
191 =item B<-cmd> I<ir|cr|kur|p10cr|rr|genm>
193 CMP command to execute.
194 Currently implemented commands are:
198 =item ir E<nbsp> - Initialization Request
200 =item cr E<nbsp> - Certificate Request
202 =item p10cr - PKCS#10 Certification Request (for legacy support)
204 =item kur E<nbsp>E<nbsp>- Key Update Request
206 =item rr E<nbsp> - Revocation Request
208 =item genm - General Message
212 B<ir> requests initialization of an End Entity into a PKI hierarchy
213 by issuing a first certificate.
215 B<cr> requests issuing an additional certificate for an End Entity already
216 initialized to the PKI hierarchy.
218 B<p10cr> requests issuing an additional certificate similarly to B<cr>
219 but using PKCS#10 CSR format.
221 B<kur> requests a (key) update for an existing, given certificate.
223 B<rr> requests revocation of an existing, given certificate.
225 B<genm> requests information using a General Message, where optionally
226 included B<InfoTypeAndValue>s may be used to state which info is of interest.
227 Upon receipt of the General Response, information about all received
228 ITAV B<infoType>s is printed to stdout.
230 =item B<-infotype> I<name>
232 Set InfoType name to use for requesting specific info in B<genm>,
233 e.g., C<signKeyPairTypes>.
235 =item B<-geninfo> I<OID:int:N>
237 generalInfo integer values to place in request PKIHeader with given OID,
238 e.g., C<1.2.3.4:int:56789>.
242 =head2 Certificate enrollment options
246 =item B<-newkey> I<filename>|I<uri>
248 The source of the private or public key for the certificate requested
249 in Initialization Request (IR), Certification Request(CR), or
250 Key Update Request (KUR).
251 Default is the public key in the PKCS#10 CSR given with the B<-csr> option,
252 if any, or else the current client key, if given.
254 =item B<-newkeypass> I<arg>
256 Pass phrase source for the key given with the B<-newkey> option.
257 If not given here, the password will be prompted for if needed.
259 For more information about the format of B<arg> see
260 L<openssl-passphrase-options(1)>.
262 =item B<-subject> I<name>
264 X509 Distinguished Name (DN) of subject to use in the requested certificate
266 For KUR, it defaults to the subject DN of any given CSR
267 or of the reference certificate (see B<-oldcert>) if provided.
268 This default is used for IR and CR only if no SANs are set.
270 The provided subject DN is also used as fallback sender of outgoing CMP messages
271 if no B<-cert> and no B<-oldcert> are given.
273 The argument must be formatted as I</type0=value0/type1=value1/type2=...>.
274 Special characters may be escaped by C<\> (backslash), whitespace is retained.
275 Empty values are permitted, but the corresponding type will not be included.
276 Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
277 Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
278 between the AttributeValueAssertions (AVAs) that specify the members of the set.
281 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
283 =item B<-issuer> I<name>
285 X509 issuer Distinguished Name (DN) of the CA server
286 to place in the requested certificate template in IR/CR/KUR.
288 If neither B<-srvcert> nor B<-recipient> is available,
289 the name given in this option is also set as the recipient of the CMP message.
291 =item B<-days> I<number>
293 Number of days the new certificate is requested to be valid for, counting from
294 the current time of the host.
295 Also triggers the explicit request that the
296 validity period starts from the current time (as seen by the host).
298 =item B<-reqexts> I<name>
300 Name of section in OpenSSL config file defining certificate request extensions.
302 =item B<-sans> I<spec>
304 One or more IP addresses, DNS names, or URIs separated by commas or whitespace
305 (where in the latter case the whole argument must be enclosed in "...")
306 to add as Subject Alternative Name(s) (SAN) certificate request extension.
307 If the special element "critical" is given the SANs are flagged as critical.
308 Cannot be used if any Subject Alternative Name extension is set via B<-reqexts>.
310 =item B<-san_nodefault>
312 When Subject Alternative Names are not given via B<-sans>
313 nor defined via B<-reqexts>,
314 they are copied by default from the reference certificate (see B<-oldcert>).
315 This can be disabled by giving the B<-san_nodefault> option.
317 =item B<-policies> I<name>
319 Name of section in OpenSSL config file defining policies to be set
320 as certificate request extension.
321 This option cannot be used together with B<-policy_oids>.
323 =item B<-policy_oids> I<names>
325 One or more OID(s), separated by commas and/or whitespace
326 (where in the latter case the whole argument must be enclosed in "...")
327 to add as certificate policies request extension.
328 This option cannot be used together with B<-policies>.
330 =item B<-policy_oids_critical>
332 Flag the policies given with B<-policy_oids> as critical.
334 =item B<-popo> I<number>
336 Proof-of-Possession (POPO) method to use for IR/CR/KUR; values: C<-1>..<2> where
337 C<-1> = NONE, C<0> = RAVERIFIED, C<1> = SIGNATURE (default), C<2> = KEYENC.
339 Note that a signature-based POPO can only be produced if a private key
340 is provided via the B<-newkey> or B<-key> options.
342 =item B<-csr> I<filename>
344 PKCS#10 CSR in PEM or DER format containing a certificate request.
345 When used with a with B<-cmd> I<p10cr> used directly in a legacy P10CR message.
346 When used with B<-cmd> I<ir>, I<cr>, or I<kur>, it is tranformed into the
347 respective regular CMP request.
348 It may also be used with B<-cmd> I<rr> to specifiy the certificate to be revoked
349 via the included subject and public key.
351 =item B<-out_trusted> I<filenames>|I<uris>
353 Trusted certificate(s) to use for verifying the newly enrolled certificate.
355 Multiple sources may be given, separated by commas and/or whitespace
356 (where in the latter case the whole argument must be enclosed in "...").
357 Each source may contain multiple certificates.
359 The certificate verification options
360 B<-verify_hostname>, B<-verify_ip>, and B<-verify_email>
361 only affect the certificate verification enabled via this option.
363 =item B<-implicit_confirm>
365 Request implicit confirmation of newly enrolled certificates.
367 =item B<-disable_confirm>
369 Do not send certificate confirmation message for newly enrolled certificate
370 without requesting implicit confirmation
371 to cope with broken servers not supporting implicit confirmation correctly.
372 B<WARNING:> This leads to behavior violating RFC 4210.
374 =item B<-certout> I<filename>
376 The file where the newly enrolled certificate should be saved.
378 =item B<-chainout> I<filename>
380 The file where the chain of the newly enrolled certificate should be saved.
384 =head2 Certificate enrollment and revocation options
388 =item B<-oldcert> I<filename>|I<uri>]
390 The certificate to be updated (i.e., renewed or re-keyed) in Key Update Request
391 (KUR) messages or to be revoked in Revocation Request (RR) messages.
392 For RR the certificate to be revoked can also be specified using B<-csr>.
393 For KUR certificate to be updated defaults to B<-cert>, and the resulting certificate is called
394 I<reference certificate>.
396 The reference certificate, if any, is also used for
397 deriving default subject DN and Subject Alternative Names and the
398 default issuer entry in the requested certificate template of a IR/CR/KUR.
399 Its subject is used as sender of outgoing messages if B<-cert> is not given.
400 Its issuer is used as default recipient in CMP message headers
401 if neither B<-recipient>, B<-srvcert>, nor B<-issuer> is given.
403 =item B<-revreason> I<number>
405 Set CRLReason to be included in revocation request (RR); values: C<0>..C<10>
406 or C<-1> for none (which is the default).
408 Reason numbers defined in RFC 5280 are:
410 CRLReason ::= ENUMERATED {
414 affiliationChanged (3),
416 cessationOfOperation (5),
418 -- value 7 is not used
420 privilegeWithdrawn (9),
426 =head2 Message transfer options
430 =item B<-server> I<[http[s]://]address[:port][/path]>
432 The IP address or DNS hostname and optionally port (defaulting to 80 or 443)
433 of the CMP server to connect to using HTTP(S) transport.
434 The optional I<http://> or I<https://> prefix is ignored.
435 If a path is included it provides the default value for the B<-path> option.
437 =item B<-path> I<remote_path>
439 HTTP path at the CMP server (aka CMP alias) to use for POST requests.
440 Defaults to any path given with B<-server>, else C<"/">.
442 =item B<-proxy> I<[http[s]://]address[:port][/path]>
444 The HTTP(S) proxy server to use for reaching the CMP server unless B<no_proxy>
446 The optional I<http://> or I<https://> prefix and any trailing path are ignored.
447 Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY>
448 in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>.
450 =item B<-no_proxy> I<addresses>
452 List of IP addresses and/or DNS names of servers
453 not to use an HTTP(S) proxy for, separated by commas and/or whitespace
454 (where in the latter case the whole argument must be enclosed in "...").
455 Default is from the environment variable C<no_proxy> if set, else C<NO_PROXY>.
457 =item B<-msg_timeout> I<seconds>
459 Number of seconds (or 0 for infinite) a CMP request-response message round trip
460 is allowed to take before a timeout error is returned.
463 =item B<-total_timeout> I<seconds>
465 Maximum number seconds an overall enrollment transaction may take,
466 including attempts polling for certificates on C<waiting> PKIStatus.
467 Default is 0 (infinite).
471 =head2 Server authentication options
475 =item B<-trusted> I<filenames>|I<uris>
477 When verifying signature-based protection of CMP response messages,
478 these are the CA certificate(s) to trust while checking certificate chains
479 during CMP server authentication.
480 This option gives more flexibility than the B<-srvcert> option because the
481 server-side CMP signer certificate is not pinned but may be any certificate
482 for which a chain to one of the given trusted certificates can be constructed.
484 If no B<-trusted>, B<-srvcert>, and B<-secret> option is given
485 then protected response messages from the server are not authenticated.
487 Multiple sources may be given, separated by commas and/or whitespace
488 (where in the latter case the whole argument must be enclosed in "...").
489 Each source may contain multiple certificates.
491 The certificate verification options
492 B<-verify_hostname>, B<-verify_ip>, and B<-verify_email>
493 have no effect on the certificate verification enabled via this option.
495 =item B<-untrusted> I<sources>
497 Non-trusted intermediate CA certificate(s).
498 Any extra certificates given with the B<-cert> option are appended to it.
499 All these certificates may be useful for cert path construction
500 for the CMP client certificate (to include in the extraCerts field of outgoing
501 messages) and for the TLS client certificate (if TLS is enabled)
502 as well as for chain building
503 when verifying the CMP server certificate (checking signature-based
504 CMP message protection) and when verifying newly enrolled certificates.
506 Multiple sources may be given, separated by commas and/or whitespace.
507 Each file may contain multiple certificates.
509 =item B<-srvcert> I<filename>|I<uri>]
511 The specific CMP server certificate to expect and directly trust (even if it is
512 expired) when verifying signature-based protection of CMP response messages.
513 May be set alternatively to the B<-trusted> option to pin the accepted server.
515 If set, the subject of the certificate is also used
516 as default value for the recipient of CMP requests
517 and as default value for the expected sender of incoming CMP messages.
519 =item B<-recipient> I<name>
521 Distinguished Name (DN) to use in the recipient field of CMP request messages,
522 i.e., the CMP server (usually the addressed CA).
524 The recipient field in the header of a CMP message is mandatory.
525 If not given explicitly the recipient is determined in the following order:
526 the subject of the CMP server certificate given with the B<-srvcert> option,
527 the B<-issuer> option,
528 the issuer of the certificate given with the B<-oldcert> option,
529 the issuer of the CMP client certificate (B<-cert> option),
530 as far as any of those is present, else the NULL-DN as last resort.
532 =item B<-expect_sender> I<name>
534 Distinguished Name (DN) expected in the sender field of incoming CMP messages.
535 Defaults to the subject DN of the pinned B<-srvcert>, if any.
537 This can be used to make sure that only a particular entity is accepted as
538 CMP message signer, and attackers are not able to use arbitrary certificates
539 of a trusted PKI hierarchy to fraudulently pose as a CMP server.
540 Note that this option gives slightly more freedom than setting the B<-srvcert>,
541 which pins the server to the holder of a particular certificate, while the
542 expected sender name will continue to match after updates of the server cert.
544 =item B<-ignore_keyusage>
546 Ignore key usage restrictions in CMP signer certificates when verifying
547 signature-based protection of incoming CMP messages,
548 else C<digitalSignature> must be allowed for signer certificate.
550 =item B<-unprotected_errors>
552 Accept missing or invalid protection of negative responses from the server.
553 This applies to the following message types and contents:
557 =item * error messages
559 =item * negative certificate responses (IP/CP/KUP)
561 =item * negative revocation responses (RP)
563 =item * negative PKIConf messages
567 B<WARNING:> This setting leads to unspecified behavior and it is meant
568 exclusively to allow interoperability with server implementations violating
573 =item * section 5.1.3.1 allows exceptions from protecting only for special
575 "There MAY be cases in which the PKIProtection BIT STRING is deliberately not
576 used to protect a message [...] because other protection, external to PKIX, will
579 =item * section 5.3.21 is clear on ErrMsgContent: "The CA MUST always sign it
580 with a signature key."
582 =item * appendix D.4 shows PKIConf message having protection
586 =item B<-extracertsout> I<filename>
588 The file where to save all certificates contained in the extraCerts field
589 of the last received response message (except for pollRep and PKIConf).
591 =item B<-cacertsout> I<filename>
593 The file where to save any CA certificates contained in the caPubs field of
594 the last received certificate response (i.e., IP, CP, or KUP) message.
598 =head2 Client authentication options
602 =item B<-ref> I<value>
604 Reference number/string/value to use as fallback senderKID; this is required
605 if no sender name can be determined from the B<-cert> or <-subject> options and
606 is typically used when authenticating with pre-shared key (password-based MAC).
608 =item B<-secret> I<arg>
610 Prefer PBM-based message protection with given source of a secret value.
611 The secret is used for creating PBM-based protection of outgoing messages
612 and (as far as needed) for verifying PBM-based protection of incoming messages.
613 PBM stands for Password-Based Message Authentication Code.
614 This takes precedence over the B<-cert> and B<-key> options.
616 For more information about the format of B<arg> see
617 L<openssl-passphrase-options(1)>.
619 =item B<-cert> I<filename>|I<uri>]
621 The client's current CMP signer certificate.
622 Requires the corresponding key to be given with B<-key>.
623 The subject of this certificate will be used as sender of outgoing CMP messages,
624 while the subject of B<-oldcert> or B<-subjectName> may provide fallback values.
625 The issuer of this certificate is used as one of the recipient fallback values
626 and as fallback issuer entry in the certificate template of IR/CR/KUR.
627 When using signature-based message protection, this "protection certificate"
628 will be included first in the extraCerts field of outgoing messages
629 and the signature is done with the corresponding key.
630 In Initialization Request (IR) messages this can be used for authenticating
631 using an external entity certificate as defined in appendix E.7 of RFC 4210.
632 For Key Update Request (KUR) messages this is also used as
633 the certificate to be updated if the B<-oldcert> option is not given.
634 If the file includes further certs, they are appended to the untrusted certs
635 because they typically constitute the chain of the client certificate, which
636 is included in the extraCerts field in signature-protected request messages.
638 =item B<-own_trusted> I<filenames>|I<uris>
640 If this list of certificates is provided then the chain built for
641 the client-side CMP signer certificate given with the B<-cert> option
642 is verified using the given certificates as trust anchors.
644 Multiple sources may be given, separated by commas and/or whitespace
645 (where in the latter case the whole argument must be enclosed in "...").
646 Each source may contain multiple certificates.
648 The certificate verification options
649 B<-verify_hostname>, B<-verify_ip>, and B<-verify_email>
650 have no effect on the certificate verification enabled via this option.
652 =item B<-key> I<filename>|I<uri>]
654 The corresponding private key file for the client's current certificate given in
656 This will be used for signature-based message protection unless
657 the B<-secret> option indicating PBM or B<-unprotected_requests> is given.
659 =item B<-keypass> I<arg>
661 Pass phrase source for the private key given with the B<-key> option.
662 Also used for B<-cert> and B<-oldcert> in case it is an encrypted PKCS#12 file.
663 If not given here, the password will be prompted for if needed.
665 For more information about the format of B<arg> see
666 L<openssl-passphrase-options(1)>.
668 =item B<-digest> I<name>
670 Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG
671 and as the one-way function (OWF) in MSG_MAC_ALG.
672 If applicable, this is used for message protection and
673 Proof-of-Possession (POPO) signatures.
674 To see the list of supported digests, use B<openssl list -digest-commands>.
675 Defaults to C<sha256>.
677 =item B<-mac> I<name>
679 Specifies the name of the MAC algorithm in MSG_MAC_ALG.
680 To get the names of supported MAC algorithms use B<openssl list -mac-algorithms>
681 and possibly combine such a name with the name of a supported digest algorithm,
682 e.g., hmacWithSHA256.
683 Defaults to C<hmac-sha1> as per RFC 4210.
685 =item B<-extracerts> I<sources>
687 Certificates to append in the extraCerts field when sending messages.
688 They can be used as the default CMP signer certificate chain to include.
690 Multiple sources may be given, separated by commas and/or whitespace
691 (where in the latter case the whole argument must be enclosed in "...").
692 Each source may contain multiple certificates.
694 =item B<-unprotected_requests>
696 Send messages without CMP-level protection.
700 =head2 Credentials format options
704 =item B<-certform> I<PEM|DER>
706 File format to use when saving a certificate to a file.
707 Default value is PEM.
709 =item B<-keyform> I<PEM|DER|P12|ENGINE>
711 The format of the key input.
712 The only value with effect is B<ENGINE>.
713 See L<openssl(1)/Format Options> for details.
715 =item B<-otherpass> I<arg>
717 Pass phrase source for certificate given with the B<-trusted>, B<-untrusted>,
718 B<-own_trusted>, B<-srvcert>, B<-out_trusted>, B<-extracerts>,
719 B<-srv_trusted>, B<-srv_untrusted>, B<-rsp_extracerts>, B<-rsp_capubs>,
720 B<-tls_extra>, and B<-tls_trusted> options.
721 If not given here, the password will be prompted for if needed.
723 For more information about the format of B<arg> see
724 L<openssl-passphrase-options(1)>.
726 {- $OpenSSL::safe::opt_engine_item -}
730 {- output_off() if $disabled{"deprecated-3.0"}; "" -}
731 As an alternative to using this combination:
733 -engine {engineid} -key {keyid} -keyform ENGINE
735 ... it's also possible to just give the key ID in URI form to B<-key>,
738 -key org.openssl.engine:{engineid}:{keyid}
740 This applies to all options specifying keys: B<-key>, B<-newkey>, and
742 {- output_on() if $disabled{"deprecated-3.0"}; "" -}
744 =head2 TLS connection options
750 Enable using TLS (even when other TLS_related options are not set)
751 when connecting to CMP server.
753 =item B<-tls_cert> I<filename>|I<uri>]
755 Client's TLS certificate.
756 If the source includes further certs they are used (along with B<-untrusted>
757 certs) for constructing the client cert chain provided to the TLS server.
759 =item B<-tls_key> I<filename>|I<uri>
761 Private key for the client's TLS certificate.
763 =item B<-tls_keypass> I<arg>
765 Pass phrase source for client's private TLS key B<tls_key>.
766 Also used for B<-tls_cert> in case it is an encrypted PKCS#12 file.
767 If not given here, the password will be prompted for if needed.
769 For more information about the format of B<arg> see
770 L<openssl-passphrase-options(1)>.
772 =item B<-tls_extra> I<filenames>|I<uris>
774 Extra certificates to provide to TLS server during TLS handshake
776 =item B<-tls_trusted> I<filenames>|I<uris>
778 Trusted certificate(s) to use for verifying the TLS server certificate.
779 This implies hostname validation.
781 Multiple sources may be given, separated by commas and/or whitespace
782 (where in the latter case the whole argument must be enclosed in "...").
783 Each source may contain multiple certificates.
785 The certificate verification options
786 B<-verify_hostname>, B<-verify_ip>, and B<-verify_email>
787 have no effect on the certificate verification enabled via this option.
789 =item B<-tls_host> I<name>
791 Address to be checked during hostname validation.
792 This may be a DNS name or an IP address.
793 If not given it defaults to the B<-server> address.
797 =head2 Client-side debugging options
803 Do not interactively prompt for input, for instance when a password is needed.
804 This can be useful for batch processing and testing.
806 =item B<-repeat> I<number>
808 Invoke the command the given number of times with the same parameters.
809 Default is one invocation.
811 =item B<-reqin> I<filenames>
813 Take sequence of CMP requests from file(s).
815 Multiple filenames may be given, separated by commas and/or whitespace
816 (where in the latter case the whole argument must be enclosed in "...").
817 As many files are read as needed for a complete transaction.
819 =item B<-reqin_new_tid>
821 Use a fresh transactionID for CMP request messages read using B<-reqin>,
822 which requires re-protecting them as far as they were protected before.
823 This may be needed in case the sequence of requests is reused
824 and the CMP server complains that the transaction ID has already been used.
826 =item B<-reqout> I<filenames>
828 Save sequence of CMP requests to file(s).
830 Multiple filenames may be given, separated by commas and/or whitespace.
831 As many files are written as needed to store the complete transaction.
833 =item B<-rspin> I<filenames>
835 Process sequence of CMP responses provided in file(s), skipping server.
837 Multiple filenames may be given, separated by commas and/or whitespace.
838 As many files are read as needed for the complete transaction.
840 =item B<-rspout> I<filenames>
842 Save sequence of CMP responses to file(s).
844 Multiple filenames may be given, separated by commas and/or whitespace.
845 As many files are written as needed to store the complete transaction.
847 =item B<-use_mock_srv>
849 Use the internal mock server for testing the client.
850 This works at API level, bypassing HTTP transport.
854 =head2 Mock server options
858 =item B<-port> I<number>
860 Act as CMP HTTP server mock-up listening on the given port.
862 =item B<-max_msgs> I<number>
864 Maximum number of CMP (request) messages the CMP HTTP server mock-up
865 should handle, which must be nonnegative.
866 The default value is 0, which means that no limit is imposed.
867 In any case the server terminates on internal errors, but not when it
868 detects a CMP-level error that it can successfully answer with an error message.
870 =item B<-srv_ref> I<value>
872 Reference value to use as senderKID of server in case no B<-srv_cert> is given.
874 =item B<-srv_secret> I<arg>
876 Password source for server authentication with a pre-shared key (secret).
878 =item B<-srv_cert> I<filename>|I<uri>]
880 Certificate of the server.
882 =item B<-srv_key> I<filename>|I<uri>]
884 Private key used by the server for signing messages.
886 =item B<-srv_keypass> I<arg>
888 Server private key (and cert) file pass phrase source.
890 =item B<-srv_trusted> I<filenames>|I<uris>
892 Trusted certificates for client authentication.
894 The certificate verification options
895 B<-verify_hostname>, B<-verify_ip>, and B<-verify_email>
896 have no effect on the certificate verification enabled via this option.
898 =item B<-srv_untrusted> I<filenames>|I<uris>
900 Intermediate CA certs that may be useful when verifying client certificates.
902 =item B<-rsp_cert> I<filename>|I<uri>]
904 Certificate to be returned as mock enrollment result.
906 =item B<-rsp_extracerts> I<filenames>|I<uris>
908 Extra certificates to be included in mock certification responses.
910 =item B<-rsp_capubs> I<filenames>|I<uris>
912 CA certificates to be included in mock Initialization Response (IP) message.
914 =item B<-poll_count> I<number>
916 Number of times the client must poll before receiving a certificate.
918 =item B<-check_after> I<number>
920 The checkAfter value (number of seconds to wait) to include in poll response.
922 =item B<-grant_implicitconf>
924 Grant implicit confirmation of newly enrolled certificate.
926 =item B<-pkistatus> I<number>
928 PKIStatus to be included in server response.
929 Valid range is 0 (accepted) .. 6 (keyUpdateWarning).
931 =item B<-failure> I<number>
933 A single failure info bit number to be included in server response.
934 Valid range is 0 (badAlg) .. 26 (duplicateCertReq).
936 =item B<-failurebits> I<number>
937 Number representing failure bits to be included in server response.
938 Valid range is 0 .. 2^27 - 1.
940 =item B<-statusstring> I<arg>
942 Text to be included as status string in server response.
946 Force server to reply with error message.
948 =item B<-send_unprotected>
950 Send response messages without CMP-level protection.
952 =item B<-send_unprot_err>
954 In case of negative responses, server shall send unprotected error messages,
955 certificate responses (IP/CP/KUP), and revocation responses (RP).
956 WARNING: This setting leads to behavior violating RFC 4210.
958 =item B<-accept_unprotected>
960 Accept missing or invalid protection of requests.
962 =item B<-accept_unprot_err>
964 Accept unprotected error messages from client.
966 =item B<-accept_raverified>
968 Accept RAVERIFED as proof-of-possession (POPO).
972 =head2 Certificate verification options, for both CMP and TLS
976 {- $OpenSSL::safe::opt_v_item -}
978 The certificate verification options
979 B<-verify_hostname>, B<-verify_ip>, and B<-verify_email>
980 only affect the certificate verification enabled via the B<-out_trusted> option.
986 When setting up CMP configurations and experimenting with enrollment options
987 typically various errors occur until the configuration is correct and complete.
988 When the CMP server reports an error the client will by default
989 check the protection of the CMP response message.
990 Yet some CMP services tend not to protect negative responses.
991 In this case the client will reject them, and thus their contents are not shown
992 although they usually contain hints that would be helpful for diagnostics.
993 For assisting in such cases the CMP client offers a workaround via the
994 B<-unprotected_errors> option, which allows accepting such negative messages.
998 =head2 Simple examples using the default OpenSSL configuration file
1000 This CMP client implementation comes with demonstrative CMP sections
1001 in the example configuration file F<openssl/apps/openssl.cnf>,
1002 which can be used to interact conveniently with the Insta Demo CA.
1004 In order to enroll an initial certificate from that CA it is sufficient
1005 to issue the following shell commands.
1008 export OPENSSL_CONF=openssl.cnf
1012 wget 'http://pki.certificate.fi:8081/install-ca-cert.html/ca-certificate.crt\
1013 ?ca-id=632&download-certificate=1' -O insta.ca.crt
1017 openssl genrsa -out insta.priv.pem
1018 openssl cmp -section insta
1020 This should produce the file F<insta.cert.pem> containing a new certificate
1021 for the private key held in F<insta.priv.pem>.
1022 It can be viewed using, e.g.,
1024 openssl x509 -noout -text -in insta.cert.pem
1026 In case the network setup requires using an HTTP proxy it may be given as usual
1027 via the environment variable B<http_proxy> or via the B<proxy> option or
1028 the CMP command-line argument B<-proxy>, for example
1030 -proxy http://192.168.1.1:8080
1032 In the Insta Demo CA scenario both clients and the server may use the pre-shared
1033 secret I<insta> and the reference value I<3078> to authenticate to each other.
1035 Alternatively, CMP messages may be protected in signature-based manner,
1036 where the trust anchor in this case is F<insta.ca.crt>
1037 and the client may use any certificate already obtained from that CA,
1038 as specified in the B<[signature]> section of the example configuration.
1039 This can be used in combination with the B<[insta]> section simply by
1041 openssl cmp -section insta,signature
1043 By default the CMP IR message type is used, yet CR works equally here.
1044 This may be specified directly at the command line:
1046 openssl cmp -section insta -cmd cr
1048 or by referencing in addition the B<[cr]> section of the example configuration:
1050 openssl cmp -section insta,cr
1052 In order to update the enrolled certificate one may call
1054 openssl cmp -section insta,kur
1056 using with PBM-based protection or
1058 openssl cmp -section insta,kur,signature
1060 using signature-based protection.
1062 In a similar way any previously enrolled certificate may be revoked by
1064 openssl cmp -section insta,rr -trusted insta.ca.crt
1068 openssl cmp -section insta,rr,signature
1070 Many more options can be used in the configuration file
1071 and/or on the command line.
1072 For instance, the B<-reqexts> CLI option may refer to a section in the
1073 configuration file defining X.509 extensions to use in certificate requests,
1074 such as B<v3_req> in F<openssl/apps/openssl.cnf>:
1076 openssl cmp -section insta,cr -reqexts v3_req
1078 =head2 Certificate enrollment
1080 The following examples at first do not make use of a configuration file.
1081 They assume that a CMP server can be contacted on the local TCP port 80
1082 and accepts requests under the alias I</pkix/>.
1084 For enrolling its very first certificate the client generates a first client key
1085 and sends an initial request message to the local CMP server
1086 using a pre-shared secret key for mutual authentication.
1087 In this example the client does not have the CA certificate yet,
1088 so we specify the name of the CA with the B<-recipient> option
1089 and save any CA certificates that we may receive in the C<capubs.pem> file.
1091 In below command line usage examples the C<\> at line ends is just used
1092 for formatting; each of the command invocations should be on a single line.
1094 openssl genrsa -out cl_key.pem
1095 openssl cmp -cmd ir -server 127.0.0.1:80/pkix/ \
1096 -ref 1234 -secret pass:1234-5678-1234-5678 \
1097 -recipient "/CN=CMPserver" \
1098 -newkey cl_key.pem -subject "/CN=MyName" \
1099 -cacertsout capubs.pem -certout cl_cert.pem
1101 =head2 Certificate update
1103 Then, when the client certificate and its related key pair needs to be updated,
1104 the client can send a key update request taking the certs in C<capubs.pem>
1105 as trusted for authenticating the server and using the previous cert and key
1106 for its own authentication.
1107 Then it can start using the new cert and key.
1109 openssl genrsa -out cl_key_new.pem
1110 openssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \
1111 -trusted capubs.pem \
1112 -cert cl_cert.pem -key cl_key.pem \
1113 -newkey cl_key_new.pem -certout cl_cert.pem
1114 cp cl_key_new.pem cl_key.pem
1116 This command sequence can be repated as often as needed.
1118 =head2 Requesting information from CMP server
1120 Requesting "all relevant information" with an empty General Message.
1121 This prints information about all received ITAV B<infoType>s to stdout.
1123 openssl cmp -cmd genm -server 127.0.0.1/pkix/ \
1124 -ref 1234 -secret pass:1234-5678-1234-5678 \
1125 -recipient "/CN=CMPserver"
1127 =head2 Using a custom configuration file
1129 For CMP client invocations, in particular for certificate enrollment,
1130 usually many parameters need to be set, which is tedious and error-prone to do
1131 on the command line.
1132 Therefore, the client offers the possibility to read
1133 options from sections of the OpenSSL config file, usually called B<openssl.cnf>.
1134 The values found there can still be extended and even overridden by any
1135 subsequently loaded sections and on the command line.
1137 After including in the configuration file the following sections:
1142 trusted = capubs.pem
1146 certout = cl_cert.pem
1149 recipient = "/CN=CMPserver"
1154 secret = pass:1234-5678-1234-567
1155 subject = "/CN=MyName"
1156 cacertsout = capubs.pem
1158 the above enrollment invocations reduce to
1160 openssl cmp -section cmp,cmp-init
1161 openssl cmp -cmd kur -newkey cl_key_new.pem
1163 and the above genm call reduces to
1165 openssl cmp -section cmp,cmp-init -cmd genm
1169 L<openssl-genrsa(1)>, L<openssl-ecparam(1)>, L<openssl-list(1)>,
1170 L<openssl-req(1)>, L<openssl-x509(1)>, L<x509v3_config(5)>
1174 The B<cmp> application was added in OpenSSL 3.0.
1176 The B<-engine option> was deprecated in OpenSSL 3.0.
1180 Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
1182 Licensed under the OpenSSL license (the "License"). You may not use
1183 this file except in compliance with the License. You can obtain a copy
1184 in the file LICENSE in the source distribution or at
1185 L<https://www.openssl.org/source/license.html>.