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 DNS hostname or IP address and optionally port 457of the CMP server to connect to using HTTP(S). 458This option excludes I<-port> and I<-use_mock_srv>. 459It is ignored if I<-rspin> is given with enough filename arguments. 460 461The scheme C<https> may be given only if the B<-tls_used> option is used. 462In this case the default port is 443, else 80. 463The optional userinfo and fragment components are ignored. 464Any given query component is handled as part of the path component. 465If a path is included it provides the default value for the B<-path> option. 466 467=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> 468 469The HTTP(S) proxy server to use for reaching the CMP server unless B<-no_proxy> 470applies, see below. 471The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that 472the optional C<http://> or C<https://> prefix is ignored (note that TLS may be 473selected by B<-tls_used>), as well as any path, userinfo, and query, and fragment 474components. 475Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY> 476in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>. 477This option is ignored if I<-server> is not given. 478 479=item B<-no_proxy> I<addresses> 480 481List of IP addresses and/or DNS names of servers 482not to use an HTTP(S) proxy for, separated by commas and/or whitespace 483(where in the latter case the whole argument must be enclosed in "..."). 484Default is from the environment variable C<no_proxy> if set, else C<NO_PROXY>. 485This option is ignored if I<-server> is not given. 486 487=item B<-recipient> I<name> 488 489Distinguished Name (DN) to use in the recipient field of CMP request message 490headers, i.e., the CMP server (usually the addressed CA). 491 492The recipient field in the header of a CMP message is mandatory. 493If not given explicitly the recipient is determined in the following order: 494the subject of the CMP server certificate given with the B<-srvcert> option, 495the B<-issuer> option, 496the issuer of the certificate given with the B<-oldcert> option, 497the issuer of the CMP client certificate (B<-cert> option), 498as far as any of those is present, else the NULL-DN as last resort. 499 500The argument must be formatted as I</type0=value0/type1=value1/type2=...>. 501For details see the description of the B<-subject> option. 502 503=item B<-path> I<remote_path> 504 505HTTP path at the CMP server (aka CMP alias) to use for POST requests. 506Defaults to any path given with B<-server>, else C<"/">. 507 508=item B<-keep_alive> I<value> 509 510If the given value is 0 then HTTP connections are not kept open 511after receiving a response, which is the default behavior for HTTP 1.0. 512If the value is 1 or 2 then persistent connections are requested. 513If the value is 2 then persistent connections are required, 514i.e., in case the server does not grant them an error occurs. 515The default value is 1, which means preferring to keep the connection open. 516 517=item B<-msg_timeout> I<seconds> 518 519Number of seconds a CMP request-response message round trip 520is allowed to take before a timeout error is returned. 521A value <= 0 means no limitation (waiting indefinitely). 522Default is to use the B<-total_timeout> setting. 523 524=item B<-total_timeout> I<seconds> 525 526Maximum total number of seconds a transaction may take, 527including polling etc. 528A value <= 0 means no limitation (waiting indefinitely). 529Default is 0. 530 531=back 532 533=head2 Server authentication options 534 535=over 4 536 537=item B<-trusted> I<filenames>|I<uris> 538 539The certificate(s), typically of root CAs, the client shall use as trust anchors 540when validating signature-based protection of CMP response messages. 541This option is ignored if the B<-srvcert> option is given as well. 542It provides more flexibility than B<-srvcert> because the CMP protection 543certificate of the server is not pinned but may be any certificate 544from which a chain to one of the given trust anchors can be constructed. 545 546If none of B<-trusted>, B<-srvcert>, and B<-secret> is given, message validation 547errors will be thrown unless B<-unprotected_errors> permits an exception. 548 549Multiple sources may be given, separated by commas and/or whitespace 550(where in the latter case the whole argument must be enclosed in "..."). 551Each source may contain multiple certificates. 552 553The certificate verification options 554B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 555have no effect on the certificate verification enabled via this option. 556 557=item B<-untrusted> I<filenames>|I<uris> 558 559Non-trusted intermediate CA certificate(s). 560Any extra certificates given with the B<-cert> option are appended to it. 561All these certificates may be useful for cert path construction 562for the own CMP signer certificate (to include in the extraCerts field of 563request messages) and for the TLS client certificate (if TLS is enabled) 564as well as for chain building 565when validating server certificates (checking signature-based 566CMP message protection) and when validating newly enrolled certificates. 567 568Multiple filenames or URLs may be given, separated by commas and/or whitespace. 569Each source may contain multiple certificates. 570 571=item B<-srvcert> I<filename>|I<uri> 572 573The specific CMP server certificate to expect and directly trust (even if it is 574expired) when verifying signature-based protection of CMP response messages. 575This pins the accepted server and results in ignoring the B<-trusted> option. 576 577If set, the subject of the certificate is also used 578as default value for the recipient of CMP requests 579and as default value for the expected sender of CMP responses. 580 581=item B<-expect_sender> I<name> 582 583Distinguished Name (DN) expected in the sender field of incoming CMP messages. 584Defaults to the subject DN of the pinned B<-srvcert>, if any. 585 586This can be used to make sure that only a particular entity is accepted as 587CMP message signer, and attackers are not able to use arbitrary certificates 588of a trusted PKI hierarchy to fraudulently pose as a CMP server. 589Note that this option gives slightly more freedom than setting the B<-srvcert>, 590which pins the server to the holder of a particular certificate, while the 591expected sender name will continue to match after updates of the server cert. 592 593The argument must be formatted as I</type0=value0/type1=value1/type2=...>. 594For details see the description of the B<-subject> option. 595 596=item B<-ignore_keyusage> 597 598Ignore key usage restrictions in CMP signer certificates when validating 599signature-based protection of incoming CMP messages. 600By default, C<digitalSignature> must be allowed by CMP signer certificates. 601 602=item B<-unprotected_errors> 603 604Accept missing or invalid protection of negative responses from the server. 605This applies to the following message types and contents: 606 607=over 4 608 609=item * error messages 610 611=item * negative certificate responses (IP/CP/KUP) 612 613=item * negative revocation responses (RP) 614 615=item * negative PKIConf messages 616 617=back 618 619B<WARNING:> This setting leads to unspecified behavior and it is meant 620exclusively to allow interoperability with server implementations violating 621RFC 4210, e.g.: 622 623=over 4 624 625=item * section 5.1.3.1 allows exceptions from protecting only for special 626cases: 627"There MAY be cases in which the PKIProtection BIT STRING is deliberately not 628used to protect a message [...] because other protection, external to PKIX, will 629be applied instead." 630 631=item * section 5.3.21 is clear on ErrMsgContent: "The CA MUST always sign it 632with a signature key." 633 634=item * appendix D.4 shows PKIConf message having protection 635 636=back 637 638=item B<-extracertsout> I<filename> 639 640The file where to save all certificates contained in the extraCerts field 641of the last received response message (except for pollRep and PKIConf). 642 643=item B<-cacertsout> I<filename> 644 645The file where to save any CA certificates contained in the caPubs field of 646the last received certificate response (i.e., IP, CP, or KUP) message. 647 648=back 649 650=head2 Client authentication options 651 652=over 4 653 654=item B<-ref> I<value> 655 656Reference number/string/value to use as fallback senderKID; this is required 657if no sender name can be determined from the B<-cert> or <-subject> options and 658is typically used when authenticating with pre-shared key (password-based MAC). 659 660=item B<-secret> I<arg> 661 662Provides the source of a secret value to use with MAC-based message protection. 663This takes precedence over the B<-cert> and B<-key> options. 664The secret is used for creating MAC-based protection of outgoing messages 665and for validating incoming messages that have MAC-based protection. 666The algorithm used by default is Password-Based Message Authentication Code (PBM) 667as defined in RFC 4210 section 5.1.3.1. 668 669For more information about the format of I<arg> see 670L<openssl-passphrase-options(1)>. 671 672=item B<-cert> I<filename>|I<uri> 673 674The client's current CMP signer certificate. 675Requires the corresponding key to be given with B<-key>. 676 677The subject and the public key contained in this certificate 678serve as fallback values in the certificate template of IR/CR/KUR messages. 679 680The subject of this certificate will be used as sender of outgoing CMP messages, 681while the subject of B<-oldcert> or B<-subjectName> may provide fallback values. 682 683The issuer of this certificate is used as one of the recipient fallback values 684and as fallback issuer entry in the certificate template of IR/CR/KUR messages. 685 686When performing signature-based message protection, 687this "protection certificate", also called "signer certificate", 688will be included first in the extraCerts field of outgoing messages 689and the signature is done with the corresponding key. 690In Initialization Request (IR) messages this can be used for authenticating 691using an external entity certificate as defined in appendix E.7 of RFC 4210. 692 693For Key Update Request (KUR) messages this is also used as 694the certificate to be updated if the B<-oldcert> option is not given. 695 696If the file includes further certs, they are appended to the untrusted certs 697because they typically constitute the chain of the client certificate, which 698is included in the extraCerts field in signature-protected request messages. 699 700=item B<-own_trusted> I<filenames>|I<uris> 701 702If this list of certificates is provided then the chain built for 703the client-side CMP signer certificate given with the B<-cert> option 704is verified using the given certificates as trust anchors. 705 706Multiple sources may be given, separated by commas and/or whitespace 707(where in the latter case the whole argument must be enclosed in "..."). 708Each source may contain multiple certificates. 709 710The certificate verification options 711B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 712have no effect on the certificate verification enabled via this option. 713 714=item B<-key> I<filename>|I<uri> 715 716The corresponding private key file for the client's current certificate given in 717the B<-cert> option. 718This will be used for signature-based message protection unless the B<-secret> 719option indicating MAC-based protection or B<-unprotected_requests> is given. 720 721It is also used as a fallback for the B<-newkey> option with IR/CR/KUR messages. 722 723=item B<-keypass> I<arg> 724 725Pass phrase source for the private key given with the B<-key> option. 726Also used for B<-cert> and B<-oldcert> in case it is an encrypted PKCS#12 file. 727If not given here, the password will be prompted for if needed. 728 729For more information about the format of I<arg> see 730L<openssl-passphrase-options(1)>. 731 732=item B<-digest> I<name> 733 734Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG 735and as the one-way function (OWF) in C<MSG_MAC_ALG>. 736If applicable, this is used for message protection and 737proof-of-possession (POPO) signatures. 738To see the list of supported digests, use C<openssl list -digest-commands>. 739Defaults to C<sha256>. 740 741=item B<-mac> I<name> 742 743Specifies the name of the MAC algorithm in C<MSG_MAC_ALG>. 744To get the names of supported MAC algorithms use C<openssl list -mac-algorithms> 745and possibly combine such a name with the name of a supported digest algorithm, 746e.g., hmacWithSHA256. 747Defaults to C<hmac-sha1> as per RFC 4210. 748 749=item B<-extracerts> I<filenames>|I<uris> 750 751Certificates to append in the extraCerts field when sending messages. 752They can be used as the default CMP signer certificate chain to include. 753 754Multiple sources may be given, separated by commas and/or whitespace 755(where in the latter case the whole argument must be enclosed in "..."). 756Each source may contain multiple certificates. 757 758=item B<-unprotected_requests> 759 760Send request messages without CMP-level protection. 761 762=back 763 764=head2 Credentials format options 765 766=over 4 767 768=item B<-certform> I<PEM|DER> 769 770File format to use when saving a certificate to a file. 771Default value is PEM. 772 773=item B<-keyform> I<PEM|DER|P12|ENGINE> 774 775The format of the key input; unspecified by default. 776See L<openssl(1)/Format Options> for details. 777 778=item B<-otherpass> I<arg> 779 780Pass phrase source for certificate given with the B<-trusted>, B<-untrusted>, 781B<-own_trusted>, B<-srvcert>, B<-out_trusted>, B<-extracerts>, 782B<-srv_trusted>, B<-srv_untrusted>, B<-rsp_extracerts>, B<-rsp_capubs>, 783B<-tls_extra>, and B<-tls_trusted> options. 784If not given here, the password will be prompted for if needed. 785 786For more information about the format of I<arg> see 787L<openssl-passphrase-options(1)>. 788 789{- $OpenSSL::safe::opt_engine_item -} 790 791{- output_off() if $disabled{"deprecated-3.0"}; "" -} 792As an alternative to using this combination: 793 794 -engine {engineid} -key {keyid} -keyform ENGINE 795 796... it's also possible to just give the key ID in URI form to B<-key>, 797like this: 798 799 -key org.openssl.engine:{engineid}:{keyid} 800 801This applies to all options specifying keys: B<-key>, B<-newkey>, and 802B<-tls_key>. 803{- output_on() if $disabled{"deprecated-3.0"}; "" -} 804 805=back 806 807=head2 Provider options 808 809=over 4 810 811{- $OpenSSL::safe::opt_provider_item -} 812 813=back 814 815=head2 Random state options 816 817=over 4 818 819{- $OpenSSL::safe::opt_r_item -} 820 821=back 822 823=head2 TLS connection options 824 825=over 4 826 827=item B<-tls_used> 828 829Enable using TLS (even when other TLS-related options are not set) 830for message exchange with CMP server via HTTP. 831This option is not supported with the I<-port> option. 832It is ignored if the I<-server> option is not given or I<-use_mock_srv> is given 833or I<-rspin> is given with enough filename arguments. 834 835The following TLS-related options are ignored 836if B<-tls_used> is not given or does not take effect. 837 838=item B<-tls_cert> I<filename>|I<uri> 839 840Client's TLS certificate. 841If the source includes further certs they are used (along with B<-untrusted> 842certs) for constructing the client cert chain provided to the TLS server. 843 844=item B<-tls_key> I<filename>|I<uri> 845 846Private key for the client's TLS certificate. 847 848=item B<-tls_keypass> I<arg> 849 850Pass phrase source for client's private TLS key B<-tls_key>. 851Also used for B<-tls_cert> in case it is an encrypted PKCS#12 file. 852If not given here, the password will be prompted for if needed. 853 854For more information about the format of I<arg> see 855L<openssl-passphrase-options(1)>. 856 857=item B<-tls_extra> I<filenames>|I<uris> 858 859Extra certificates to provide to TLS server during TLS handshake 860 861=item B<-tls_trusted> I<filenames>|I<uris> 862 863Trusted certificate(s) to use for validating the TLS server certificate. 864This implies hostname validation. 865 866Multiple sources may be given, separated by commas and/or whitespace 867(where in the latter case the whole argument must be enclosed in "..."). 868Each source may contain multiple certificates. 869 870The certificate verification options 871B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 872have no effect on the certificate verification enabled via this option. 873 874=item B<-tls_host> I<name> 875 876Address to be checked during hostname validation. 877This may be a DNS name or an IP address. 878If not given it defaults to the B<-server> address. 879 880=back 881 882=head2 Client-side debugging options 883 884=over 4 885 886=item B<-batch> 887 888Do not interactively prompt for input, for instance when a password is needed. 889This can be useful for batch processing and testing. 890 891=item B<-repeat> I<number> 892 893Invoke the command the given positive number of times with the same parameters. 894Default is one invocation. 895 896=item B<-reqin> I<filenames> 897 898Take the sequence of CMP requests to send to the server from the given file(s) 899rather than from the sequence of requests produced internally. 900 901This option is ignored if the B<-rspin> option is given 902because in the latter case no requests are actually sent. 903 904Multiple filenames may be given, separated by commas and/or whitespace 905(where in the latter case the whole argument must be enclosed in "..."). 906 907The files are read as far as needed to complete the transaction 908and filenames have been provided. If more requests are needed, 909the remaining ones are taken from the items at the respective position 910in the sequence of requests produced internally. 911 912The client needs to update the recipNonce field in the given requests (except 913for the first one) in order to satisfy the checks to be performed by the server. 914This causes re-protection (if protecting requests is required). 915 916=item B<-reqin_new_tid> 917 918Use a fresh transactionID for CMP request messages read using B<-reqin>, 919which causes their reprotection (if protecting requests is required). 920This may be needed in case the sequence of requests is reused 921and the CMP server complains that the transaction ID has already been used. 922 923=item B<-reqout> I<filenames> 924 925Save the sequence of CMP requests created by the client to the given file(s). 926These requests are not sent to the server if the B<-reqin> option is used, too. 927 928Multiple filenames may be given, separated by commas and/or whitespace. 929 930Files are written as far as needed to save the transaction 931and filenames have been provided. 932If the transaction contains more requests, the remaining ones are not saved. 933 934=item B<-rspin> I<filenames> 935 936Process the sequence of CMP responses provided in the given file(s), 937not contacting any given server, 938as long as enough filenames are provided to complete the transaction. 939 940Multiple filenames may be given, separated by commas and/or whitespace. 941 942Any server specified via the I<-server> or I<-use_mock_srv> options is contacted 943only if more responses are needed to complete the transaction. 944In this case the transaction will fail 945unless the server has been prepared to continue the already started transaction. 946 947=item B<-rspout> I<filenames> 948 949Save the sequence of actually used CMP responses to the given file(s). 950These have been received from the server unless B<-rspin> takes effect. 951 952Multiple filenames may be given, separated by commas and/or whitespace. 953 954Files are written as far as needed to save the responses 955contained in the transaction and filenames have been provided. 956If the transaction contains more responses, the remaining ones are not saved. 957 958=item B<-use_mock_srv> 959 960Test the client using the internal CMP server mock-up at API level, 961bypassing socket-based transfer via HTTP. 962This excludes the B<-server> and B<-port> options. 963 964=back 965 966=head2 Mock server options 967 968=over 4 969 970=item B<-port> I<number> 971 972Act as HTTP-based CMP server mock-up listening on the given port. 973This excludes the B<-server> and B<-use_mock_srv> options. 974The B<-rspin>, B<-rspout>, B<-reqin>, and B<-reqout> options 975so far are not supported in this mode. 976 977=item B<-max_msgs> I<number> 978 979Maximum number of CMP (request) messages the CMP HTTP server mock-up 980should handle, which must be nonnegative. 981The default value is 0, which means that no limit is imposed. 982In any case the server terminates on internal errors, but not when it 983detects a CMP-level error that it can successfully answer with an error message. 984 985=item B<-srv_ref> I<value> 986 987Reference value to use as senderKID of server in case no B<-srv_cert> is given. 988 989=item B<-srv_secret> I<arg> 990 991Password source for server authentication with a pre-shared key (secret). 992 993=item B<-srv_cert> I<filename>|I<uri> 994 995Certificate of the server. 996 997=item B<-srv_key> I<filename>|I<uri> 998 999Private key used by the server for signing messages. 1000 1001=item B<-srv_keypass> I<arg> 1002 1003Server private key (and cert) file pass phrase source. 1004 1005=item B<-srv_trusted> I<filenames>|I<uris> 1006 1007Trusted certificates for client authentication. 1008 1009The certificate verification options 1010B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 1011have no effect on the certificate verification enabled via this option. 1012 1013=item B<-srv_untrusted> I<filenames>|I<uris> 1014 1015Intermediate CA certs that may be useful when validating client certificates. 1016 1017=item B<-rsp_cert> I<filename>|I<uri> 1018 1019Certificate to be returned as mock enrollment result. 1020 1021=item B<-rsp_extracerts> I<filenames>|I<uris> 1022 1023Extra certificates to be included in mock certification responses. 1024 1025=item B<-rsp_capubs> I<filenames>|I<uris> 1026 1027CA certificates to be included in mock Initialization Response (IP) message. 1028 1029=item B<-poll_count> I<number> 1030 1031Number of times the client must poll before receiving a certificate. 1032 1033=item B<-check_after> I<number> 1034 1035The checkAfter value (number of seconds to wait) to include in poll response. 1036 1037=item B<-grant_implicitconf> 1038 1039Grant implicit confirmation of newly enrolled certificate. 1040 1041=item B<-pkistatus> I<number> 1042 1043PKIStatus to be included in server response. 1044Valid range is 0 (accepted) .. 6 (keyUpdateWarning). 1045 1046=item B<-failure> I<number> 1047 1048A single failure info bit number to be included in server response. 1049Valid range is 0 (badAlg) .. 26 (duplicateCertReq). 1050 1051=item B<-failurebits> I<number> 1052Number representing failure bits to be included in server response. 1053Valid range is 0 .. 2^27 - 1. 1054 1055=item B<-statusstring> I<arg> 1056 1057Text to be included as status string in server response. 1058 1059=item B<-send_error> 1060 1061Force server to reply with error message. 1062 1063=item B<-send_unprotected> 1064 1065Send response messages without CMP-level protection. 1066 1067=item B<-send_unprot_err> 1068 1069In case of negative responses, server shall send unprotected error messages, 1070certificate responses (IP/CP/KUP), and revocation responses (RP). 1071WARNING: This setting leads to behavior violating RFC 4210. 1072 1073=item B<-accept_unprotected> 1074 1075Accept missing or invalid protection of requests. 1076 1077=item B<-accept_unprot_err> 1078 1079Accept unprotected error messages from client. 1080So far this has no effect because the server does not accept any error messages. 1081 1082=item B<-accept_raverified> 1083 1084Accept RAVERIFED as proof of possession (POPO). 1085 1086=back 1087 1088=head2 Certificate verification options, for both CMP and TLS 1089 1090=over 4 1091 1092{- $OpenSSL::safe::opt_v_item -} 1093 1094The certificate verification options 1095B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 1096only affect the certificate verification enabled via the B<-out_trusted> option. 1097 1098=back 1099 1100=head1 NOTES 1101 1102When a client obtains from a CMP server CA certificates that it is going to 1103trust, for instance via the C<caPubs> field of a certificate response, 1104authentication of the CMP server is particularly critical. 1105So special care must be taken setting up server authentication 1106using B<-trusted> and related options for certificate-based authentication 1107or B<-secret> for MAC-based protection. 1108 1109When setting up CMP configurations and experimenting with enrollment options 1110typically various errors occur until the configuration is correct and complete. 1111When the CMP server reports an error the client will by default 1112check the protection of the CMP response message. 1113Yet some CMP services tend not to protect negative responses. 1114In this case the client will reject them, and thus their contents are not shown 1115although they usually contain hints that would be helpful for diagnostics. 1116For assisting in such cases the CMP client offers a workaround via the 1117B<-unprotected_errors> option, which allows accepting such negative messages. 1118 1119=head1 EXAMPLES 1120 1121=head2 Simple examples using the default OpenSSL configuration file 1122 1123This CMP client implementation comes with demonstrative CMP sections 1124in the example configuration file F<openssl/apps/openssl.cnf>, 1125which can be used to interact conveniently with the Insta Demo CA. 1126 1127In order to enroll an initial certificate from that CA it is sufficient 1128to issue the following shell commands. 1129 1130 export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf 1131 1132=begin comment 1133 1134 wget 'http://pki.certificate.fi:8081/install-ca-cert.html/ca-certificate.crt\ 1135 ?ca-id=632&download-certificate=1' -O insta.ca.crt 1136 1137=end comment 1138 1139 openssl genrsa -out insta.priv.pem 1140 openssl cmp -section insta 1141 1142This should produce the file F<insta.cert.pem> containing a new certificate 1143for the private key held in F<insta.priv.pem>. 1144It can be viewed using, e.g., 1145 1146 openssl x509 -noout -text -in insta.cert.pem 1147 1148In case the network setup requires using an HTTP proxy it may be given as usual 1149via the environment variable B<http_proxy> or via the B<-proxy> option in the 1150configuration file or the CMP command-line argument B<-proxy>, for example 1151 1152 -proxy http://192.168.1.1:8080 1153 1154In the Insta Demo CA scenario both clients and the server may use the pre-shared 1155secret I<insta> and the reference value I<3078> to authenticate to each other. 1156 1157Alternatively, CMP messages may be protected in signature-based manner, 1158where the trust anchor in this case is F<insta.ca.crt> 1159and the client may use any certificate already obtained from that CA, 1160as specified in the B<[signature]> section of the example configuration. 1161This can be used in combination with the B<[insta]> section simply by 1162 1163 openssl cmp -section insta,signature 1164 1165By default the CMP IR message type is used, yet CR works equally here. 1166This may be specified directly at the command line: 1167 1168 openssl cmp -section insta -cmd cr 1169 1170or by referencing in addition the B<[cr]> section of the example configuration: 1171 1172 openssl cmp -section insta,cr 1173 1174In order to update the enrolled certificate one may call 1175 1176 openssl cmp -section insta,kur 1177 1178using MAC-based protection with PBM or 1179 1180 openssl cmp -section insta,kur,signature 1181 1182using signature-based protection. 1183 1184In a similar way any previously enrolled certificate may be revoked by 1185 1186 openssl cmp -section insta,rr -trusted insta.ca.crt 1187 1188or 1189 1190 openssl cmp -section insta,rr,signature 1191 1192Many more options can be given in the configuration file 1193and/or on the command line. 1194For instance, the B<-reqexts> CLI option may refer to a section in the 1195configuration file defining X.509 extensions to use in certificate requests, 1196such as C<v3_req> in F<openssl/apps/openssl.cnf>: 1197 1198 openssl cmp -section insta,cr -reqexts v3_req 1199 1200=head2 Certificate enrollment 1201 1202The following examples do not make use of a configuration file at first. 1203They assume that a CMP server can be contacted on the local TCP port 80 1204and accepts requests under the alias I</pkix/>. 1205 1206For enrolling its very first certificate the client generates a client key 1207and sends an initial request message to the local CMP server 1208using a pre-shared secret key for mutual authentication. 1209In this example the client does not have the CA certificate yet, 1210so we specify the name of the CA with the B<-recipient> option 1211and save any CA certificates that we may receive in the C<capubs.pem> file. 1212 1213In below command line usage examples the C<\> at line ends is used just 1214for formatting; each of the command invocations should be on a single line. 1215 1216 openssl genrsa -out cl_key.pem 1217 openssl cmp -cmd ir -server 127.0.0.1:80/pkix/ -recipient "/CN=CMPserver" \ 1218 -ref 1234 -secret pass:1234-5678 \ 1219 -newkey cl_key.pem -subject "/CN=MyName" \ 1220 -cacertsout capubs.pem -certout cl_cert.pem 1221 1222=head2 Certificate update 1223 1224Then, when the client certificate and its related key pair needs to be updated, 1225the client can send a key update request taking the certs in C<capubs.pem> 1226as trusted for authenticating the server and using the previous cert and key 1227for its own authentication. 1228Then it can start using the new cert and key. 1229 1230 openssl genrsa -out cl_key_new.pem 1231 openssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \ 1232 -trusted capubs.pem \ 1233 -cert cl_cert.pem -key cl_key.pem \ 1234 -newkey cl_key_new.pem -certout cl_cert.pem 1235 cp cl_key_new.pem cl_key.pem 1236 1237This command sequence can be repeated as often as needed. 1238 1239=head2 Requesting information from CMP server 1240 1241Requesting "all relevant information" with an empty General Message. 1242This prints information about all received ITAV B<infoType>s to stdout. 1243 1244 openssl cmp -cmd genm -server 127.0.0.1/pkix/ -recipient "/CN=CMPserver" \ 1245 -ref 1234 -secret pass:1234-5678 1246 1247=head2 Using a custom configuration file 1248 1249For CMP client invocations, in particular for certificate enrollment, 1250usually many parameters need to be set, which is tedious and error-prone to do 1251on the command line. 1252Therefore, the client offers the possibility to read 1253options from sections of the OpenSSL config file, usually called F<openssl.cnf>. 1254The values found there can still be extended and even overridden by any 1255subsequently loaded sections and on the command line. 1256 1257After including in the configuration file the following sections: 1258 1259 [cmp] 1260 server = 127.0.0.1 1261 path = pkix/ 1262 trusted = capubs.pem 1263 cert = cl_cert.pem 1264 key = cl_key.pem 1265 newkey = cl_key.pem 1266 certout = cl_cert.pem 1267 1268 [init] 1269 recipient = "/CN=CMPserver" 1270 trusted = 1271 cert = 1272 key = 1273 ref = 1234 1274 secret = pass:1234-5678-1234-567 1275 subject = "/CN=MyName" 1276 cacertsout = capubs.pem 1277 1278the above enrollment transactions reduce to 1279 1280 openssl cmp -section cmp,init 1281 openssl cmp -cmd kur -newkey cl_key_new.pem 1282 1283and the above transaction using a general message reduces to 1284 1285 openssl cmp -section cmp,init -cmd genm 1286 1287=head1 SEE ALSO 1288 1289L<openssl-genrsa(1)>, L<openssl-ecparam(1)>, L<openssl-list(1)>, 1290L<openssl-req(1)>, L<openssl-x509(1)>, L<x509v3_config(5)> 1291 1292=head1 HISTORY 1293 1294The B<cmp> application was added in OpenSSL 3.0. 1295 1296The B<-engine option> was deprecated in OpenSSL 3.0. 1297 1298=head1 COPYRIGHT 1299 1300Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved. 1301 1302Licensed under the Apache License 2.0 (the "License"). You may not use 1303this file except in compliance with the License. You can obtain a copy 1304in the file LICENSE in the source distribution or at 1305L<https://www.openssl.org/source/license.html>. 1306 1307=cut 1308