313 lines
9.3 KiB
Text
313 lines
9.3 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
smime - S/MIME utility
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<openssl> B<smime>
|
|
[B<-encrypt>]
|
|
[B<-decrypt>]
|
|
[B<-sign>]
|
|
[B<-verify>]
|
|
[B<-pk7out>]
|
|
[B<-des>]
|
|
[B<-des3>]
|
|
[B<-rc2-40>]
|
|
[B<-rc2-64>]
|
|
[B<-rc2-128>]
|
|
[B<-in file>]
|
|
[B<-certfile file>]
|
|
[B<-signer file>]
|
|
[B<-recip file>]
|
|
[B<-in file>]
|
|
[B<-inkey file>]
|
|
[B<-out file>]
|
|
[B<-to addr>]
|
|
[B<-from ad>]
|
|
[B<-subject s>]
|
|
[B<-text>]
|
|
[cert.pem]...
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
|
|
verify S/MIME messages.
|
|
|
|
=head1 COMMAND OPTIONS
|
|
|
|
There are five 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<-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.
|
|
|
|
=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<-in filename>
|
|
|
|
the input message to be encrypted or signed or the MIME message to
|
|
be decrypted or verified.
|
|
|
|
=item B<-out filename>
|
|
|
|
the message text that has been decrypted or verified or the output MIME
|
|
format message that has been signed or verified.
|
|
|
|
=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 file>
|
|
|
|
a file containing trusted CA certificates, only used with B<-verify>.
|
|
|
|
=item B<-CApath dir>
|
|
|
|
a directory containing trusted CA certificates, only used with
|
|
B<-verify>. This directory must be a standard certificate directory: that
|
|
is a hash of each subject name (using B<x509 -hash>) should be linked
|
|
to each certificate.
|
|
|
|
=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128>
|
|
|
|
the encryption algorithm to use. DES (56 bits), triple DES (168 bits)
|
|
or 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 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 certfificates: 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<-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 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 file>
|
|
|
|
the signers certificate when signing a message. If a message is
|
|
being verified then the signers certificates will be written to this
|
|
file if the 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.
|
|
|
|
=item B<-inkey file>
|
|
|
|
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.
|
|
|
|
=item B<cert.pem...>
|
|
|
|
one or more certificates of message recipients: used when encrypting
|
|
a message.
|
|
|
|
=item B<-to, -from, -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.
|
|
|
|
=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 wont 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 mutiple 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.
|
|
|
|
=head1 EXIT CODES
|
|
|
|
=over 4
|
|
|
|
=item 0
|
|
|
|
the operation was completely successfully.
|
|
|
|
=item 1
|
|
|
|
an error occurred parsing the command options.
|
|
|
|
=item 2
|
|
|
|
one of the input files could not be read.
|
|
|
|
=item 3
|
|
|
|
an error occurred creating the PKCS#7 file or when reading the MIME
|
|
message.
|
|
|
|
=item 4
|
|
|
|
an error occurred decrypting or verifying the message.
|
|
|
|
=item 5
|
|
|
|
the message was verified correctly but an error occured 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 and 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
|
|
|
|
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 -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
|
|
|
|
=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.
|
|
|
|
=cut
|