diff options
author | Rich Salz <rsalz@akamai.com> | 2019-10-12 17:45:56 -0400 |
---|---|---|
committer | Tomas Mraz <tmraz@fedoraproject.org> | 2019-10-31 14:19:29 +0100 |
commit | 9fcb9702fba8aa135945f96aefddf050a6f4f11d (patch) | |
tree | 5fa0e0061ca70c9b0678636ee68c713653e7dba8 /doc/man1/openssl-smime.pod.in | |
parent | fb1ecf85c9f732e5827771ff243d7a70e06ce112 (diff) |
Infrastructure for templated doc in POD files
Use new doc-build capabilities
Add -i flag to dofile.
Add doc/man1 to SUBDIRS for the new templated doc files
Rewrite commit a397aca (merged from PR 10118) to use the doc-template stuff.
Put template references in common place
Template options and text come at the end of command-specific options:
opt_x, opt_trust, opt_r (in that order).
Refactor xchain options.
Do doc-nits after building generated sources.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10159)
Diffstat (limited to 'doc/man1/openssl-smime.pod.in')
-rw-r--r-- | doc/man1/openssl-smime.pod.in | 498 |
1 files changed, 498 insertions, 0 deletions
diff --git a/doc/man1/openssl-smime.pod.in b/doc/man1/openssl-smime.pod.in new file mode 100644 index 0000000000..4e07af3860 --- /dev/null +++ b/doc/man1/openssl-smime.pod.in @@ -0,0 +1,498 @@ +=pod + +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + +=head1 NAME + +openssl-smime - S/MIME utility + +=head1 SYNOPSIS + +B<openssl> B<smime> +[B<-help>] +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-resign>] +[B<-verify>] +[B<-pk7out>] +[B<-binary>] +[B<-crlfeol>] +[B<-I<cipher>>] +[B<-in> I<file>] +[B<-attime> I<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<-partial_chain>] +[B<-policy> I<arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose> I<purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level> I<num>] +[B<-verify_depth> I<num>] +[B<-verify_email> I<email>] +[B<-verify_hostname> I<hostname>] +[B<-verify_ip> I<ip>] +[B<-verify_name> I<name>] +[B<-x509_strict>] +[B<-certfile> I<file>] +[B<-signer> I<file>] +[B<-recip> I< file>] +[B<-inform> B<DER>|B<PEM>|B<SMIME>] +[B<-outform> B<DER>|B<PEM>|B<SMIME>] +[B<-keyform> B<DER>|B<PEM>|B<ENGINE>] +[B<-passin> I<arg>] +[B<-inkey> I<file_or_id>] +[B<-out> I<file>] +[B<-content> I<file>] +[B<-to> I<addr>] +[B<-from> I<ad>] +[B<-subject> I<s>] +[B<-text>] +[B<-indef>] +[B<-noindef>] +[B<-stream>] +[B<-md> I<digest>] +{- $OpenSSL::safe::opt_trust_synopsis -} +{- $OpenSSL::safe::opt_r_synopsis -} +I<cert.pem> ... + +=for openssl ifdef engine + +=head1 DESCRIPTION + +This command handles S/MIME mail. It can encrypt, decrypt, sign +and verify S/MIME messages. + +=head1 OPTIONS + +There are six 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<-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. + +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 +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<-pk7out> + +Takes an input message and writes out a PEM encoded PKCS#7 structure. + +=item B<-resign> + +Resign a message: take an existing message and one or more new signers. + +=item B<-in> I<filename> + +The input message to be encrypted or signed or the MIME message to +be decrypted or verified. + +=item B<-out> I<filename> + +The message text that has been decrypted or verified or the output MIME +format message that has been signed or verified. + +=item B<-inform> B<DER>|B<PEM>|B<SMIME> + +The input format of the PKCS#7 (S/MIME) structure (if one is being read); +the default is B<SMIME>. +See L<openssl(1)/Format Options> for details. + +=item B<-outform> B<DER>|B<PEM>|B<SMIME> + +The output format of the PKCS#7 (S/MIME) structure (if one is being written); +the default is B<SMIME>. +See L<openssl(1)/Format Options> for details. + +=item B<-keyform> B<DER>|B<PEM> + +The key format; the default is B<PEM>. +See L<openssl(1)/Format Options> for details. + +=item B<-stream>, B<-indef>, B<-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> I<filename> + +This specifies a file containing the detached content, this is only +useful with the B<-verify> command. This is only usable if the PKCS#7 +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<-md> I<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<-I<cipher>> + +The encryption algorithm to use. For example DES (56 bits) - B<-des>, +triple DES (168 bits) - B<-des3>, +EVP_get_cipherbyname() function) can also be used preceded by a dash, for +example B<-aes-128-cbc>. See L<openssl-enc(1)> for list of ciphers +supported by your version of OpenSSL. + +If not specified triple DES is used. Only used with B<-encrypt>. + +=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<-nochain> + +Do not do chain verification of signers certificates: that is don't +use the certificates in the signed message as untrusted CAs. + +=item B<-nosigs> + +Don't try to verify the signatures on the 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<-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<-crlfeol> + +Normally the output file uses a single B<LF> as end of line. When this +option is present B<CRLF> is used instead. + +=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> I<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> I<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> I<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<-inkey> I<file_or_id> + +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. +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-passin> I<arg> + +The private key password source. For more information about the format of I<arg> +see L<openssl(1)/Pass Phrase Options>. + +=item B<-to>, B<-from>, B<-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<-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<-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 options of certificate chain verification. See +L<openssl-verify(1)> manual page for details. + +{- $OpenSSL::safe::opt_trust_item -} + +{- $OpenSSL::safe::opt_r_item -} + +=item I<cert.pem> ... + +One or more certificates of message recipients, used when encrypting +a message. + +=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 won't 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 PKCS#7 enveloped data: PKCS#7 +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 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 PKCS#7 structure the encoding +remains DER. + +=head1 EXIT CODES + +=over 4 + +=item Z<>0 + +The operation was completely successfully. + +=item Z<>1 + +An error occurred parsing the command options. + +=item Z<>2 + +One of the input files could not be read. + +=item Z<>3 + +An error occurred creating the PKCS#7 file or when reading the MIME +message. + +=item Z<>4 + +An error occurred decrypting or verifying the message. + +=item Z<>5 + +The message was verified correctly but an error occurred writing out +the signers certificates. + +=back + +=head1 EXAMPLES + +Create a cleartext signed message: + + openssl smime -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem + +Create an opaque signed message: + + openssl smime -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 smime -sign -in in.txt -text -out mail.msg \ + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem + +Create a signed message with two signers: + + openssl smime -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem -signer othercert.pem + +Send a signed message under Unix directly to sendmail, including headers: + + openssl smime -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 smime -verify -in mail.msg -signer user.pem -out signedtext.txt + +Send encrypted mail using triple DES: + + openssl smime -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 smime -sign -in ml.txt -signer my.pem -text \ + | openssl smime -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 smime -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 smime -verify -inform PEM -in signature.pem -content content.txt + +Alternatively you can base64 decode the signature and use: + + openssl smime -verify -inform DER -in signature.der -content content.txt + +Create an encrypted message using 128 bit Camellia: + + openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem + +Add a signer to an existing message: + + openssl smime -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. + +The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 +structures may cause parsing errors. + +=head1 HISTORY + +The use of multiple B<-signer> options and the B<-resign> command were first +added in OpenSSL 1.0.0 + +The -no_alt_chains option was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (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<https://www.openssl.org/source/license.html>. + +=cut |