svn merge -r514:HEAD ^/branches/released .

1 files changed, 602 insertions, 0 deletions

diff --git a/openssl/doc/apps/cms.pod b/openssl/doc/apps/cms.pod
new file mode 100644
index 000000000..a09588a18
--- /dev/null
+++ b/openssl/doc/apps/cms.pod
@@ -0,0 +1,602 @@
+=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<-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>.
+
+=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<-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>
+
+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.
+
+=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 1.0.0
+
+
+=cut