You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
623 lines
20 KiB
623 lines
20 KiB
=pod |
|
|
|
=head1 NAME |
|
|
|
cms - CMS utility |
|
|
|
=head1 SYNOPSIS |
|
|
|
B<openssl> B<cms> |
|
[B<-encrypt>] |
|
[B<-decrypt>] |
|
[B<-sign>] |
|
[B<-verify>] |
|
[B<-cmsout>] |
|
[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<-rctform SMIME|PEM|DER>] |
|
[B<-out filename>] |
|
[B<-outform SMIME|PEM|DER>] |
|
[B<-stream -indef -noindef>] |
|
[B<-noindef>] |
|
[B<-content filename>] |
|
[B<-text>] |
|
[B<-noout>] |
|
[B<-print>] |
|
[B<-CAfile file>] |
|
[B<-CApath dir>] |
|
[B<-no_alt_chains>] |
|
[B<-md digest>] |
|
[B<-[cipher]>] |
|
[B<-nointern>] |
|
[B<-no_signer_cert_verify>] |
|
[B<-nocerts>] |
|
[B<-noattr>] |
|
[B<-nosmimecap>] |
|
[B<-binary>] |
|
[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<-passin arg>] |
|
[B<-rand file(s)>] |
|
[B<cert.pem...>] |
|
[B<-to addr>] |
|
[B<-from addr>] |
|
[B<-subject subj>] |
|
[cert.pem]... |
|
|
|
=head1 DESCRIPTION |
|
|
|
The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and |
|
verify, compress and uncompress S/MIME messages. |
|
|
|
=head1 COMMAND OPTIONS |
|
|
|
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 |
|
|
|
=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 |
|
the message to be signed. The signed message in MIME format is written |
|
to the output file. |
|
|
|
=item B<-verify> |
|
|
|
verify signed mail. Expects a signed mail message on input and outputs |
|
the signed data. Both clear text and opaque signing is supported. |
|
|
|
=item B<-cmsout> |
|
|
|
takes an input message and writes out a PEM encoded CMS structure. |
|
|
|
=item B<-resign> |
|
|
|
resign a message: take an existing message and one or more new signers. |
|
|
|
=item B<-data_create> |
|
|
|
Create a CMS B<Data> type. |
|
|
|
=item B<-data_out> |
|
|
|
B<Data> type and output the content. |
|
|
|
=item B<-digest_create> |
|
|
|
Create a CMS B<DigestedData> type. |
|
|
|
=item B<-digest_verify> |
|
|
|
Verify a CMS B<DigestedData> type and output the content. |
|
|
|
=item B<-compress> |
|
|
|
Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> |
|
support for this option to work, otherwise it will output an error. |
|
|
|
=item B<-uncompress> |
|
|
|
Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be |
|
compiled with B<zlib> support for this option to work, otherwise it will |
|
output an error. |
|
|
|
=item B<-EncryptedData_encrypt> |
|
|
|
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 message to be decrypted |
|
or verified. |
|
|
|
=item B<-inform SMIME|PEM|DER> |
|
|
|
this specifies the input format for the CMS structure. The default |
|
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> |
|
format change this to expect PEM and DER format CMS structures |
|
instead. This currently only affects the input format of the CMS |
|
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 |
|
format message that has been signed or verified. |
|
|
|
=item B<-outform SMIME|PEM|DER> |
|
|
|
this specifies the output format for the CMS structure. The default |
|
is B<SMIME> which writes 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 |
|
B<-verify> or B<-decrypt>) this option has no effect. |
|
|
|
=item B<-stream -indef -noindef> |
|
|
|
the B<-stream> and B<-indef> options are equivalent and enable streaming I/O |
|
for encoding operations. This permits single pass processing of data without |
|
the need to hold the entire contents in memory, potentially supporting very |
|
large files. Streaming is automatically set for S/MIME signing with detached |
|
data if the output format is B<SMIME> it is currently off by default for all |
|
other operations. |
|
|
|
=item B<-noindef> |
|
|
|
disable streaming I/O where it would produce and indefinite length constructed |
|
encoding. This option currently has no effect. In future streaming will be |
|
enabled by default on all relevant operations and this option will disable it. |
|
|
|
=item B<-content filename> |
|
|
|
This specifies a file containing the detached content, this is only |
|
useful with the B<-verify> command. This is only usable if the CMS |
|
structure is using the detached signature form where the content is |
|
not included. This option will override any content if the input format |
|
is S/MIME and it uses the multipart/signed MIME content type. |
|
|
|
=item B<-text> |
|
|
|
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 |
|
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>. |
|
|
|
=item B<-CApath dir> |
|
|
|
a directory containing trusted CA certificates, only used with |
|
B<-verify>. This directory must be a standard certificate directory: that |
|
is a hash of each subject name (using B<x509 -hash>) should be linked |
|
to each certificate. |
|
|
|
=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<-[cipher]> |
|
|
|
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 |
|
B<-EncryptedData_create> commands. |
|
|
|
=item B<-nointern> |
|
|
|
when verifying a message normally certificates (if any) included in |
|
the message are searched for the signing certificate. With this option |
|
only the certificates specified in the B<-certfile> option are used. |
|
The supplied certificates can still be used as untrusted CAs however. |
|
|
|
=item B<-no_signer_cert_verify> |
|
|
|
do not verify the signers certificate of a signed message. |
|
|
|
=item B<-nocerts> |
|
|
|
when signing a message the signer's certificate is normally included |
|
with this option it is excluded. This will reduce the size of the |
|
signed message but the verifier must have a copy of the signers certificate |
|
available locally (passed using the B<-certfile> option for example). |
|
|
|
=item B<-noattr> |
|
|
|
normally when a message is signed a set of attributes are included which |
|
include the signing time and supported symmetric algorithms. With this |
|
option they are not included. |
|
|
|
=item B<-nosmimecap> |
|
|
|
exclude the list of supported algorithms from signed attributes, other options |
|
such as signing time and content type are still included. |
|
|
|
=item B<-binary> |
|
|
|
normally the input message is converted to "canonical" format which is |
|
effectively using CR and LF as end of line: as required by the S/MIME |
|
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<-nodetach> |
|
|
|
when signing a message use opaque signing: this form is more resistant |
|
to translation by mail relays but it cannot be read by mail agents that |
|
do not support S/MIME. Without this option cleartext signing with |
|
the MIME type multipart/signed is used. |
|
|
|
=item B<-certfile file> |
|
|
|
allows additional certificates to be specified. When signing these will |
|
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 |
|
used multiple times if more than one signer is required. If a message is being |
|
verified then the signers certificates will be written to this file if the |
|
verification was successful. |
|
|
|
=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. |
|
|
|
=item B<-keyid> |
|
|
|
use subject key identifier to identify certificates instead of issuer name and |
|
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 |
|
consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> |
|
B<-EncrryptedData_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. |
|
|
|
=item B<-secretkeyid id> |
|
|
|
the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. |
|
This option B<must> be present if the B<-secretkey> option is used with |
|
B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the |
|
relevant key if it is not supplied then an attempt is used to decrypt any |
|
B<KEKRecipientInfo> structures. |
|
|
|
=item B<-econtent_type 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. |
|
|
|
=item B<-inkey file> |
|
|
|
the private key to use when signing or decrypting. This must match the |
|
corresponding certificate. If this option is not specified then the |
|
private key must be included in the certificate file specified with |
|
the B<-recip> or B<-signer> file. When signing this option can be used |
|
multiple times to specify successive keys. |
|
|
|
=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)>. |
|
|
|
=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. |
|
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. |
|
|
|
=item B<-to, -from, -subject> |
|
|
|
the relevant mail headers. These are included outside the signed |
|
portion of a message so they may be included manually. If signing |
|
then many S/MIME mail clients check the signers certificate's email |
|
address matches that specified in the From: address. |
|
|
|
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> |
|
|
|
Set various certificate chain valiadition option. See the |
|
L<B<verify>|verify(1)> manual page for details. |
|
|
|
=back |
|
|
|
=head1 NOTES |
|
|
|
The MIME message must be sent without any blank lines between the |
|
headers and the output. Some mail programs will automatically add |
|
a blank line. Piping the mail directly to sendmail is one way to |
|
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 |
|
properly (if at all). You can use the B<-text> option to automatically |
|
add plain text headers. |
|
|
|
A "signed and encrypted" message is one where a signed message is |
|
then encrypted. This can be produced by encrypting an already signed |
|
message: see the examples section. |
|
|
|
This version of the program only allows one signer per message but it |
|
will verify multiple signers on received messages. Some S/MIME clients |
|
choke if a message contains multiple signers. It is possible to sign |
|
messages "in parallel" by signing an already signed message. |
|
|
|
The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME |
|
clients. Strictly speaking these process CMS enveloped data: CMS |
|
encrypted data is used for other purposes. |
|
|
|
The B<-resign> option uses an existing message digest when adding a new |
|
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. |
|
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. |
|
|
|
Streaming is always used for the B<-sign> operation with detached data but |
|
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 Z<>0 |
|
|
|
the operation was completely successfully. |
|
|
|
=item Z<>1 |
|
|
|
an error occurred parsing the command options. |
|
|
|
=item Z<>2 |
|
|
|
one of the input files could not be read. |
|
|
|
=item Z<>3 |
|
|
|
an error occurred creating the CMS file or when reading the MIME |
|
message. |
|
|
|
=item Z<>4 |
|
|
|
an error occurred decrypting or verifying the message. |
|
|
|
=item Z<>5 |
|
|
|
the message was verified correctly but an error occurred writing out |
|
the signers certificates. |
|
|
|
=back |
|
|
|
=head1 COMPATIBILITY WITH PKCS#7 format. |
|
|
|
The B<smime> utility can only process the older B<PKCS#7> format. The B<cms> |
|
utility supports Cryptographic Message Syntax format. Use of some features |
|
will result in messages which cannot be processed by applications which only |
|
support the older format. These are detailed below. |
|
|
|
The use of the B<-keyid> option with B<-sign> or B<-encrypt>. |
|
|
|
The B<-outform PEM> option uses different headers. |
|
|
|
The B<-compress> option. |
|
|
|
The B<-secretkey> option when used with B<-encrypt>. |
|
|
|
Additionally the B<-EncryptedData_create> and B<-data_create> type cannot |
|
be processed by the older B<smime> command. |
|
|
|
=head1 EXAMPLES |
|
|
|
Create a cleartext signed message: |
|
|
|
openssl cms -sign -in message.txt -text -out mail.msg \ |
|
-signer mycert.pem |
|
|
|
Create an opaque signed message |
|
|
|
openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ |
|
-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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
Verify a message and extract the signer's certificate if successful: |
|
|
|
openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt |
|
|
|
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 |
|
|
|
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 |
|
|
|
Note: the encryption command does not include the B<-text> option because the |
|
message being encrypted already has MIME headers. |
|
|
|
Decrypt mail: |
|
|
|
openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem |
|
|
|
The output from Netscape form signing is a PKCS#7 structure with the |
|
detached signature format. You can use this program to verify the |
|
signature by line wrapping the base64 encoded structure and surrounding |
|
it with: |
|
|
|
-----BEGIN PKCS7----- |
|
-----END PKCS7----- |
|
|
|
and using the command, |
|
|
|
openssl cms -verify -inform PEM -in signature.pem -content content.txt |
|
|
|
alternatively you can base64 decode the signature and use |
|
|
|
openssl cms -verify -inform DER -in signature.der -content content.txt |
|
|
|
Create an encrypted message using 128 bit Camellia: |
|
|
|
openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem |
|
|
|
Add a signer to an existing message: |
|
|
|
openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg |
|
|
|
=head1 BUGS |
|
|
|
The MIME parser isn't very clever: it seems to handle most messages that I've |
|
thrown at it but it may choke on others. |
|
|
|
The code currently will only write out the signer's certificate to a file: if |
|
the signer has a separate encryption certificate this must be manually |
|
extracted. There should be some heuristic that determines the correct |
|
encryption certificate. |
|
|
|
Ideally a database should be maintained of a certificates for each email |
|
address. |
|
|
|
The code doesn't currently take note of the permitted symmetric encryption |
|
algorithms as supplied in the SMIMECapabilities signed attribute. this means the |
|
user has to manually include the correct encryption algorithm. It should store |
|
the list of permitted ciphers in a database and only use those. |
|
|
|
No revocation checking is done on the signer's certificate. |
|
|
|
=head1 HISTORY |
|
|
|
The use of multiple B<-signer> options and the B<-resign> command were first |
|
added in OpenSSL 1.0.0 |
|
|
|
|
|
The -no_alt_chains options was first added to OpenSSL 1.0.1n and 1.0.2b. |
|
|
|
=cut
|
|
|