X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fcms.pod;h=a1c896c1e3c32276c26a9f2cfcfb6892ea8ae09a;hp=18fe43caa96b1b66bc37fdad46133046a54628ec;hb=0dd5b94aeb77c2982bdf6886962b7a8491c6c9ed;hpb=4bf4a6501c6ca3fa1853f07c82e0e9cfe22dee45

diff --git a/doc/apps/cms.pod b/doc/apps/cms.pod
index 18fe43caa9..a1c896c1e3 100644
--- a/doc/apps/cms.pod
+++ b/doc/apps/cms.pod
@@ -43,6 +43,7 @@ B<openssl> B<cms>
 [B<-noattr>]
 [B<-nosmimecap>]
 [B<-binary>]
+[B<-asciicrlf>]
 [B<-nodetach>]
 [B<-certfile file>]
 [B<-certsout file>]
@@ -57,6 +58,7 @@ B<openssl> B<cms>
 [B<-secretkeyid id>]
 [B<-econtent_type type>]
 [B<-inkey file>]
+[B<-keyopt name:parameter>]
 [B<-passin arg>]
 [B<-rand file(s)>]
 [B<cert.pem...>]
@@ -90,6 +92,11 @@ 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
@@ -290,6 +297,15 @@ 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<-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
@@ -385,7 +401,8 @@ multiple times to specify successive keys.
 
 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 or RSA-OAEP for encryption.
+currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
+or to modify default parameters for ECDH.
 
 =item B<-passin arg>
 
@@ -457,32 +474,42 @@ 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 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.
@@ -504,6 +531,10 @@ The B<-compress> option.
 
 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.
 
@@ -591,9 +622,14 @@ Sign mail using RSA-PSS:
 
 Create encrypted mail using RSA-OAEP:
 
- openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg \
+ 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
@@ -626,4 +662,7 @@ 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