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