1OPENSSL-CMP(1ossl)                  OpenSSL                 OPENSSL-CMP(1ossl)
2
3
4

NAME

6       openssl-cmp - Certificate Management Protocol (CMP, RFC 4210)
7       application
8

SYNOPSIS

10       openssl cmp [-help] [-config filename] [-section names] [-verbosity
11       level]
12
13       Generic message options:
14
15       [-cmd ir|cr|kur|p10cr|rr|genm] [-infotype name] [-geninfo OID:int:N]
16
17       Certificate enrollment options:
18
19       [-newkey filename|uri] [-newkeypass arg] [-subject name] [-issuer name]
20       [-days number] [-reqexts name] [-sans spec] [-san_nodefault] [-policies
21       name] [-policy_oids names] [-policy_oids_critical] [-popo number] [-csr
22       filename] [-out_trusted filenames|uris] [-implicit_confirm]
23       [-disable_confirm] [-certout filename] [-chainout filename]
24
25       Certificate enrollment and revocation options:
26
27       [-oldcert filename|uri] [-revreason number]
28
29       Message transfer options:
30
31       [-server [http[s]://][userinfo@]host[:port][/path][?query][#fragment]]
32       [-proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]]
33       [-no_proxy addresses] [-recipient name] [-path remote_path]
34       [-keep_alive value] [-msg_timeout seconds] [-total_timeout seconds]
35
36       Server authentication options:
37
38       [-trusted filenames|uris] [-untrusted filenames|uris] [-srvcert
39       filename|uri] [-expect_sender name] [-ignore_keyusage]
40       [-unprotected_errors] [-extracertsout filename] [-cacertsout filename]
41
42       Client authentication and protection options:
43
44       [-ref value] [-secret arg] [-cert filename|uri] [-own_trusted
45       filenames|uris] [-key filename|uri] [-keypass arg] [-digest name] [-mac
46       name] [-extracerts filenames|uris] [-unprotected_requests]
47
48       Credentials format options:
49
50       [-certform PEM|DER] [-keyform PEM|DER|P12|ENGINE] [-otherpass arg]
51       [-engine id] [-provider name] [-provider-path path] [-propquery propq]
52
53       Random state options:
54
55       [-rand files] [-writerand file]
56
57       TLS connection options:
58
59       [-tls_used] [-tls_cert filename|uri] [-tls_key filename|uri]
60       [-tls_keypass arg] [-tls_extra filenames|uris] [-tls_trusted
61       filenames|uris] [-tls_host name]
62
63       Client-side debugging options:
64
65       [-batch] [-repeat number] [-reqin filenames] [-reqin_new_tid] [-reqout
66       filenames] [-rspin filenames] [-rspout filenames] [-use_mock_srv]
67
68       Mock server options:
69
70       [-port number] [-max_msgs number] [-srv_ref value] [-srv_secret arg]
71       [-srv_cert filename|uri] [-srv_key filename|uri] [-srv_keypass arg]
72       [-srv_trusted filenames|uris] [-srv_untrusted filenames|uris]
73       [-rsp_cert filename|uri] [-rsp_extracerts filenames|uris] [-rsp_capubs
74       filenames|uris] [-poll_count number] [-check_after number]
75       [-grant_implicitconf] [-pkistatus number] [-failure number]
76       [-failurebits number] [-statusstring arg] [-send_error]
77       [-send_unprotected] [-send_unprot_err] [-accept_unprotected]
78       [-accept_unprot_err] [-accept_raverified]
79
80       Certificate verification options, for both CMP and TLS:
81
82       [-allow_proxy_certs] [-attime timestamp] [-no_check_time]
83       [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy]
84       [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map]
85       [-partial_chain] [-policy arg] [-policy_check] [-policy_print]
86       [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192]
87       [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num]
88       [-verify_depth num] [-verify_email email] [-verify_hostname hostname]
89       [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]
90

DESCRIPTION

92       The cmp command is a client implementation for the Certificate
93       Management Protocol (CMP) as defined in RFC4210.  It can be used to
94       request certificates from a CA server, update their certificates,
95       request certificates to be revoked, and perform other types of CMP
96       requests.
97

OPTIONS

99       -help
100           Display a summary of all options
101
102       -config filename
103           Configuration file to use.  An empty string "" means none.  Default
104           filename is from the environment variable "OPENSSL_CONF".
105
106       -section names
107           Section(s) to use within config file defining CMP options.  An
108           empty string "" means no specific section.  Default is "cmp".
109
110           Multiple section names may be given, separated by commas and/or
111           whitespace (where in the latter case the whole argument must be
112           enclosed in "...").  Contents of sections named later may override
113           contents of sections named before.  In any case, as usual, the
114           "[default]" section and finally the unnamed section (as far as
115           present) can provide per-option fallback values.
116
117       -verbosity level
118           Level of verbosity for logging, error output, etc.  0 = EMERG, 1 =
119           ALERT, 2 = CRIT, 3 = ERR, 4 = WARN, 5 = NOTE, 6 = INFO, 7 = DEBUG,
120           8 = TRACE.  Defaults to 6 = INFO.
121
122   Generic message options
123       -cmd ir|cr|kur|p10cr|rr|genm
124           CMP command to execute.  Currently implemented commands are:
125
126           ir    - Initialization Request
127           cr    - Certificate Request
128           p10cr - PKCS#10 Certification Request (for legacy support)
129           kur   - Key Update Request
130           rr    - Revocation Request
131           genm  - General Message
132
133           ir requests initialization of an end entity into a PKI hierarchy by
134           issuing a first certificate.
135
136           cr requests issuing an additional certificate for an end entity
137           already initialized to the PKI hierarchy.
138
139           p10cr requests issuing an additional certificate similarly to cr
140           but using legacy PKCS#10 CSR format.
141
142           kur requests a (key) update for an existing certificate.
143
144           rr requests revocation of an existing certificate.
145
146           genm requests information using a General Message, where optionally
147           included InfoTypeAndValues may be used to state which info is of
148           interest.  Upon receipt of the General Response, information about
149           all received ITAV infoTypes is printed to stdout.
150
151       -infotype name
152           Set InfoType name to use for requesting specific info in genm,
153           e.g., "signKeyPairTypes".
154
155       -geninfo OID:int:N
156           generalInfo integer values to place in request PKIHeader with given
157           OID, e.g., "1.2.3.4:int:56789".
158
159   Certificate enrollment options
160       -newkey filename|uri
161           The source of the private or public key for the certificate being
162           requested.  Defaults to the public key in the PKCS#10 CSR given
163           with the -csr option, the public key of the reference certificate,
164           or the current client key.
165
166           The public portion of the key is placed in the certification
167           request.
168
169           Unless -cmd p10cr, -popo -1, or -popo 0 is given, the private key
170           will be needed as well to provide the proof of possession (POPO),
171           where the -key option may provide a fallback.
172
173       -newkeypass arg
174           Pass phrase source for the key given with the -newkey option.  If
175           not given here, the password will be prompted for if needed.
176
177           For more information about the format of arg see
178           openssl-passphrase-options(1).
179
180       -subject name
181           X509 Distinguished Name (DN) of subject to use in the requested
182           certificate template.  If the NULL-DN ("/") is given then no
183           subject is placed in the template.  Default is the subject DN of
184           any PKCS#10 CSR given with the -csr option.  For KUR, a further
185           fallback is the subject DN of the reference certificate (see
186           -oldcert) if provided.  This fallback is used for IR and CR only if
187           no SANs are set.
188
189           If provided and neither -cert nor -oldcert is given, the subject DN
190           is used as fallback sender of outgoing CMP messages.
191
192           The argument must be formatted as
193           /type0=value0/type1=value1/type2=....  Special characters may be
194           escaped by "\" (backslash); whitespace is retained.  Empty values
195           are permitted, but the corresponding type will not be included.
196           Giving a single "/" will lead to an empty sequence of RDNs (a NULL-
197           DN).  Multi-valued RDNs can be formed by placing a "+" character
198           instead of a "/" between the AttributeValueAssertions (AVAs) that
199           specify the members of the set.  Example:
200
201           "/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe"
202
203       -issuer name
204           X509 issuer Distinguished Name (DN) of the CA server to place in
205           the requested certificate template in IR/CR/KUR.  If the NULL-DN
206           ("/") is given then no issuer is placed in the template.
207
208           If provided and neither -recipient nor -srvcert is given, the
209           issuer DN is used as fallback recipient of outgoing CMP messages.
210
211           The argument must be formatted as
212           /type0=value0/type1=value1/type2=....  For details see the
213           description of the -subject option.
214
215       -days number
216           Number of days the new certificate is requested to be valid for,
217           counting from the current time of the host.  Also triggers the
218           explicit request that the validity period starts from the current
219           time (as seen by the host).
220
221       -reqexts name
222           Name of section in OpenSSL config file defining certificate request
223           extensions.  If the -csr option is present, these extensions
224           augment the extensions contained the given PKCS#10 CSR, overriding
225           any extensions with same OIDs.
226
227       -sans spec
228           One or more IP addresses, DNS names, or URIs separated by commas or
229           whitespace (where in the latter case the whole argument must be
230           enclosed in "...")  to add as Subject Alternative Name(s) (SAN)
231           certificate request extension.  If the special element "critical"
232           is given the SANs are flagged as critical.  Cannot be used if any
233           Subject Alternative Name extension is set via -reqexts.
234
235       -san_nodefault
236           When Subject Alternative Names are not given via -sans nor defined
237           via -reqexts, they are copied by default from the reference
238           certificate (see -oldcert).  This can be disabled by giving the
239           -san_nodefault option.
240
241       -policies name
242           Name of section in OpenSSL config file defining policies to be set
243           as certificate request extension.  This option cannot be used
244           together with -policy_oids.
245
246       -policy_oids names
247           One or more OID(s), separated by commas and/or whitespace (where in
248           the latter case the whole argument must be enclosed in "...")  to
249           add as certificate policies request extension.  This option cannot
250           be used together with -policies.
251
252       -policy_oids_critical
253           Flag the policies given with -policy_oids as critical.
254
255       -popo number
256           Proof-of-possession (POPO) method to use for IR/CR/KUR; values:
257           -1..<2> where -1 = NONE, 0 = RAVERIFIED, 1 = SIGNATURE (default), 2
258           = KEYENC.
259
260           Note that a signature-based POPO can only be produced if a private
261           key is provided via the -newkey or -key options.
262
263       -csr filename
264           PKCS#10 CSR in PEM or DER format containing a certificate request.
265           With -cmd p10cr it is used directly in a legacy P10CR message.
266
267           When used with -cmd ir, cr, or kur, it is transformed into the
268           respective regular CMP request.  In this case, a private key must
269           be provided (with -newkey or -key) for the proof of possession
270           (unless -popo -1 or -popo 0 is used) and the respective public key
271           is placed in the certification request (rather than taking over the
272           public key contained in the PKCS#10 CSR).
273
274           PKCS#10 CSR input may also be used with -cmd rr to specify the
275           certificate to be revoked via the included subject name and public
276           key.
277
278       -out_trusted filenames|uris
279           Trusted certificate(s) to use for validating the newly enrolled
280           certificate.  During this verification, any certificate status
281           checking is disabled.
282
283           Multiple sources may be given, separated by commas and/or
284           whitespace (where in the latter case the whole argument must be
285           enclosed in "...").  Each source may contain multiple certificates.
286
287           The certificate verification options -verify_hostname, -verify_ip,
288           and -verify_email only affect the certificate verification enabled
289           via this option.
290
291       -implicit_confirm
292           Request implicit confirmation of newly enrolled certificates.
293
294       -disable_confirm
295           Do not send certificate confirmation message for newly enrolled
296           certificate without requesting implicit confirmation to cope with
297           broken servers not supporting implicit confirmation correctly.
298           WARNING: This leads to behavior violating RFC 4210.
299
300       -certout filename
301           The file where the newly enrolled certificate should be saved.
302
303       -chainout filename
304           The file where the chain of the newly enrolled certificate should
305           be saved.
306
307   Certificate enrollment and revocation options
308       -oldcert filename|uri
309           The certificate to be updated (i.e., renewed or re-keyed) in Key
310           Update Request (KUR) messages or to be revoked in Revocation
311           Request (RR) messages.  For KUR the certificate to be updated
312           defaults to -cert, and the resulting certificate is called
313           reference certificate.  For RR the certificate to be revoked can
314           also be specified using -csr.
315
316           The reference certificate, if any, is also used for deriving
317           default subject DN and Subject Alternative Names and the default
318           issuer entry in the requested certificate template of an IR/CR/KUR.
319           Its public key is used as a fallback in the template of
320           certification requests.  Its subject is used as sender of outgoing
321           messages if -cert is not given.  Its issuer is used as default
322           recipient in CMP message headers if neither -recipient, -srvcert,
323           nor -issuer is given.
324
325       -revreason number
326           Set CRLReason to be included in revocation request (RR); values:
327           0..10 or -1 for none (which is the default).
328
329           Reason numbers defined in RFC 5280 are:
330
331              CRLReason ::= ENUMERATED {
332                   unspecified             (0),
333                   keyCompromise           (1),
334                   cACompromise            (2),
335                   affiliationChanged      (3),
336                   superseded              (4),
337                   cessationOfOperation    (5),
338                   certificateHold         (6),
339                   -- value 7 is not used
340                   removeFromCRL           (8),
341                   privilegeWithdrawn      (9),
342                   aACompromise           (10)
343               }
344
345   Message transfer options
346       -server [http[s]://][userinfo@]host[:port][/path][?query][#fragment]
347           The DNS hostname or IP address and optionally port of the CMP
348           server to connect to using HTTP(S).  This option excludes -port and
349           -use_mock_srv.  It is ignored if -rspin is given with enough
350           filename arguments.
351
352           The scheme "https" may be given only if the -tls_used option is
353           used.  In this case the default port is 443, else 80.  The optional
354           userinfo and fragment components are ignored.  Any given query
355           component is handled as part of the path component.  If a path is
356           included it provides the default value for the -path option.
357
358       -proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]
359           The HTTP(S) proxy server to use for reaching the CMP server unless
360           -no_proxy applies, see below.  The proxy port defaults to 80 or 443
361           if the scheme is "https"; apart from that the optional "http://" or
362           "https://" prefix is ignored (note that TLS may be selected by
363           -tls_used), as well as any path, userinfo, and query, and fragment
364           components.  Defaults to the environment variable "http_proxy" if
365           set, else "HTTP_PROXY" in case no TLS is used, otherwise
366           "https_proxy" if set, else "HTTPS_PROXY".  This option is ignored
367           if -server is not given.
368
369       -no_proxy addresses
370           List of IP addresses and/or DNS names of servers not to use an
371           HTTP(S) proxy for, separated by commas and/or whitespace (where in
372           the latter case the whole argument must be enclosed in "...").
373           Default is from the environment variable "no_proxy" if set, else
374           "NO_PROXY".  This option is ignored if -server is not given.
375
376       -recipient name
377           Distinguished Name (DN) to use in the recipient field of CMP
378           request message headers, i.e., the CMP server (usually the
379           addressed CA).
380
381           The recipient field in the header of a CMP message is mandatory.
382           If not given explicitly the recipient is determined in the
383           following order: the subject of the CMP server certificate given
384           with the -srvcert option, the -issuer option, the issuer of the
385           certificate given with the -oldcert option, the issuer of the CMP
386           client certificate (-cert option), as far as any of those is
387           present, else the NULL-DN as last resort.
388
389           The argument must be formatted as
390           /type0=value0/type1=value1/type2=....  For details see the
391           description of the -subject option.
392
393       -path remote_path
394           HTTP path at the CMP server (aka CMP alias) to use for POST
395           requests.  Defaults to any path given with -server, else "/".
396
397       -keep_alive value
398           If the given value is 0 then HTTP connections are not kept open
399           after receiving a response, which is the default behavior for HTTP
400           1.0.  If the value is 1 or 2 then persistent connections are
401           requested.  If the value is 2 then persistent connections are
402           required, i.e., in case the server does not grant them an error
403           occurs.  The default value is 1, which means preferring to keep the
404           connection open.
405
406       -msg_timeout seconds
407           Number of seconds a CMP request-response message round trip is
408           allowed to take before a timeout error is returned.  A value <= 0
409           means no limitation (waiting indefinitely).  Default is to use the
410           -total_timeout setting.
411
412       -total_timeout seconds
413           Maximum total number of seconds a transaction may take, including
414           polling etc.  A value <= 0 means no limitation (waiting
415           indefinitely).  Default is 0.
416
417   Server authentication options
418       -trusted filenames|uris
419           The certificate(s), typically of root CAs, the client shall use as
420           trust anchors when validating signature-based protection of CMP
421           response messages.  This option is ignored if the -srvcert option
422           is given as well.  It provides more flexibility than -srvcert
423           because the CMP protection certificate of the server is not pinned
424           but may be any certificate from which a chain to one of the given
425           trust anchors can be constructed.
426
427           If none of -trusted, -srvcert, and -secret is given, message
428           validation errors will be thrown unless -unprotected_errors permits
429           an exception.
430
431           Multiple sources may be given, separated by commas and/or
432           whitespace (where in the latter case the whole argument must be
433           enclosed in "...").  Each source may contain multiple certificates.
434
435           The certificate verification options -verify_hostname, -verify_ip,
436           and -verify_email have no effect on the certificate verification
437           enabled via this option.
438
439       -untrusted filenames|uris
440           Non-trusted intermediate CA certificate(s).  Any extra certificates
441           given with the -cert option are appended to it.  All these
442           certificates may be useful for cert path construction for the own
443           CMP signer certificate (to include in the extraCerts field of
444           request messages) and for the TLS client certificate (if TLS is
445           enabled) as well as for chain building when validating server
446           certificates (checking signature-based CMP message protection) and
447           when validating newly enrolled certificates.
448
449           Multiple filenames or URLs may be given, separated by commas and/or
450           whitespace.  Each source may contain multiple certificates.
451
452       -srvcert filename|uri
453           The specific CMP server certificate to expect and directly trust
454           (even if it is expired) when verifying signature-based protection
455           of CMP response messages.  This pins the accepted server and
456           results in ignoring the -trusted option.
457
458           If set, the subject of the certificate is also used as default
459           value for the recipient of CMP requests and as default value for
460           the expected sender of CMP responses.
461
462       -expect_sender name
463           Distinguished Name (DN) expected in the sender field of incoming
464           CMP messages.  Defaults to the subject DN of the pinned -srvcert,
465           if any.
466
467           This can be used to make sure that only a particular entity is
468           accepted as CMP message signer, and attackers are not able to use
469           arbitrary certificates of a trusted PKI hierarchy to fraudulently
470           pose as a CMP server.  Note that this option gives slightly more
471           freedom than setting the -srvcert, which pins the server to the
472           holder of a particular certificate, while the expected sender name
473           will continue to match after updates of the server cert.
474
475           The argument must be formatted as
476           /type0=value0/type1=value1/type2=....  For details see the
477           description of the -subject option.
478
479       -ignore_keyusage
480           Ignore key usage restrictions in CMP signer certificates when
481           validating signature-based protection of incoming CMP messages.  By
482           default, "digitalSignature" must be allowed by CMP signer
483           certificates.
484
485       -unprotected_errors
486           Accept missing or invalid protection of negative responses from the
487           server.  This applies to the following message types and contents:
488
489           •   error messages
490
491           •   negative certificate responses (IP/CP/KUP)
492
493           •   negative revocation responses (RP)
494
495           •   negative PKIConf messages
496
497           WARNING: This setting leads to unspecified behavior and it is meant
498           exclusively to allow interoperability with server implementations
499           violating RFC 4210, e.g.:
500
501           •   section 5.1.3.1 allows exceptions from protecting only for
502               special cases: "There MAY be cases in which the PKIProtection
503               BIT STRING is deliberately not used to protect a message [...]
504               because other protection, external to PKIX, will be applied
505               instead."
506
507           •   section 5.3.21 is clear on ErrMsgContent: "The CA MUST always
508               sign it with a signature key."
509
510           •   appendix D.4 shows PKIConf message having protection
511
512       -extracertsout filename
513           The file where to save all certificates contained in the extraCerts
514           field of the last received response message (except for pollRep and
515           PKIConf).
516
517       -cacertsout filename
518           The file where to save any CA certificates contained in the caPubs
519           field of the last received certificate response (i.e., IP, CP, or
520           KUP) message.
521
522   Client authentication options
523       -ref value
524           Reference number/string/value to use as fallback senderKID; this is
525           required if no sender name can be determined from the -cert or
526           <-subject> options and is typically used when authenticating with
527           pre-shared key (password-based MAC).
528
529       -secret arg
530           Prefer PBM-based message protection with given source of a secret
531           value.  The secret is used for creating PBM-based protection of
532           outgoing messages and (as far as needed) for validating PBM-based
533           protection of incoming messages.  PBM stands for Password-Based
534           Message Authentication Code.  This takes precedence over the -cert
535           and -key options.
536
537           For more information about the format of arg see
538           openssl-passphrase-options(1).
539
540       -cert filename|uri
541           The client's current CMP signer certificate.  Requires the
542           corresponding key to be given with -key.
543
544           The subject and the public key contained in this certificate serve
545           as fallback values in the certificate template of IR/CR/KUR
546           messages.
547
548           The subject of this certificate will be used as sender of outgoing
549           CMP messages, while the subject of -oldcert or -subjectName may
550           provide fallback values.
551
552           The issuer of this certificate is used as one of the recipient
553           fallback values and as fallback issuer entry in the certificate
554           template of IR/CR/KUR messages.
555
556           When using signature-based message protection, this "protection
557           certificate" will be included first in the extraCerts field of
558           outgoing messages and the signature is done with the corresponding
559           key.  In Initialization Request (IR) messages this can be used for
560           authenticating using an external entity certificate as defined in
561           appendix E.7 of RFC 4210.
562
563           For Key Update Request (KUR) messages this is also used as the
564           certificate to be updated if the -oldcert option is not given.
565
566           If the file includes further certs, they are appended to the
567           untrusted certs because they typically constitute the chain of the
568           client certificate, which is included in the extraCerts field in
569           signature-protected request messages.
570
571       -own_trusted filenames|uris
572           If this list of certificates is provided then the chain built for
573           the client-side CMP signer certificate given with the -cert option
574           is verified using the given certificates as trust anchors.
575
576           Multiple sources may be given, separated by commas and/or
577           whitespace (where in the latter case the whole argument must be
578           enclosed in "...").  Each source may contain multiple certificates.
579
580           The certificate verification options -verify_hostname, -verify_ip,
581           and -verify_email have no effect on the certificate verification
582           enabled via this option.
583
584       -key filename|uri
585           The corresponding private key file for the client's current
586           certificate given in the -cert option.  This will be used for
587           signature-based message protection unless the -secret option
588           indicating PBM or -unprotected_requests is given.
589
590           It is also used as a fallback for the -newkey option with IR/CR/KUR
591           messages.
592
593       -keypass arg
594           Pass phrase source for the private key given with the -key option.
595           Also used for -cert and -oldcert in case it is an encrypted PKCS#12
596           file.  If not given here, the password will be prompted for if
597           needed.
598
599           For more information about the format of arg see
600           openssl-passphrase-options(1).
601
602       -digest name
603           Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG
604           and as the one-way function (OWF) in MSG_MAC_ALG.  If applicable,
605           this is used for message protection and proof-of-possession (POPO)
606           signatures.  To see the list of supported digests, use "openssl
607           list -digest-commands".  Defaults to "sha256".
608
609       -mac name
610           Specifies the name of the MAC algorithm in MSG_MAC_ALG.  To get the
611           names of supported MAC algorithms use "openssl list
612           -mac-algorithms" and possibly combine such a name with the name of
613           a supported digest algorithm, e.g., hmacWithSHA256.  Defaults to
614           "hmac-sha1" as per RFC 4210.
615
616       -extracerts filenames|uris
617           Certificates to append in the extraCerts field when sending
618           messages.  They can be used as the default CMP signer certificate
619           chain to include.
620
621           Multiple sources may be given, separated by commas and/or
622           whitespace (where in the latter case the whole argument must be
623           enclosed in "...").  Each source may contain multiple certificates.
624
625       -unprotected_requests
626           Send request messages without CMP-level protection.
627
628   Credentials format options
629       -certform PEM|DER
630           File format to use when saving a certificate to a file.  Default
631           value is PEM.
632
633       -keyform PEM|DER|P12|ENGINE
634           The format of the key input; unspecified by default.  See "Format
635           Options" in openssl(1) for details.
636
637       -otherpass arg
638           Pass phrase source for certificate given with the -trusted,
639           -untrusted, -own_trusted, -srvcert, -out_trusted, -extracerts,
640           -srv_trusted, -srv_untrusted, -rsp_extracerts, -rsp_capubs,
641           -tls_extra, and -tls_trusted options.  If not given here, the
642           password will be prompted for if needed.
643
644           For more information about the format of arg see
645           openssl-passphrase-options(1).
646
647       -engine id
648           See "Engine Options" in openssl(1).  This option is deprecated.
649
650           As an alternative to using this combination:
651
652               -engine {engineid} -key {keyid} -keyform ENGINE
653
654           ... it's also possible to just give the key ID in URI form to -key,
655           like this:
656
657               -key org.openssl.engine:{engineid}:{keyid}
658
659           This applies to all options specifying keys: -key, -newkey, and
660           -tls_key.
661
662   Provider options
663       -provider name
664       -provider-path path
665       -propquery propq
666           See "Provider Options" in openssl(1), provider(7), and property(7).
667
668   Random state options
669       -rand files, -writerand file
670           See "Random State Options" in openssl(1) for details.
671
672   TLS connection options
673       -tls_used
674           Enable using TLS (even when other TLS-related options are not set)
675           for message exchange with CMP server via HTTP.  This option is not
676           supported with the -port option.  It is ignored if the -server
677           option is not given or -use_mock_srv is given or -rspin is given
678           with enough filename arguments.
679
680           The following TLS-related options are ignored if -tls_used is not
681           given or does not take effect.
682
683       -tls_cert filename|uri
684           Client's TLS certificate.  If the source includes further certs
685           they are used (along with -untrusted certs) for constructing the
686           client cert chain provided to the TLS server.
687
688       -tls_key filename|uri
689           Private key for the client's TLS certificate.
690
691       -tls_keypass arg
692           Pass phrase source for client's private TLS key -tls_key.  Also
693           used for -tls_cert in case it is an encrypted PKCS#12 file.  If not
694           given here, the password will be prompted for if needed.
695
696           For more information about the format of arg see
697           openssl-passphrase-options(1).
698
699       -tls_extra filenames|uris
700           Extra certificates to provide to TLS server during TLS handshake
701
702       -tls_trusted filenames|uris
703           Trusted certificate(s) to use for validating the TLS server
704           certificate.  This implies hostname validation.
705
706           Multiple sources may be given, separated by commas and/or
707           whitespace (where in the latter case the whole argument must be
708           enclosed in "...").  Each source may contain multiple certificates.
709
710           The certificate verification options -verify_hostname, -verify_ip,
711           and -verify_email have no effect on the certificate verification
712           enabled via this option.
713
714       -tls_host name
715           Address to be checked during hostname validation.  This may be a
716           DNS name or an IP address.  If not given it defaults to the -server
717           address.
718
719   Client-side debugging options
720       -batch
721           Do not interactively prompt for input, for instance when a password
722           is needed.  This can be useful for batch processing and testing.
723
724       -repeat number
725           Invoke the command the given positive number of times with the same
726           parameters.  Default is one invocation.
727
728       -reqin filenames
729           Take the sequence of CMP requests to send to the server from the
730           given file(s) rather than from the sequence of requests produced
731           internally.
732
733           This option is ignored if the -rspin option is given because in the
734           latter case no requests are actually sent.
735
736           Multiple filenames may be given, separated by commas and/or
737           whitespace (where in the latter case the whole argument must be
738           enclosed in "...").
739
740           The files are read as far as needed to complete the transaction and
741           filenames have been provided.  If more requests are needed, the
742           remaining ones are taken from the items at the respective position
743           in the sequence of requests produced internally.
744
745           The client needs to update the recipNonce field in the given
746           requests (except for the first one) in order to satisfy the checks
747           to be performed by the server.  This causes re-protection (if
748           protecting requests is required).
749
750       -reqin_new_tid
751           Use a fresh transactionID for CMP request messages read using
752           -reqin, which causes their reprotection (if protecting requests is
753           required).  This may be needed in case the sequence of requests is
754           reused and the CMP server complains that the transaction ID has
755           already been used.
756
757       -reqout filenames
758           Save the sequence of CMP requests created by the client to the
759           given file(s).  These requests are not sent to the server if the
760           -reqin option is used, too.
761
762           Multiple filenames may be given, separated by commas and/or
763           whitespace.
764
765           Files are written as far as needed to save the transaction and
766           filenames have been provided.  If the transaction contains more
767           requests, the remaining ones are not saved.
768
769       -rspin filenames
770           Process the sequence of CMP responses provided in the given
771           file(s), not contacting any given server, as long as enough
772           filenames are provided to complete the transaction.
773
774           Multiple filenames may be given, separated by commas and/or
775           whitespace.
776
777           Any server specified via the -server or -use_mock_srv options is
778           contacted only if more responses are needed to complete the
779           transaction.  In this case the transaction will fail unless the
780           server has been prepared to continue the already started
781           transaction.
782
783       -rspout filenames
784           Save the sequence of actually used CMP responses to the given
785           file(s).  These have been received from the server unless -rspin
786           takes effect.
787
788           Multiple filenames may be given, separated by commas and/or
789           whitespace.
790
791           Files are written as far as needed to save the responses contained
792           in the transaction and filenames have been provided.  If the
793           transaction contains more responses, the remaining ones are not
794           saved.
795
796       -use_mock_srv
797           Test the client using the internal CMP server mock-up at API level,
798           bypassing socket-based transfer via HTTP.  This excludes the
799           -server and -port options.
800
801   Mock server options
802       -port number
803           Act as HTTP-based CMP server mock-up listening on the given port.
804           This excludes the -server and -use_mock_srv options.  The -rspin,
805           -rspout, -reqin, and -reqout options so far are not supported in
806           this mode.
807
808       -max_msgs number
809           Maximum number of CMP (request) messages the CMP HTTP server mock-
810           up should handle, which must be nonnegative.  The default value is
811           0, which means that no limit is imposed.  In any case the server
812           terminates on internal errors, but not when it detects a CMP-level
813           error that it can successfully answer with an error message.
814
815       -srv_ref value
816           Reference value to use as senderKID of server in case no -srv_cert
817           is given.
818
819       -srv_secret arg
820           Password source for server authentication with a pre-shared key
821           (secret).
822
823       -srv_cert filename|uri
824           Certificate of the server.
825
826       -srv_key filename|uri
827           Private key used by the server for signing messages.
828
829       -srv_keypass arg
830           Server private key (and cert) file pass phrase source.
831
832       -srv_trusted filenames|uris
833           Trusted certificates for client authentication.
834
835           The certificate verification options -verify_hostname, -verify_ip,
836           and -verify_email have no effect on the certificate verification
837           enabled via this option.
838
839       -srv_untrusted filenames|uris
840           Intermediate CA certs that may be useful when validating client
841           certificates.
842
843       -rsp_cert filename|uri
844           Certificate to be returned as mock enrollment result.
845
846       -rsp_extracerts filenames|uris
847           Extra certificates to be included in mock certification responses.
848
849       -rsp_capubs filenames|uris
850           CA certificates to be included in mock Initialization Response (IP)
851           message.
852
853       -poll_count number
854           Number of times the client must poll before receiving a
855           certificate.
856
857       -check_after number
858           The checkAfter value (number of seconds to wait) to include in poll
859           response.
860
861       -grant_implicitconf
862           Grant implicit confirmation of newly enrolled certificate.
863
864       -pkistatus number
865           PKIStatus to be included in server response.  Valid range is 0
866           (accepted) .. 6 (keyUpdateWarning).
867
868       -failure number
869           A single failure info bit number to be included in server response.
870           Valid range is 0 (badAlg) .. 26 (duplicateCertReq).
871
872       -failurebits number Number representing failure bits to be included in
873       server response. Valid range is 0 .. 2^27 - 1.
874       -statusstring arg
875           Text to be included as status string in server response.
876
877       -send_error
878           Force server to reply with error message.
879
880       -send_unprotected
881           Send response messages without CMP-level protection.
882
883       -send_unprot_err
884           In case of negative responses, server shall send unprotected error
885           messages, certificate responses (IP/CP/KUP), and revocation
886           responses (RP).  WARNING: This setting leads to behavior violating
887           RFC 4210.
888
889       -accept_unprotected
890           Accept missing or invalid protection of requests.
891
892       -accept_unprot_err
893           Accept unprotected error messages from client.  So far this has no
894           effect because the server does not accept any error messages.
895
896       -accept_raverified
897           Accept RAVERIFED as proof of possession (POPO).
898
899   Certificate verification options, for both CMP and TLS
900       -allow_proxy_certs, -attime, -no_check_time, -check_ss_sig, -crl_check,
901       -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical,
902       -inhibit_any, -inhibit_map, -no_alt_chains, -partial_chain, -policy,
903       -policy_check, -policy_print, -purpose, -suiteB_128, -suiteB_128_only,
904       -suiteB_192, -trusted_first, -use_deltas, -auth_level, -verify_depth,
905       -verify_email, -verify_hostname, -verify_ip, -verify_name, -x509_strict
906       -issuer_checks
907           Set various options of certificate chain verification.  See
908           "Verification Options" in openssl-verification-options(1) for
909           details.
910
911           The certificate verification options -verify_hostname, -verify_ip,
912           and -verify_email only affect the certificate verification enabled
913           via the -out_trusted option.
914

NOTES

916       When setting up CMP configurations and experimenting with enrollment
917       options typically various errors occur until the configuration is
918       correct and complete.  When the CMP server reports an error the client
919       will by default check the protection of the CMP response message.  Yet
920       some CMP services tend not to protect negative responses.  In this case
921       the client will reject them, and thus their contents are not shown
922       although they usually contain hints that would be helpful for
923       diagnostics.  For assisting in such cases the CMP client offers a
924       workaround via the -unprotected_errors option, which allows accepting
925       such negative messages.
926

EXAMPLES

928   Simple examples using the default OpenSSL configuration file
929       This CMP client implementation comes with demonstrative CMP sections in
930       the example configuration file openssl/apps/openssl.cnf, which can be
931       used to interact conveniently with the Insta Demo CA.
932
933       In order to enroll an initial certificate from that CA it is sufficient
934       to issue the following shell commands.
935
936         export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf
937
938         openssl genrsa -out insta.priv.pem
939         openssl cmp -section insta
940
941       This should produce the file insta.cert.pem containing a new
942       certificate for the private key held in insta.priv.pem.  It can be
943       viewed using, e.g.,
944
945         openssl x509 -noout -text -in insta.cert.pem
946
947       In case the network setup requires using an HTTP proxy it may be given
948       as usual via the environment variable http_proxy or via the -proxy
949       option in the configuration file or the CMP command-line argument
950       -proxy, for example
951
952         -proxy http://192.168.1.1:8080
953
954       In the Insta Demo CA scenario both clients and the server may use the
955       pre-shared secret insta and the reference value 3078 to authenticate to
956       each other.
957
958       Alternatively, CMP messages may be protected in signature-based manner,
959       where the trust anchor in this case is insta.ca.crt and the client may
960       use any certificate already obtained from that CA, as specified in the
961       [signature] section of the example configuration.  This can be used in
962       combination with the [insta] section simply by
963
964         openssl cmp -section insta,signature
965
966       By default the CMP IR message type is used, yet CR works equally here.
967       This may be specified directly at the command line:
968
969         openssl cmp -section insta -cmd cr
970
971       or by referencing in addition the [cr] section of the example
972       configuration:
973
974         openssl cmp -section insta,cr
975
976       In order to update the enrolled certificate one may call
977
978         openssl cmp -section insta,kur
979
980       using with PBM-based protection or
981
982         openssl cmp -section insta,kur,signature
983
984       using signature-based protection.
985
986       In a similar way any previously enrolled certificate may be revoked by
987
988         openssl cmp -section insta,rr -trusted insta.ca.crt
989
990       or
991
992         openssl cmp -section insta,rr,signature
993
994       Many more options can be given in the configuration file and/or on the
995       command line.  For instance, the -reqexts CLI option may refer to a
996       section in the configuration file defining X.509 extensions to use in
997       certificate requests, such as "v3_req" in openssl/apps/openssl.cnf:
998
999         openssl cmp -section insta,cr -reqexts v3_req
1000
1001   Certificate enrollment
1002       The following examples do not make use of a configuration file at
1003       first.  They assume that a CMP server can be contacted on the local TCP
1004       port 80 and accepts requests under the alias /pkix/.
1005
1006       For enrolling its very first certificate the client generates a client
1007       key and sends an initial request message to the local CMP server using
1008       a pre-shared secret key for mutual authentication.  In this example the
1009       client does not have the CA certificate yet, so we specify the name of
1010       the CA with the -recipient option and save any CA certificates that we
1011       may receive in the "capubs.pem" file.
1012
1013       In below command line usage examples the "\" at line ends is used just
1014       for formatting; each of the command invocations should be on a single
1015       line.
1016
1017         openssl genrsa -out cl_key.pem
1018         openssl cmp -cmd ir -server 127.0.0.1:80/pkix/ -recipient "/CN=CMPserver" \
1019           -ref 1234 -secret pass:1234-5678 \
1020           -newkey cl_key.pem -subject "/CN=MyName" \
1021           -cacertsout capubs.pem -certout cl_cert.pem
1022
1023   Certificate update
1024       Then, when the client certificate and its related key pair needs to be
1025       updated, the client can send a key update request taking the certs in
1026       "capubs.pem" as trusted for authenticating the server and using the
1027       previous cert and key for its own authentication.  Then it can start
1028       using the new cert and key.
1029
1030         openssl genrsa -out cl_key_new.pem
1031         openssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \
1032           -trusted capubs.pem \
1033           -cert cl_cert.pem -key cl_key.pem \
1034           -newkey cl_key_new.pem -certout cl_cert.pem
1035         cp cl_key_new.pem cl_key.pem
1036
1037       This command sequence can be repated as often as needed.
1038
1039   Requesting information from CMP server
1040       Requesting "all relevant information" with an empty General Message.
1041       This prints information about all received ITAV infoTypes to stdout.
1042
1043         openssl cmp -cmd genm -server 127.0.0.1/pkix/ -recipient "/CN=CMPserver" \
1044           -ref 1234 -secret pass:1234-5678
1045
1046   Using a custom configuration file
1047       For CMP client invocations, in particular for certificate enrollment,
1048       usually many parameters need to be set, which is tedious and error-
1049       prone to do on the command line.  Therefore, the client offers the
1050       possibility to read options from sections of the OpenSSL config file,
1051       usually called openssl.cnf.  The values found there can still be
1052       extended and even overridden by any subsequently loaded sections and on
1053       the command line.
1054
1055       After including in the configuration file the following sections:
1056
1057         [cmp]
1058         server = 127.0.0.1
1059         path = pkix/
1060         trusted = capubs.pem
1061         cert = cl_cert.pem
1062         key = cl_key.pem
1063         newkey = cl_key.pem
1064         certout = cl_cert.pem
1065
1066         [init]
1067         recipient = "/CN=CMPserver"
1068         trusted =
1069         cert =
1070         key =
1071         ref = 1234
1072         secret = pass:1234-5678-1234-567
1073         subject = "/CN=MyName"
1074         cacertsout = capubs.pem
1075
1076       the above enrollment transactions reduce to
1077
1078         openssl cmp -section cmp,init
1079         openssl cmp -cmd kur -newkey cl_key_new.pem
1080
1081       and the above transaction using a general message reduces to
1082
1083         openssl cmp -section cmp,init -cmd genm
1084

SEE ALSO

1086       openssl-genrsa(1), openssl-ecparam(1), openssl-list(1), openssl-req(1),
1087       openssl-x509(1), x509v3_config(5)
1088

HISTORY

1090       The cmp application was added in OpenSSL 3.0.
1091
1092       The -engine option was deprecated in OpenSSL 3.0.
1093
1095       Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved.
1096
1097       Licensed under the Apache License 2.0 (the "License").  You may not use
1098       this file except in compliance with the License.  You can obtain a copy
1099       in the file LICENSE in the source distribution or at
1100       <https://www.openssl.org/source/license.html>.
1101
1102
1103
11043.0.9                             2023-07-27                OPENSSL-CMP(1ossl)
Impressum