X-Git-Url: https://code.wpia.club/?a=blobdiff_plain;f=lib%2Fopenssl%2Fdoc%2Fapps%2Fcms.pod;h=d5529bea6bc91ea8fdcc100600be57acc6b8af66;hb=02ed66432c92de70694700164f986190aad3cbc5;hp=75b698834a2877c1a8417dcd1a16185775b2ce04;hpb=f69f31caeda734d6d9c8ab00e693671ac7512bea;p=cassiopeia.git diff --git a/lib/openssl/doc/apps/cms.pod b/lib/openssl/doc/apps/cms.pod index 75b6988..d5529be 100644 --- a/lib/openssl/doc/apps/cms.pod +++ b/lib/openssl/doc/apps/cms.pod @@ -7,6 +7,7 @@ cms - CMS utility =head1 SYNOPSIS B B +[B<-help>] [B<-encrypt>] [B<-decrypt>] [B<-sign>] @@ -35,6 +36,36 @@ B B [B<-print>] [B<-CAfile file>] [B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] [B<-md digest>] [B<-[cipher]>] [B<-nointern>] @@ -43,6 +74,8 @@ B B [B<-noattr>] [B<-nosmimecap>] [B<-binary>] +[B<-crlfeol>] +[B<-asciicrlf>] [B<-nodetach>] [B<-certfile file>] [B<-certsout file>] @@ -57,6 +90,7 @@ B B [B<-secretkeyid id>] [B<-econtent_type type>] [B<-inkey file>] +[B<-keyopt name:parameter>] [B<-passin arg>] [B<-rand file(s)>] [B] @@ -78,12 +112,19 @@ type. =over 4 +=item B<-help> + +Print out a usage message. + =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 EnvelopedData. +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 @@ -148,13 +189,13 @@ B type and output the content. =item B<-sign_receipt> -Generate and output a signed receipt for the supplied message. The input +Generate and output a signed receipt for the supplied message. The input message B 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. The input message B +Verify a signed receipt in filename B. The input message B contain the original receipt request. Functionality is otherwise similar to the B<-verify> operation. @@ -218,7 +259,7 @@ is S/MIME and it uses the multipart/signed MIME content type. 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 +off text headers: if the decrypted or verified message is not of MIME type text/plain then an error occurs. =item B<-noout> @@ -243,6 +284,14 @@ B<-verify>. This directory must be a standard certificate directory: that is a hash of each subject name (using B) should be linked to each certificate. +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + =item B<-md digest> digest algorithm to use when signing or resigning. If not present then the @@ -252,11 +301,11 @@ default digest algorithm for the signing key will be used (usually SHA1). 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|enc(1)> for a list of ciphers +EVP_get_cipherbyname() function) can also be used preceded by a dash, for +example B<-aes-128-cbc>. See L|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 +If not specified triple DES is used. Only used with B<-encrypt> and B<-EncryptedData_create> commands. =item B<-nointern> @@ -295,6 +344,20 @@ 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<-crlfeol> + +normally the output file uses a single B as end of line. When this +option is present B is used instead. + +=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 @@ -321,8 +384,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 be used if customised parameters are +required (for example to specify RSA-OAEP). =item B<-keyid> @@ -333,7 +401,7 @@ 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 +be provided by all recipient 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> @@ -343,7 +411,7 @@ 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 +Add an explicit email address where signed receipts should be sent to. This option B but supplied if a signed receipt it requested. =item B<-receipt_request_print> @@ -355,7 +423,7 @@ requests. 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 +B<-EncryptedData_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 type. @@ -371,7 +439,7 @@ B structures. set the encapsulated content type to B if not supplied the B type is used. The B argument can be any valid OID name in either text or -numerical format. +numerical format. =item B<-inkey file> @@ -381,23 +449,30 @@ 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 -see the B section in L. +see the B section in L. =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). -Multiple files can be specified separated by a OS-dependent character. +generator, or an EGD socket (see L). +Multiple files can be specified separated by an OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. =item B one or more certificates of message recipients: used when encrypting -a message. +a message. =item B<-to, -from, -subject> @@ -406,10 +481,16 @@ 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> +=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, +B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> -Set various certificate chain valiadition option. See the -L|verify(1)> manual page for details. +Set various certificate chain validation options. See the +L manual page for details. =back @@ -421,7 +502,7 @@ 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 +necessary MIME headers or many S/MIME clients won't display it properly (if at all). You can use the B<-text> option to automatically add plain text headers. @@ -442,7 +523,7 @@ 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. +The B<-stream> and B<-indef> options enable 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. @@ -456,10 +537,10 @@ 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. +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). +with caution. For a fuller description see L). =head1 EXIT CODES @@ -508,6 +589,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 command. @@ -516,29 +601,29 @@ be processed by the older B command. Create a cleartext signed message: openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem + -signer mycert.pem Create an opaque signed message openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ - -signer mycert.pem + -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 + -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 + -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 + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed message" | sendmail someone@somewhere Verify a message and extract the signer's certificate if successful: @@ -547,15 +632,15 @@ Verify a message and extract the signer's certificate if successful: 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 + -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 + | 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. @@ -572,7 +657,7 @@ it with: -----BEGIN PKCS7----- -----END PKCS7----- -and using the command, +and using the command, openssl cms -verify -inform PEM -in signature.pem -content content.txt @@ -588,6 +673,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 @@ -613,5 +713,25 @@ No revocation checking is done on the signer's certificate. The use of multiple B<-signer> options and the B<-resign> command were first added in OpenSSL 1.0.0 +The B 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. + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. =cut