1=pod 2{- OpenSSL::safe::output_do_not_edit_headers(); -} 3 4=head1 NAME 5 6openssl-cmp - Certificate Management Protocol (CMP, RFC 4210) application 7 8=head1 SYNOPSIS 9 10B<openssl> B<cmp> 11[B<-help>] 12[B<-config> I<filename>] 13[B<-section> I<names>] 14[B<-verbosity> I<level>] 15 16Generic message options: 17 18[B<-cmd> I<ir|cr|kur|p10cr|rr|genm>] 19[B<-infotype> I<name>] 20[B<-geninfo> I<OID:int:N>] 21 22Certificate enrollment options: 23 24[B<-newkey> I<filename>|I<uri>] 25[B<-newkeypass> I<arg>] 26[B<-subject> I<name>] 27[B<-issuer> I<name>] 28[B<-days> I<number>] 29[B<-reqexts> I<name>] 30[B<-sans> I<spec>] 31[B<-san_nodefault>] 32[B<-policies> I<name>] 33[B<-policy_oids> I<names>] 34[B<-policy_oids_critical>] 35[B<-popo> I<number>] 36[B<-csr> I<filename>] 37[B<-out_trusted> I<filenames>|I<uris>] 38[B<-implicit_confirm>] 39[B<-disable_confirm>] 40[B<-certout> I<filename>] 41[B<-chainout> I<filename>] 42 43Certificate enrollment and revocation options: 44 45[B<-oldcert> I<filename>|I<uri>] 46[B<-revreason> I<number>] 47 48Message transfer options: 49 50[B<-server> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>] 51[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>] 52[B<-no_proxy> I<addresses>] 53[B<-recipient> I<name>] 54[B<-path> I<remote_path>] 55[B<-keep_alive> I<value>] 56[B<-msg_timeout> I<seconds>] 57[B<-total_timeout> I<seconds>] 58 59Server authentication options: 60 61[B<-trusted> I<filenames>|I<uris>] 62[B<-untrusted> I<filenames>|I<uris>] 63[B<-srvcert> I<filename>|I<uri>] 64[B<-expect_sender> I<name>] 65[B<-ignore_keyusage>] 66[B<-unprotected_errors>] 67[B<-extracertsout> I<filename>] 68[B<-cacertsout> I<filename>] 69 70Client authentication and protection options: 71 72[B<-ref> I<value>] 73[B<-secret> I<arg>] 74[B<-cert> I<filename>|I<uri>] 75[B<-own_trusted> I<filenames>|I<uris>] 76[B<-key> I<filename>|I<uri>] 77[B<-keypass> I<arg>] 78[B<-digest> I<name>] 79[B<-mac> I<name>] 80[B<-extracerts> I<filenames>|I<uris>] 81[B<-unprotected_requests>] 82 83Credentials format options: 84 85[B<-certform> I<PEM|DER>] 86[B<-keyform> I<PEM|DER|P12|ENGINE>] 87[B<-otherpass> I<arg>] 88{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} 89 90Random state options: 91 92{- $OpenSSL::safe::opt_r_synopsis -} 93 94TLS connection options: 95 96[B<-tls_used>] 97[B<-tls_cert> I<filename>|I<uri>] 98[B<-tls_key> I<filename>|I<uri>] 99[B<-tls_keypass> I<arg>] 100[B<-tls_extra> I<filenames>|I<uris>] 101[B<-tls_trusted> I<filenames>|I<uris>] 102[B<-tls_host> I<name>] 103 104Client-side debugging options: 105 106[B<-batch>] 107[B<-repeat> I<number>] 108[B<-reqin> I<filenames>] 109[B<-reqin_new_tid>] 110[B<-reqout> I<filenames>] 111[B<-rspin> I<filenames>] 112[B<-rspout> I<filenames>] 113[B<-use_mock_srv>] 114 115Mock server options: 116 117[B<-port> I<number>] 118[B<-max_msgs> I<number>] 119[B<-srv_ref> I<value>] 120[B<-srv_secret> I<arg>] 121[B<-srv_cert> I<filename>|I<uri>] 122[B<-srv_key> I<filename>|I<uri>] 123[B<-srv_keypass> I<arg>] 124[B<-srv_trusted> I<filenames>|I<uris>] 125[B<-srv_untrusted> I<filenames>|I<uris>] 126[B<-rsp_cert> I<filename>|I<uri>] 127[B<-rsp_extracerts> I<filenames>|I<uris>] 128[B<-rsp_capubs> I<filenames>|I<uris>] 129[B<-poll_count> I<number>] 130[B<-check_after> I<number>] 131[B<-grant_implicitconf>] 132[B<-pkistatus> I<number>] 133[B<-failure> I<number>] 134[B<-failurebits> I<number>] 135[B<-statusstring> I<arg>] 136[B<-send_error>] 137[B<-send_unprotected>] 138[B<-send_unprot_err>] 139[B<-accept_unprotected>] 140[B<-accept_unprot_err>] 141[B<-accept_raverified>] 142 143Certificate verification options, for both CMP and TLS: 144 145{- $OpenSSL::safe::opt_v_synopsis -} 146 147=head1 DESCRIPTION 148 149The B<cmp> command is a client implementation for the Certificate 150Management Protocol (CMP) as defined in RFC4210. 151It can be used to request certificates from a CA server, 152update their certificates, 153request certificates to be revoked, and perform other types of CMP requests. 154 155=head1 OPTIONS 156 157=over 4 158 159=item B<-help> 160 161Display a summary of all options 162 163=item B<-config> I<filename> 164 165Configuration file to use. 166An empty string C<""> means none. 167Default filename is from the environment variable C<OPENSSL_CONF>. 168 169=item B<-section> I<names> 170 171Section(s) to use within config file defining CMP options. 172An empty string C<""> means no specific section. 173Default is C<cmp>. 174 175Multiple section names may be given, separated by commas and/or whitespace 176(where in the latter case the whole argument must be enclosed in "..."). 177Contents of sections named later may override contents of sections named before. 178In any case, as usual, the C<[default]> section and finally the unnamed 179section (as far as present) can provide per-option fallback values. 180 181=item B<-verbosity> I<level> 182 183Level of verbosity for logging, error output, etc. 1840 = EMERG, 1 = ALERT, 2 = CRIT, 3 = ERR, 4 = WARN, 5 = NOTE, 1856 = INFO, 7 = DEBUG, 8 = TRACE. 186Defaults to 6 = INFO. 187 188=back 189 190=head2 Generic message options 191 192=over 4 193 194=item B<-cmd> I<ir|cr|kur|p10cr|rr|genm> 195 196CMP command to execute. 197Currently implemented commands are: 198 199=over 8 200 201=item ir E<nbsp> - Initialization Request 202 203=item cr E<nbsp> - Certificate Request 204 205=item p10cr - PKCS#10 Certification Request (for legacy support) 206 207=item kur E<nbsp>E<nbsp>- Key Update Request 208 209=item rr E<nbsp> - Revocation Request 210 211=item genm - General Message 212 213=back 214 215B<ir> requests initialization of an end entity into a PKI hierarchy 216by issuing a first certificate. 217 218B<cr> requests issuing an additional certificate for an end entity already 219initialized to the PKI hierarchy. 220 221B<p10cr> requests issuing an additional certificate similarly to B<cr> 222but using legacy PKCS#10 CSR format. 223 224B<kur> requests a (key) update for an existing certificate. 225 226B<rr> requests revocation of an existing certificate. 227 228B<genm> requests information using a General Message, where optionally 229included B<InfoTypeAndValue>s may be used to state which info is of interest. 230Upon receipt of the General Response, information about all received 231ITAV B<infoType>s is printed to stdout. 232 233=item B<-infotype> I<name> 234 235Set InfoType name to use for requesting specific info in B<genm>, 236e.g., C<signKeyPairTypes>. 237 238=item B<-geninfo> I<OID:int:N> 239 240generalInfo integer values to place in request PKIHeader with given OID, 241e.g., C<1.2.3.4:int:56789>. 242 243=back 244 245=head2 Certificate enrollment options 246 247=over 4 248 249=item B<-newkey> I<filename>|I<uri> 250 251The source of the private or public key for the certificate being requested. 252Defaults to the public key in the PKCS#10 CSR given with the B<-csr> option, 253the public key of the reference certificate, or the current client key. 254 255The public portion of the key is placed in the certification request. 256 257Unless B<-cmd> I<p10cr>, B<-popo> I<-1>, or B<-popo> I<0> is given, the 258private key will be needed as well to provide the proof of possession (POPO), 259where the B<-key> option may provide a fallback. 260 261=item B<-newkeypass> I<arg> 262 263Pass phrase source for the key given with the B<-newkey> option. 264If not given here, the password will be prompted for if needed. 265 266For more information about the format of I<arg> see 267L<openssl-passphrase-options(1)>. 268 269=item B<-subject> I<name> 270 271X509 Distinguished Name (DN) of subject to use in the requested certificate 272template. 273If the NULL-DN (C<"/">) is given then no subject is placed in the template. 274Default is the subject DN of any PKCS#10 CSR given with the B<-csr> option. 275For KUR, a further fallback is the subject DN 276of the reference certificate (see B<-oldcert>) if provided. 277This fallback is used for IR and CR only if no SANs are set. 278 279If provided and neither B<-cert> nor B<-oldcert> is given, 280the subject DN is used as fallback sender of outgoing CMP messages. 281 282The argument must be formatted as I</type0=value0/type1=value1/type2=...>. 283Special characters may be escaped by C<\> (backslash); whitespace is retained. 284Empty values are permitted, but the corresponding type will not be included. 285Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN). 286Multi-valued RDNs can be formed by placing a C<+> character instead of a C</> 287between the AttributeValueAssertions (AVAs) that specify the members of the set. 288Example: 289 290C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> 291 292=item B<-issuer> I<name> 293 294X509 issuer Distinguished Name (DN) of the CA server 295to place in the requested certificate template in IR/CR/KUR. 296If the NULL-DN (C<"/">) is given then no issuer is placed in the template. 297 298If provided and neither B<-recipient> nor B<-srvcert> is given, 299the issuer DN is used as fallback recipient of outgoing CMP messages. 300 301The argument must be formatted as I</type0=value0/type1=value1/type2=...>. 302For details see the description of the B<-subject> option. 303 304=item B<-days> I<number> 305 306Number of days the new certificate is requested to be valid for, counting from 307the current time of the host. 308Also triggers the explicit request that the 309validity period starts from the current time (as seen by the host). 310 311=item B<-reqexts> I<name> 312 313Name of section in OpenSSL config file defining certificate request extensions. 314If the B<-csr> option is present, these extensions augment the extensions 315contained the given PKCS#10 CSR, overriding any extensions with same OIDs. 316 317=item B<-sans> I<spec> 318 319One or more IP addresses, DNS names, or URIs separated by commas or whitespace 320(where in the latter case the whole argument must be enclosed in "...") 321to add as Subject Alternative Name(s) (SAN) certificate request extension. 322If the special element "critical" is given the SANs are flagged as critical. 323Cannot be used if any Subject Alternative Name extension is set via B<-reqexts>. 324 325=item B<-san_nodefault> 326 327When Subject Alternative Names are not given via B<-sans> 328nor defined via B<-reqexts>, 329they are copied by default from the reference certificate (see B<-oldcert>). 330This can be disabled by giving the B<-san_nodefault> option. 331 332=item B<-policies> I<name> 333 334Name of section in OpenSSL config file defining policies to be set 335as certificate request extension. 336This option cannot be used together with B<-policy_oids>. 337 338=item B<-policy_oids> I<names> 339 340One or more OID(s), separated by commas and/or whitespace 341(where in the latter case the whole argument must be enclosed in "...") 342to add as certificate policies request extension. 343This option cannot be used together with B<-policies>. 344 345=item B<-policy_oids_critical> 346 347Flag the policies given with B<-policy_oids> as critical. 348 349=item B<-popo> I<number> 350 351Proof-of-possession (POPO) method to use for IR/CR/KUR; values: C<-1>..<2> where 352C<-1> = NONE, C<0> = RAVERIFIED, C<1> = SIGNATURE (default), C<2> = KEYENC. 353 354Note that a signature-based POPO can only be produced if a private key 355is provided via the B<-newkey> or B<-key> options. 356 357=item B<-csr> I<filename> 358 359PKCS#10 CSR in PEM or DER format containing a certificate request. 360With B<-cmd> I<p10cr> it is used directly in a legacy P10CR message. 361 362When used with B<-cmd> I<ir>, I<cr>, or I<kur>, 363it is transformed into the respective regular CMP request. 364In this case, a private key must be provided (with B<-newkey> or B<-key>) 365for the proof of possession (unless B<-popo> I<-1> or B<-popo> I<0> is used) 366and the respective public key is placed in the certification request 367(rather than taking over the public key contained in the PKCS#10 CSR). 368 369PKCS#10 CSR input may also be used with B<-cmd> I<rr> 370to specify the certificate to be revoked 371via the included subject name and public key. 372 373=item B<-out_trusted> I<filenames>|I<uris> 374 375Trusted certificate(s) to use for validating the newly enrolled certificate. 376During this verification, any certificate status checking is disabled. 377 378Multiple sources may be given, separated by commas and/or whitespace 379(where in the latter case the whole argument must be enclosed in "..."). 380Each source may contain multiple certificates. 381 382The certificate verification options 383B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 384only affect the certificate verification enabled via this option. 385 386=item B<-implicit_confirm> 387 388Request implicit confirmation of newly enrolled certificates. 389 390=item B<-disable_confirm> 391 392Do not send certificate confirmation message for newly enrolled certificate 393without requesting implicit confirmation 394to cope with broken servers not supporting implicit confirmation correctly. 395B<WARNING:> This leads to behavior violating RFC 4210. 396 397=item B<-certout> I<filename> 398 399The file where the newly enrolled certificate should be saved. 400 401=item B<-chainout> I<filename> 402 403The file where the chain of the newly enrolled certificate should be saved. 404 405=back 406 407=head2 Certificate enrollment and revocation options 408 409=over 4 410 411=item B<-oldcert> I<filename>|I<uri> 412 413The certificate to be updated (i.e., renewed or re-keyed) in Key Update Request 414(KUR) messages or to be revoked in Revocation Request (RR) messages. 415For KUR the certificate to be updated defaults to B<-cert>, 416and the resulting certificate is called I<reference certificate>. 417For RR the certificate to be revoked can also be specified using B<-csr>. 418 419The reference certificate, if any, is also used for 420deriving default subject DN and Subject Alternative Names and the 421default issuer entry in the requested certificate template of an IR/CR/KUR. 422Its public key is used as a fallback in the template of certification requests. 423Its subject is used as sender of outgoing messages if B<-cert> is not given. 424Its issuer is used as default recipient in CMP message headers 425if neither B<-recipient>, B<-srvcert>, nor B<-issuer> is given. 426 427=item B<-revreason> I<number> 428 429Set CRLReason to be included in revocation request (RR); values: C<0>..C<10> 430or C<-1> for none (which is the default). 431 432Reason numbers defined in RFC 5280 are: 433 434 CRLReason ::= ENUMERATED { 435 unspecified (0), 436 keyCompromise (1), 437 cACompromise (2), 438 affiliationChanged (3), 439 superseded (4), 440 cessationOfOperation (5), 441 certificateHold (6), 442 -- value 7 is not used 443 removeFromCRL (8), 444 privilegeWithdrawn (9), 445 aACompromise (10) 446 } 447 448=back 449 450=head2 Message transfer options 451 452=over 4 453 454=item B<-server> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> 455 456The I<host> domain name or IP address and optionally I<port> 457of the CMP server to connect to using HTTP(S). 458IP address may be for v4 or v6, such as C<127.0.0.1> or C<[::1]> for localhost. 459If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. 460 461This option excludes I<-port> and I<-use_mock_srv>. 462It is ignored if I<-rspin> is given with enough filename arguments. 463 464The scheme C<https> may be given only if the B<-tls_used> option is used. 465In this case the default port is 443, else 80. 466The optional userinfo and fragment components are ignored. 467Any given query component is handled as part of the path component. 468If a path is included it provides the default value for the B<-path> option. 469 470=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> 471 472The HTTP(S) proxy server to use for reaching the CMP server unless B<-no_proxy> 473applies, see below. 474If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. 475The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that 476the optional C<http://> or C<https://> prefix is ignored (note that TLS may be 477selected by B<-tls_used>), as well as any path, userinfo, and query, and fragment 478components. 479Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY> 480in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>. 481This option is ignored if I<-server> is not given. 482 483=item B<-no_proxy> I<addresses> 484 485List of IP addresses and/or DNS names of servers 486not to use an HTTP(S) proxy for, separated by commas and/or whitespace 487(where in the latter case the whole argument must be enclosed in "..."). 488Default is from the environment variable C<no_proxy> if set, else C<NO_PROXY>. 489This option is ignored if I<-server> is not given. 490 491=item B<-recipient> I<name> 492 493Distinguished Name (DN) to use in the recipient field of CMP request message 494headers, i.e., the CMP server (usually the addressed CA). 495 496The recipient field in the header of a CMP message is mandatory. 497If not given explicitly the recipient is determined in the following order: 498the subject of the CMP server certificate given with the B<-srvcert> option, 499the B<-issuer> option, 500the issuer of the certificate given with the B<-oldcert> option, 501the issuer of the CMP client certificate (B<-cert> option), 502as far as any of those is present, else the NULL-DN as last resort. 503 504The argument must be formatted as I</type0=value0/type1=value1/type2=...>. 505For details see the description of the B<-subject> option. 506 507=item B<-path> I<remote_path> 508 509HTTP path at the CMP server (aka CMP alias) to use for POST requests. 510Defaults to any path given with B<-server>, else C<"/">. 511 512=item B<-keep_alive> I<value> 513 514If the given value is 0 then HTTP connections are not kept open 515after receiving a response, which is the default behavior for HTTP 1.0. 516If the value is 1 or 2 then persistent connections are requested. 517If the value is 2 then persistent connections are required, 518i.e., in case the server does not grant them an error occurs. 519The default value is 1, which means preferring to keep the connection open. 520 521=item B<-msg_timeout> I<seconds> 522 523Number of seconds a CMP request-response message round trip 524is allowed to take before a timeout error is returned. 525A value <= 0 means no limitation (waiting indefinitely). 526Default is to use the B<-total_timeout> setting. 527 528=item B<-total_timeout> I<seconds> 529 530Maximum total number of seconds a transaction may take, 531including polling etc. 532A value <= 0 means no limitation (waiting indefinitely). 533Default is 0. 534 535=back 536 537=head2 Server authentication options 538 539=over 4 540 541=item B<-trusted> I<filenames>|I<uris> 542 543The certificate(s), typically of root CAs, the client shall use as trust anchors 544when validating signature-based protection of CMP response messages. 545This option is ignored if the B<-srvcert> option is given as well. 546It provides more flexibility than B<-srvcert> because the CMP protection 547certificate of the server is not pinned but may be any certificate 548from which a chain to one of the given trust anchors can be constructed. 549 550If none of B<-trusted>, B<-srvcert>, and B<-secret> is given, message validation 551errors will be thrown unless B<-unprotected_errors> permits an exception. 552 553Multiple sources may be given, separated by commas and/or whitespace 554(where in the latter case the whole argument must be enclosed in "..."). 555Each source may contain multiple certificates. 556 557The certificate verification options 558B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 559have no effect on the certificate verification enabled via this option. 560 561=item B<-untrusted> I<filenames>|I<uris> 562 563Non-trusted intermediate CA certificate(s). 564Any extra certificates given with the B<-cert> option are appended to it. 565All these certificates may be useful for cert path construction 566for the own CMP signer certificate (to include in the extraCerts field of 567request messages) and for the TLS client certificate (if TLS is enabled) 568as well as for chain building 569when validating server certificates (checking signature-based 570CMP message protection) and when validating newly enrolled certificates. 571 572Multiple filenames or URLs may be given, separated by commas and/or whitespace. 573Each source may contain multiple certificates. 574 575=item B<-srvcert> I<filename>|I<uri> 576 577The specific CMP server certificate to expect and directly trust (even if it is 578expired) when verifying signature-based protection of CMP response messages. 579This pins the accepted server and results in ignoring the B<-trusted> option. 580 581If set, the subject of the certificate is also used 582as default value for the recipient of CMP requests 583and as default value for the expected sender of CMP responses. 584 585=item B<-expect_sender> I<name> 586 587Distinguished Name (DN) expected in the sender field of incoming CMP messages. 588Defaults to the subject DN of the pinned B<-srvcert>, if any. 589 590This can be used to make sure that only a particular entity is accepted as 591CMP message signer, and attackers are not able to use arbitrary certificates 592of a trusted PKI hierarchy to fraudulently pose as a CMP server. 593Note that this option gives slightly more freedom than setting the B<-srvcert>, 594which pins the server to the holder of a particular certificate, while the 595expected sender name will continue to match after updates of the server cert. 596 597The argument must be formatted as I</type0=value0/type1=value1/type2=...>. 598For details see the description of the B<-subject> option. 599 600=item B<-ignore_keyusage> 601 602Ignore key usage restrictions in CMP signer certificates when validating 603signature-based protection of incoming CMP messages. 604By default, C<digitalSignature> must be allowed by CMP signer certificates. 605 606=item B<-unprotected_errors> 607 608Accept missing or invalid protection of negative responses from the server. 609This applies to the following message types and contents: 610 611=over 4 612 613=item * error messages 614 615=item * negative certificate responses (IP/CP/KUP) 616 617=item * negative revocation responses (RP) 618 619=item * negative PKIConf messages 620 621=back 622 623B<WARNING:> This setting leads to unspecified behavior and it is meant 624exclusively to allow interoperability with server implementations violating 625RFC 4210, e.g.: 626 627=over 4 628 629=item * section 5.1.3.1 allows exceptions from protecting only for special 630cases: 631"There MAY be cases in which the PKIProtection BIT STRING is deliberately not 632used to protect a message [...] because other protection, external to PKIX, will 633be applied instead." 634 635=item * section 5.3.21 is clear on ErrMsgContent: "The CA MUST always sign it 636with a signature key." 637 638=item * appendix D.4 shows PKIConf message having protection 639 640=back 641 642=item B<-extracertsout> I<filename> 643 644The file where to save all certificates contained in the extraCerts field 645of the last received response message (except for pollRep and PKIConf). 646 647=item B<-cacertsout> I<filename> 648 649The file where to save any CA certificates contained in the caPubs field of 650the last received certificate response (i.e., IP, CP, or KUP) message. 651 652=back 653 654=head2 Client authentication options 655 656=over 4 657 658=item B<-ref> I<value> 659 660Reference number/string/value to use as fallback senderKID; this is required 661if no sender name can be determined from the B<-cert> or <-subject> options and 662is typically used when authenticating with pre-shared key (password-based MAC). 663 664=item B<-secret> I<arg> 665 666Provides the source of a secret value to use with MAC-based message protection. 667This takes precedence over the B<-cert> and B<-key> options. 668The secret is used for creating MAC-based protection of outgoing messages 669and for validating incoming messages that have MAC-based protection. 670The algorithm used by default is Password-Based Message Authentication Code (PBM) 671as defined in RFC 4210 section 5.1.3.1. 672 673For more information about the format of I<arg> see 674L<openssl-passphrase-options(1)>. 675 676=item B<-cert> I<filename>|I<uri> 677 678The client's current CMP signer certificate. 679Requires the corresponding key to be given with B<-key>. 680 681The subject and the public key contained in this certificate 682serve as fallback values in the certificate template of IR/CR/KUR messages. 683 684The subject of this certificate will be used as sender of outgoing CMP messages, 685while the subject of B<-oldcert> or B<-subjectName> may provide fallback values. 686 687The issuer of this certificate is used as one of the recipient fallback values 688and as fallback issuer entry in the certificate template of IR/CR/KUR messages. 689 690When performing signature-based message protection, 691this "protection certificate", also called "signer certificate", 692will be included first in the extraCerts field of outgoing messages 693and the signature is done with the corresponding key. 694In Initialization Request (IR) messages this can be used for authenticating 695using an external entity certificate as defined in appendix E.7 of RFC 4210. 696 697For Key Update Request (KUR) messages this is also used as 698the certificate to be updated if the B<-oldcert> option is not given. 699 700If the file includes further certs, they are appended to the untrusted certs 701because they typically constitute the chain of the client certificate, which 702is included in the extraCerts field in signature-protected request messages. 703 704=item B<-own_trusted> I<filenames>|I<uris> 705 706If this list of certificates is provided then the chain built for 707the client-side CMP signer certificate given with the B<-cert> option 708is verified using the given certificates as trust anchors. 709 710Multiple sources may be given, separated by commas and/or whitespace 711(where in the latter case the whole argument must be enclosed in "..."). 712Each source may contain multiple certificates. 713 714The certificate verification options 715B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 716have no effect on the certificate verification enabled via this option. 717 718=item B<-key> I<filename>|I<uri> 719 720The corresponding private key file for the client's current certificate given in 721the B<-cert> option. 722This will be used for signature-based message protection unless the B<-secret> 723option indicating MAC-based protection or B<-unprotected_requests> is given. 724 725It is also used as a fallback for the B<-newkey> option with IR/CR/KUR messages. 726 727=item B<-keypass> I<arg> 728 729Pass phrase source for the private key given with the B<-key> option. 730Also used for B<-cert> and B<-oldcert> in case it is an encrypted PKCS#12 file. 731If not given here, the password will be prompted for if needed. 732 733For more information about the format of I<arg> see 734L<openssl-passphrase-options(1)>. 735 736=item B<-digest> I<name> 737 738Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG 739and as the one-way function (OWF) in C<MSG_MAC_ALG>. 740If applicable, this is used for message protection and 741proof-of-possession (POPO) signatures. 742To see the list of supported digests, use C<openssl list -digest-commands>. 743Defaults to C<sha256>. 744 745=item B<-mac> I<name> 746 747Specifies the name of the MAC algorithm in C<MSG_MAC_ALG>. 748To get the names of supported MAC algorithms use C<openssl list -mac-algorithms> 749and possibly combine such a name with the name of a supported digest algorithm, 750e.g., hmacWithSHA256. 751Defaults to C<hmac-sha1> as per RFC 4210. 752 753=item B<-extracerts> I<filenames>|I<uris> 754 755Certificates to append in the extraCerts field when sending messages. 756They can be used as the default CMP signer certificate chain to include. 757 758Multiple sources may be given, separated by commas and/or whitespace 759(where in the latter case the whole argument must be enclosed in "..."). 760Each source may contain multiple certificates. 761 762=item B<-unprotected_requests> 763 764Send request messages without CMP-level protection. 765 766=back 767 768=head2 Credentials format options 769 770=over 4 771 772=item B<-certform> I<PEM|DER> 773 774File format to use when saving a certificate to a file. 775Default value is PEM. 776 777=item B<-keyform> I<PEM|DER|P12|ENGINE> 778 779The format of the key input; unspecified by default. 780See L<openssl(1)/Format Options> for details. 781 782=item B<-otherpass> I<arg> 783 784Pass phrase source for certificate given with the B<-trusted>, B<-untrusted>, 785B<-own_trusted>, B<-srvcert>, B<-out_trusted>, B<-extracerts>, 786B<-srv_trusted>, B<-srv_untrusted>, B<-rsp_extracerts>, B<-rsp_capubs>, 787B<-tls_extra>, and B<-tls_trusted> options. 788If not given here, the password will be prompted for if needed. 789 790For more information about the format of I<arg> see 791L<openssl-passphrase-options(1)>. 792 793{- $OpenSSL::safe::opt_engine_item -} 794 795{- output_off() if $disabled{"deprecated-3.0"}; "" -} 796As an alternative to using this combination: 797 798 -engine {engineid} -key {keyid} -keyform ENGINE 799 800... it's also possible to just give the key ID in URI form to B<-key>, 801like this: 802 803 -key org.openssl.engine:{engineid}:{keyid} 804 805This applies to all options specifying keys: B<-key>, B<-newkey>, and 806B<-tls_key>. 807{- output_on() if $disabled{"deprecated-3.0"}; "" -} 808 809=back 810 811=head2 Provider options 812 813=over 4 814 815{- $OpenSSL::safe::opt_provider_item -} 816 817=back 818 819=head2 Random state options 820 821=over 4 822 823{- $OpenSSL::safe::opt_r_item -} 824 825=back 826 827=head2 TLS connection options 828 829=over 4 830 831=item B<-tls_used> 832 833Enable using TLS (even when other TLS-related options are not set) 834for message exchange with CMP server via HTTP. 835This option is not supported with the I<-port> option. 836It is ignored if the I<-server> option is not given or I<-use_mock_srv> is given 837or I<-rspin> is given with enough filename arguments. 838 839The following TLS-related options are ignored 840if B<-tls_used> is not given or does not take effect. 841 842=item B<-tls_cert> I<filename>|I<uri> 843 844Client's TLS certificate. 845If the source includes further certs they are used (along with B<-untrusted> 846certs) for constructing the client cert chain provided to the TLS server. 847 848=item B<-tls_key> I<filename>|I<uri> 849 850Private key for the client's TLS certificate. 851 852=item B<-tls_keypass> I<arg> 853 854Pass phrase source for client's private TLS key B<-tls_key>. 855Also used for B<-tls_cert> in case it is an encrypted PKCS#12 file. 856If not given here, the password will be prompted for if needed. 857 858For more information about the format of I<arg> see 859L<openssl-passphrase-options(1)>. 860 861=item B<-tls_extra> I<filenames>|I<uris> 862 863Extra certificates to provide to TLS server during TLS handshake 864 865=item B<-tls_trusted> I<filenames>|I<uris> 866 867Trusted certificate(s) to use for validating the TLS server certificate. 868This implies hostname validation. 869 870Multiple sources may be given, separated by commas and/or whitespace 871(where in the latter case the whole argument must be enclosed in "..."). 872Each source may contain multiple certificates. 873 874The certificate verification options 875B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 876have no effect on the certificate verification enabled via this option. 877 878=item B<-tls_host> I<name> 879 880Address to be checked during hostname validation. 881This may be a DNS name or an IP address. 882If not given it defaults to the B<-server> address. 883 884=back 885 886=head2 Client-side debugging options 887 888=over 4 889 890=item B<-batch> 891 892Do not interactively prompt for input, for instance when a password is needed. 893This can be useful for batch processing and testing. 894 895=item B<-repeat> I<number> 896 897Invoke the command the given positive number of times with the same parameters. 898Default is one invocation. 899 900=item B<-reqin> I<filenames> 901 902Take the sequence of CMP requests to send to the server from the given file(s) 903rather than from the sequence of requests produced internally. 904 905This option is ignored if the B<-rspin> option is given 906because in the latter case no requests are actually sent. 907 908Multiple filenames may be given, separated by commas and/or whitespace 909(where in the latter case the whole argument must be enclosed in "..."). 910 911The files are read as far as needed to complete the transaction 912and filenames have been provided. If more requests are needed, 913the remaining ones are taken from the items at the respective position 914in the sequence of requests produced internally. 915 916The client needs to update the recipNonce field in the given requests (except 917for the first one) in order to satisfy the checks to be performed by the server. 918This causes re-protection (if protecting requests is required). 919 920=item B<-reqin_new_tid> 921 922Use a fresh transactionID for CMP request messages read using B<-reqin>, 923which causes their reprotection (if protecting requests is required). 924This may be needed in case the sequence of requests is reused 925and the CMP server complains that the transaction ID has already been used. 926 927=item B<-reqout> I<filenames> 928 929Save the sequence of CMP requests created by the client to the given file(s). 930These requests are not sent to the server if the B<-reqin> option is used, too. 931 932Multiple filenames may be given, separated by commas and/or whitespace. 933 934Files are written as far as needed to save the transaction 935and filenames have been provided. 936If the transaction contains more requests, the remaining ones are not saved. 937 938=item B<-rspin> I<filenames> 939 940Process the sequence of CMP responses provided in the given file(s), 941not contacting any given server, 942as long as enough filenames are provided to complete the transaction. 943 944Multiple filenames may be given, separated by commas and/or whitespace. 945 946Any server specified via the I<-server> or I<-use_mock_srv> options is contacted 947only if more responses are needed to complete the transaction. 948In this case the transaction will fail 949unless the server has been prepared to continue the already started transaction. 950 951=item B<-rspout> I<filenames> 952 953Save the sequence of actually used CMP responses to the given file(s). 954These have been received from the server unless B<-rspin> takes effect. 955 956Multiple filenames may be given, separated by commas and/or whitespace. 957 958Files are written as far as needed to save the responses 959contained in the transaction and filenames have been provided. 960If the transaction contains more responses, the remaining ones are not saved. 961 962=item B<-use_mock_srv> 963 964Test the client using the internal CMP server mock-up at API level, 965bypassing socket-based transfer via HTTP. 966This excludes the B<-server> and B<-port> options. 967 968=back 969 970=head2 Mock server options 971 972=over 4 973 974=item B<-port> I<number> 975 976Act as HTTP-based CMP server mock-up listening on the given local port. 977The client may address the server via, e.g., C<127.0.0.1> or C<[::1]>. 978This option excludes the B<-server> and B<-use_mock_srv> options. 979The B<-rspin>, B<-rspout>, B<-reqin>, and B<-reqout> options 980so far are not supported in this mode. 981 982=item B<-max_msgs> I<number> 983 984Maximum number of CMP (request) messages the CMP HTTP server mock-up 985should handle, which must be nonnegative. 986The default value is 0, which means that no limit is imposed. 987In any case the server terminates on internal errors, but not when it 988detects a CMP-level error that it can successfully answer with an error message. 989 990=item B<-srv_ref> I<value> 991 992Reference value to use as senderKID of server in case no B<-srv_cert> is given. 993 994=item B<-srv_secret> I<arg> 995 996Password source for server authentication with a pre-shared key (secret). 997 998=item B<-srv_cert> I<filename>|I<uri> 999 1000Certificate of the server. 1001 1002=item B<-srv_key> I<filename>|I<uri> 1003 1004Private key used by the server for signing messages. 1005 1006=item B<-srv_keypass> I<arg> 1007 1008Server private key (and cert) file pass phrase source. 1009 1010=item B<-srv_trusted> I<filenames>|I<uris> 1011 1012Trusted certificates for client authentication. 1013 1014The certificate verification options 1015B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 1016have no effect on the certificate verification enabled via this option. 1017 1018=item B<-srv_untrusted> I<filenames>|I<uris> 1019 1020Intermediate CA certs that may be useful when validating client certificates. 1021 1022=item B<-rsp_cert> I<filename>|I<uri> 1023 1024Certificate to be returned as mock enrollment result. 1025 1026=item B<-rsp_extracerts> I<filenames>|I<uris> 1027 1028Extra certificates to be included in mock certification responses. 1029 1030=item B<-rsp_capubs> I<filenames>|I<uris> 1031 1032CA certificates to be included in mock Initialization Response (IP) message. 1033 1034=item B<-poll_count> I<number> 1035 1036Number of times the client must poll before receiving a certificate. 1037 1038=item B<-check_after> I<number> 1039 1040The checkAfter value (number of seconds to wait) to include in poll response. 1041 1042=item B<-grant_implicitconf> 1043 1044Grant implicit confirmation of newly enrolled certificate. 1045 1046=item B<-pkistatus> I<number> 1047 1048PKIStatus to be included in server response. 1049Valid range is 0 (accepted) .. 6 (keyUpdateWarning). 1050 1051=item B<-failure> I<number> 1052 1053A single failure info bit number to be included in server response. 1054Valid range is 0 (badAlg) .. 26 (duplicateCertReq). 1055 1056=item B<-failurebits> I<number> 1057Number representing failure bits to be included in server response. 1058Valid range is 0 .. 2^27 - 1. 1059 1060=item B<-statusstring> I<arg> 1061 1062Text to be included as status string in server response. 1063 1064=item B<-send_error> 1065 1066Force server to reply with error message. 1067 1068=item B<-send_unprotected> 1069 1070Send response messages without CMP-level protection. 1071 1072=item B<-send_unprot_err> 1073 1074In case of negative responses, server shall send unprotected error messages, 1075certificate responses (IP/CP/KUP), and revocation responses (RP). 1076WARNING: This setting leads to behavior violating RFC 4210. 1077 1078=item B<-accept_unprotected> 1079 1080Accept missing or invalid protection of requests. 1081 1082=item B<-accept_unprot_err> 1083 1084Accept unprotected error messages from client. 1085So far this has no effect because the server does not accept any error messages. 1086 1087=item B<-accept_raverified> 1088 1089Accept RAVERIFED as proof of possession (POPO). 1090 1091=back 1092 1093=head2 Certificate verification options, for both CMP and TLS 1094 1095=over 4 1096 1097{- $OpenSSL::safe::opt_v_item -} 1098 1099The certificate verification options 1100B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 1101only affect the certificate verification enabled via the B<-out_trusted> option. 1102 1103=back 1104 1105=head1 NOTES 1106 1107When a client obtains from a CMP server CA certificates that it is going to 1108trust, for instance via the C<caPubs> field of a certificate response, 1109authentication of the CMP server is particularly critical. 1110So special care must be taken setting up server authentication 1111using B<-trusted> and related options for certificate-based authentication 1112or B<-secret> for MAC-based protection. 1113 1114When setting up CMP configurations and experimenting with enrollment options 1115typically various errors occur until the configuration is correct and complete. 1116When the CMP server reports an error the client will by default 1117check the protection of the CMP response message. 1118Yet some CMP services tend not to protect negative responses. 1119In this case the client will reject them, and thus their contents are not shown 1120although they usually contain hints that would be helpful for diagnostics. 1121For assisting in such cases the CMP client offers a workaround via the 1122B<-unprotected_errors> option, which allows accepting such negative messages. 1123 1124=head1 EXAMPLES 1125 1126=head2 Simple examples using the default OpenSSL configuration file 1127 1128This CMP client implementation comes with demonstrative CMP sections 1129in the example configuration file F<openssl/apps/openssl.cnf>, 1130which can be used to interact conveniently with the Insta Demo CA. 1131 1132In order to enroll an initial certificate from that CA it is sufficient 1133to issue the following shell commands. 1134 1135 export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf 1136 1137=begin comment 1138 1139 wget 'http://pki.certificate.fi:8081/install-ca-cert.html/ca-certificate.crt\ 1140 ?ca-id=632&download-certificate=1' -O insta.ca.crt 1141 1142=end comment 1143 1144 openssl genrsa -out insta.priv.pem 1145 openssl cmp -section insta 1146 1147This should produce the file F<insta.cert.pem> containing a new certificate 1148for the private key held in F<insta.priv.pem>. 1149It can be viewed using, e.g., 1150 1151 openssl x509 -noout -text -in insta.cert.pem 1152 1153In case the network setup requires using an HTTP proxy it may be given as usual 1154via the environment variable B<http_proxy> or via the B<-proxy> option in the 1155configuration file or the CMP command-line argument B<-proxy>, for example 1156 1157 -proxy http://192.168.1.1:8080 1158 1159In the Insta Demo CA scenario both clients and the server may use the pre-shared 1160secret I<insta> and the reference value I<3078> to authenticate to each other. 1161 1162Alternatively, CMP messages may be protected in signature-based manner, 1163where the trust anchor in this case is F<insta.ca.crt> 1164and the client may use any certificate already obtained from that CA, 1165as specified in the B<[signature]> section of the example configuration. 1166This can be used in combination with the B<[insta]> section simply by 1167 1168 openssl cmp -section insta,signature 1169 1170By default the CMP IR message type is used, yet CR works equally here. 1171This may be specified directly at the command line: 1172 1173 openssl cmp -section insta -cmd cr 1174 1175or by referencing in addition the B<[cr]> section of the example configuration: 1176 1177 openssl cmp -section insta,cr 1178 1179In order to update the enrolled certificate one may call 1180 1181 openssl cmp -section insta,kur 1182 1183using MAC-based protection with PBM or 1184 1185 openssl cmp -section insta,kur,signature 1186 1187using signature-based protection. 1188 1189In a similar way any previously enrolled certificate may be revoked by 1190 1191 openssl cmp -section insta,rr -trusted insta.ca.crt 1192 1193or 1194 1195 openssl cmp -section insta,rr,signature 1196 1197Many more options can be given in the configuration file 1198and/or on the command line. 1199For instance, the B<-reqexts> CLI option may refer to a section in the 1200configuration file defining X.509 extensions to use in certificate requests, 1201such as C<v3_req> in F<openssl/apps/openssl.cnf>: 1202 1203 openssl cmp -section insta,cr -reqexts v3_req 1204 1205=head2 Certificate enrollment 1206 1207The following examples do not make use of a configuration file at first. 1208They assume that a CMP server can be contacted on the local TCP port 80 1209and accepts requests under the alias I</pkix/>. 1210 1211For enrolling its very first certificate the client generates a client key 1212and sends an initial request message to the local CMP server 1213using a pre-shared secret key for mutual authentication. 1214In this example the client does not have the CA certificate yet, 1215so we specify the name of the CA with the B<-recipient> option 1216and save any CA certificates that we may receive in the C<capubs.pem> file. 1217 1218In below command line usage examples the C<\> at line ends is used just 1219for formatting; each of the command invocations should be on a single line. 1220 1221 openssl genrsa -out cl_key.pem 1222 openssl cmp -cmd ir -server 127.0.0.1:80/pkix/ -recipient "/CN=CMPserver" \ 1223 -ref 1234 -secret pass:1234-5678 \ 1224 -newkey cl_key.pem -subject "/CN=MyName" \ 1225 -cacertsout capubs.pem -certout cl_cert.pem 1226 1227=head2 Certificate update 1228 1229Then, when the client certificate and its related key pair needs to be updated, 1230the client can send a key update request taking the certs in C<capubs.pem> 1231as trusted for authenticating the server and using the previous cert and key 1232for its own authentication. 1233Then it can start using the new cert and key. 1234 1235 openssl genrsa -out cl_key_new.pem 1236 openssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \ 1237 -trusted capubs.pem \ 1238 -cert cl_cert.pem -key cl_key.pem \ 1239 -newkey cl_key_new.pem -certout cl_cert.pem 1240 cp cl_key_new.pem cl_key.pem 1241 1242This command sequence can be repeated as often as needed. 1243 1244=head2 Requesting information from CMP server 1245 1246Requesting "all relevant information" with an empty General Message. 1247This prints information about all received ITAV B<infoType>s to stdout. 1248 1249 openssl cmp -cmd genm -server 127.0.0.1/pkix/ -recipient "/CN=CMPserver" \ 1250 -ref 1234 -secret pass:1234-5678 1251 1252=head2 Using a custom configuration file 1253 1254For CMP client invocations, in particular for certificate enrollment, 1255usually many parameters need to be set, which is tedious and error-prone to do 1256on the command line. 1257Therefore, the client offers the possibility to read 1258options from sections of the OpenSSL config file, usually called F<openssl.cnf>. 1259The values found there can still be extended and even overridden by any 1260subsequently loaded sections and on the command line. 1261 1262After including in the configuration file the following sections: 1263 1264 [cmp] 1265 server = 127.0.0.1 1266 path = pkix/ 1267 trusted = capubs.pem 1268 cert = cl_cert.pem 1269 key = cl_key.pem 1270 newkey = cl_key.pem 1271 certout = cl_cert.pem 1272 1273 [init] 1274 recipient = "/CN=CMPserver" 1275 trusted = 1276 cert = 1277 key = 1278 ref = 1234 1279 secret = pass:1234-5678-1234-567 1280 subject = "/CN=MyName" 1281 cacertsout = capubs.pem 1282 1283the above enrollment transactions reduce to 1284 1285 openssl cmp -section cmp,init 1286 openssl cmp -cmd kur -newkey cl_key_new.pem 1287 1288and the above transaction using a general message reduces to 1289 1290 openssl cmp -section cmp,init -cmd genm 1291 1292=head1 SEE ALSO 1293 1294L<openssl-genrsa(1)>, L<openssl-ecparam(1)>, L<openssl-list(1)>, 1295L<openssl-req(1)>, L<openssl-x509(1)>, L<x509v3_config(5)> 1296 1297=head1 HISTORY 1298 1299The B<cmp> application was added in OpenSSL 3.0. 1300 1301The B<-engine option> was deprecated in OpenSSL 3.0. 1302 1303=head1 COPYRIGHT 1304 1305Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved. 1306 1307Licensed under the Apache License 2.0 (the "License"). You may not use 1308this file except in compliance with the License. You can obtain a copy 1309in the file LICENSE in the source distribution or at 1310L<https://www.openssl.org/source/license.html>. 1311 1312=cut 1313