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