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 662Prefer PBM-based message protection with given source of a secret value. 663The secret is used for creating PBM-based protection of outgoing messages 664and (as far as needed) for validating PBM-based protection of incoming messages. 665PBM stands for Password-Based Message Authentication Code. 666This takes precedence over the B<-cert> and B<-key> options. 667 668For more information about the format of I<arg> see 669L<openssl-passphrase-options(1)>. 670 671=item B<-cert> I<filename>|I<uri> 672 673The client's current CMP signer certificate. 674Requires the corresponding key to be given with B<-key>. 675 676The subject and the public key contained in this certificate 677serve as fallback values in the certificate template of IR/CR/KUR messages. 678 679The subject of this certificate will be used as sender of outgoing CMP messages, 680while the subject of B<-oldcert> or B<-subjectName> may provide fallback values. 681 682The issuer of this certificate is used as one of the recipient fallback values 683and as fallback issuer entry in the certificate template of IR/CR/KUR messages. 684 685When using signature-based message protection, this "protection certificate" 686will be included first in the extraCerts field of outgoing messages 687and the signature is done with the corresponding key. 688In Initialization Request (IR) messages this can be used for authenticating 689using an external entity certificate as defined in appendix E.7 of RFC 4210. 690 691For Key Update Request (KUR) messages this is also used as 692the certificate to be updated if the B<-oldcert> option is not given. 693 694If the file includes further certs, they are appended to the untrusted certs 695because they typically constitute the chain of the client certificate, which 696is included in the extraCerts field in signature-protected request messages. 697 698=item B<-own_trusted> I<filenames>|I<uris> 699 700If this list of certificates is provided then the chain built for 701the client-side CMP signer certificate given with the B<-cert> option 702is verified using the given certificates as trust anchors. 703 704Multiple sources may be given, separated by commas and/or whitespace 705(where in the latter case the whole argument must be enclosed in "..."). 706Each source may contain multiple certificates. 707 708The certificate verification options 709B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 710have no effect on the certificate verification enabled via this option. 711 712=item B<-key> I<filename>|I<uri> 713 714The corresponding private key file for the client's current certificate given in 715the B<-cert> option. 716This will be used for signature-based message protection unless 717the B<-secret> option indicating PBM or B<-unprotected_requests> is given. 718 719It is also used as a fallback for the B<-newkey> option with IR/CR/KUR messages. 720 721=item B<-keypass> I<arg> 722 723Pass phrase source for the private key given with the B<-key> option. 724Also used for B<-cert> and B<-oldcert> in case it is an encrypted PKCS#12 file. 725If not given here, the password will be prompted for if needed. 726 727For more information about the format of I<arg> see 728L<openssl-passphrase-options(1)>. 729 730=item B<-digest> I<name> 731 732Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG 733and as the one-way function (OWF) in MSG_MAC_ALG. 734If applicable, this is used for message protection and 735proof-of-possession (POPO) signatures. 736To see the list of supported digests, use C<openssl list -digest-commands>. 737Defaults to C<sha256>. 738 739=item B<-mac> I<name> 740 741Specifies the name of the MAC algorithm in MSG_MAC_ALG. 742To get the names of supported MAC algorithms use C<openssl list -mac-algorithms> 743and possibly combine such a name with the name of a supported digest algorithm, 744e.g., hmacWithSHA256. 745Defaults to C<hmac-sha1> as per RFC 4210. 746 747=item B<-extracerts> I<filenames>|I<uris> 748 749Certificates to append in the extraCerts field when sending messages. 750They can be used as the default CMP signer certificate chain to include. 751 752Multiple sources may be given, separated by commas and/or whitespace 753(where in the latter case the whole argument must be enclosed in "..."). 754Each source may contain multiple certificates. 755 756=item B<-unprotected_requests> 757 758Send request messages without CMP-level protection. 759 760=back 761 762=head2 Credentials format options 763 764=over 4 765 766=item B<-certform> I<PEM|DER> 767 768File format to use when saving a certificate to a file. 769Default value is PEM. 770 771=item B<-keyform> I<PEM|DER|P12|ENGINE> 772 773The format of the key input; unspecified by default. 774See L<openssl(1)/Format Options> for details. 775 776=item B<-otherpass> I<arg> 777 778Pass phrase source for certificate given with the B<-trusted>, B<-untrusted>, 779B<-own_trusted>, B<-srvcert>, B<-out_trusted>, B<-extracerts>, 780B<-srv_trusted>, B<-srv_untrusted>, B<-rsp_extracerts>, B<-rsp_capubs>, 781B<-tls_extra>, and B<-tls_trusted> options. 782If not given here, the password will be prompted for if needed. 783 784For more information about the format of I<arg> see 785L<openssl-passphrase-options(1)>. 786 787{- $OpenSSL::safe::opt_engine_item -} 788 789{- output_off() if $disabled{"deprecated-3.0"}; "" -} 790As an alternative to using this combination: 791 792 -engine {engineid} -key {keyid} -keyform ENGINE 793 794... it's also possible to just give the key ID in URI form to B<-key>, 795like this: 796 797 -key org.openssl.engine:{engineid}:{keyid} 798 799This applies to all options specifying keys: B<-key>, B<-newkey>, and 800B<-tls_key>. 801{- output_on() if $disabled{"deprecated-3.0"}; "" -} 802 803=back 804 805=head2 Provider options 806 807=over 4 808 809{- $OpenSSL::safe::opt_provider_item -} 810 811=back 812 813=head2 Random state options 814 815=over 4 816 817{- $OpenSSL::safe::opt_r_item -} 818 819=back 820 821=head2 TLS connection options 822 823=over 4 824 825=item B<-tls_used> 826 827Enable using TLS (even when other TLS-related options are not set) 828for message exchange with CMP server via HTTP. 829This option is not supported with the I<-port> option. 830It is ignored if the I<-server> option is not given or I<-use_mock_srv> is given 831or I<-rspin> is given with enough filename arguments. 832 833The following TLS-related options are ignored 834if B<-tls_used> is not given or does not take effect. 835 836=item B<-tls_cert> I<filename>|I<uri> 837 838Client's TLS certificate. 839If the source includes further certs they are used (along with B<-untrusted> 840certs) for constructing the client cert chain provided to the TLS server. 841 842=item B<-tls_key> I<filename>|I<uri> 843 844Private key for the client's TLS certificate. 845 846=item B<-tls_keypass> I<arg> 847 848Pass phrase source for client's private TLS key B<-tls_key>. 849Also used for B<-tls_cert> in case it is an encrypted PKCS#12 file. 850If not given here, the password will be prompted for if needed. 851 852For more information about the format of I<arg> see 853L<openssl-passphrase-options(1)>. 854 855=item B<-tls_extra> I<filenames>|I<uris> 856 857Extra certificates to provide to TLS server during TLS handshake 858 859=item B<-tls_trusted> I<filenames>|I<uris> 860 861Trusted certificate(s) to use for validating the TLS server certificate. 862This implies hostname validation. 863 864Multiple sources may be given, separated by commas and/or whitespace 865(where in the latter case the whole argument must be enclosed in "..."). 866Each source may contain multiple certificates. 867 868The certificate verification options 869B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 870have no effect on the certificate verification enabled via this option. 871 872=item B<-tls_host> I<name> 873 874Address to be checked during hostname validation. 875This may be a DNS name or an IP address. 876If not given it defaults to the B<-server> address. 877 878=back 879 880=head2 Client-side debugging options 881 882=over 4 883 884=item B<-batch> 885 886Do not interactively prompt for input, for instance when a password is needed. 887This can be useful for batch processing and testing. 888 889=item B<-repeat> I<number> 890 891Invoke the command the given positive number of times with the same parameters. 892Default is one invocation. 893 894=item B<-reqin> I<filenames> 895 896Take the sequence of CMP requests to send to the server from the given file(s) 897rather than from the sequence of requests produced internally. 898 899This option is ignored if the B<-rspin> option is given 900because in the latter case no requests are actually sent. 901 902Multiple filenames may be given, separated by commas and/or whitespace 903(where in the latter case the whole argument must be enclosed in "..."). 904 905The files are read as far as needed to complete the transaction 906and filenames have been provided. If more requests are needed, 907the remaining ones are taken from the items at the respective position 908in the sequence of requests produced internally. 909 910The client needs to update the recipNonce field in the given requests (except 911for the first one) in order to satisfy the checks to be performed by the server. 912This causes re-protection (if protecting requests is required). 913 914=item B<-reqin_new_tid> 915 916Use a fresh transactionID for CMP request messages read using B<-reqin>, 917which causes their reprotection (if protecting requests is required). 918This may be needed in case the sequence of requests is reused 919and the CMP server complains that the transaction ID has already been used. 920 921=item B<-reqout> I<filenames> 922 923Save the sequence of CMP requests created by the client to the given file(s). 924These requests are not sent to the server if the B<-reqin> option is used, too. 925 926Multiple filenames may be given, separated by commas and/or whitespace. 927 928Files are written as far as needed to save the transaction 929and filenames have been provided. 930If the transaction contains more requests, the remaining ones are not saved. 931 932=item B<-rspin> I<filenames> 933 934Process the sequence of CMP responses provided in the given file(s), 935not contacting any given server, 936as long as enough filenames are provided to complete the transaction. 937 938Multiple filenames may be given, separated by commas and/or whitespace. 939 940Any server specified via the I<-server> or I<-use_mock_srv> options is contacted 941only if more responses are needed to complete the transaction. 942In this case the transaction will fail 943unless the server has been prepared to continue the already started transaction. 944 945=item B<-rspout> I<filenames> 946 947Save the sequence of actually used CMP responses to the given file(s). 948These have been received from the server unless B<-rspin> takes effect. 949 950Multiple filenames may be given, separated by commas and/or whitespace. 951 952Files are written as far as needed to save the responses 953contained in the transaction and filenames have been provided. 954If the transaction contains more responses, the remaining ones are not saved. 955 956=item B<-use_mock_srv> 957 958Test the client using the internal CMP server mock-up at API level, 959bypassing socket-based transfer via HTTP. 960This excludes the B<-server> and B<-port> options. 961 962=back 963 964=head2 Mock server options 965 966=over 4 967 968=item B<-port> I<number> 969 970Act as HTTP-based CMP server mock-up listening on the given port. 971This excludes the B<-server> and B<-use_mock_srv> options. 972The B<-rspin>, B<-rspout>, B<-reqin>, and B<-reqout> options 973so far are not supported in this mode. 974 975=item B<-max_msgs> I<number> 976 977Maximum number of CMP (request) messages the CMP HTTP server mock-up 978should handle, which must be nonnegative. 979The default value is 0, which means that no limit is imposed. 980In any case the server terminates on internal errors, but not when it 981detects a CMP-level error that it can successfully answer with an error message. 982 983=item B<-srv_ref> I<value> 984 985Reference value to use as senderKID of server in case no B<-srv_cert> is given. 986 987=item B<-srv_secret> I<arg> 988 989Password source for server authentication with a pre-shared key (secret). 990 991=item B<-srv_cert> I<filename>|I<uri> 992 993Certificate of the server. 994 995=item B<-srv_key> I<filename>|I<uri> 996 997Private key used by the server for signing messages. 998 999=item B<-srv_keypass> I<arg> 1000 1001Server private key (and cert) file pass phrase source. 1002 1003=item B<-srv_trusted> I<filenames>|I<uris> 1004 1005Trusted certificates for client authentication. 1006 1007The certificate verification options 1008B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 1009have no effect on the certificate verification enabled via this option. 1010 1011=item B<-srv_untrusted> I<filenames>|I<uris> 1012 1013Intermediate CA certs that may be useful when validating client certificates. 1014 1015=item B<-rsp_cert> I<filename>|I<uri> 1016 1017Certificate to be returned as mock enrollment result. 1018 1019=item B<-rsp_extracerts> I<filenames>|I<uris> 1020 1021Extra certificates to be included in mock certification responses. 1022 1023=item B<-rsp_capubs> I<filenames>|I<uris> 1024 1025CA certificates to be included in mock Initialization Response (IP) message. 1026 1027=item B<-poll_count> I<number> 1028 1029Number of times the client must poll before receiving a certificate. 1030 1031=item B<-check_after> I<number> 1032 1033The checkAfter value (number of seconds to wait) to include in poll response. 1034 1035=item B<-grant_implicitconf> 1036 1037Grant implicit confirmation of newly enrolled certificate. 1038 1039=item B<-pkistatus> I<number> 1040 1041PKIStatus to be included in server response. 1042Valid range is 0 (accepted) .. 6 (keyUpdateWarning). 1043 1044=item B<-failure> I<number> 1045 1046A single failure info bit number to be included in server response. 1047Valid range is 0 (badAlg) .. 26 (duplicateCertReq). 1048 1049=item B<-failurebits> I<number> 1050Number representing failure bits to be included in server response. 1051Valid range is 0 .. 2^27 - 1. 1052 1053=item B<-statusstring> I<arg> 1054 1055Text to be included as status string in server response. 1056 1057=item B<-send_error> 1058 1059Force server to reply with error message. 1060 1061=item B<-send_unprotected> 1062 1063Send response messages without CMP-level protection. 1064 1065=item B<-send_unprot_err> 1066 1067In case of negative responses, server shall send unprotected error messages, 1068certificate responses (IP/CP/KUP), and revocation responses (RP). 1069WARNING: This setting leads to behavior violating RFC 4210. 1070 1071=item B<-accept_unprotected> 1072 1073Accept missing or invalid protection of requests. 1074 1075=item B<-accept_unprot_err> 1076 1077Accept unprotected error messages from client. 1078So far this has no effect because the server does not accept any error messages. 1079 1080=item B<-accept_raverified> 1081 1082Accept RAVERIFED as proof of possession (POPO). 1083 1084=back 1085 1086=head2 Certificate verification options, for both CMP and TLS 1087 1088=over 4 1089 1090{- $OpenSSL::safe::opt_v_item -} 1091 1092The certificate verification options 1093B<-verify_hostname>, B<-verify_ip>, and B<-verify_email> 1094only affect the certificate verification enabled via the B<-out_trusted> option. 1095 1096=back 1097 1098=head1 NOTES 1099 1100When setting up CMP configurations and experimenting with enrollment options 1101typically various errors occur until the configuration is correct and complete. 1102When the CMP server reports an error the client will by default 1103check the protection of the CMP response message. 1104Yet some CMP services tend not to protect negative responses. 1105In this case the client will reject them, and thus their contents are not shown 1106although they usually contain hints that would be helpful for diagnostics. 1107For assisting in such cases the CMP client offers a workaround via the 1108B<-unprotected_errors> option, which allows accepting such negative messages. 1109 1110=head1 EXAMPLES 1111 1112=head2 Simple examples using the default OpenSSL configuration file 1113 1114This CMP client implementation comes with demonstrative CMP sections 1115in the example configuration file F<openssl/apps/openssl.cnf>, 1116which can be used to interact conveniently with the Insta Demo CA. 1117 1118In order to enroll an initial certificate from that CA it is sufficient 1119to issue the following shell commands. 1120 1121 export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf 1122 1123=begin comment 1124 1125 wget 'http://pki.certificate.fi:8081/install-ca-cert.html/ca-certificate.crt\ 1126 ?ca-id=632&download-certificate=1' -O insta.ca.crt 1127 1128=end comment 1129 1130 openssl genrsa -out insta.priv.pem 1131 openssl cmp -section insta 1132 1133This should produce the file F<insta.cert.pem> containing a new certificate 1134for the private key held in F<insta.priv.pem>. 1135It can be viewed using, e.g., 1136 1137 openssl x509 -noout -text -in insta.cert.pem 1138 1139In case the network setup requires using an HTTP proxy it may be given as usual 1140via the environment variable B<http_proxy> or via the B<-proxy> option in the 1141configuration file or the CMP command-line argument B<-proxy>, for example 1142 1143 -proxy http://192.168.1.1:8080 1144 1145In the Insta Demo CA scenario both clients and the server may use the pre-shared 1146secret I<insta> and the reference value I<3078> to authenticate to each other. 1147 1148Alternatively, CMP messages may be protected in signature-based manner, 1149where the trust anchor in this case is F<insta.ca.crt> 1150and the client may use any certificate already obtained from that CA, 1151as specified in the B<[signature]> section of the example configuration. 1152This can be used in combination with the B<[insta]> section simply by 1153 1154 openssl cmp -section insta,signature 1155 1156By default the CMP IR message type is used, yet CR works equally here. 1157This may be specified directly at the command line: 1158 1159 openssl cmp -section insta -cmd cr 1160 1161or by referencing in addition the B<[cr]> section of the example configuration: 1162 1163 openssl cmp -section insta,cr 1164 1165In order to update the enrolled certificate one may call 1166 1167 openssl cmp -section insta,kur 1168 1169using with PBM-based protection or 1170 1171 openssl cmp -section insta,kur,signature 1172 1173using signature-based protection. 1174 1175In a similar way any previously enrolled certificate may be revoked by 1176 1177 openssl cmp -section insta,rr -trusted insta.ca.crt 1178 1179or 1180 1181 openssl cmp -section insta,rr,signature 1182 1183Many more options can be given in the configuration file 1184and/or on the command line. 1185For instance, the B<-reqexts> CLI option may refer to a section in the 1186configuration file defining X.509 extensions to use in certificate requests, 1187such as C<v3_req> in F<openssl/apps/openssl.cnf>: 1188 1189 openssl cmp -section insta,cr -reqexts v3_req 1190 1191=head2 Certificate enrollment 1192 1193The following examples do not make use of a configuration file at first. 1194They assume that a CMP server can be contacted on the local TCP port 80 1195and accepts requests under the alias I</pkix/>. 1196 1197For enrolling its very first certificate the client generates a client key 1198and sends an initial request message to the local CMP server 1199using a pre-shared secret key for mutual authentication. 1200In this example the client does not have the CA certificate yet, 1201so we specify the name of the CA with the B<-recipient> option 1202and save any CA certificates that we may receive in the C<capubs.pem> file. 1203 1204In below command line usage examples the C<\> at line ends is used just 1205for formatting; each of the command invocations should be on a single line. 1206 1207 openssl genrsa -out cl_key.pem 1208 openssl cmp -cmd ir -server 127.0.0.1:80/pkix/ -recipient "/CN=CMPserver" \ 1209 -ref 1234 -secret pass:1234-5678 \ 1210 -newkey cl_key.pem -subject "/CN=MyName" \ 1211 -cacertsout capubs.pem -certout cl_cert.pem 1212 1213=head2 Certificate update 1214 1215Then, when the client certificate and its related key pair needs to be updated, 1216the client can send a key update request taking the certs in C<capubs.pem> 1217as trusted for authenticating the server and using the previous cert and key 1218for its own authentication. 1219Then it can start using the new cert and key. 1220 1221 openssl genrsa -out cl_key_new.pem 1222 openssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \ 1223 -trusted capubs.pem \ 1224 -cert cl_cert.pem -key cl_key.pem \ 1225 -newkey cl_key_new.pem -certout cl_cert.pem 1226 cp cl_key_new.pem cl_key.pem 1227 1228This command sequence can be repated as often as needed. 1229 1230=head2 Requesting information from CMP server 1231 1232Requesting "all relevant information" with an empty General Message. 1233This prints information about all received ITAV B<infoType>s to stdout. 1234 1235 openssl cmp -cmd genm -server 127.0.0.1/pkix/ -recipient "/CN=CMPserver" \ 1236 -ref 1234 -secret pass:1234-5678 1237 1238=head2 Using a custom configuration file 1239 1240For CMP client invocations, in particular for certificate enrollment, 1241usually many parameters need to be set, which is tedious and error-prone to do 1242on the command line. 1243Therefore, the client offers the possibility to read 1244options from sections of the OpenSSL config file, usually called F<openssl.cnf>. 1245The values found there can still be extended and even overridden by any 1246subsequently loaded sections and on the command line. 1247 1248After including in the configuration file the following sections: 1249 1250 [cmp] 1251 server = 127.0.0.1 1252 path = pkix/ 1253 trusted = capubs.pem 1254 cert = cl_cert.pem 1255 key = cl_key.pem 1256 newkey = cl_key.pem 1257 certout = cl_cert.pem 1258 1259 [init] 1260 recipient = "/CN=CMPserver" 1261 trusted = 1262 cert = 1263 key = 1264 ref = 1234 1265 secret = pass:1234-5678-1234-567 1266 subject = "/CN=MyName" 1267 cacertsout = capubs.pem 1268 1269the above enrollment transactions reduce to 1270 1271 openssl cmp -section cmp,init 1272 openssl cmp -cmd kur -newkey cl_key_new.pem 1273 1274and the above transaction using a general message reduces to 1275 1276 openssl cmp -section cmp,init -cmd genm 1277 1278=head1 SEE ALSO 1279 1280L<openssl-genrsa(1)>, L<openssl-ecparam(1)>, L<openssl-list(1)>, 1281L<openssl-req(1)>, L<openssl-x509(1)>, L<x509v3_config(5)> 1282 1283=head1 HISTORY 1284 1285The B<cmp> application was added in OpenSSL 3.0. 1286 1287The B<-engine option> was deprecated in OpenSSL 3.0. 1288 1289=head1 COPYRIGHT 1290 1291Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved. 1292 1293Licensed under the Apache License 2.0 (the "License"). You may not use 1294this file except in compliance with the License. You can obtain a copy 1295in the file LICENSE in the source distribution or at 1296L<https://www.openssl.org/source/license.html>. 1297 1298=cut 1299