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