Debian Codegraph @

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