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