[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
-[B<-resign>]
[B<-verify>]
[B<-cmsout>]
-[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<-in file>]
-[B<-certfile file>]
-[B<-signer file>]
-[B<-recip file>]
+[B<-resign>]
+[B<-data_create>]
+[B<-data_out>]
+[B<-digest_create>]
+[B<-digest_verify>]
+[B<-compress>]
+[B<-uncompress>]
+[B<-EncryptedData_encrypt>]
+[B<-sign_receipt>]
+[B<-verify_receipt receipt>]
+[B<-in filename>]
[B<-inform SMIME|PEM|DER>]
-[B<-passin arg>]
-[B<-inkey file>]
-[B<-out file>]
+[B<-rctform SMIME|PEM|DER>]
+[B<-out filename>]
[B<-outform SMIME|PEM|DER>]
-[B<-content file>]
-[B<-to addr>]
-[B<-from ad>]
-[B<-subject s>]
-[B<-text>]
-[B<-indef>]
+[B<-stream -indef -noindef>]
[B<-noindef>]
-[B<-stream>]
-[B<-rand file(s)>]
+[B<-content filename>]
+[B<-text>]
+[B<-noout>]
+[B<-print>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+[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<-issuer_checks>]
+[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<-use_deltas>]
+[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<-[cipher]>]
+[B<-nointern>]
+[B<-no_signer_cert_verify>]
+[B<-nocerts>]
+[B<-noattr>]
+[B<-nosmimecap>]
+[B<-binary>]
+[B<-asciicrlf>]
+[B<-nodetach>]
+[B<-certfile file>]
+[B<-certsout file>]
+[B<-signer file>]
+[B<-recip file>]
+[B<-keyid>]
+[B<-receipt_request_all -receipt_request_first>]
+[B<-receipt_request_from emailaddress>]
+[B<-receipt_request_to emailaddress>]
+[B<-receipt_request_print>]
+[B<-secretkey key>]
+[B<-secretkeyid id>]
+[B<-econtent_type type>]
+[B<-inkey file>]
+[B<-keyopt name:parameter>]
+[B<-passin arg>]
+[B<-rand file(s)>]
+[B<cert.pem...>]
+[B<-to addr>]
+[B<-from addr>]
+[B<-subject subj>]
[cert.pem]...
=head1 DESCRIPTION
=head1 COMMAND OPTIONS
-There are twelve operation options that set the type of operation to be
-performed. The meaning of the other options varies according to the operation
+There are fourteen operation options that set the type of operation to be
+performed. The meaning of the other options varies according to the operation
type.
=over 4
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
+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>
+contain the original receipt request. Functionality is otherwise similar
+to the B<-verify> operation.
+
=item B<-in filename>
-the input message to be encrypted or signed or the MIME message to
-be decrypted or verified.
+the input message to be encrypted or signed or the message to be decrypted
+or verified.
=item B<-inform SMIME|PEM|DER>
structure, if no CMS structure is being input (for example with
B<-encrypt> or B<-sign>) this option has no effect.
+=item B<-rctform SMIME|PEM|DER>
+
+specify the format for a signed receipt for use with the B<-receipt_verify>
+operation.
+
=item B<-out filename>
the message text that has been decrypted or verified or the output MIME
=item B<-outform SMIME|PEM|DER>
this specifies the output format for the CMS structure. The default
-is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
+is B<SMIME> which write
s an S/MIME format message. B<PEM> and B<DER>
format change this to write PEM and DER format CMS structures
instead. This currently only affects the output format of the CMS
structure, if no CMS structure is being output (for example with
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
+=item B<-noout>
+
+for the B<-cmsout> operation do not output the parsed CMS structure. This
+is useful when combined with the B<-print> option or if the syntax of the CMS
+structure is being checked.
+
+=item B<-print>
+
+for the B<-cmsout> operation print out all fields of the CMS structure. This
+is mainly useful for testing purposes.
+
=item B<-CAfile file>
a file containing trusted CA certificates, only used with B<-verify>.
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
+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>.
+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
B<-EncryptedData_create> commands.
only the certificates specified in the B<-certfile> option are used.
The supplied certificates can still be used as untrusted CAs however.
-=item B<-noverify>
+=item B<-no_signer_cert_verify>
do not verify the signers certificate of a signed message.
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<-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
be included with the message. When verifying these will be searched for
the signers certificates. The certificates should be in PEM format.
+=item B<-certsout file>
+
+any certificates contained in the message are written to B<file>.
+
=item B<-signer file>
a signing certificate when signing or resigning a message, this option can be
=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>
serial number. The supplied certificate B<must> include a subject key
identifier extension. Supported by B<-sign> and B<-encrypt> options.
+=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
+and not from a mailing list). Ignored it B<-receipt_request_from> is included.
+
+=item B<-receipt_request_from emailaddress>
+
+for B<-sign> option include a signed receipt request. Add an explicit email
+address where receipts should be supplied.
+
+=item B<-receipt_request_to emailaddress>
+
+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>
+
+For the B<-verify> operation print out the contents of any signed receipt
+requests.
+
=item B<-secretkey key>
specify symmetric key to use. The key must be supplied in hex format and be
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>
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<-issuer_checks>, 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<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
+B<-verify_name>, B<-x509_strict>
+
+Set various certificate chain valiadition options. See the
+L<B<verify>|verify(1)> manual page for details.
+
=back
=head1 NOTES
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)|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.
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.
=cut
projects / oweals / openssl.git / blobdiff