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 | |
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')
-rw-r--r-- | doc/man1/openssl-smime.pod | 501 |
1 files changed, 0 insertions, 501 deletions
diff --git a/doc/man1/openssl-smime.pod b/doc/man1/openssl-smime.pod deleted file mode 100644 index 935a89b678..0000000000 --- a/doc/man1/openssl-smime.pod +++ /dev/null @@ -1,501 +0,0 @@ -=pod - -=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<-CAfile> I<file>] -[B<-CApath> I<dir>] -[B<-no-CAfile>] -[B<-no-CApath>] -[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<-rand> I<files>] -[B<-writerand> I<file>] -[B<-md> I<digest>] -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<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath> - -See L<openssl(1)/Trusted Certificate Options> for more information. - -=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<-rand> I<files>, B<-writerand> I<file> - -See L<openssl(1)/Random State Options> for more information. - -=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. - -=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 |