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