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