mirror of https://github.com/openssl/openssl.git
Preliminary documentation for CMS utility.
This commit is contained in:
Dr. Stephen Henson
parent
5ffba305c8
commit
7122aafce5
|
|
@ -0,0 +1,524 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
cms - CMS utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<cms>
|
||||
[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<-inform SMIME|PEM|DER>]
|
||||
[B<-passin arg>]
|
||||
[B<-inkey file>]
|
||||
[B<-out file>]
|
||||
[B<-outform SMIME|PEM|DER>]
|
||||
[B<-content file>]
|
||||
[B<-to addr>]
|
||||
[B<-from ad>]
|
||||
[B<-subject s>]
|
||||
[B<-text>]
|
||||
[B<-indef>]
|
||||
[B<-noindef>]
|
||||
[B<-stream>]
|
||||
[B<-rand file(s)>]
|
||||
[B<-md digest>]
|
||||
[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 twelve 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>.
|
||||
|
||||
=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<-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 suppled content using supplied symmetric key and algorithm using a CMS
|
||||
B<EncrytedData> type and output the content.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
the input message to be encrypted or signed or the MIME 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<-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 write 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<-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<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256>
|
||||
|
||||
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>.
|
||||
|
||||
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<-noverify>
|
||||
|
||||
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<-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<-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.
|
||||
|
||||
=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.
|
||||
|
||||
=head1 EXIT CODES
|
||||
|
||||
=over 4
|
||||
|
||||
=item 0
|
||||
|
||||
the operation was completely successfully.
|
||||
|
||||
=item 1
|
||||
|
||||
an error occurred parsing the command options.
|
||||
|
||||
=item 2
|
||||
|
||||
one of the input files could not be read.
|
||||
|
||||
=item 3
|
||||
|
||||
an error occurred creating the CMS file or when reading the MIME
|
||||
message.
|
||||
|
||||
=item 4
|
||||
|
||||
an error occurred decrypting or verifying the message.
|
||||
|
||||
=item 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 0.9.9
|
||||
|
||||
|
||||
=cut
|
||||
Loading…
Reference in New Issue