1=pod 2 3=head1 NAME 4 5openssl-smime, 6smime - S/MIME utility 7 8=head1 SYNOPSIS 9 10B<openssl> B<smime> 11[B<-help>] 12[B<-encrypt>] 13[B<-decrypt>] 14[B<-sign>] 15[B<-resign>] 16[B<-verify>] 17[B<-pk7out>] 18[B<-binary>] 19[B<-crlfeol>] 20[B<-I<cipher>>] 21[B<-in file>] 22[B<-CAfile file>] 23[B<-CApath dir>] 24[B<-no-CAfile>] 25[B<-no-CApath>] 26[B<-attime timestamp>] 27[B<-check_ss_sig>] 28[B<-crl_check>] 29[B<-crl_check_all>] 30[B<-explicit_policy>] 31[B<-extended_crl>] 32[B<-ignore_critical>] 33[B<-inhibit_any>] 34[B<-inhibit_map>] 35[B<-partial_chain>] 36[B<-policy arg>] 37[B<-policy_check>] 38[B<-policy_print>] 39[B<-purpose purpose>] 40[B<-suiteB_128>] 41[B<-suiteB_128_only>] 42[B<-suiteB_192>] 43[B<-trusted_first>] 44[B<-no_alt_chains>] 45[B<-use_deltas>] 46[B<-auth_level num>] 47[B<-verify_depth num>] 48[B<-verify_email email>] 49[B<-verify_hostname hostname>] 50[B<-verify_ip ip>] 51[B<-verify_name name>] 52[B<-x509_strict>] 53[B<-certfile file>] 54[B<-signer file>] 55[B<-recip file>] 56[B<-inform SMIME|PEM|DER>] 57[B<-passin arg>] 58[B<-inkey file_or_id>] 59[B<-out file>] 60[B<-outform SMIME|PEM|DER>] 61[B<-content file>] 62[B<-to addr>] 63[B<-from ad>] 64[B<-subject s>] 65[B<-text>] 66[B<-indef>] 67[B<-noindef>] 68[B<-stream>] 69[B<-rand file...>] 70[B<-writerand file>] 71[B<-md digest>] 72[cert.pem]... 73 74=head1 DESCRIPTION 75 76The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and 77verify S/MIME messages. 78 79=head1 OPTIONS 80 81There are six operation options that set the type of operation to be performed. 82The meaning of the other options varies according to the operation type. 83 84=over 4 85 86=item B<-help> 87 88Print out a usage message. 89 90=item B<-encrypt> 91 92Encrypt mail for the given recipient certificates. Input file is the message 93to be encrypted. The output file is the encrypted mail in MIME format. 94 95Note that no revocation check is done for the recipient cert, so if that 96key has been compromised, others may be able to decrypt the text. 97 98=item B<-decrypt> 99 100Decrypt mail using the supplied certificate and private key. Expects an 101encrypted mail message in MIME format for the input file. The decrypted mail 102is written to the output file. 103 104=item B<-sign> 105 106Sign mail using the supplied certificate and private key. Input file is 107the message to be signed. The signed message in MIME format is written 108to the output file. 109 110=item B<-verify> 111 112Verify signed mail. Expects a signed mail message on input and outputs 113the signed data. Both clear text and opaque signing is supported. 114 115=item B<-pk7out> 116 117Takes an input message and writes out a PEM encoded PKCS#7 structure. 118 119=item B<-resign> 120 121Resign a message: take an existing message and one or more new signers. 122 123=item B<-in filename> 124 125The input message to be encrypted or signed or the MIME message to 126be decrypted or verified. 127 128=item B<-inform SMIME|PEM|DER> 129 130This specifies the input format for the PKCS#7 structure. The default 131is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> 132format change this to expect PEM and DER format PKCS#7 structures 133instead. This currently only affects the input format of the PKCS#7 134structure, if no PKCS#7 structure is being input (for example with 135B<-encrypt> or B<-sign>) this option has no effect. 136 137=item B<-out filename> 138 139The message text that has been decrypted or verified or the output MIME 140format message that has been signed or verified. 141 142=item B<-outform SMIME|PEM|DER> 143 144This specifies the output format for the PKCS#7 structure. The default 145is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> 146format change this to write PEM and DER format PKCS#7 structures 147instead. This currently only affects the output format of the PKCS#7 148structure, if no PKCS#7 structure is being output (for example with 149B<-verify> or B<-decrypt>) this option has no effect. 150 151=item B<-stream -indef -noindef> 152 153The B<-stream> and B<-indef> options are equivalent and enable streaming I/O 154for encoding operations. This permits single pass processing of data without 155the need to hold the entire contents in memory, potentially supporting very 156large files. Streaming is automatically set for S/MIME signing with detached 157data if the output format is B<SMIME> it is currently off by default for all 158other operations. 159 160=item B<-noindef> 161 162Disable streaming I/O where it would produce and indefinite length constructed 163encoding. This option currently has no effect. In future streaming will be 164enabled by default on all relevant operations and this option will disable it. 165 166=item B<-content filename> 167 168This specifies a file containing the detached content, this is only 169useful with the B<-verify> command. This is only usable if the PKCS#7 170structure is using the detached signature form where the content is 171not included. This option will override any content if the input format 172is S/MIME and it uses the multipart/signed MIME content type. 173 174=item B<-text> 175 176This option adds plain text (text/plain) MIME headers to the supplied 177message if encrypting or signing. If decrypting or verifying it strips 178off text headers: if the decrypted or verified message is not of MIME 179type text/plain then an error occurs. 180 181=item B<-CAfile file> 182 183A file containing trusted CA certificates, only used with B<-verify>. 184 185=item B<-CApath dir> 186 187A directory containing trusted CA certificates, only used with 188B<-verify>. This directory must be a standard certificate directory: that 189is a hash of each subject name (using B<x509 -hash>) should be linked 190to each certificate. 191 192=item B<-no-CAfile> 193 194Do not load the trusted CA certificates from the default file location. 195 196=item B<-no-CApath> 197 198Do not load the trusted CA certificates from the default directory location. 199 200=item B<-md digest> 201 202Digest algorithm to use when signing or resigning. If not present then the 203default digest algorithm for the signing key will be used (usually SHA1). 204 205=item B<-I<cipher>> 206 207The encryption algorithm to use. For example DES (56 bits) - B<-des>, 208triple DES (168 bits) - B<-des3>, 209EVP_get_cipherbyname() function) can also be used preceded by a dash, for 210example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers 211supported by your version of OpenSSL. 212 213If not specified triple DES is used. Only used with B<-encrypt>. 214 215=item B<-nointern> 216 217When verifying a message normally certificates (if any) included in 218the message are searched for the signing certificate. With this option 219only the certificates specified in the B<-certfile> option are used. 220The supplied certificates can still be used as untrusted CAs however. 221 222=item B<-noverify> 223 224Do not verify the signers certificate of a signed message. 225 226=item B<-nochain> 227 228Do not do chain verification of signers certificates: that is don't 229use the certificates in the signed message as untrusted CAs. 230 231=item B<-nosigs> 232 233Don't try to verify the signatures on the message. 234 235=item B<-nocerts> 236 237When signing a message the signer's certificate is normally included 238with this option it is excluded. This will reduce the size of the 239signed message but the verifier must have a copy of the signers certificate 240available locally (passed using the B<-certfile> option for example). 241 242=item B<-noattr> 243 244Normally when a message is signed a set of attributes are included which 245include the signing time and supported symmetric algorithms. With this 246option they are not included. 247 248=item B<-binary> 249 250Normally the input message is converted to "canonical" format which is 251effectively using CR and LF as end of line: as required by the S/MIME 252specification. When this option is present no translation occurs. This 253is useful when handling binary data which may not be in MIME format. 254 255=item B<-crlfeol> 256 257Normally the output file uses a single B<LF> as end of line. When this 258option is present B<CRLF> is used instead. 259 260=item B<-nodetach> 261 262When signing a message use opaque signing: this form is more resistant 263to translation by mail relays but it cannot be read by mail agents that 264do not support S/MIME. Without this option cleartext signing with 265the MIME type multipart/signed is used. 266 267=item B<-certfile file> 268 269Allows additional certificates to be specified. When signing these will 270be included with the message. When verifying these will be searched for 271the signers certificates. The certificates should be in PEM format. 272 273=item B<-signer file> 274 275A signing certificate when signing or resigning a message, this option can be 276used multiple times if more than one signer is required. If a message is being 277verified then the signers certificates will be written to this file if the 278verification was successful. 279 280=item B<-recip file> 281 282The recipients certificate when decrypting a message. This certificate 283must match one of the recipients of the message or an error occurs. 284 285=item B<-inkey file_or_id> 286 287The private key to use when signing or decrypting. This must match the 288corresponding certificate. If this option is not specified then the 289private key must be included in the certificate file specified with 290the B<-recip> or B<-signer> file. When signing this option can be used 291multiple times to specify successive keys. 292If no engine is used, the argument is taken as a file; if an engine is 293specified, the argument is given to the engine as a key identifier. 294 295=item B<-passin arg> 296 297The private key password source. For more information about the format of B<arg> 298see L<openssl(1)/Pass Phrase Options>. 299 300=item B<-rand file...> 301 302A file or files containing random data used to seed the random number 303generator. 304Multiple files can be specified separated by an OS-dependent character. 305The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 306all others. 307 308=item [B<-writerand file>] 309 310Writes random data to the specified I<file> upon exit. 311This can be used with a subsequent B<-rand> flag. 312 313=item B<cert.pem...> 314 315One or more certificates of message recipients: used when encrypting 316a message. 317 318=item B<-to, -from, -subject> 319 320The relevant mail headers. These are included outside the signed 321portion of a message so they may be included manually. If signing 322then many S/MIME mail clients check the signers certificate's email 323address matches that specified in the From: address. 324 325=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, 326B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, 327B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>, 328B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, 329B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, 330B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, 331B<-verify_ip>, B<-verify_name>, B<-x509_strict> 332 333Set various options of certificate chain verification. See 334L<verify(1)> manual page for details. 335 336=back 337 338=head1 NOTES 339 340The MIME message must be sent without any blank lines between the 341headers and the output. Some mail programs will automatically add 342a blank line. Piping the mail directly to sendmail is one way to 343achieve the correct format. 344 345The supplied message to be signed or encrypted must include the 346necessary MIME headers or many S/MIME clients won't display it 347properly (if at all). You can use the B<-text> option to automatically 348add plain text headers. 349 350A "signed and encrypted" message is one where a signed message is 351then encrypted. This can be produced by encrypting an already signed 352message: see the examples section. 353 354This version of the program only allows one signer per message but it 355will verify multiple signers on received messages. Some S/MIME clients 356choke if a message contains multiple signers. It is possible to sign 357messages "in parallel" by signing an already signed message. 358 359The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME 360clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 361encrypted data is used for other purposes. 362 363The B<-resign> option uses an existing message digest when adding a new 364signer. This means that attributes must be present in at least one existing 365signer using the same message digest or this operation will fail. 366 367The B<-stream> and B<-indef> options enable streaming I/O support. 368As a result the encoding is BER using indefinite length constructed encoding 369and no longer DER. Streaming is supported for the B<-encrypt> operation and the 370B<-sign> operation if the content is not detached. 371 372Streaming is always used for the B<-sign> operation with detached data but 373since the content is no longer part of the PKCS#7 structure the encoding 374remains DER. 375 376=head1 EXIT CODES 377 378=over 4 379 380=item Z<>0 381 382The operation was completely successfully. 383 384=item Z<>1 385 386An error occurred parsing the command options. 387 388=item Z<>2 389 390One of the input files could not be read. 391 392=item Z<>3 393 394An error occurred creating the PKCS#7 file or when reading the MIME 395message. 396 397=item Z<>4 398 399An error occurred decrypting or verifying the message. 400 401=item Z<>5 402 403The message was verified correctly but an error occurred writing out 404the signers certificates. 405 406=back 407 408=head1 EXAMPLES 409 410Create a cleartext signed message: 411 412 openssl smime -sign -in message.txt -text -out mail.msg \ 413 -signer mycert.pem 414 415Create an opaque signed message: 416 417 openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ 418 -signer mycert.pem 419 420Create a signed message, include some additional certificates and 421read the private key from another file: 422 423 openssl smime -sign -in in.txt -text -out mail.msg \ 424 -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem 425 426Create a signed message with two signers: 427 428 openssl smime -sign -in message.txt -text -out mail.msg \ 429 -signer mycert.pem -signer othercert.pem 430 431Send a signed message under Unix directly to sendmail, including headers: 432 433 openssl smime -sign -in in.txt -text -signer mycert.pem \ 434 -from steve@openssl.org -to someone@somewhere \ 435 -subject "Signed message" | sendmail someone@somewhere 436 437Verify a message and extract the signer's certificate if successful: 438 439 openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt 440 441Send encrypted mail using triple DES: 442 443 openssl smime -encrypt -in in.txt -from steve@openssl.org \ 444 -to someone@somewhere -subject "Encrypted message" \ 445 -des3 user.pem -out mail.msg 446 447Sign and encrypt mail: 448 449 openssl smime -sign -in ml.txt -signer my.pem -text \ 450 | openssl smime -encrypt -out mail.msg \ 451 -from steve@openssl.org -to someone@somewhere \ 452 -subject "Signed and Encrypted message" -des3 user.pem 453 454Note: the encryption command does not include the B<-text> option because the 455message being encrypted already has MIME headers. 456 457Decrypt mail: 458 459 openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem 460 461The output from Netscape form signing is a PKCS#7 structure with the 462detached signature format. You can use this program to verify the 463signature by line wrapping the base64 encoded structure and surrounding 464it with: 465 466 -----BEGIN PKCS7----- 467 -----END PKCS7----- 468 469and using the command: 470 471 openssl smime -verify -inform PEM -in signature.pem -content content.txt 472 473Alternatively you can base64 decode the signature and use: 474 475 openssl smime -verify -inform DER -in signature.der -content content.txt 476 477Create an encrypted message using 128 bit Camellia: 478 479 openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem 480 481Add a signer to an existing message: 482 483 openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg 484 485=head1 BUGS 486 487The MIME parser isn't very clever: it seems to handle most messages that I've 488thrown at it but it may choke on others. 489 490The code currently will only write out the signer's certificate to a file: if 491the signer has a separate encryption certificate this must be manually 492extracted. There should be some heuristic that determines the correct 493encryption certificate. 494 495Ideally a database should be maintained of a certificates for each email 496address. 497 498The code doesn't currently take note of the permitted symmetric encryption 499algorithms as supplied in the SMIMECapabilities signed attribute. This means the 500user has to manually include the correct encryption algorithm. It should store 501the list of permitted ciphers in a database and only use those. 502 503No revocation checking is done on the signer's certificate. 504 505The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 506structures may cause parsing errors. 507 508=head1 HISTORY 509 510The use of multiple B<-signer> options and the B<-resign> command were first 511added in OpenSSL 1.0.0 512 513The -no_alt_chains option was added in OpenSSL 1.1.0. 514 515=head1 COPYRIGHT 516 517Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 518 519Licensed under the OpenSSL license (the "License"). You may not use 520this file except in compliance with the License. You can obtain a copy 521in the file LICENSE in the source distribution or at 522L<https://www.openssl.org/source/license.html>. 523 524=cut 525