Debian Codegraph @

upstream/debian-unstable/man1/openssl-cms.1ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-CMS 1SSL"
58 .TH OPENSSL-CMS 1SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-cms \- CMS command
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBopenssl\fR \fBcms\fR
68 [\fB\-help\fR]
69 .PP
70 General options:
71 .PP
72 [\fB\-in\fR \fIfilename\fR]
73 [\fB\-out\fR \fIfilename\fR]
74 [\fB\-config\fR \fIconfigfile\fR]
75 .PP
76 Operation options:
77 .PP
78 [\fB\-encrypt\fR]
79 [\fB\-decrypt\fR]
80 [\fB\-sign\fR]
81 [\fB\-verify\fR]
82 [\fB\-resign\fR]
83 [\fB\-sign_receipt\fR]
84 [\fB\-verify_receipt\fR \fIreceipt\fR]
85 [\fB\-digest\fR \fIdigest\fR]
86 [\fB\-digest_create\fR]
87 [\fB\-digest_verify\fR]
88 [\fB\-compress\fR]
89 [\fB\-uncompress\fR]
90 [\fB\-EncryptedData_encrypt\fR]
91 [\fB\-EncryptedData_decrypt\fR]
92 [\fB\-data_create\fR]
93 [\fB\-data_out\fR]
94 [\fB\-cmsout\fR]
95 .PP
96 File format options:
97 .PP
98 [\fB\-inform\fR \fBDER\fR|\fBPEM\fR|\fBSMIME\fR]
99 [\fB\-outform\fR \fBDER\fR|\fBPEM\fR|\fBSMIME\fR]
100 [\fB\-rctform\fR \fBDER\fR|\fBPEM\fR|\fBSMIME\fR]
101 [\fB\-stream\fR]
102 [\fB\-indef\fR]
103 [\fB\-noindef\fR]
104 [\fB\-binary\fR]
105 [\fB\-crlfeol\fR]
106 [\fB\-asciicrlf\fR]
107 .PP
108 Keys and password options:
109 .PP
110 [\fB\-pwri_password\fR \fIpassword\fR]
111 [\fB\-secretkey\fR \fIkey\fR]
112 [\fB\-secretkeyid\fR \fIid\fR]
113 [\fB\-inkey\fR \fIfilename\fR|\fIuri\fR]
114 [\fB\-passin\fR \fIarg\fR]
115 [\fB\-keyopt\fR \fIname\fR:\fIparameter\fR]
116 [\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR]
117 [\fB\-engine\fR \fIid\fR]
118 [\fB\-provider\fR \fIname\fR]
119 [\fB\-provider\-path\fR \fIpath\fR]
120 [\fB\-provparam\fR \fI[name:]key=value\fR]
121 [\fB\-propquery\fR \fIpropq\fR]
122 [\fB\-rand\fR \fIfiles\fR]
123 [\fB\-writerand\fR \fIfile\fR]
124 .PP
125 Encryption options:
126 .PP
127 [\fB\-originator\fR \fIfile\fR]
128 [\fB\-recip\fR \fIfile\fR]
129 [\fIrecipient-cert\fR ...]
130 [\fB\-\fR\f(BIcipher\fR]
131 [\fB\-kekcipher\fR \fIcipher\fR]
132 [\fB\-wrap\fR \fIcipher\fR]
133 [\fB\-aes128\-wrap\fR]
134 [\fB\-aes192\-wrap\fR]
135 [\fB\-aes256\-wrap\fR]
136 [\fB\-des3\-wrap\fR]
137 [\fB\-debug_decrypt\fR]
138 [\fB\-recip_kdf\fR \fIkdf\fR]
139 [\fB\-recip_ukm\fR \fIukm\fR]
140 .PP
141 Signing options:
142 .PP
143 [\fB\-md\fR \fIdigest\fR]
144 [\fB\-signer\fR \fIfile\fR]
145 [\fB\-certfile\fR \fIfile\fR]
146 [\fB\-cades\fR]
147 [\fB\-nodetach\fR]
148 [\fB\-nocerts\fR]
149 [\fB\-noattr\fR]
150 [\fB\-nosmimecap\fR]
151 [\fB\-no_signing_time\fR]
152 [\fB\-receipt_request_all\fR]
153 [\fB\-receipt_request_first\fR]
154 [\fB\-receipt_request_from\fR \fIemailaddress\fR]
155 [\fB\-receipt_request_to\fR \fIemailaddress\fR]
156 .PP
157 Verification options:
158 .PP
159 [\fB\-signer\fR \fIfile\fR]
160 [\fB\-content\fR \fIfilename\fR]
161 [\fB\-no_content_verify\fR]
162 [\fB\-no_attr_verify\fR]
163 [\fB\-nosigs\fR]
164 [\fB\-noverify\fR]
165 [\fB\-nointern\fR]
166 [\fB\-cades\fR]
167 [\fB\-verify_retcode\fR]
168 [\fB\-CAfile\fR \fIfile\fR]
169 [\fB\-no\-CAfile\fR]
170 [\fB\-CApath\fR \fIdir\fR]
171 [\fB\-no\-CApath\fR]
172 [\fB\-CAstore\fR \fIuri\fR]
173 [\fB\-no\-CAstore\fR]
174 .PP
175 Output options:
176 .PP
177 [\fB\-keyid\fR]
178 [\fB\-econtent_type\fR \fItype\fR]
179 [\fB\-text\fR]
180 [\fB\-certsout\fR \fIfile\fR]
181 [\fB\-to\fR \fIaddr\fR]
182 [\fB\-from\fR \fIaddr\fR]
183 [\fB\-subject\fR \fIsubj\fR]
184 .PP
185 Printing options:
186 .PP
187 [\fB\-noout\fR]
188 [\fB\-print\fR]
189 [\fB\-nameopt\fR \fIoption\fR]
190 [\fB\-receipt_request_print\fR]
191 .PP
192 Validation options:
193 .PP
194 [\fB\-allow_proxy_certs\fR]
195 [\fB\-attime\fR \fItimestamp\fR]
196 [\fB\-no_check_time\fR]
197 [\fB\-check_ss_sig\fR]
198 [\fB\-crl_check\fR]
199 [\fB\-crl_check_all\fR]
200 [\fB\-explicit_policy\fR]
201 [\fB\-extended_crl\fR]
202 [\fB\-ignore_critical\fR]
203 [\fB\-inhibit_any\fR]
204 [\fB\-inhibit_map\fR]
205 [\fB\-partial_chain\fR]
206 [\fB\-policy\fR \fIarg\fR]
207 [\fB\-policy_check\fR]
208 [\fB\-policy_print\fR]
209 [\fB\-purpose\fR \fIpurpose\fR]
210 [\fB\-suiteB_128\fR]
211 [\fB\-suiteB_128_only\fR]
212 [\fB\-suiteB_192\fR]
213 [\fB\-trusted_first\fR]
214 [\fB\-no_alt_chains\fR]
215 [\fB\-use_deltas\fR]
216 [\fB\-auth_level\fR \fInum\fR]
217 [\fB\-verify_depth\fR \fInum\fR]
218 [\fB\-verify_email\fR \fIemail\fR]
219 [\fB\-verify_hostname\fR \fIhostname\fR]
220 [\fB\-verify_ip\fR \fIip\fR]
221 [\fB\-verify_name\fR \fIname\fR]
222 [\fB\-x509_strict\fR]
223 [\fB\-issuer_checks\fR]
224 .SH DESCRIPTION
225 .IX Header "DESCRIPTION"
226 This command handles data in CMS format such as S/MIME v3.1 email messages.
227 It can encrypt, decrypt, sign, verify, compress, uncompress, and print messages.
228 .SH OPTIONS
229 .IX Header "OPTIONS"
230 There are a number of operation options that set the type of operation to be
231 performed: encrypt, decrypt, sign, verify, resign, sign_receipt, verify_receipt,
232 digest_create, digest_verify, compress, uncompress,
233 EncryptedData_encrypt, EncryptedData_decrypt, data_create, data_out, or cmsout.
234 The relevance of the other options depends on the operation type
235 and their meaning may vary according to it.
236 .IP \fB\-help\fR 4
237 .IX Item "-help"
238 Print out a usage message.
239 .SS "General options"
240 .IX Subsection "General options"
241 .IP "\fB\-in\fR \fIfilename\fR" 4
242 .IX Item "-in filename"
243 The input message to be encrypted or signed or the message to be decrypted
244 or verified.
245 .IP "\fB\-out\fR \fIfilename\fR" 4
246 .IX Item "-out filename"
247 The message text that has been decrypted or verified or the output MIME
248 format message that has been signed or verified.
249 .IP "\fB\-config\fR \fIconfigfile\fR" 4
250 .IX Item "-config configfile"
251 See "Configuration Option" in \fBopenssl\fR\|(1).
252 .SS "Operation options"
253 .IX Subsection "Operation options"
254 .IP \fB\-encrypt\fR 4
255 .IX Item "-encrypt"
256 Encrypt data for the given recipient certificates. Input file is the message
257 to be encrypted. The output file is the encrypted data in MIME format. The
258 actual CMS type is \fBEnvelopedData\fR.
259 .Sp
260 Note that no revocation check is done for the recipient cert, so if that
261 key has been compromised, others may be able to decrypt the text.
262 .IP \fB\-decrypt\fR 4
263 .IX Item "-decrypt"
264 Decrypt data using the supplied certificate and private key. Expects
265 encrypted datain MIME format for the input file. The decrypted data
266 is written to the output file.
267 .IP \fB\-sign\fR 4
268 .IX Item "-sign"
269 Sign data using the supplied certificate and private key. Input file is
270 the message to be signed. The signed data in MIME format is written
271 to the output file.
272 .IP \fB\-verify\fR 4
273 .IX Item "-verify"
274 Verify signed data. Expects a signed data on input and outputs
275 the signed data. Both clear text and opaque signing is supported.
276 .Sp
277 By default, validation of signer certificates and their chain
278 is done w.r.t. the S/MIME signing (\f(CW\*(C`smimesign\*(C'\fR) purpose.
279 For details see "Certificate Extensions" in \fBopenssl\-verification\-options\fR\|(1).
280 .IP \fB\-resign\fR 4
281 .IX Item "-resign"
282 Resign a message: take an existing message and one or more new signers.
283 .IP \fB\-sign_receipt\fR 4
284 .IX Item "-sign_receipt"
285 Generate and output a signed receipt for the supplied message. The input
286 message \fBmust\fR contain a signed receipt request. Functionality is otherwise
287 similar to the \fB\-sign\fR operation.
288 .IP "\fB\-verify_receipt\fR \fIreceipt\fR" 4
289 .IX Item "-verify_receipt receipt"
290 Verify a signed receipt in filename \fBreceipt\fR. The input message \fBmust\fR
291 contain the original receipt request. Functionality is otherwise similar
292 to the \fB\-verify\fR operation.
293 .IP "\fB\-digest\fR \fIdigest\fR" 4
294 .IX Item "-digest digest"
295 When used with \fB\-sign\fR, provides the digest in hexadecimal form instead of
296 computing it from the original message content. Cannot be combined with \fB\-in\fR
297 or \fB\-nodetach\fR.
298 .Sp
299 This operation is the CMS equivalent of \fBopenssl\-pkeyutl\fR\|(1) signing.
300 When signing a pre-computed digest, the security relies on the digest and its
301 computation from the original message being trusted.
302 .IP \fB\-digest_create\fR 4
303 .IX Item "-digest_create"
304 Create a CMS \fBDigestedData\fR type.
305 .IP \fB\-digest_verify\fR 4
306 .IX Item "-digest_verify"
307 Verify a CMS \fBDigestedData\fR type and output the content.
308 .IP \fB\-compress\fR 4
309 .IX Item "-compress"
310 Create a CMS \fBCompressedData\fR type. OpenSSL must be compiled with \fBzlib\fR
311 support for this option to work, otherwise it will output an error.
312 .IP \fB\-uncompress\fR 4
313 .IX Item "-uncompress"
314 Uncompress a CMS \fBCompressedData\fR type and output the content. OpenSSL must be
315 compiled with \fBzlib\fR support for this option to work, otherwise it will
316 output an error.
317 .IP \fB\-EncryptedData_encrypt\fR 4
318 .IX Item "-EncryptedData_encrypt"
319 Encrypt content using supplied symmetric key and algorithm using a CMS
320 \&\fBEncryptedData\fR type and output the content.
321 .IP \fB\-EncryptedData_decrypt\fR 4
322 .IX Item "-EncryptedData_decrypt"
323 Decrypt content using supplied symmetric key and algorithm using a CMS
324 \&\fBEncryptedData\fR type and output the content.
325 .IP \fB\-data_create\fR 4
326 .IX Item "-data_create"
327 Create a CMS \fBData\fR type.
328 .IP \fB\-data_out\fR 4
329 .IX Item "-data_out"
330 \&\fBData\fR type and output the content.
331 .IP \fB\-cmsout\fR 4
332 .IX Item "-cmsout"
333 Takes an input message and writes out a PEM encoded CMS structure.
334 .SS "File format options"
335 .IX Subsection "File format options"
336 .IP "\fB\-inform\fR \fBDER\fR|\fBPEM\fR|\fBSMIME\fR" 4
337 .IX Item "-inform DER|PEM|SMIME"
338 The input format of the CMS structure (if one is being read);
339 the default is \fBSMIME\fR.
340 See \fBopenssl\-format\-options\fR\|(1) for details.
341 .IP "\fB\-outform\fR \fBDER\fR|\fBPEM\fR|\fBSMIME\fR" 4
342 .IX Item "-outform DER|PEM|SMIME"
343 The output format of the CMS structure (if one is being written);
344 the default is \fBSMIME\fR.
345 See \fBopenssl\-format\-options\fR\|(1) for details.
346 .IP "\fB\-rctform\fR \fBDER\fR|\fBPEM\fR|\fBSMIME\fR" 4
347 .IX Item "-rctform DER|PEM|SMIME"
348 The signed receipt format for use with the \fB\-receipt_verify\fR; the default
349 is \fBSMIME\fR.
350 See \fBopenssl\-format\-options\fR\|(1) for details.
351 .IP "\fB\-stream\fR, \fB\-indef\fR" 4
352 .IX Item "-stream, -indef"
353 The \fB\-stream\fR and \fB\-indef\fR options are equivalent and enable streaming I/O
354 for encoding operations. This permits single pass processing of data without
355 the need to hold the entire contents in memory, potentially supporting very
356 large files. Streaming is automatically set for S/MIME signing with detached
357 data if the output format is \fBSMIME\fR it is currently off by default for all
358 other operations.
359 .IP \fB\-noindef\fR 4
360 .IX Item "-noindef"
361 Disable streaming I/O where it would produce and indefinite length constructed
362 encoding. This option currently has no effect. In future streaming will be
363 enabled by default on all relevant operations and this option will disable it.
364 .IP \fB\-binary\fR 4
365 .IX Item "-binary"
366 Normally the input message is converted to "canonical" format which is
367 effectively using CR and LF as end of line: as required by the S/MIME
368 specification. When this option is present no translation occurs. This
369 is useful when handling binary data which may not be in MIME format.
370 .IP \fB\-crlfeol\fR 4
371 .IX Item "-crlfeol"
372 Normally the output file uses a single \fBLF\fR as end of line. When this
373 option is present \fBCRLF\fR is used instead.
374 .IP \fB\-asciicrlf\fR 4
375 .IX Item "-asciicrlf"
376 When signing use ASCII CRLF format canonicalisation. This strips trailing
377 whitespace from all lines, deletes trailing blank lines at EOF and sets
378 the encapsulated content type. This option is normally used with detached
379 content and an output signature format of DER. This option is not normally
380 needed when verifying as it is enabled automatically if the encapsulated
381 content format is detected.
382 .SS "Keys and password options"
383 .IX Subsection "Keys and password options"
384 .IP "\fB\-pwri_password\fR \fIpassword\fR" 4
385 .IX Item "-pwri_password password"
386 Specify password for recipient.
387 .IP "\fB\-secretkey\fR \fIkey\fR" 4
388 .IX Item "-secretkey key"
389 Specify symmetric key to use. The key must be supplied in hex format and be
390 consistent with the algorithm used. Supported by the \fB\-EncryptedData_encrypt\fR
391 \&\fB\-EncryptedData_decrypt\fR, \fB\-encrypt\fR and \fB\-decrypt\fR options. When used
392 with \fB\-encrypt\fR or \fB\-decrypt\fR the supplied key is used to wrap or unwrap the
393 content encryption key using an AES key in the \fBKEKRecipientInfo\fR type.
394 .IP "\fB\-secretkeyid\fR \fIid\fR" 4
395 .IX Item "-secretkeyid id"
396 The key identifier for the supplied symmetric key for \fBKEKRecipientInfo\fR type.
397 This option \fBmust\fR be present if the \fB\-secretkey\fR option is used with
398 \&\fB\-encrypt\fR. With \fB\-decrypt\fR operations the \fIid\fR is used to locate the
399 relevant key if it is not supplied then an attempt is used to decrypt any
400 \&\fBKEKRecipientInfo\fR structures.
401 .IP "\fB\-inkey\fR \fIfilename\fR|\fIuri\fR" 4
402 .IX Item "-inkey filename|uri"
403 The private key to use when signing or decrypting. This must match the
404 corresponding certificate. If this option is not specified then the
405 private key must be included in the certificate file specified with
406 the \fB\-recip\fR or \fB\-signer\fR file. When signing this option can be used
407 multiple times to specify successive keys.
408 .IP "\fB\-passin\fR \fIarg\fR" 4
409 .IX Item "-passin arg"
410 The private key password source. For more information about the format of \fBarg\fR
411 see \fBopenssl\-passphrase\-options\fR\|(1).
412 .IP "\fB\-keyopt\fR \fIname\fR:\fIparameter\fR" 4
413 .IX Item "-keyopt name:parameter"
414 For signing and encryption this option can be used multiple times to
415 set customised parameters for the preceding key or certificate. It can
416 currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
417 or to modify default parameters for ECDH.
418 .IP "\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4
419 .IX Item "-keyform DER|PEM|P12|ENGINE"
420 The format of the private key file; unspecified by default.
421 See \fBopenssl\-format\-options\fR\|(1) for details.
422 .IP "\fB\-engine\fR \fIid\fR" 4
423 .IX Item "-engine id"
424 See "Engine Options" in \fBopenssl\fR\|(1).
425 This option is deprecated.
426 .IP "\fB\-provider\fR \fIname\fR" 4
427 .IX Item "-provider name"
428 .PD 0
429 .IP "\fB\-provider\-path\fR \fIpath\fR" 4
430 .IX Item "-provider-path path"
431 .IP "\fB\-provparam\fR \fI[name:]key=value\fR" 4
432 .IX Item "-provparam [name:]key=value"
433 .IP "\fB\-propquery\fR \fIpropq\fR" 4
434 .IX Item "-propquery propq"
435 .PD
436 See "Provider Options" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7).
437 .IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
438 .IX Item "-rand files, -writerand file"
439 See "Random State Options" in \fBopenssl\fR\|(1) for details.
440 .SS "Encryption and decryption options"
441 .IX Subsection "Encryption and decryption options"
442 .IP "\fB\-originator\fR \fIfile\fR" 4
443 .IX Item "-originator file"
444 A certificate of the originator of the encrypted message. Necessary for
445 decryption when Key Agreement is in use for a shared key. Currently, not
446 allowed for encryption.
447 .IP "\fB\-recip\fR \fIfile\fR" 4
448 .IX Item "-recip file"
449 When decrypting a message this specifies the certificate of the recipient.
450 The certificate must match one of the recipients of the message.
451 .Sp
452 When encrypting a message this option may be used multiple times to specify
453 each recipient. This form \fBmust\fR be used if customised parameters are
454 required (for example to specify RSA-OAEP).
455 .Sp
456 Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this
457 option.
458 .IP "\fIrecipient-cert\fR ..." 4
459 .IX Item "recipient-cert ..."
460 This is an alternative to using the \fB\-recip\fR option when encrypting a message.
461 One or more certificate filenames may be given.
462 .IP \fB\-\fR\f(BIcipher\fR 4
463 .IX Item "-cipher"
464 The encryption algorithm to use. For example, AES (256 bits) \- \fB\-aes256\fR
465 or triple DES (168 bits) \- \fB\-des3\fR. Any standard algorithm name (as used by the
466 \&\fBEVP_get_cipherbyname()\fR function) can also be used preceded by a dash, for
467 example \fB\-aes\-128\-cbc\fR. See \fBopenssl\-enc\fR\|(1) for a list of ciphers
468 supported by your version of OpenSSL.
469 .Sp
470 Currently, the AES variants with GCM mode are the only supported AEAD
471 algorithms.
472 .Sp
473 If not specified, AES\-256\-CBC is used as the default. Only used with \fB\-encrypt\fR and
474 \&\fB\-EncryptedData_encrypt\fR commands.
475 .IP "\fB\-kekcipher\fR \fIcipher\fR" 4
476 .IX Item "-kekcipher cipher"
477 Cipher algorithm to use for password key encryption. This option is relevant
478 when a password for password recipient information is provided using
479 \&\fB\-pwri_password\fR, and an AEAD encryption algorithm is selected. In such cases,
480 a non-AEAD algorithm should be specified using this option.
481 .IP "\fB\-wrap\fR \fIcipher\fR" 4
482 .IX Item "-wrap cipher"
483 Cipher algorithm to use for key wrap when encrypting the message using Key
484 Agreement for key transport. The algorithm specified should be suitable for key
485 wrap.
486 .IP "\fB\-aes128\-wrap\fR, \fB\-aes192\-wrap\fR, \fB\-aes256\-wrap\fR, \fB\-des3\-wrap\fR" 4
487 .IX Item "-aes128-wrap, -aes192-wrap, -aes256-wrap, -des3-wrap"
488 Use AES128, AES192, AES256, or 3DES\-EDE, respectively, to wrap key.
489 Depending on the OpenSSL build options used, \fB\-des3\-wrap\fR may not be supported.
490 .IP \fB\-debug_decrypt\fR 4
491 .IX Item "-debug_decrypt"
492 This option sets the \fBCMS_DEBUG_DECRYPT\fR flag. This option should be used
493 with caution: see the notes section below.
494 .IP \fB\-recip_kdf\fR 4
495 .IX Item "-recip_kdf"
496 This option sets the KDF used to generate the key encryption key in the
497 \&\fBKEMRecipientInfo\fR type. Any KDF that takes \fBOSSL_KDF_PARAM_KEY\fR and
498 \&\fBOSSL_KDF_PARAM_INFO\fR parameters and is otherwise fully defined by its name or
499 OID can be used, for example \fBHKDF\-SHA256\fR.
500 .IP \fB\-recip_ukm\fR 4
501 .IX Item "-recip_ukm"
502 This option sets the \fBKEMRecipientInfo\fR type's optional user keying material (UKM)
503 in hexadecimal form. The UKM will be encoded, along with other information, into the
504 \&\fBOSSL_KDF_PARAM_INFO\fR parameter of the \fBKEMRecipientInfo\fR type's KDF.
505 .SS "Signing options"
506 .IX Subsection "Signing options"
507 .IP "\fB\-md\fR \fIdigest\fR" 4
508 .IX Item "-md digest"
509 Digest algorithm to use when signing or resigning. If not present then the
510 default digest algorithm for the signing key will be used (usually SHA\-256).
511 .IP "\fB\-signer\fR \fIfile\fR" 4
512 .IX Item "-signer file"
513 A signing certificate. When signing or resigning a message, this option can be
514 used multiple times if more than one signer is required.
515 .IP "\fB\-certfile\fR \fIfile\fR" 4
516 .IX Item "-certfile file"
517 Allows additional certificates to be specified. When signing these will
518 be included with the message. When verifying, these will be searched for
519 signer certificates and will be used for chain building.
520 .Sp
521 The input can be in PEM, DER, or PKCS#12 format.
522 .IP \fB\-cades\fR 4
523 .IX Item "-cades"
524 When used with \fB\-sign\fR,
525 add an ESS signingCertificate or ESS signingCertificateV2 signed-attribute
526 to the SignerInfo, in order to make the signature comply with the requirements
527 for a CAdES Basic Electronic Signature (CAdES-BES).
528 .IP \fB\-nodetach\fR 4
529 .IX Item "-nodetach"
530 When signing a message use opaque signing: this form is more resistant
531 to translation by mail relays but it cannot be read by mail agents that
532 do not support S/MIME. Without this option cleartext signing with
533 the MIME type multipart/signed is used.
534 .IP \fB\-nocerts\fR 4
535 .IX Item "-nocerts"
536 When signing a message the signer's certificate is normally included
537 with this option it is excluded. This will reduce the size of the
538 signed message but the verifier must have a copy of the signers certificate
539 available locally (passed using the \fB\-certfile\fR option for example).
540 .IP \fB\-noattr\fR 4
541 .IX Item "-noattr"
542 Normally when a message is signed a set of attributes are included which
543 include the signing time and supported symmetric algorithms. With this
544 option they are not included.
545 .IP \fB\-nosmimecap\fR 4
546 .IX Item "-nosmimecap"
547 Exclude the list of supported algorithms from signed attributes, other options
548 such as content type and (optionally) signing time are still included.
549 .IP \fB\-no_signing_time\fR 4
550 .IX Item "-no_signing_time"
551 Exclude the signing time from signed attributes, other options
552 such as content type are still included.
553 .IP "\fB\-receipt_request_all\fR, \fB\-receipt_request_first\fR" 4
554 .IX Item "-receipt_request_all, -receipt_request_first"
555 For \fB\-sign\fR option include a signed receipt request. Indicate requests should
556 be provided by all recipient or first tier recipients (those mailed directly
557 and not from a mailing list). Ignored it \fB\-receipt_request_from\fR is included.
558 .IP "\fB\-receipt_request_from\fR \fIemailaddress\fR" 4
559 .IX Item "-receipt_request_from emailaddress"
560 For \fB\-sign\fR option include a signed receipt request. Add an explicit email
561 address where receipts should be supplied.
562 .IP "\fB\-receipt_request_to\fR \fIemailaddress\fR" 4
563 .IX Item "-receipt_request_to emailaddress"
564 Add an explicit email address where signed receipts should be sent to. This
565 option \fBmust\fR but supplied if a signed receipt is requested.
566 .SS "Verification options"
567 .IX Subsection "Verification options"
568 .IP "\fB\-signer\fR \fIfile\fR" 4
569 .IX Item "-signer file"
570 If a message has been verified successfully then the signers certificate(s)
571 will be written to this file if the verification was successful.
572 .IP "\fB\-content\fR \fIfilename\fR" 4
573 .IX Item "-content filename"
574 This specifies a file containing the detached content for operations taking
575 S/MIME input, such as the \fB\-verify\fR command. This is only usable if the CMS
576 structure is using the detached signature form where the content is
577 not included. This option will override any content if the input format
578 is S/MIME and it uses the multipart/signed MIME content type.
579 .IP \fB\-no_content_verify\fR 4
580 .IX Item "-no_content_verify"
581 Do not verify signed content signatures.
582 .IP \fB\-no_attr_verify\fR 4
583 .IX Item "-no_attr_verify"
584 Do not verify signed attribute signatures.
585 .IP \fB\-nosigs\fR 4
586 .IX Item "-nosigs"
587 Don't verify message signature.
588 .IP \fB\-noverify\fR 4
589 .IX Item "-noverify"
590 Do not verify the signers certificate of a signed message.
591 .IP \fB\-nointern\fR 4
592 .IX Item "-nointern"
593 When verifying a message normally certificates (if any) included in
594 the message are searched for the signing certificate. With this option
595 only the certificates specified in the \fB\-certfile\fR option are used.
596 The supplied certificates can still be used as untrusted CAs however.
597 .IP \fB\-cades\fR 4
598 .IX Item "-cades"
599 When used with \fB\-verify\fR, require and check signer certificate digest.
600 See the NOTES section for more details.
601 .IP \fB\-verify_retcode\fR 4
602 .IX Item "-verify_retcode"
603 Exit nonzero on verification failure.
604 .IP "\fB\-CAfile\fR \fIfile\fR, \fB\-no\-CAfile\fR, \fB\-CApath\fR \fIdir\fR, \fB\-no\-CApath\fR, \fB\-CAstore\fR \fIuri\fR, \fB\-no\-CAstore\fR" 4
605 .IX Item "-CAfile file, -no-CAfile, -CApath dir, -no-CApath, -CAstore uri, -no-CAstore"
606 See "Trusted Certificate Options" in \fBopenssl\-verification\-options\fR\|(1) for details.
607 .SS "Output options"
608 .IX Subsection "Output options"
609 .IP \fB\-keyid\fR 4
610 .IX Item "-keyid"
611 Use subject key identifier to identify certificates instead of issuer name and
612 serial number. The supplied certificate \fBmust\fR include a subject key
613 identifier extension. Supported by \fB\-sign\fR and \fB\-encrypt\fR options.
614 .IP "\fB\-econtent_type\fR \fItype\fR" 4
615 .IX Item "-econtent_type type"
616 Set the encapsulated content type to \fItype\fR if not supplied the \fBData\fR type
617 is used. The \fItype\fR argument can be any valid OID name in either text or
618 numerical format.
619 .IP \fB\-text\fR 4
620 .IX Item "-text"
621 This option adds plain text (text/plain) MIME headers to the supplied
622 message if encrypting or signing. If decrypting or verifying it strips
623 off text headers: if the decrypted or verified message is not of MIME
624 type text/plain then an error occurs.
625 .IP "\fB\-certsout\fR \fIfile\fR" 4
626 .IX Item "-certsout file"
627 Any certificates contained in the input message are written to \fIfile\fR.
628 .IP "\fB\-to\fR, \fB\-from\fR, \fB\-subject\fR" 4
629 .IX Item "-to, -from, -subject"
630 The relevant email headers. These are included outside the signed
631 portion of a message so they may be included manually. If signing
632 then many S/MIME mail clients check the signers certificate's email
633 address matches that specified in the From: address.
634 .SS "Printing options"
635 .IX Subsection "Printing options"
636 .IP \fB\-noout\fR 4
637 .IX Item "-noout"
638 For the \fB\-cmsout\fR operation do not output the parsed CMS structure.
639 This is useful if the syntax of the CMS structure is being checked.
640 .IP \fB\-print\fR 4
641 .IX Item "-print"
642 For the \fB\-cmsout\fR operation print out all fields of the CMS structure.
643 This implies \fB\-noout\fR.
644 This is mainly useful for testing purposes.
645 .IP "\fB\-nameopt\fR \fIoption\fR" 4
646 .IX Item "-nameopt option"
647 For the \fB\-cmsout\fR operation when \fB\-print\fR option is in use, specifies
648 printing options for string fields. For most cases \fButf8\fR is reasonable value.
649 See \fBopenssl\-namedisplay\-options\fR\|(1) for details.
650 .IP \fB\-receipt_request_print\fR 4
651 .IX Item "-receipt_request_print"
652 For the \fB\-verify\fR operation print out the contents of any signed receipt
653 requests.
654 .SS "Validation options"
655 .IX Subsection "Validation options"
656 .IP "\fB\-allow_proxy_certs\fR, \fB\-attime\fR, \fB\-no_check_time\fR, \fB\-check_ss_sig\fR, \fB\-crl_check\fR, \fB\-crl_check_all\fR, \fB\-explicit_policy\fR, \fB\-extended_crl\fR, \fB\-ignore_critical\fR, \fB\-inhibit_any\fR, \fB\-inhibit_map\fR, \fB\-no_alt_chains\fR, \fB\-partial_chain\fR, \fB\-policy\fR, \fB\-policy_check\fR, \fB\-policy_print\fR, \fB\-purpose\fR, \fB\-suiteB_128\fR, \fB\-suiteB_128_only\fR, \fB\-suiteB_192\fR, \fB\-trusted_first\fR, \fB\-use_deltas\fR, \fB\-auth_level\fR, \fB\-verify_depth\fR, \fB\-verify_email\fR, \fB\-verify_hostname\fR, \fB\-verify_ip\fR, \fB\-verify_name\fR, \fB\-x509_strict\fR \fB\-issuer_checks\fR" 4
657 .IX Item "-allow_proxy_certs, -attime, -no_check_time, -check_ss_sig, -crl_check, -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical, -inhibit_any, -inhibit_map, -no_alt_chains, -partial_chain, -policy, -policy_check, -policy_print, -purpose, -suiteB_128, -suiteB_128_only, -suiteB_192, -trusted_first, -use_deltas, -auth_level, -verify_depth, -verify_email, -verify_hostname, -verify_ip, -verify_name, -x509_strict -issuer_checks"
658 Set various options of certificate chain verification.
659 See "Verification Options" in \fBopenssl\-verification\-options\fR\|(1) for details.
660 .Sp
661 Any validation errors cause the command to exit.
662 .SH NOTES
663 .IX Header "NOTES"
664 The MIME message must be sent without any blank lines between the
665 headers and the output. Some mail programs will automatically add
666 a blank line. Piping the mail directly to sendmail is one way to
667 achieve the correct format.
668 .PP
669 The supplied message to be signed or encrypted must include the
670 necessary MIME headers or many S/MIME clients won't display it
671 properly (if at all). You can use the \fB\-text\fR option to automatically
672 add plain text headers.
673 .PP
674 A "signed and encrypted" message is one where a signed message is
675 then encrypted. This can be produced by encrypting an already signed
676 message: see the examples section.
677 .PP
678 This version of the program only allows one signer per message but it
679 will verify multiple signers on received messages. Some S/MIME clients
680 choke if a message contains multiple signers. It is possible to sign
681 messages "in parallel" by signing an already signed message.
682 .PP
683 The options \fB\-encrypt\fR and \fB\-decrypt\fR reflect common usage in S/MIME
684 clients. Strictly speaking these process CMS enveloped data: CMS
685 encrypted data is used for other purposes.
686 .PP
687 The \fB\-resign\fR option uses an existing message digest when adding a new
688 signer. This means that attributes must be present in at least one existing
689 signer using the same message digest or this operation will fail.
690 .PP
691 The \fB\-stream\fR and \fB\-indef\fR options enable streaming I/O support.
692 As a result the encoding is BER using indefinite length constructed encoding
693 and no longer DER. Streaming is supported for the \fB\-encrypt\fR operation and the
694 \&\fB\-sign\fR operation if the content is not detached.
695 .PP
696 Streaming is always used for the \fB\-sign\fR operation with detached data but
697 since the content is no longer part of the CMS structure the encoding
698 remains DER.
699 .PP
700 If the \fB\-decrypt\fR option is used without a recipient certificate then an
701 attempt is made to locate the recipient by trying each potential recipient
702 in turn using the supplied private key. To thwart the MMA attack
703 (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
704 tried whether they succeed or not and if no recipients match the message
705 is "decrypted" using a random key which will typically output garbage.
706 The \fB\-debug_decrypt\fR option can be used to disable the MMA attack protection
707 and return an error if no recipient can be found: this option should be used
708 with caution. For a fuller description see \fBCMS_decrypt\fR\|(3)).
709 .SH "CADES BASIC ELECTRONIC SIGNATURE (CADES-BES)"
710 .IX Header "CADES BASIC ELECTRONIC SIGNATURE (CADES-BES)"
711 A CAdES Basic Electronic Signature (CAdES-BES),
712 as defined in the European Standard ETSI EN 319 122\-1 V1.1.1, contains:
713 .IP \(bu 4
714 The signed user data as defined in CMS (RFC 3852);
715 .IP \(bu 4
716 Content-type of the EncapsulatedContentInfo value being signed;
717 .IP \(bu 4
718 Message-digest of the eContent OCTET STRING within encapContentInfo being signed;
719 .IP \(bu 4
720 An ESS signingCertificate or ESS signingCertificateV2 attribute,
721 as defined in Enhanced Security Services (ESS), RFC 2634 and RFC 5035.
722 An ESS signingCertificate attribute only allows for SHA\-1 as digest algorithm.
723 An ESS signingCertificateV2 attribute allows for any digest algorithm.
724 .IP \(bu 4
725 The digital signature value computed on the user data and, when present, on the signed attributes.
726 .Sp
727 NOTE that the \fB\-cades\fR option applies to the \fB\-sign\fR or \fB\-verify\fR operations.
728 With this option, the \fB\-verify\fR operation also requires that the
729 signingCertificate attribute is present and checks that the given identifiers
730 match the verification trust chain built during the verification process.
731 .SH "EXIT CODES"
732 .IX Header "EXIT CODES"
733 .IP 0 4
734 The operation was completely successfully.
735 .IP 1 4
736 .IX Item "1"
737 An error occurred parsing the command options.
738 .IP 2 4
739 .IX Item "2"
740 One of the input files could not be read.
741 .IP 3 4
742 .IX Item "3"
743 An error occurred creating the CMS file or when reading the MIME
744 message.
745 .IP 4 4
746 .IX Item "4"
747 An error occurred decrypting or verifying the message.
748 .IP 5 4
749 .IX Item "5"
750 The message was verified correctly but an error occurred writing out
751 the signers certificates.
752 .SH "COMPATIBILITY WITH PKCS#7 FORMAT"
753 .IX Header "COMPATIBILITY WITH PKCS#7 FORMAT"
754 \&\fBopenssl\-smime\fR\|(1) can only process the older \fBPKCS#7\fR format.
755 \&\fBopenssl cms\fR supports Cryptographic Message Syntax format.
756 Use of some features will result in messages which cannot be processed by
757 applications which only support the older format. These are detailed below.
758 .PP
759 The use of the \fB\-keyid\fR option with \fB\-sign\fR or \fB\-encrypt\fR.
760 .PP
761 The \fB\-outform\fR \fIPEM\fR option uses different headers.
762 .PP
763 The \fB\-compress\fR option.
764 .PP
765 The \fB\-secretkey\fR option when used with \fB\-encrypt\fR.
766 .PP
767 The use of PSS with \fB\-sign\fR.
768 .PP
769 The use of OAEP or non-RSA keys with \fB\-encrypt\fR.
770 .PP
771 Additionally the \fB\-EncryptedData_encrypt\fR and \fB\-data_create\fR type cannot
772 be processed by the older \fBopenssl\-smime\fR\|(1) command.
773 .SH EXAMPLES
774 .IX Header "EXAMPLES"
775 Create a cleartext signed message:
776 .PP
777 .Vb 2
778 \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \e
779 \& \-signer mycert.pem
780 .Ve
781 .PP
782 Create an opaque signed message
783 .PP
784 .Vb 2
785 \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \-nodetach \e
786 \& \-signer mycert.pem
787 .Ve
788 .PP
789 Create a signed message, include some additional certificates and
790 read the private key from another file:
791 .PP
792 .Vb 2
793 \& openssl cms \-sign \-in in.txt \-text \-out mail.msg \e
794 \& \-signer mycert.pem \-inkey mykey.pem \-certfile mycerts.pem
795 .Ve
796 .PP
797 Create a signed message with two signers, use key identifier:
798 .PP
799 .Vb 2
800 \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \e
801 \& \-signer mycert.pem \-signer othercert.pem \-keyid
802 .Ve
803 .PP
804 Send a signed message under Unix directly to sendmail, including headers:
805 .PP
806 .Vb 3
807 \& openssl cms \-sign \-in in.txt \-text \-signer mycert.pem \e
808 \& \-from [email protected] \-to someone@somewhere \e
809 \& \-subject "Signed message" | sendmail someone@somewhere
810 .Ve
811 .PP
812 Verify a message and extract the signer's certificate if successful:
813 .PP
814 .Vb 1
815 \& openssl cms \-verify \-in mail.msg \-signer user.pem \-out signedtext.txt
816 .Ve
817 .PP
818 Send encrypted mail using triple DES:
819 .PP
820 .Vb 3
821 \& openssl cms \-encrypt \-in in.txt \-from [email protected] \e
822 \& \-to someone@somewhere \-subject "Encrypted message" \e
823 \& \-des3 user.pem \-out mail.msg
824 .Ve
825 .PP
826 Sign and encrypt mail:
827 .PP
828 .Vb 4
829 \& openssl cms \-sign \-in ml.txt \-signer my.pem \-text \e
830 \& | openssl cms \-encrypt \-out mail.msg \e
831 \& \-from [email protected] \-to someone@somewhere \e
832 \& \-subject "Signed and Encrypted message" \-des3 user.pem
833 .Ve
834 .PP
835 Note: the encryption command does not include the \fB\-text\fR option because the
836 message being encrypted already has MIME headers.
837 .PP
838 Decrypt a message:
839 .PP
840 .Vb 1
841 \& openssl cms \-decrypt \-in mail.msg \-recip mycert.pem \-inkey key.pem
842 .Ve
843 .PP
844 The output from Netscape form signing is a PKCS#7 structure with the
845 detached signature format. You can use this program to verify the
846 signature by line wrapping the base64 encoded structure and surrounding
847 it with:
848 .PP
849 .Vb 2
850 \& \-\-\-\-\-BEGIN PKCS7\-\-\-\-\-
851 \& \-\-\-\-\-END PKCS7\-\-\-\-\-
852 .Ve
853 .PP
854 and using the command,
855 .PP
856 .Vb 1
857 \& openssl cms \-verify \-inform PEM \-in signature.pem \-content content.txt
858 .Ve
859 .PP
860 alternatively you can base64 decode the signature and use
861 .PP
862 .Vb 1
863 \& openssl cms \-verify \-inform DER \-in signature.der \-content content.txt
864 .Ve
865 .PP
866 Create an encrypted message using 128 bit Camellia:
867 .PP
868 .Vb 1
869 \& openssl cms \-encrypt \-in plain.txt \-camellia128 \-out mail.msg cert.pem
870 .Ve
871 .PP
872 Add a signer to an existing message:
873 .PP
874 .Vb 1
875 \& openssl cms \-resign \-in mail.msg \-signer newsign.pem \-out mail2.msg
876 .Ve
877 .PP
878 Sign a message using RSA-PSS:
879 .PP
880 .Vb 2
881 \& openssl cms \-sign \-in message.txt \-text \-out mail.msg \e
882 \& \-signer mycert.pem \-keyopt rsa_padding_mode:pss
883 .Ve
884 .PP
885 Create an encrypted message using RSA-OAEP:
886 .PP
887 .Vb 2
888 \& openssl cms \-encrypt \-in plain.txt \-out mail.msg \e
889 \& \-recip cert.pem \-keyopt rsa_padding_mode:oaep
890 .Ve
891 .PP
892 Use SHA256 KDF with an ECDH certificate:
893 .PP
894 .Vb 2
895 \& openssl cms \-encrypt \-in plain.txt \-out mail.msg \e
896 \& \-recip ecdhcert.pem \-keyopt ecdh_kdf_md:sha256
897 .Ve
898 .PP
899 Print CMS signed binary data in human-readable form:
900 .PP
901 .Vb 1
902 \& openssl cms \-in signed.cms \-binary \-inform DER \-cmsout \-print
903 .Ve
904 .SH BUGS
905 .IX Header "BUGS"
906 The MIME parser isn't very clever: it seems to handle most messages that I've
907 thrown at it but it may choke on others.
908 .PP
909 The code currently will only write out the signer's certificate to a file: if
910 the signer has a separate encryption certificate this must be manually
911 extracted. There should be some heuristic that determines the correct
912 encryption certificate.
913 .PP
914 Ideally a database should be maintained of a certificates for each email
915 address.
916 .PP
917 The code doesn't currently take note of the permitted symmetric encryption
918 algorithms as supplied in the SMIMECapabilities signed attribute. this means the
919 user has to manually include the correct encryption algorithm. It should store
920 the list of permitted ciphers in a database and only use those.
921 .PP
922 No revocation checking is done on the signer's certificate.
923 .SH "SEE ALSO"
924 .IX Header "SEE ALSO"
925 \&\fBossl_store\-file\fR\|(7)
926 .SH HISTORY
927 .IX Header "HISTORY"
928 The default encryption cipher was changed from 3DES to AES\-256 in OpenSSL 3.5.
929 .PP
930 The use of multiple \fB\-signer\fR options and the \fB\-resign\fR command were first
931 added in OpenSSL 1.0.0.
932 .PP
933 The \fB\-keyopt\fR option was added in OpenSSL 1.0.2.
934 .PP
935 Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2.
936 .PP
937 The use of non-RSA keys with \fB\-encrypt\fR and \fB\-decrypt\fR
938 was added in OpenSSL 1.0.2.
939 .PP
940 The \-no_alt_chains option was added in OpenSSL 1.0.2b.
941 .PP
942 The \fB\-nameopt\fR option was added in OpenSSL 3.0.0.
943 .PP
944 The \fB\-engine\fR option was deprecated in OpenSSL 3.0.
945 .PP
946 The \fB\-digest\fR option was added in OpenSSL 3.2.
947 .PP
948 The \fB\-recip_kdf\fR and \fB\-recip_ukm\fR options were added in OpenSSL 3.6.
949 .SH COPYRIGHT
950 .IX Header "COPYRIGHT"
951 Copyright 2008\-2026 The OpenSSL Project Authors. All Rights Reserved.
952 .PP
953 Licensed under the Apache License 2.0 (the "License"). You may not use
954 this file except in compliance with the License. You can obtain a copy
955 in the file LICENSE in the source distribution or at
956 <https://www.openssl.org/source/license.html>.