diff options
Diffstat (limited to 'secure/usr.bin/openssl/man/openssl-cmp.1')
| -rw-r--r-- | secure/usr.bin/openssl/man/openssl-cmp.1 | 1355 |
1 files changed, 1355 insertions, 0 deletions
diff --git a/secure/usr.bin/openssl/man/openssl-cmp.1 b/secure/usr.bin/openssl/man/openssl-cmp.1 new file mode 100644 index 000000000000..007b011c4401 --- /dev/null +++ b/secure/usr.bin/openssl/man/openssl-cmp.1 @@ -0,0 +1,1355 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "OPENSSL-CMP 1ossl" +.TH OPENSSL-CMP 1ossl "2023-09-22" "3.0.11" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +openssl\-cmp \- Certificate Management Protocol (CMP, RFC 4210) application +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBopenssl\fR \fBcmp\fR +[\fB\-help\fR] +[\fB\-config\fR \fIfilename\fR] +[\fB\-section\fR \fInames\fR] +[\fB\-verbosity\fR \fIlevel\fR] +.PP +Generic message options: +.PP +[\fB\-cmd\fR \fIir|cr|kur|p10cr|rr|genm\fR] +[\fB\-infotype\fR \fIname\fR] +[\fB\-geninfo\fR \fIOID:int:N\fR] +.PP +Certificate enrollment options: +.PP +[\fB\-newkey\fR \fIfilename\fR|\fIuri\fR] +[\fB\-newkeypass\fR \fIarg\fR] +[\fB\-subject\fR \fIname\fR] +[\fB\-issuer\fR \fIname\fR] +[\fB\-days\fR \fInumber\fR] +[\fB\-reqexts\fR \fIname\fR] +[\fB\-sans\fR \fIspec\fR] +[\fB\-san_nodefault\fR] +[\fB\-policies\fR \fIname\fR] +[\fB\-policy_oids\fR \fInames\fR] +[\fB\-policy_oids_critical\fR] +[\fB\-popo\fR \fInumber\fR] +[\fB\-csr\fR \fIfilename\fR] +[\fB\-out_trusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-implicit_confirm\fR] +[\fB\-disable_confirm\fR] +[\fB\-certout\fR \fIfilename\fR] +[\fB\-chainout\fR \fIfilename\fR] +.PP +Certificate enrollment and revocation options: +.PP +[\fB\-oldcert\fR \fIfilename\fR|\fIuri\fR] +[\fB\-revreason\fR \fInumber\fR] +.PP +Message transfer options: +.PP +[\fB\-server\fR \fI[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\fR] +[\fB\-proxy\fR \fI[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\fR] +[\fB\-no_proxy\fR \fIaddresses\fR] +[\fB\-recipient\fR \fIname\fR] +[\fB\-path\fR \fIremote_path\fR] +[\fB\-keep_alive\fR \fIvalue\fR] +[\fB\-msg_timeout\fR \fIseconds\fR] +[\fB\-total_timeout\fR \fIseconds\fR] +.PP +Server authentication options: +.PP +[\fB\-trusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-untrusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-srvcert\fR \fIfilename\fR|\fIuri\fR] +[\fB\-expect_sender\fR \fIname\fR] +[\fB\-ignore_keyusage\fR] +[\fB\-unprotected_errors\fR] +[\fB\-extracertsout\fR \fIfilename\fR] +[\fB\-cacertsout\fR \fIfilename\fR] +.PP +Client authentication and protection options: +.PP +[\fB\-ref\fR \fIvalue\fR] +[\fB\-secret\fR \fIarg\fR] +[\fB\-cert\fR \fIfilename\fR|\fIuri\fR] +[\fB\-own_trusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-key\fR \fIfilename\fR|\fIuri\fR] +[\fB\-keypass\fR \fIarg\fR] +[\fB\-digest\fR \fIname\fR] +[\fB\-mac\fR \fIname\fR] +[\fB\-extracerts\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-unprotected_requests\fR] +.PP +Credentials format options: +.PP +[\fB\-certform\fR \fIPEM|DER\fR] +[\fB\-keyform\fR \fIPEM|DER|P12|ENGINE\fR] +[\fB\-otherpass\fR \fIarg\fR] +[\fB\-engine\fR \fIid\fR] +[\fB\-provider\fR \fIname\fR] +[\fB\-provider\-path\fR \fIpath\fR] +[\fB\-propquery\fR \fIpropq\fR] +.PP +Random state options: +.PP +[\fB\-rand\fR \fIfiles\fR] +[\fB\-writerand\fR \fIfile\fR] +.PP +\&\s-1TLS\s0 connection options: +.PP +[\fB\-tls_used\fR] +[\fB\-tls_cert\fR \fIfilename\fR|\fIuri\fR] +[\fB\-tls_key\fR \fIfilename\fR|\fIuri\fR] +[\fB\-tls_keypass\fR \fIarg\fR] +[\fB\-tls_extra\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-tls_trusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-tls_host\fR \fIname\fR] +.PP +Client-side debugging options: +.PP +[\fB\-batch\fR] +[\fB\-repeat\fR \fInumber\fR] +[\fB\-reqin\fR \fIfilenames\fR] +[\fB\-reqin_new_tid\fR] +[\fB\-reqout\fR \fIfilenames\fR] +[\fB\-rspin\fR \fIfilenames\fR] +[\fB\-rspout\fR \fIfilenames\fR] +[\fB\-use_mock_srv\fR] +.PP +Mock server options: +.PP +[\fB\-port\fR \fInumber\fR] +[\fB\-max_msgs\fR \fInumber\fR] +[\fB\-srv_ref\fR \fIvalue\fR] +[\fB\-srv_secret\fR \fIarg\fR] +[\fB\-srv_cert\fR \fIfilename\fR|\fIuri\fR] +[\fB\-srv_key\fR \fIfilename\fR|\fIuri\fR] +[\fB\-srv_keypass\fR \fIarg\fR] +[\fB\-srv_trusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-srv_untrusted\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-rsp_cert\fR \fIfilename\fR|\fIuri\fR] +[\fB\-rsp_extracerts\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-rsp_capubs\fR \fIfilenames\fR|\fIuris\fR] +[\fB\-poll_count\fR \fInumber\fR] +[\fB\-check_after\fR \fInumber\fR] +[\fB\-grant_implicitconf\fR] +[\fB\-pkistatus\fR \fInumber\fR] +[\fB\-failure\fR \fInumber\fR] +[\fB\-failurebits\fR \fInumber\fR] +[\fB\-statusstring\fR \fIarg\fR] +[\fB\-send_error\fR] +[\fB\-send_unprotected\fR] +[\fB\-send_unprot_err\fR] +[\fB\-accept_unprotected\fR] +[\fB\-accept_unprot_err\fR] +[\fB\-accept_raverified\fR] +.PP +Certificate verification options, for both \s-1CMP\s0 and \s-1TLS:\s0 +.PP +[\fB\-allow_proxy_certs\fR] +[\fB\-attime\fR \fItimestamp\fR] +[\fB\-no_check_time\fR] +[\fB\-check_ss_sig\fR] +[\fB\-crl_check\fR] +[\fB\-crl_check_all\fR] +[\fB\-explicit_policy\fR] +[\fB\-extended_crl\fR] +[\fB\-ignore_critical\fR] +[\fB\-inhibit_any\fR] +[\fB\-inhibit_map\fR] +[\fB\-partial_chain\fR] +[\fB\-policy\fR \fIarg\fR] +[\fB\-policy_check\fR] +[\fB\-policy_print\fR] +[\fB\-purpose\fR \fIpurpose\fR] +[\fB\-suiteB_128\fR] +[\fB\-suiteB_128_only\fR] +[\fB\-suiteB_192\fR] +[\fB\-trusted_first\fR] +[\fB\-no_alt_chains\fR] +[\fB\-use_deltas\fR] +[\fB\-auth_level\fR \fInum\fR] +[\fB\-verify_depth\fR \fInum\fR] +[\fB\-verify_email\fR \fIemail\fR] +[\fB\-verify_hostname\fR \fIhostname\fR] +[\fB\-verify_ip\fR \fIip\fR] +[\fB\-verify_name\fR \fIname\fR] +[\fB\-x509_strict\fR] +[\fB\-issuer_checks\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBcmp\fR command is a client implementation for the Certificate +Management Protocol (\s-1CMP\s0) as defined in \s-1RFC4210.\s0 +It can be used to request certificates from a \s-1CA\s0 server, +update their certificates, +request certificates to be revoked, and perform other types of \s-1CMP\s0 requests. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-help\fR" 4 +.IX Item "-help" +Display a summary of all options +.IP "\fB\-config\fR \fIfilename\fR" 4 +.IX Item "-config filename" +Configuration file to use. +An empty string \f(CW""\fR means none. +Default filename is from the environment variable \f(CW\*(C`OPENSSL_CONF\*(C'\fR. +.IP "\fB\-section\fR \fInames\fR" 4 +.IX Item "-section names" +Section(s) to use within config file defining \s-1CMP\s0 options. +An empty string \f(CW""\fR means no specific section. +Default is \f(CW\*(C`cmp\*(C'\fR. +.Sp +Multiple section names may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Contents of sections named later may override contents of sections named before. +In any case, as usual, the \f(CW\*(C`[default]\*(C'\fR section and finally the unnamed +section (as far as present) can provide per-option fallback values. +.IP "\fB\-verbosity\fR \fIlevel\fR" 4 +.IX Item "-verbosity level" +Level of verbosity for logging, error output, etc. +0 = \s-1EMERG, 1\s0 = \s-1ALERT, 2\s0 = \s-1CRIT, 3\s0 = \s-1ERR, 4\s0 = \s-1WARN, 5\s0 = \s-1NOTE, +6\s0 = \s-1INFO, 7\s0 = \s-1DEBUG, 8\s0 = \s-1TRACE.\s0 +Defaults to 6 = \s-1INFO.\s0 +.SS "Generic message options" +.IX Subsection "Generic message options" +.IP "\fB\-cmd\fR \fIir|cr|kur|p10cr|rr|genm\fR" 4 +.IX Item "-cmd ir|cr|kur|p10cr|rr|genm" +\&\s-1CMP\s0 command to execute. +Currently implemented commands are: +.RS 4 +.IP "ir \ \- Initialization Request" 8 +.IX Item "ir - Initialization Request" +.PD 0 +.IP "cr \ \- Certificate Request" 8 +.IX Item "cr - Certificate Request" +.IP "p10cr \- PKCS#10 Certification Request (for legacy support)" 8 +.IX Item "p10cr - PKCS#10 Certification Request (for legacy support)" +.IP "kur \ \ \- Key Update Request" 8 +.IX Item "kur - Key Update Request" +.IP "rr \ \- Revocation Request" 8 +.IX Item "rr - Revocation Request" +.IP "genm \- General Message" 8 +.IX Item "genm - General Message" +.RE +.RS 4 +.PD +.Sp +\&\fBir\fR requests initialization of an end entity into a \s-1PKI\s0 hierarchy +by issuing a first certificate. +.Sp +\&\fBcr\fR requests issuing an additional certificate for an end entity already +initialized to the \s-1PKI\s0 hierarchy. +.Sp +\&\fBp10cr\fR requests issuing an additional certificate similarly to \fBcr\fR +but using legacy PKCS#10 \s-1CSR\s0 format. +.Sp +\&\fBkur\fR requests a (key) update for an existing certificate. +.Sp +\&\fBrr\fR requests revocation of an existing certificate. +.Sp +\&\fBgenm\fR requests information using a General Message, where optionally +included \fBInfoTypeAndValue\fRs may be used to state which info is of interest. +Upon receipt of the General Response, information about all received +\&\s-1ITAV\s0 \fBinfoType\fRs is printed to stdout. +.RE +.IP "\fB\-infotype\fR \fIname\fR" 4 +.IX Item "-infotype name" +Set InfoType name to use for requesting specific info in \fBgenm\fR, +e.g., \f(CW\*(C`signKeyPairTypes\*(C'\fR. +.IP "\fB\-geninfo\fR \fIOID:int:N\fR" 4 +.IX Item "-geninfo OID:int:N" +generalInfo integer values to place in request PKIHeader with given \s-1OID,\s0 +e.g., \f(CW\*(C`1.2.3.4:int:56789\*(C'\fR. +.SS "Certificate enrollment options" +.IX Subsection "Certificate enrollment options" +.IP "\fB\-newkey\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-newkey filename|uri" +The source of the private or public key for the certificate being requested. +Defaults to the public key in the PKCS#10 \s-1CSR\s0 given with the \fB\-csr\fR option, +the public key of the reference certificate, or the current client key. +.Sp +The public portion of the key is placed in the certification request. +.Sp +Unless \fB\-cmd\fR \fIp10cr\fR, \fB\-popo\fR \fI\-1\fR, or \fB\-popo\fR \fI0\fR is given, the +private key will be needed as well to provide the proof of possession (\s-1POPO\s0), +where the \fB\-key\fR option may provide a fallback. +.IP "\fB\-newkeypass\fR \fIarg\fR" 4 +.IX Item "-newkeypass arg" +Pass phrase source for the key given with the \fB\-newkey\fR option. +If not given here, the password will be prompted for if needed. +.Sp +For more information about the format of \fIarg\fR see +\&\fBopenssl\-passphrase\-options\fR\|(1). +.IP "\fB\-subject\fR \fIname\fR" 4 +.IX Item "-subject name" +X509 Distinguished Name (\s-1DN\s0) of subject to use in the requested certificate +template. +If the NULL-DN (\f(CW"/"\fR) is given then no subject is placed in the template. +Default is the subject \s-1DN\s0 of any PKCS#10 \s-1CSR\s0 given with the \fB\-csr\fR option. +For \s-1KUR,\s0 a further fallback is the subject \s-1DN\s0 +of the reference certificate (see \fB\-oldcert\fR) if provided. +This fallback is used for \s-1IR\s0 and \s-1CR\s0 only if no SANs are set. +.Sp +If provided and neither \fB\-cert\fR nor \fB\-oldcert\fR is given, +the subject \s-1DN\s0 is used as fallback sender of outgoing \s-1CMP\s0 messages. +.Sp +The argument must be formatted as \fI/type0=value0/type1=value1/type2=...\fR. +Special characters may be escaped by \f(CW\*(C`\e\*(C'\fR (backslash); whitespace is retained. +Empty values are permitted, but the corresponding type will not be included. +Giving a single \f(CW\*(C`/\*(C'\fR will lead to an empty sequence of RDNs (a NULL-DN). +Multi-valued RDNs can be formed by placing a \f(CW\*(C`+\*(C'\fR character instead of a \f(CW\*(C`/\*(C'\fR +between the AttributeValueAssertions (AVAs) that specify the members of the set. +Example: +.Sp +\&\f(CW\*(C`/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\*(C'\fR +.IP "\fB\-issuer\fR \fIname\fR" 4 +.IX Item "-issuer name" +X509 issuer Distinguished Name (\s-1DN\s0) of the \s-1CA\s0 server +to place in the requested certificate template in \s-1IR/CR/KUR.\s0 +If the NULL-DN (\f(CW"/"\fR) is given then no issuer is placed in the template. +.Sp +If provided and neither \fB\-recipient\fR nor \fB\-srvcert\fR is given, +the issuer \s-1DN\s0 is used as fallback recipient of outgoing \s-1CMP\s0 messages. +.Sp +The argument must be formatted as \fI/type0=value0/type1=value1/type2=...\fR. +For details see the description of the \fB\-subject\fR option. +.IP "\fB\-days\fR \fInumber\fR" 4 +.IX Item "-days number" +Number of days the new certificate is requested to be valid for, counting from +the current time of the host. +Also triggers the explicit request that the +validity period starts from the current time (as seen by the host). +.IP "\fB\-reqexts\fR \fIname\fR" 4 +.IX Item "-reqexts name" +Name of section in OpenSSL config file defining certificate request extensions. +If the \fB\-csr\fR option is present, these extensions augment the extensions +contained the given PKCS#10 \s-1CSR,\s0 overriding any extensions with same OIDs. +.IP "\fB\-sans\fR \fIspec\fR" 4 +.IX Item "-sans spec" +One or more \s-1IP\s0 addresses, \s-1DNS\s0 names, or URIs separated by commas or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R") +to add as Subject Alternative Name(s) (\s-1SAN\s0) certificate request extension. +If the special element \*(L"critical\*(R" is given the SANs are flagged as critical. +Cannot be used if any Subject Alternative Name extension is set via \fB\-reqexts\fR. +.IP "\fB\-san_nodefault\fR" 4 +.IX Item "-san_nodefault" +When Subject Alternative Names are not given via \fB\-sans\fR +nor defined via \fB\-reqexts\fR, +they are copied by default from the reference certificate (see \fB\-oldcert\fR). +This can be disabled by giving the \fB\-san_nodefault\fR option. +.IP "\fB\-policies\fR \fIname\fR" 4 +.IX Item "-policies name" +Name of section in OpenSSL config file defining policies to be set +as certificate request extension. +This option cannot be used together with \fB\-policy_oids\fR. +.IP "\fB\-policy_oids\fR \fInames\fR" 4 +.IX Item "-policy_oids names" +One or more \s-1OID\s0(s), separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R") +to add as certificate policies request extension. +This option cannot be used together with \fB\-policies\fR. +.IP "\fB\-policy_oids_critical\fR" 4 +.IX Item "-policy_oids_critical" +Flag the policies given with \fB\-policy_oids\fR as critical. +.IP "\fB\-popo\fR \fInumber\fR" 4 +.IX Item "-popo number" +Proof-of-possession (\s-1POPO\s0) method to use for \s-1IR/CR/KUR\s0; values: \f(CW\*(C`\-1\*(C'\fR..<2> where +\&\f(CW\*(C`\-1\*(C'\fR = \s-1NONE,\s0 \f(CW0\fR = \s-1RAVERIFIED,\s0 \f(CW1\fR = \s-1SIGNATURE\s0 (default), \f(CW2\fR = \s-1KEYENC.\s0 +.Sp +Note that a signature-based \s-1POPO\s0 can only be produced if a private key +is provided via the \fB\-newkey\fR or \fB\-key\fR options. +.IP "\fB\-csr\fR \fIfilename\fR" 4 +.IX Item "-csr filename" +PKCS#10 \s-1CSR\s0 in \s-1PEM\s0 or \s-1DER\s0 format containing a certificate request. +With \fB\-cmd\fR \fIp10cr\fR it is used directly in a legacy P10CR message. +.Sp +When used with \fB\-cmd\fR \fIir\fR, \fIcr\fR, or \fIkur\fR, +it is transformed into the respective regular \s-1CMP\s0 request. +In this case, a private key must be provided (with \fB\-newkey\fR or \fB\-key\fR) +for the proof of possession (unless \fB\-popo\fR \fI\-1\fR or \fB\-popo\fR \fI0\fR is used) +and the respective public key is placed in the certification request +(rather than taking over the public key contained in the PKCS#10 \s-1CSR\s0). +.Sp +PKCS#10 \s-1CSR\s0 input may also be used with \fB\-cmd\fR \fIrr\fR +to specify the certificate to be revoked +via the included subject name and public key. +.IP "\fB\-out_trusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-out_trusted filenames|uris" +Trusted certificate(s) to use for validating the newly enrolled certificate. +During this verification, any certificate status checking is disabled. +.Sp +Multiple sources may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Each source may contain multiple certificates. +.Sp +The certificate verification options +\&\fB\-verify_hostname\fR, \fB\-verify_ip\fR, and \fB\-verify_email\fR +only affect the certificate verification enabled via this option. +.IP "\fB\-implicit_confirm\fR" 4 +.IX Item "-implicit_confirm" +Request implicit confirmation of newly enrolled certificates. +.IP "\fB\-disable_confirm\fR" 4 +.IX Item "-disable_confirm" +Do not send certificate confirmation message for newly enrolled certificate +without requesting implicit confirmation +to cope with broken servers not supporting implicit confirmation correctly. +\&\fB\s-1WARNING:\s0\fR This leads to behavior violating \s-1RFC 4210.\s0 +.IP "\fB\-certout\fR \fIfilename\fR" 4 +.IX Item "-certout filename" +The file where the newly enrolled certificate should be saved. +.IP "\fB\-chainout\fR \fIfilename\fR" 4 +.IX Item "-chainout filename" +The file where the chain of the newly enrolled certificate should be saved. +.SS "Certificate enrollment and revocation options" +.IX Subsection "Certificate enrollment and revocation options" +.IP "\fB\-oldcert\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-oldcert filename|uri" +The certificate to be updated (i.e., renewed or re-keyed) in Key Update Request +(\s-1KUR\s0) messages or to be revoked in Revocation Request (\s-1RR\s0) messages. +For \s-1KUR\s0 the certificate to be updated defaults to \fB\-cert\fR, +and the resulting certificate is called \fIreference certificate\fR. +For \s-1RR\s0 the certificate to be revoked can also be specified using \fB\-csr\fR. +.Sp +The reference certificate, if any, is also used for +deriving default subject \s-1DN\s0 and Subject Alternative Names and the +default issuer entry in the requested certificate template of an \s-1IR/CR/KUR.\s0 +Its public key is used as a fallback in the template of certification requests. +Its subject is used as sender of outgoing messages if \fB\-cert\fR is not given. +Its issuer is used as default recipient in \s-1CMP\s0 message headers +if neither \fB\-recipient\fR, \fB\-srvcert\fR, nor \fB\-issuer\fR is given. +.IP "\fB\-revreason\fR \fInumber\fR" 4 +.IX Item "-revreason number" +Set CRLReason to be included in revocation request (\s-1RR\s0); values: \f(CW0\fR..\f(CW10\fR +or \f(CW\*(C`\-1\*(C'\fR for none (which is the default). +.Sp +Reason numbers defined in \s-1RFC 5280\s0 are: +.Sp +.Vb 10 +\& CRLReason ::= ENUMERATED { +\& unspecified (0), +\& keyCompromise (1), +\& cACompromise (2), +\& affiliationChanged (3), +\& superseded (4), +\& cessationOfOperation (5), +\& certificateHold (6), +\& \-\- value 7 is not used +\& removeFromCRL (8), +\& privilegeWithdrawn (9), +\& aACompromise (10) +\& } +.Ve +.SS "Message transfer options" +.IX Subsection "Message transfer options" +.IP "\fB\-server\fR \fI[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\fR" 4 +.IX Item "-server [http[s]://][userinfo@]host[:port][/path][?query][#fragment]" +The \s-1DNS\s0 hostname or \s-1IP\s0 address and optionally port +of the \s-1CMP\s0 server to connect to using \s-1HTTP\s0(S). +This option excludes \fI\-port\fR and \fI\-use_mock_srv\fR. +It is ignored if \fI\-rspin\fR is given with enough filename arguments. +.Sp +The scheme \f(CW\*(C`https\*(C'\fR may be given only if the \fB\-tls_used\fR option is used. +In this case the default port is 443, else 80. +The optional userinfo and fragment components are ignored. +Any given query component is handled as part of the path component. +If a path is included it provides the default value for the \fB\-path\fR option. +.IP "\fB\-proxy\fR \fI[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\fR" 4 +.IX Item "-proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]" +The \s-1HTTP\s0(S) proxy server to use for reaching the \s-1CMP\s0 server unless \fB\-no_proxy\fR +applies, see below. +The proxy port defaults to 80 or 443 if the scheme is \f(CW\*(C`https\*(C'\fR; apart from that +the optional \f(CW\*(C`http://\*(C'\fR or \f(CW\*(C`https://\*(C'\fR prefix is ignored (note that \s-1TLS\s0 may be +selected by \fB\-tls_used\fR), as well as any path, userinfo, and query, and fragment +components. +Defaults to the environment variable \f(CW\*(C`http_proxy\*(C'\fR if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR +in case no \s-1TLS\s0 is used, otherwise \f(CW\*(C`https_proxy\*(C'\fR if set, else \f(CW\*(C`HTTPS_PROXY\*(C'\fR. +This option is ignored if \fI\-server\fR is not given. +.IP "\fB\-no_proxy\fR \fIaddresses\fR" 4 +.IX Item "-no_proxy addresses" +List of \s-1IP\s0 addresses and/or \s-1DNS\s0 names of servers +not to use an \s-1HTTP\s0(S) proxy for, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Default is from the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR. +This option is ignored if \fI\-server\fR is not given. +.IP "\fB\-recipient\fR \fIname\fR" 4 +.IX Item "-recipient name" +Distinguished Name (\s-1DN\s0) to use in the recipient field of \s-1CMP\s0 request message +headers, i.e., the \s-1CMP\s0 server (usually the addressed \s-1CA\s0). +.Sp +The recipient field in the header of a \s-1CMP\s0 message is mandatory. +If not given explicitly the recipient is determined in the following order: +the subject of the \s-1CMP\s0 server certificate given with the \fB\-srvcert\fR option, +the \fB\-issuer\fR option, +the issuer of the certificate given with the \fB\-oldcert\fR option, +the issuer of the \s-1CMP\s0 client certificate (\fB\-cert\fR option), +as far as any of those is present, else the NULL-DN as last resort. +.Sp +The argument must be formatted as \fI/type0=value0/type1=value1/type2=...\fR. +For details see the description of the \fB\-subject\fR option. +.IP "\fB\-path\fR \fIremote_path\fR" 4 +.IX Item "-path remote_path" +\&\s-1HTTP\s0 path at the \s-1CMP\s0 server (aka \s-1CMP\s0 alias) to use for \s-1POST\s0 requests. +Defaults to any path given with \fB\-server\fR, else \f(CW"/"\fR. +.IP "\fB\-keep_alive\fR \fIvalue\fR" 4 +.IX Item "-keep_alive value" +If the given value is 0 then \s-1HTTP\s0 connections are not kept open +after receiving a response, which is the default behavior for \s-1HTTP 1.0.\s0 +If the value is 1 or 2 then persistent connections are requested. +If the value is 2 then persistent connections are required, +i.e., in case the server does not grant them an error occurs. +The default value is 1, which means preferring to keep the connection open. +.IP "\fB\-msg_timeout\fR \fIseconds\fR" 4 +.IX Item "-msg_timeout seconds" +Number of seconds a \s-1CMP\s0 request-response message round trip +is allowed to take before a timeout error is returned. +A value <= 0 means no limitation (waiting indefinitely). +Default is to use the \fB\-total_timeout\fR setting. +.IP "\fB\-total_timeout\fR \fIseconds\fR" 4 +.IX Item "-total_timeout seconds" +Maximum total number of seconds a transaction may take, +including polling etc. +A value <= 0 means no limitation (waiting indefinitely). +Default is 0. +.SS "Server authentication options" +.IX Subsection "Server authentication options" +.IP "\fB\-trusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-trusted filenames|uris" +The certificate(s), typically of root CAs, the client shall use as trust anchors +when validating signature-based protection of \s-1CMP\s0 response messages. +This option is ignored if the \fB\-srvcert\fR option is given as well. +It provides more flexibility than \fB\-srvcert\fR because the \s-1CMP\s0 protection +certificate of the server is not pinned but may be any certificate +from which a chain to one of the given trust anchors can be constructed. +.Sp +If none of \fB\-trusted\fR, \fB\-srvcert\fR, and \fB\-secret\fR is given, message validation +errors will be thrown unless \fB\-unprotected_errors\fR permits an exception. +.Sp +Multiple sources may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Each source may contain multiple certificates. +.Sp +The certificate verification options +\&\fB\-verify_hostname\fR, \fB\-verify_ip\fR, and \fB\-verify_email\fR +have no effect on the certificate verification enabled via this option. +.IP "\fB\-untrusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-untrusted filenames|uris" +Non-trusted intermediate \s-1CA\s0 certificate(s). +Any extra certificates given with the \fB\-cert\fR option are appended to it. +All these certificates may be useful for cert path construction +for the own \s-1CMP\s0 signer certificate (to include in the extraCerts field of +request messages) and for the \s-1TLS\s0 client certificate (if \s-1TLS\s0 is enabled) +as well as for chain building +when validating server certificates (checking signature-based +\&\s-1CMP\s0 message protection) and when validating newly enrolled certificates. +.Sp +Multiple filenames or URLs may be given, separated by commas and/or whitespace. +Each source may contain multiple certificates. +.IP "\fB\-srvcert\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-srvcert filename|uri" +The specific \s-1CMP\s0 server certificate to expect and directly trust (even if it is +expired) when verifying signature-based protection of \s-1CMP\s0 response messages. +This pins the accepted server and results in ignoring the \fB\-trusted\fR option. +.Sp +If set, the subject of the certificate is also used +as default value for the recipient of \s-1CMP\s0 requests +and as default value for the expected sender of \s-1CMP\s0 responses. +.IP "\fB\-expect_sender\fR \fIname\fR" 4 +.IX Item "-expect_sender name" +Distinguished Name (\s-1DN\s0) expected in the sender field of incoming \s-1CMP\s0 messages. +Defaults to the subject \s-1DN\s0 of the pinned \fB\-srvcert\fR, if any. +.Sp +This can be used to make sure that only a particular entity is accepted as +\&\s-1CMP\s0 message signer, and attackers are not able to use arbitrary certificates +of a trusted \s-1PKI\s0 hierarchy to fraudulently pose as a \s-1CMP\s0 server. +Note that this option gives slightly more freedom than setting the \fB\-srvcert\fR, +which pins the server to the holder of a particular certificate, while the +expected sender name will continue to match after updates of the server cert. +.Sp +The argument must be formatted as \fI/type0=value0/type1=value1/type2=...\fR. +For details see the description of the \fB\-subject\fR option. +.IP "\fB\-ignore_keyusage\fR" 4 +.IX Item "-ignore_keyusage" +Ignore key usage restrictions in \s-1CMP\s0 signer certificates when validating +signature-based protection of incoming \s-1CMP\s0 messages. +By default, \f(CW\*(C`digitalSignature\*(C'\fR must be allowed by \s-1CMP\s0 signer certificates. +.IP "\fB\-unprotected_errors\fR" 4 +.IX Item "-unprotected_errors" +Accept missing or invalid protection of negative responses from the server. +This applies to the following message types and contents: +.RS 4 +.IP "\(bu" 4 +error messages +.IP "\(bu" 4 +negative certificate responses (\s-1IP/CP/KUP\s0) +.IP "\(bu" 4 +negative revocation responses (\s-1RP\s0) +.IP "\(bu" 4 +negative PKIConf messages +.RE +.RS 4 +.Sp +\&\fB\s-1WARNING:\s0\fR This setting leads to unspecified behavior and it is meant +exclusively to allow interoperability with server implementations violating +\&\s-1RFC 4210,\s0 e.g.: +.IP "\(bu" 4 +section 5.1.3.1 allows exceptions from protecting only for special +cases: +\&\*(L"There \s-1MAY\s0 be cases in which the PKIProtection \s-1BIT STRING\s0 is deliberately not +used to protect a message [...] because other protection, external to \s-1PKIX,\s0 will +be applied instead.\*(R" +.IP "\(bu" 4 +section 5.3.21 is clear on ErrMsgContent: \*(L"The \s-1CA MUST\s0 always sign it +with a signature key.\*(R" +.IP "\(bu" 4 +appendix D.4 shows PKIConf message having protection +.RE +.RS 4 +.RE +.IP "\fB\-extracertsout\fR \fIfilename\fR" 4 +.IX Item "-extracertsout filename" +The file where to save all certificates contained in the extraCerts field +of the last received response message (except for pollRep and PKIConf). +.IP "\fB\-cacertsout\fR \fIfilename\fR" 4 +.IX Item "-cacertsout filename" +The file where to save any \s-1CA\s0 certificates contained in the caPubs field of +the last received certificate response (i.e., \s-1IP, CP,\s0 or \s-1KUP\s0) message. +.SS "Client authentication options" +.IX Subsection "Client authentication options" +.IP "\fB\-ref\fR \fIvalue\fR" 4 +.IX Item "-ref value" +Reference number/string/value to use as fallback senderKID; this is required +if no sender name can be determined from the \fB\-cert\fR or <\-subject> options and +is typically used when authenticating with pre-shared key (password-based \s-1MAC\s0). +.IP "\fB\-secret\fR \fIarg\fR" 4 +.IX Item "-secret arg" +Provides the source of a secret value to use with MAC-based message protection. +This takes precedence over the \fB\-cert\fR and \fB\-key\fR options. +The secret is used for creating MAC-based protection of outgoing messages +and for validating incoming messages that have MAC-based protection. +The algorithm used by default is Password-Based Message Authentication Code (\s-1PBM\s0) +as defined in \s-1RFC 4210\s0 section 5.1.3.1. +.Sp +For more information about the format of \fIarg\fR see +\&\fBopenssl\-passphrase\-options\fR\|(1). +.IP "\fB\-cert\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-cert filename|uri" +The client's current \s-1CMP\s0 signer certificate. +Requires the corresponding key to be given with \fB\-key\fR. +.Sp +The subject and the public key contained in this certificate +serve as fallback values in the certificate template of \s-1IR/CR/KUR\s0 messages. +.Sp +The subject of this certificate will be used as sender of outgoing \s-1CMP\s0 messages, +while the subject of \fB\-oldcert\fR or \fB\-subjectName\fR may provide fallback values. +.Sp +The issuer of this certificate is used as one of the recipient fallback values +and as fallback issuer entry in the certificate template of \s-1IR/CR/KUR\s0 messages. +.Sp +When performing signature-based message protection, +this \*(L"protection certificate\*(R", also called \*(L"signer certificate\*(R", +will be included first in the extraCerts field of outgoing messages +and the signature is done with the corresponding key. +In Initialization Request (\s-1IR\s0) messages this can be used for authenticating +using an external entity certificate as defined in appendix E.7 of \s-1RFC 4210.\s0 +.Sp +For Key Update Request (\s-1KUR\s0) messages this is also used as +the certificate to be updated if the \fB\-oldcert\fR option is not given. +.Sp +If the file includes further certs, they are appended to the untrusted certs +because they typically constitute the chain of the client certificate, which +is included in the extraCerts field in signature-protected request messages. +.IP "\fB\-own_trusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-own_trusted filenames|uris" +If this list of certificates is provided then the chain built for +the client-side \s-1CMP\s0 signer certificate given with the \fB\-cert\fR option +is verified using the given certificates as trust anchors. +.Sp +Multiple sources may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Each source may contain multiple certificates. +.Sp +The certificate verification options +\&\fB\-verify_hostname\fR, \fB\-verify_ip\fR, and \fB\-verify_email\fR +have no effect on the certificate verification enabled via this option. +.IP "\fB\-key\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-key filename|uri" +The corresponding private key file for the client's current certificate given in +the \fB\-cert\fR option. +This will be used for signature-based message protection unless the \fB\-secret\fR +option indicating MAC-based protection or \fB\-unprotected_requests\fR is given. +.Sp +It is also used as a fallback for the \fB\-newkey\fR option with \s-1IR/CR/KUR\s0 messages. +.IP "\fB\-keypass\fR \fIarg\fR" 4 +.IX Item "-keypass arg" +Pass phrase source for the private key given with the \fB\-key\fR option. +Also used for \fB\-cert\fR and \fB\-oldcert\fR in case it is an encrypted PKCS#12 file. +If not given here, the password will be prompted for if needed. +.Sp +For more information about the format of \fIarg\fR see +\&\fBopenssl\-passphrase\-options\fR\|(1). +.IP "\fB\-digest\fR \fIname\fR" 4 +.IX Item "-digest name" +Specifies name of supported digest to use in \s-1RFC 4210\s0's \s-1MSG_SIG_ALG\s0 +and as the one-way function (\s-1OWF\s0) in \f(CW\*(C`MSG_MAC_ALG\*(C'\fR. +If applicable, this is used for message protection and +proof-of-possession (\s-1POPO\s0) signatures. +To see the list of supported digests, use \f(CW\*(C`openssl list \-digest\-commands\*(C'\fR. +Defaults to \f(CW\*(C`sha256\*(C'\fR. +.IP "\fB\-mac\fR \fIname\fR" 4 +.IX Item "-mac name" +Specifies the name of the \s-1MAC\s0 algorithm in \f(CW\*(C`MSG_MAC_ALG\*(C'\fR. +To get the names of supported \s-1MAC\s0 algorithms use \f(CW\*(C`openssl list \-mac\-algorithms\*(C'\fR +and possibly combine such a name with the name of a supported digest algorithm, +e.g., hmacWithSHA256. +Defaults to \f(CW\*(C`hmac\-sha1\*(C'\fR as per \s-1RFC 4210.\s0 +.IP "\fB\-extracerts\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-extracerts filenames|uris" +Certificates to append in the extraCerts field when sending messages. +They can be used as the default \s-1CMP\s0 signer certificate chain to include. +.Sp +Multiple sources may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Each source may contain multiple certificates. +.IP "\fB\-unprotected_requests\fR" 4 +.IX Item "-unprotected_requests" +Send request messages without CMP-level protection. +.SS "Credentials format options" +.IX Subsection "Credentials format options" +.IP "\fB\-certform\fR \fIPEM|DER\fR" 4 +.IX Item "-certform PEM|DER" +File format to use when saving a certificate to a file. +Default value is \s-1PEM.\s0 +.IP "\fB\-keyform\fR \fIPEM|DER|P12|ENGINE\fR" 4 +.IX Item "-keyform PEM|DER|P12|ENGINE" +The format of the key input; unspecified by default. +See \*(L"Format Options\*(R" in \fBopenssl\fR\|(1) for details. +.IP "\fB\-otherpass\fR \fIarg\fR" 4 +.IX Item "-otherpass arg" +Pass phrase source for certificate given with the \fB\-trusted\fR, \fB\-untrusted\fR, +\&\fB\-own_trusted\fR, \fB\-srvcert\fR, \fB\-out_trusted\fR, \fB\-extracerts\fR, +\&\fB\-srv_trusted\fR, \fB\-srv_untrusted\fR, \fB\-rsp_extracerts\fR, \fB\-rsp_capubs\fR, +\&\fB\-tls_extra\fR, and \fB\-tls_trusted\fR options. +If not given here, the password will be prompted for if needed. +.Sp +For more information about the format of \fIarg\fR see +\&\fBopenssl\-passphrase\-options\fR\|(1). +.IP "\fB\-engine\fR \fIid\fR" 4 +.IX Item "-engine id" +See \*(L"Engine Options\*(R" in \fBopenssl\fR\|(1). +This option is deprecated. +.Sp +As an alternative to using this combination: +.Sp +.Vb 1 +\& \-engine {engineid} \-key {keyid} \-keyform ENGINE +.Ve +.Sp +\&... it's also possible to just give the key \s-1ID\s0 in \s-1URI\s0 form to \fB\-key\fR, +like this: +.Sp +.Vb 1 +\& \-key org.openssl.engine:{engineid}:{keyid} +.Ve +.Sp +This applies to all options specifying keys: \fB\-key\fR, \fB\-newkey\fR, and +\&\fB\-tls_key\fR. +.SS "Provider options" +.IX Subsection "Provider options" +.IP "\fB\-provider\fR \fIname\fR" 4 +.IX Item "-provider name" +.PD 0 +.IP "\fB\-provider\-path\fR \fIpath\fR" 4 +.IX Item "-provider-path path" +.IP "\fB\-propquery\fR \fIpropq\fR" 4 +.IX Item "-propquery propq" +.PD +See \*(L"Provider Options\*(R" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7). +.SS "Random state options" +.IX Subsection "Random state options" +.IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4 +.IX Item "-rand files, -writerand file" +See \*(L"Random State Options\*(R" in \fBopenssl\fR\|(1) for details. +.SS "\s-1TLS\s0 connection options" +.IX Subsection "TLS connection options" +.IP "\fB\-tls_used\fR" 4 +.IX Item "-tls_used" +Enable using \s-1TLS\s0 (even when other TLS-related options are not set) +for message exchange with \s-1CMP\s0 server via \s-1HTTP.\s0 +This option is not supported with the \fI\-port\fR option. +It is ignored if the \fI\-server\fR option is not given or \fI\-use_mock_srv\fR is given +or \fI\-rspin\fR is given with enough filename arguments. +.Sp +The following TLS-related options are ignored +if \fB\-tls_used\fR is not given or does not take effect. +.IP "\fB\-tls_cert\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-tls_cert filename|uri" +Client's \s-1TLS\s0 certificate. +If the source includes further certs they are used (along with \fB\-untrusted\fR +certs) for constructing the client cert chain provided to the \s-1TLS\s0 server. +.IP "\fB\-tls_key\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-tls_key filename|uri" +Private key for the client's \s-1TLS\s0 certificate. +.IP "\fB\-tls_keypass\fR \fIarg\fR" 4 +.IX Item "-tls_keypass arg" +Pass phrase source for client's private \s-1TLS\s0 key \fB\-tls_key\fR. +Also used for \fB\-tls_cert\fR in case it is an encrypted PKCS#12 file. +If not given here, the password will be prompted for if needed. +.Sp +For more information about the format of \fIarg\fR see +\&\fBopenssl\-passphrase\-options\fR\|(1). +.IP "\fB\-tls_extra\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-tls_extra filenames|uris" +Extra certificates to provide to \s-1TLS\s0 server during \s-1TLS\s0 handshake +.IP "\fB\-tls_trusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-tls_trusted filenames|uris" +Trusted certificate(s) to use for validating the \s-1TLS\s0 server certificate. +This implies hostname validation. +.Sp +Multiple sources may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +Each source may contain multiple certificates. +.Sp +The certificate verification options +\&\fB\-verify_hostname\fR, \fB\-verify_ip\fR, and \fB\-verify_email\fR +have no effect on the certificate verification enabled via this option. +.IP "\fB\-tls_host\fR \fIname\fR" 4 +.IX Item "-tls_host name" +Address to be checked during hostname validation. +This may be a \s-1DNS\s0 name or an \s-1IP\s0 address. +If not given it defaults to the \fB\-server\fR address. +.SS "Client-side debugging options" +.IX Subsection "Client-side debugging options" +.IP "\fB\-batch\fR" 4 +.IX Item "-batch" +Do not interactively prompt for input, for instance when a password is needed. +This can be useful for batch processing and testing. +.IP "\fB\-repeat\fR \fInumber\fR" 4 +.IX Item "-repeat number" +Invoke the command the given positive number of times with the same parameters. +Default is one invocation. +.IP "\fB\-reqin\fR \fIfilenames\fR" 4 +.IX Item "-reqin filenames" +Take the sequence of \s-1CMP\s0 requests to send to the server from the given file(s) +rather than from the sequence of requests produced internally. +.Sp +This option is ignored if the \fB\-rspin\fR option is given +because in the latter case no requests are actually sent. +.Sp +Multiple filenames may be given, separated by commas and/or whitespace +(where in the latter case the whole argument must be enclosed in \*(L"...\*(R"). +.Sp +The files are read as far as needed to complete the transaction +and filenames have been provided. If more requests are needed, +the remaining ones are taken from the items at the respective position +in the sequence of requests produced internally. +.Sp +The client needs to update the recipNonce field in the given requests (except +for the first one) in order to satisfy the checks to be performed by the server. +This causes re-protection (if protecting requests is required). +.IP "\fB\-reqin_new_tid\fR" 4 +.IX Item "-reqin_new_tid" +Use a fresh transactionID for \s-1CMP\s0 request messages read using \fB\-reqin\fR, +which causes their reprotection (if protecting requests is required). +This may be needed in case the sequence of requests is reused +and the \s-1CMP\s0 server complains that the transaction \s-1ID\s0 has already been used. +.IP "\fB\-reqout\fR \fIfilenames\fR" 4 +.IX Item "-reqout filenames" +Save the sequence of \s-1CMP\s0 requests created by the client to the given file(s). +These requests are not sent to the server if the \fB\-reqin\fR option is used, too. +.Sp +Multiple filenames may be given, separated by commas and/or whitespace. +.Sp +Files are written as far as needed to save the transaction +and filenames have been provided. +If the transaction contains more requests, the remaining ones are not saved. +.IP "\fB\-rspin\fR \fIfilenames\fR" 4 +.IX Item "-rspin filenames" +Process the sequence of \s-1CMP\s0 responses provided in the given file(s), +not contacting any given server, +as long as enough filenames are provided to complete the transaction. +.Sp +Multiple filenames may be given, separated by commas and/or whitespace. +.Sp +Any server specified via the \fI\-server\fR or \fI\-use_mock_srv\fR options is contacted +only if more responses are needed to complete the transaction. +In this case the transaction will fail +unless the server has been prepared to continue the already started transaction. +.IP "\fB\-rspout\fR \fIfilenames\fR" 4 +.IX Item "-rspout filenames" +Save the sequence of actually used \s-1CMP\s0 responses to the given file(s). +These have been received from the server unless \fB\-rspin\fR takes effect. +.Sp +Multiple filenames may be given, separated by commas and/or whitespace. +.Sp +Files are written as far as needed to save the responses +contained in the transaction and filenames have been provided. +If the transaction contains more responses, the remaining ones are not saved. +.IP "\fB\-use_mock_srv\fR" 4 +.IX Item "-use_mock_srv" +Test the client using the internal \s-1CMP\s0 server mock-up at \s-1API\s0 level, +bypassing socket-based transfer via \s-1HTTP.\s0 +This excludes the \fB\-server\fR and \fB\-port\fR options. +.SS "Mock server options" +.IX Subsection "Mock server options" +.IP "\fB\-port\fR \fInumber\fR" 4 +.IX Item "-port number" +Act as HTTP-based \s-1CMP\s0 server mock-up listening on the given port. +This excludes the \fB\-server\fR and \fB\-use_mock_srv\fR options. +The \fB\-rspin\fR, \fB\-rspout\fR, \fB\-reqin\fR, and \fB\-reqout\fR options +so far are not supported in this mode. +.IP "\fB\-max_msgs\fR \fInumber\fR" 4 +.IX Item "-max_msgs number" +Maximum number of \s-1CMP\s0 (request) messages the \s-1CMP HTTP\s0 server mock-up +should handle, which must be nonnegative. +The default value is 0, which means that no limit is imposed. +In any case the server terminates on internal errors, but not when it +detects a CMP-level error that it can successfully answer with an error message. +.IP "\fB\-srv_ref\fR \fIvalue\fR" 4 +.IX Item "-srv_ref value" +Reference value to use as senderKID of server in case no \fB\-srv_cert\fR is given. +.IP "\fB\-srv_secret\fR \fIarg\fR" 4 +.IX Item "-srv_secret arg" +Password source for server authentication with a pre-shared key (secret). +.IP "\fB\-srv_cert\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-srv_cert filename|uri" +Certificate of the server. +.IP "\fB\-srv_key\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-srv_key filename|uri" +Private key used by the server for signing messages. +.IP "\fB\-srv_keypass\fR \fIarg\fR" 4 +.IX Item "-srv_keypass arg" +Server private key (and cert) file pass phrase source. +.IP "\fB\-srv_trusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-srv_trusted filenames|uris" +Trusted certificates for client authentication. +.Sp +The certificate verification options +\&\fB\-verify_hostname\fR, \fB\-verify_ip\fR, and \fB\-verify_email\fR +have no effect on the certificate verification enabled via this option. +.IP "\fB\-srv_untrusted\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-srv_untrusted filenames|uris" +Intermediate \s-1CA\s0 certs that may be useful when validating client certificates. +.IP "\fB\-rsp_cert\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-rsp_cert filename|uri" +Certificate to be returned as mock enrollment result. +.IP "\fB\-rsp_extracerts\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-rsp_extracerts filenames|uris" +Extra certificates to be included in mock certification responses. +.IP "\fB\-rsp_capubs\fR \fIfilenames\fR|\fIuris\fR" 4 +.IX Item "-rsp_capubs filenames|uris" +\&\s-1CA\s0 certificates to be included in mock Initialization Response (\s-1IP\s0) message. +.IP "\fB\-poll_count\fR \fInumber\fR" 4 +.IX Item "-poll_count number" +Number of times the client must poll before receiving a certificate. +.IP "\fB\-check_after\fR \fInumber\fR" 4 +.IX Item "-check_after number" +The checkAfter value (number of seconds to wait) to include in poll response. +.IP "\fB\-grant_implicitconf\fR" 4 +.IX Item "-grant_implicitconf" +Grant implicit confirmation of newly enrolled certificate. +.IP "\fB\-pkistatus\fR \fInumber\fR" 4 +.IX Item "-pkistatus number" +PKIStatus to be included in server response. +Valid range is 0 (accepted) .. 6 (keyUpdateWarning). +.IP "\fB\-failure\fR \fInumber\fR" 4 +.IX Item "-failure number" +A single failure info bit number to be included in server response. +Valid range is 0 (badAlg) .. 26 (duplicateCertReq). +.IP "\fB\-failurebits\fR \fInumber\fR Number representing failure bits to be included in server response. Valid range is 0 .. 2^27 \- 1." 4 +.IX Item "-failurebits number Number representing failure bits to be included in server response. Valid range is 0 .. 2^27 - 1." +.PD 0 +.IP "\fB\-statusstring\fR \fIarg\fR" 4 +.IX Item "-statusstring arg" +.PD +Text to be included as status string in server response. +.IP "\fB\-send_error\fR" 4 +.IX Item "-send_error" +Force server to reply with error message. +.IP "\fB\-send_unprotected\fR" 4 +.IX Item "-send_unprotected" +Send response messages without CMP-level protection. +.IP "\fB\-send_unprot_err\fR" 4 +.IX Item "-send_unprot_err" +In case of negative responses, server shall send unprotected error messages, +certificate responses (\s-1IP/CP/KUP\s0), and revocation responses (\s-1RP\s0). +\&\s-1WARNING:\s0 This setting leads to behavior violating \s-1RFC 4210.\s0 +.IP "\fB\-accept_unprotected\fR" 4 +.IX Item "-accept_unprotected" +Accept missing or invalid protection of requests. +.IP "\fB\-accept_unprot_err\fR" 4 +.IX Item "-accept_unprot_err" +Accept unprotected error messages from client. +So far this has no effect because the server does not accept any error messages. +.IP "\fB\-accept_raverified\fR" 4 +.IX Item "-accept_raverified" +Accept \s-1RAVERIFED\s0 as proof of possession (\s-1POPO\s0). +.SS "Certificate verification options, for both \s-1CMP\s0 and \s-1TLS\s0" +.IX Subsection "Certificate verification options, for both CMP and TLS" +.IP "\fB\-allow_proxy_certs\fR, \fB\-attime\fR, \fB\-no_check_time\fR, \fB\-check_ss_sig\fR, \fB\-crl_check\fR, \fB\-crl_check_all\fR, \fB\-explicit_policy\fR, \fB\-extended_crl\fR, \fB\-ignore_critical\fR, \fB\-inhibit_any\fR, \fB\-inhibit_map\fR, \fB\-no_alt_chains\fR, \fB\-partial_chain\fR, \fB\-policy\fR, \fB\-policy_check\fR, \fB\-policy_print\fR, \fB\-purpose\fR, \fB\-suiteB_128\fR, \fB\-suiteB_128_only\fR, \fB\-suiteB_192\fR, \fB\-trusted_first\fR, \fB\-use_deltas\fR, \fB\-auth_level\fR, \fB\-verify_depth\fR, \fB\-verify_email\fR, \fB\-verify_hostname\fR, \fB\-verify_ip\fR, \fB\-verify_name\fR, \fB\-x509_strict\fR \fB\-issuer_checks\fR" 4 +.IX Item "-allow_proxy_certs, -attime, -no_check_time, -check_ss_sig, -crl_check, -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical, -inhibit_any, -inhibit_map, -no_alt_chains, -partial_chain, -policy, -policy_check, -policy_print, -purpose, -suiteB_128, -suiteB_128_only, -suiteB_192, -trusted_first, -use_deltas, -auth_level, -verify_depth, -verify_email, -verify_hostname, -verify_ip, -verify_name, -x509_strict -issuer_checks" +Set various options of certificate chain verification. +See \*(L"Verification Options\*(R" in \fBopenssl\-verification\-options\fR\|(1) for details. +.Sp +The certificate verification options +\&\fB\-verify_hostname\fR, \fB\-verify_ip\fR, and \fB\-verify_email\fR +only affect the certificate verification enabled via the \fB\-out_trusted\fR option. +.SH "NOTES" +.IX Header "NOTES" +When a client obtains from a \s-1CMP\s0 server \s-1CA\s0 certificates that it is going to +trust, for instance via the \f(CW\*(C`caPubs\*(C'\fR field of a certificate response, +authentication of the \s-1CMP\s0 server is particularly critical. +So special care must be taken setting up server authentication +using \fB\-trusted\fR and related options for certificate-based authentication +or \fB\-secret\fR for MAC-based protection. +.PP +When setting up \s-1CMP\s0 configurations and experimenting with enrollment options +typically various errors occur until the configuration is correct and complete. +When the \s-1CMP\s0 server reports an error the client will by default +check the protection of the \s-1CMP\s0 response message. +Yet some \s-1CMP\s0 services tend not to protect negative responses. +In this case the client will reject them, and thus their contents are not shown +although they usually contain hints that would be helpful for diagnostics. +For assisting in such cases the \s-1CMP\s0 client offers a workaround via the +\&\fB\-unprotected_errors\fR option, which allows accepting such negative messages. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.SS "Simple examples using the default OpenSSL configuration file" +.IX Subsection "Simple examples using the default OpenSSL configuration file" +This \s-1CMP\s0 client implementation comes with demonstrative \s-1CMP\s0 sections +in the example configuration file \fIopenssl/apps/openssl.cnf\fR, +which can be used to interact conveniently with the Insta Demo \s-1CA.\s0 +.PP +In order to enroll an initial certificate from that \s-1CA\s0 it is sufficient +to issue the following shell commands. +.PP +.Vb 1 +\& export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf +.Ve +.PP +.Vb 2 +\& openssl genrsa \-out insta.priv.pem +\& openssl cmp \-section insta +.Ve +.PP +This should produce the file \fIinsta.cert.pem\fR containing a new certificate +for the private key held in \fIinsta.priv.pem\fR. +It can be viewed using, e.g., +.PP +.Vb 1 +\& openssl x509 \-noout \-text \-in insta.cert.pem +.Ve +.PP +In case the network setup requires using an \s-1HTTP\s0 proxy it may be given as usual +via the environment variable \fBhttp_proxy\fR or via the \fB\-proxy\fR option in the +configuration file or the \s-1CMP\s0 command-line argument \fB\-proxy\fR, for example +.PP +.Vb 1 +\& \-proxy http://192.168.1.1:8080 +.Ve +.PP +In the Insta Demo \s-1CA\s0 scenario both clients and the server may use the pre-shared +secret \fIinsta\fR and the reference value \fI3078\fR to authenticate to each other. +.PP +Alternatively, \s-1CMP\s0 messages may be protected in signature-based manner, +where the trust anchor in this case is \fIinsta.ca.crt\fR +and the client may use any certificate already obtained from that \s-1CA,\s0 +as specified in the \fB[signature]\fR section of the example configuration. +This can be used in combination with the \fB[insta]\fR section simply by +.PP +.Vb 1 +\& openssl cmp \-section insta,signature +.Ve +.PP +By default the \s-1CMP IR\s0 message type is used, yet \s-1CR\s0 works equally here. +This may be specified directly at the command line: +.PP +.Vb 1 +\& openssl cmp \-section insta \-cmd cr +.Ve +.PP +or by referencing in addition the \fB[cr]\fR section of the example configuration: +.PP +.Vb 1 +\& openssl cmp \-section insta,cr +.Ve +.PP +In order to update the enrolled certificate one may call +.PP +.Vb 1 +\& openssl cmp \-section insta,kur +.Ve +.PP +using MAC-based protection with \s-1PBM\s0 or +.PP +.Vb 1 +\& openssl cmp \-section insta,kur,signature +.Ve +.PP +using signature-based protection. +.PP +In a similar way any previously enrolled certificate may be revoked by +.PP +.Vb 1 +\& openssl cmp \-section insta,rr \-trusted insta.ca.crt +.Ve +.PP +or +.PP +.Vb 1 +\& openssl cmp \-section insta,rr,signature +.Ve +.PP +Many more options can be given in the configuration file +and/or on the command line. +For instance, the \fB\-reqexts\fR \s-1CLI\s0 option may refer to a section in the +configuration file defining X.509 extensions to use in certificate requests, +such as \f(CW\*(C`v3_req\*(C'\fR in \fIopenssl/apps/openssl.cnf\fR: +.PP +.Vb 1 +\& openssl cmp \-section insta,cr \-reqexts v3_req +.Ve +.SS "Certificate enrollment" +.IX Subsection "Certificate enrollment" +The following examples do not make use of a configuration file at first. +They assume that a \s-1CMP\s0 server can be contacted on the local \s-1TCP\s0 port 80 +and accepts requests under the alias \fI/pkix/\fR. +.PP +For enrolling its very first certificate the client generates a client key +and sends an initial request message to the local \s-1CMP\s0 server +using a pre-shared secret key for mutual authentication. +In this example the client does not have the \s-1CA\s0 certificate yet, +so we specify the name of the \s-1CA\s0 with the \fB\-recipient\fR option +and save any \s-1CA\s0 certificates that we may receive in the \f(CW\*(C`capubs.pem\*(C'\fR file. +.PP +In below command line usage examples the \f(CW\*(C`\e\*(C'\fR at line ends is used just +for formatting; each of the command invocations should be on a single line. +.PP +.Vb 5 +\& openssl genrsa \-out cl_key.pem +\& openssl cmp \-cmd ir \-server 127.0.0.1:80/pkix/ \-recipient "/CN=CMPserver" \e +\& \-ref 1234 \-secret pass:1234\-5678 \e +\& \-newkey cl_key.pem \-subject "/CN=MyName" \e +\& \-cacertsout capubs.pem \-certout cl_cert.pem +.Ve +.SS "Certificate update" +.IX Subsection "Certificate update" +Then, when the client certificate and its related key pair needs to be updated, +the client can send a key update request taking the certs in \f(CW\*(C`capubs.pem\*(C'\fR +as trusted for authenticating the server and using the previous cert and key +for its own authentication. +Then it can start using the new cert and key. +.PP +.Vb 6 +\& openssl genrsa \-out cl_key_new.pem +\& openssl cmp \-cmd kur \-server 127.0.0.1:80/pkix/ \e +\& \-trusted capubs.pem \e +\& \-cert cl_cert.pem \-key cl_key.pem \e +\& \-newkey cl_key_new.pem \-certout cl_cert.pem +\& cp cl_key_new.pem cl_key.pem +.Ve +.PP +This command sequence can be repeated as often as needed. +.SS "Requesting information from \s-1CMP\s0 server" +.IX Subsection "Requesting information from CMP server" +Requesting \*(L"all relevant information\*(R" with an empty General Message. +This prints information about all received \s-1ITAV\s0 \fBinfoType\fRs to stdout. +.PP +.Vb 2 +\& openssl cmp \-cmd genm \-server 127.0.0.1/pkix/ \-recipient "/CN=CMPserver" \e +\& \-ref 1234 \-secret pass:1234\-5678 +.Ve +.SS "Using a custom configuration file" +.IX Subsection "Using a custom configuration file" +For \s-1CMP\s0 client invocations, in particular for certificate enrollment, +usually many parameters need to be set, which is tedious and error-prone to do +on the command line. +Therefore, the client offers the possibility to read +options from sections of the OpenSSL config file, usually called \fIopenssl.cnf\fR. +The values found there can still be extended and even overridden by any +subsequently loaded sections and on the command line. +.PP +After including in the configuration file the following sections: +.PP +.Vb 8 +\& [cmp] +\& server = 127.0.0.1 +\& path = pkix/ +\& trusted = capubs.pem +\& cert = cl_cert.pem +\& key = cl_key.pem +\& newkey = cl_key.pem +\& certout = cl_cert.pem +\& +\& [init] +\& recipient = "/CN=CMPserver" +\& trusted = +\& cert = +\& key = +\& ref = 1234 +\& secret = pass:1234\-5678\-1234\-567 +\& subject = "/CN=MyName" +\& cacertsout = capubs.pem +.Ve +.PP +the above enrollment transactions reduce to +.PP +.Vb 2 +\& openssl cmp \-section cmp,init +\& openssl cmp \-cmd kur \-newkey cl_key_new.pem +.Ve +.PP +and the above transaction using a general message reduces to +.PP +.Vb 1 +\& openssl cmp \-section cmp,init \-cmd genm +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-genrsa\fR\|(1), \fBopenssl\-ecparam\fR\|(1), \fBopenssl\-list\fR\|(1), +\&\fBopenssl\-req\fR\|(1), \fBopenssl\-x509\fR\|(1), \fBx509v3_config\fR\|(5) +.SH "HISTORY" +.IX Header "HISTORY" +The \fBcmp\fR application was added in OpenSSL 3.0. +.PP +The \fB\-engine option\fR was deprecated in OpenSSL 3.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2007\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |