=head1 SYNOPSIS
B<openssl> B<cms>
+[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
[B<-print>]
[B<-CAfile file>]
[B<-CApath dir>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-no_check_time>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-auth_level num>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
[B<-md digest>]
-[B<-des>]
-[B<-des3>]
-[B<-rc2-40>]
-[B<-rc2-64>]
-[B<-rc2-128>]
-[B<-aes128>]
-[B<-aes192>]
-[B<-aes256>]
-[B<-camellia128>]
-[B<-camellia192>]
-[B<-camellia256>]
+[B<-[cipher]>]
[B<-nointern>]
[B<-no_signer_cert_verify>]
[B<-nocerts>]
[B<-noattr>]
[B<-nosmimecap>]
[B<-binary>]
+[B<-crlfeol>]
+[B<-asciicrlf>]
[B<-nodetach>]
[B<-certfile file>]
[B<-certsout file>]
[B<-secretkeyid id>]
[B<-econtent_type type>]
[B<-inkey file>]
+[B<-keyopt name:parameter>]
[B<-passin arg>]
[B<-rand file(s)>]
[B<cert.pem...>]
=over 4
+=item B<-help>
+
+Print out a usage message.
+
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
to be encrypted. The output file is the encrypted mail in MIME format. The
actual CMS type is <B>EnvelopedData<B>.
+Note that no revocation check is done for the recipient cert, so if that
+key has been compromised, others may be able to decrypt the text.
+
=item B<-decrypt>
decrypt mail using the supplied certificate and private key. Expects an
encrypted mail message in MIME format for the input file. The decrypted mail
is written to the output file.
+=item B<-debug_decrypt>
+
+this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
+with caution: see the notes section below.
+
=item B<-sign>
sign mail using the supplied certificate and private key. Input file is
=item B<-EncryptedData_encrypt>
-Encrypt suppled content using supplied symmetric key and algorithm using a CMS
+Encrypt content using supplied symmetric key and algorithm using a CMS
B<EncrytedData> type and output the content.
=item B<-sign_receipt>
-Generate and output a signed receipt for the supplied message. The input
+Generate and output a signed receipt for the supplied message. The input
message B<must> contain a signed receipt request. Functionality is otherwise
similar to the B<-sign> operation.
=item B<-verify_receipt receipt>
-Verify a signed receipt in filename B<receipt>. The input message B<must>
+Verify a signed receipt in filename B<receipt>. The input message B<must>
contain the original receipt request. Functionality is otherwise similar
to the B<-verify> operation.
this option adds plain text (text/plain) MIME headers to the supplied
message if encrypting or signing. If decrypting or verifying it strips
-off text headers: if the decrypted or verified message is not of MIME
+off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-noout>
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
default digest algorithm for the signing key will be used (usually SHA1).
-=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256>
+=item B<-[cipher]>
-the encryption algorithm to use. DES (56 bits), triple DES (168 bits), 40, 64
-or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia
-respectively. Any other cipher name (as recognized by the
-EVP_get_cipherbyname() function) can also be used preceded by a dash, for
-example B<-aes_128_cbc>.
+the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
+or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
+EVP_get_cipherbyname() function) can also be used preceded by a dash, for
+example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers
+supported by your version of OpenSSL.
-If not specified triple DES is used. Only used with B<-encrypt> and
+If not specified triple DES is used. Only used with B<-encrypt> and
B<-EncryptedData_create> commands.
=item B<-nointern>
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
+=item B<-crlfeol>
+
+normally the output file uses a single B<LF> as end of line. When this
+option is present B<CRLF> is used instead.
+
+=item B<-asciicrlf>
+
+when signing use ASCII CRLF format canonicalisation. This strips trailing
+whitespace from all lines, deletes trailing blank lines at EOF and sets
+the encapsulated content type. This option is normally used with detached
+content and an output signature format of DER. This option is not normally
+needed when verifying as it is enabled automatically if the encapsulated
+content format is detected.
+
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
=item B<-certsout file>
-any certificates contained in to the message are written to B<file>.
+any certificates contained in the message are written to B<file>.
=item B<-signer file>
=item B<-recip file>
-the recipients certificate when decrypting a message. This certificate
-must match one of the recipients of the message or an error occurs.
+when decrypting a message this specifies the recipients certificate. The
+certificate must match one of the recipients of the message or an error
+occurs.
+
+When encrypting a message this option may be used multiple times to specify
+each recipient. This form B<must> be used if customised parameters are
+required (for example to specify RSA-OAEP).
=item B<-keyid>
=item B<-receipt_request_all -receipt_request_first>
for B<-sign> option include a signed receipt request. Indicate requests should
-be provided by all receipient or first tier recipients (those mailed directly
+be provided by all recipient or first tier recipients (those mailed directly
and not from a mailing list). Ignored it B<-receipt_request_from> is included.
=item B<-receipt_request_from emailaddress>
=item B<-receipt_request_to emailaddress>
-Add an explicit email address where signed receipts should be sent to. This
+Add an explicit email address where signed receipts should be sent to. This
option B<must> but supplied if a signed receipt it requested.
=item B<-receipt_request_print>
specify symmetric key to use. The key must be supplied in hex format and be
consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
-B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
+B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
content encryption key using an AES key in the B<KEKRecipientInfo> type.
set the encapsulated content type to B<type> if not supplied the B<Data> type
is used. The B<type> argument can be any valid OID name in either text or
-numerical format.
+numerical format.
=item B<-inkey file>
the B<-recip> or B<-signer> file. When signing this option can be used
multiple times to specify successive keys.
+=item B<-keyopt name:opt>
+
+for signing and encryption this option can be used multiple times to
+set customised parameters for the preceding key or certificate. It can
+currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
+or to modify default parameters for ECDH.
+
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
-Multiple files can be specified separated by a OS-dependent character.
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
-a message.
+a message.
=item B<-to, -from, -subject>
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
+B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set various certificate chain validation options. See the
+L<verify(1)> manual page for details.
+
=back
=head1 NOTES
achieve the correct format.
The supplied message to be signed or encrypted must include the
-necessary MIME headers or many S/MIME clients wont display it
+necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
signer. This means that attributes must be present in at least one existing
signer using the same message digest or this operation will fail.
-The B<-stream> and B<-indef> options enable experimental streaming I/O support.
+The B<-stream> and B<-indef> options enable streaming I/O support.
As a result the encoding is BER using indefinite length constructed encoding
and no longer DER. Streaming is supported for the B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
since the content is no longer part of the CMS structure the encoding
remains DER.
+If the B<-decrypt> option is used without a recipient certificate then an
+attempt is made to locate the recipient by trying each potential recipient
+in turn using the supplied private key. To thwart the MMA attack
+(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
+tried whether they succeed or not and if no recipients match the message
+is "decrypted" using a random key which will typically output garbage.
+The B<-debug_decrypt> option can be used to disable the MMA attack protection
+and return an error if no recipient can be found: this option should be used
+with caution. For a fuller description see L<CMS_decrypt(3)>).
+
=head1 EXIT CODES
=over 4
-=item 0
+=item Z<>0
the operation was completely successfully.
-=item 1
+=item Z<>1
an error occurred parsing the command options.
-=item 2
+=item Z<>2
one of the input files could not be read.
-=item 3
+=item Z<>3
an error occurred creating the CMS file or when reading the MIME
message.
-=item 4
+=item Z<>4
an error occurred decrypting or verifying the message.
-=item 5
+=item Z<>5
the message was verified correctly but an error occurred writing out
the signers certificates.
The B<-secretkey> option when used with B<-encrypt>.
+The use of PSS with B<-sign>.
+
+The use of OAEP or non-RSA keys with B<-encrypt>.
+
Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
be processed by the older B<smime> command.
Create a cleartext signed message:
openssl cms -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem
+ -signer mycert.pem
Create an opaque signed message
openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
- -signer mycert.pem
+ -signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl cms -sign -in in.txt -text -out mail.msg \
- -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
+ -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers, use key identifier:
openssl cms -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem -signer othercert.pem -keyid
+ -signer mycert.pem -signer othercert.pem -keyid
Send a signed message under Unix directly to sendmail, including headers:
openssl cms -sign -in in.txt -text -signer mycert.pem \
- -from steve@openssl.org -to someone@somewhere \
- -subject "Signed message" | sendmail someone@somewhere
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
Send encrypted mail using triple DES:
openssl cms -encrypt -in in.txt -from steve@openssl.org \
- -to someone@somewhere -subject "Encrypted message" \
- -des3 user.pem -out mail.msg
+ -to someone@somewhere -subject "Encrypted message" \
+ -des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl cms -sign -in ml.txt -signer my.pem -text \
- | openssl cms -encrypt -out mail.msg \
- -from steve@openssl.org -to someone@somewhere \
- -subject "Signed and Encrypted message" -des3 user.pem
+ | openssl cms -encrypt -out mail.msg \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
-----BEGIN PKCS7-----
-----END PKCS7-----
-and using the command,
+and using the command,
openssl cms -verify -inform PEM -in signature.pem -content content.txt
openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
+Sign mail using RSA-PSS:
+
+ openssl cms -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem -keyopt rsa_padding_mode:pss
+
+Create encrypted mail using RSA-OAEP:
+
+ openssl cms -encrypt -in plain.txt -out mail.msg \
+ -recip cert.pem -keyopt rsa_padding_mode:oaep
+
+Use SHA256 KDF with an ECDH certificate:
+
+ openssl cms -encrypt -in plain.txt -out mail.msg \
+ -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
+
=head1 BUGS
The MIME parser isn't very clever: it seems to handle most messages that I've
=head1 HISTORY
The use of multiple B<-signer> options and the B<-resign> command were first
-added in OpenSSL 0.9.9
+added in OpenSSL 1.0.0
+
+The B<keyopt> option was first added in OpenSSL 1.1.0
+
+The use of B<-recip> to specify the recipient when encrypting mail was first
+added to OpenSSL 1.1.0
+
+Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
+
+The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
+to OpenSSL 1.1.0.
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
=cut
projects / oweals / openssl.git / blobdiff