Add suppot for ASCII with CRLF canonicalisation.

[openssl.git] / doc / apps / cms.pod

diff --git a/doc/apps/cms.pod b/doc/apps/cms.pod
index 520279eeabcdf83c7a45d4f5bc3366a67064bd91..cfdc4cb13452b333be540542f054bf3dc8263637 100644 (file)
--- 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...>]
@@ -290,6 +292,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
@@ -316,8 +327,13 @@ 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.
+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>
 
@@ -376,6 +392,13 @@ 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<-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>
@@ -401,7 +424,7 @@ 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>
+=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.
@@ -450,28 +473,28 @@ remains DER.
 
 =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.
@@ -493,6 +516,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.
 
@@ -573,6 +600,21 @@ Add a signer to an existing message:
 
  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
@@ -596,7 +638,16 @@ 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
+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