doc/apps/cms.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 cms - CMS utility
   6
   7 =head1 SYNOPSIS
   8
   9 B<openssl> B<cms>
  10 [B<-encrypt>]
  11 [B<-decrypt>]
  12 [B<-sign>]
  13 [B<-verify>]
  14 [B<-cmsout>]
  15 [B<-resign>]
  16 [B<-data_create>]
  17 [B<-data_out>]
  18 [B<-digest_create>]
  19 [B<-digest_verify>]
  20 [B<-compress>]
  21 [B<-uncompress>]
  22 [B<-EncryptedData_encrypt>]
  23 [B<-sign_receipt>]
  24 [B<-verify_receipt receipt>]
  25 [B<-in filename>]
  26 [B<-inform SMIME|PEM|DER>]
  27 [B<-rctform SMIME|PEM|DER>]
  28 [B<-out filename>]
  29 [B<-outform SMIME|PEM|DER>]
  30 [B<-stream -indef -noindef>]
  31 [B<-noindef>]
  32 [B<-content filename>]
  33 [B<-text>]
  34 [B<-noout>]
  35 [B<-print>]
  36 [B<-CAfile file>]
  37 [B<-CApath dir>]
  38 [B<-md digest>]
  39 [B<-des>]
  40 [B<-des3>]
  41 [B<-rc2-40>]
  42 [B<-rc2-64>]
  43 [B<-rc2-128>]
  44 [B<-aes128>]
  45 [B<-aes192>]
  46 [B<-aes256>]
  47 [B<-camellia128>]
  48 [B<-camellia192>]
  49 [B<-camellia256>]
  50 [B<-nointern>]
  51 [B<-no_signer_cert_verify>]
  52 [B<-nocerts>]
  53 [B<-noattr>]
  54 [B<-nosmimecap>]
  55 [B<-binary>]
  56 [B<-nodetach>]
  57 [B<-certfile file>]
  58 [B<-certsout file>]
  59 [B<-signer file>]
  60 [B<-recip file>]
  61 [B<-keyid>]
  62 [B<-receipt_request_all -receipt_request_first>]
  63 [B<-receipt_request_from emailaddress>]
  64 [B<-receipt_request_to emailaddress>]
  65 [B<-receipt_request_print>]
  66 [B<-secretkey key>]
  67 [B<-secretkeyid id>]
  68 [B<-econtent_type type>]
  69 [B<-inkey file>]
  70 [B<-passin arg>]
  71 [B<-rand file(s)>]
  72 [B<cert.pem...>]
  73 [B<-to addr>]
  74 [B<-from addr>]
  75 [B<-subject subj>]
  76 [cert.pem]...
  77
  78 =head1 DESCRIPTION
  79
  80 The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
  81 verify, compress and uncompress S/MIME messages.
  82
  83 =head1 COMMAND OPTIONS
  84
  85 There are fourteen operation options that set the type of operation to be
  86 performed. The meaning of the other options varies according to the operation
  87 type.
  88
  89 =over 4
  90
  91 =item B<-encrypt>
  92
  93 encrypt mail for the given recipient certificates. Input file is the message
  94 to be encrypted. The output file is the encrypted mail in MIME format. The
  95 actual CMS type is <B>EnvelopedData<B>.
  96
  97 =item B<-decrypt>
  98
  99 decrypt mail using the supplied certificate and private key. Expects an
 100 encrypted mail message in MIME format for the input file. The decrypted mail
 101 is written to the output file.
 102
 103 =item B<-sign>
 104
 105 sign mail using the supplied certificate and private key. Input file is
 106 the message to be signed. The signed message in MIME format is written
 107 to the output file.
 108
 109 =item B<-verify>
 110
 111 verify signed mail. Expects a signed mail message on input and outputs
 112 the signed data. Both clear text and opaque signing is supported.
 113
 114 =item B<-cmsout>
 115
 116 takes an input message and writes out a PEM encoded CMS structure.
 117
 118 =item B<-resign>
 119
 120 resign a message: take an existing message and one or more new signers.
 121
 122 =item B<-data_create>
 123
 124 Create a CMS B<Data> type.
 125
 126 =item B<-data_out>
 127
 128 B<Data> type and output the content.
 129
 130 =item B<-digest_create>
 131
 132 Create a CMS B<DigestedData> type.
 133
 134 =item B<-digest_verify>
 135
 136 Verify a CMS B<DigestedData> type and output the content.
 137
 138 =item B<-compress>
 139
 140 Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib>
 141 support for this option to work, otherwise it will output an error.
 142
 143 =item B<-uncompress>
 144
 145 Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be
 146 compiled with B<zlib> support for this option to work, otherwise it will
 147 output an error.
 148
 149 =item B<-EncryptedData_encrypt>
 150
 151 Encrypt suppled content using supplied symmetric key and algorithm using a CMS
 152 B<EncrytedData> type and output the content.
 153
 154 =item B<-sign_receipt>
 155
 156 Generate and output a signed receipt for the supplied message. The input
 157 message B<must> contain a signed receipt request. Functionality is otherwise
 158 similar to the B<-sign> operation.
 159
 160 =item B<-verify_receipt receipt>
 161
 162 Verify a signed receipt in filename B<receipt>. The input message B<must>
 163 contain the original receipt request. Functionality is otherwise similar
 164 to the B<-verify> operation.
 165
 166 =item B<-in filename>
 167
 168 the input message to be encrypted or signed or the message to be decrypted
 169 or verified.
 170
 171 =item B<-inform SMIME|PEM|DER>
 172
 173 this specifies the input format for the CMS structure. The default
 174 is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
 175 format change this to expect PEM and DER format CMS structures
 176 instead. This currently only affects the input format of the CMS
 177 structure, if no CMS structure is being input (for example with
 178 B<-encrypt> or B<-sign>) this option has no effect.
 179
 180 =item B<-rctform SMIME|PEM|DER>
 181
 182 specify the format for a signed receipt for use with the B<-receipt_verify>
 183 operation.
 184
 185 =item B<-out filename>
 186
 187 the message text that has been decrypted or verified or the output MIME
 188 format message that has been signed or verified.
 189
 190 =item B<-outform SMIME|PEM|DER>
 191
 192 this specifies the output format for the CMS structure. The default
 193 is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER>
 194 format change this to write PEM and DER format CMS structures
 195 instead. This currently only affects the output format of the CMS
 196 structure, if no CMS structure is being output (for example with
 197 B<-verify> or B<-decrypt>) this option has no effect.
 198
 199 =item B<-stream -indef -noindef>
 200
 201 the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
 202 for encoding operations. This permits single pass processing of data without
 203 the need to hold the entire contents in memory, potentially supporting very
 204 large files. Streaming is automatically set for S/MIME signing with detached
 205 data if the output format is B<SMIME> it is currently off by default for all
 206 other operations.
 207
 208 =item B<-noindef>
 209
 210 disable streaming I/O where it would produce and indefinite length constructed
 211 encoding. This option currently has no effect. In future streaming will be
 212 enabled by default on all relevant operations and this option will disable it.
 213
 214 =item B<-content filename>
 215
 216 This specifies a file containing the detached content, this is only
 217 useful with the B<-verify> command. This is only usable if the CMS
 218 structure is using the detached signature form where the content is
 219 not included. This option will override any content if the input format
 220 is S/MIME and it uses the multipart/signed MIME content type.
 221
 222 =item B<-text>
 223
 224 this option adds plain text (text/plain) MIME headers to the supplied
 225 message if encrypting or signing. If decrypting or verifying it strips
 226 off text headers: if the decrypted or verified message is not of MIME
 227 type text/plain then an error occurs.
 228
 229 =item B<-noout>
 230
 231 for the B<-cmsout> operation do not output the parsed CMS structure. This
 232 is useful when combined with the B<-print> option or if the syntax of the CMS
 233 structure is being checked.
 234
 235 =item B<-print>
 236
 237 for the B<-cmsout> operation print out all fields of the CMS structure. This
 238 is mainly useful for testing purposes.
 239
 240 =item B<-CAfile file>
 241
 242 a file containing trusted CA certificates, only used with B<-verify>.
 243
 244 =item B<-CApath dir>
 245
 246 a directory containing trusted CA certificates, only used with
 247 B<-verify>. This directory must be a standard certificate directory: that
 248 is a hash of each subject name (using B<x509 -hash>) should be linked
 249 to each certificate.
 250
 251 =item B<-md digest>
 252
 253 digest algorithm to use when signing or resigning. If not present then the
 254 default digest algorithm for the signing key will be used (usually SHA1).
 255
 256 =item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256>
 257
 258 the encryption algorithm to use. DES (56 bits), triple DES (168 bits), 40, 64
 259 or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia
 260 respectively. Any other cipher name (as recognized by the
 261 EVP_get_cipherbyname() function) can also be used preceded by a dash, for
 262 example B<-aes_128_cbc>.
 263
 264 If not specified triple DES is used. Only used with B<-encrypt> and
 265 B<-EncryptedData_create> commands.
 266
 267 =item B<-nointern>
 268
 269 when verifying a message normally certificates (if any) included in
 270 the message are searched for the signing certificate. With this option
 271 only the certificates specified in the B<-certfile> option are used.
 272 The supplied certificates can still be used as untrusted CAs however.
 273
 274 =item B<-no_signer_cert_verify>
 275
 276 do not verify the signers certificate of a signed message.
 277
 278 =item B<-nocerts>
 279
 280 when signing a message the signer's certificate is normally included
 281 with this option it is excluded. This will reduce the size of the
 282 signed message but the verifier must have a copy of the signers certificate
 283 available locally (passed using the B<-certfile> option for example).
 284
 285 =item B<-noattr>
 286
 287 normally when a message is signed a set of attributes are included which
 288 include the signing time and supported symmetric algorithms. With this
 289 option they are not included.
 290
 291 =item B<-nosmimecap>
 292
 293 exclude the list of supported algorithms from signed attributes, other options
 294 such as signing time and content type are still included.
 295
 296 =item B<-binary>
 297
 298 normally the input message is converted to "canonical" format which is
 299 effectively using CR and LF as end of line: as required by the S/MIME
 300 specification. When this option is present no translation occurs. This
 301 is useful when handling binary data which may not be in MIME format.
 302
 303 =item B<-nodetach>
 304
 305 when signing a message use opaque signing: this form is more resistant
 306 to translation by mail relays but it cannot be read by mail agents that
 307 do not support S/MIME.  Without this option cleartext signing with
 308 the MIME type multipart/signed is used.
 309
 310 =item B<-certfile file>
 311
 312 allows additional certificates to be specified. When signing these will
 313 be included with the message. When verifying these will be searched for
 314 the signers certificates. The certificates should be in PEM format.
 315
 316 =item B<-certsout file>
 317
 318 any certificates contained in to the message are written to B<file>.
 319
 320 =item B<-signer file>
 321
 322 a signing certificate when signing or resigning a message, this option can be
 323 used multiple times if more than one signer is required. If a message is being
 324 verified then the signers certificates will be written to this file if the
 325 verification was successful.
 326
 327 =item B<-recip file>
 328
 329 the recipients certificate when decrypting a message. This certificate
 330 must match one of the recipients of the message or an error occurs.
 331
 332 =item B<-keyid>
 333
 334 use subject key identifier to identify certificates instead of issuer name and
 335 serial number. The supplied certificate B<must> include a subject key
 336 identifier extension. Supported by B<-sign> and B<-encrypt> options.
 337
 338 =item B<-receipt_request_all -receipt_request_first>
 339
 340 for B<-sign> option include a signed receipt request. Indicate requests should
 341 be provided by all receipient or first tier recipients (those mailed directly
 342 and not from a mailing list). Ignored it B<-receipt_request_from> is included.
 343
 344 =item B<-receipt_request_from emailaddress>
 345
 346 for B<-sign> option include a signed receipt request. Add an explicit email
 347 address where receipts should be supplied.
 348
 349 =item B<-receipt_request_to emailaddress>
 350
 351 Add an explicit email address where signed receipts should be sent to. This
 352 option B<must> but supplied if a signed receipt it requested.
 353
 354 =item B<-receipt_request_print>
 355
 356 For the B<-verify> operation print out the contents of any signed receipt
 357 requests.
 358
 359 =item B<-secretkey key>
 360
 361 specify symmetric key to use. The key must be supplied in hex format and be
 362 consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
 363 B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
 364 with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
 365 content encryption key using an AES key in the B<KEKRecipientInfo> type.
 366
 367 =item B<-secretkeyid id>
 368
 369 the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type.
 370 This option B<must> be present if the B<-secretkey> option is used with
 371 B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the
 372 relevant key if it is not supplied then an attempt is used to decrypt any
 373 B<KEKRecipientInfo> structures.
 374
 375 =item B<-econtent_type type>
 376
 377 set the encapsulated content type to B<type> if not supplied the B<Data> type
 378 is used. The B<type> argument can be any valid OID name in either text or
 379 numerical format.
 380
 381 =item B<-inkey file>
 382
 383 the private key to use when signing or decrypting. This must match the
 384 corresponding certificate. If this option is not specified then the
 385 private key must be included in the certificate file specified with
 386 the B<-recip> or B<-signer> file. When signing this option can be used
 387 multiple times to specify successive keys.
 388
 389 =item B<-passin arg>
 390
 391 the private key password source. For more information about the format of B<arg>
 392 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
 393
 394 =item B<-rand file(s)>
 395
 396 a file or files containing random data used to seed the random number
 397 generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
 398 Multiple files can be specified separated by a OS-dependent character.
 399 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 400 all others.
 401
 402 =item B<cert.pem...>
 403
 404 one or more certificates of message recipients: used when encrypting
 405 a message.
 406
 407 =item B<-to, -from, -subject>
 408
 409 the relevant mail headers. These are included outside the signed
 410 portion of a message so they may be included manually. If signing
 411 then many S/MIME mail clients check the signers certificate's email
 412 address matches that specified in the From: address.
 413
 414 =back
 415
 416 =head1 NOTES
 417
 418 The MIME message must be sent without any blank lines between the
 419 headers and the output. Some mail programs will automatically add
 420 a blank line. Piping the mail directly to sendmail is one way to
 421 achieve the correct format.
 422
 423 The supplied message to be signed or encrypted must include the
 424 necessary MIME headers or many S/MIME clients wont display it
 425 properly (if at all). You can use the B<-text> option to automatically
 426 add plain text headers.
 427
 428 A "signed and encrypted" message is one where a signed message is
 429 then encrypted. This can be produced by encrypting an already signed
 430 message: see the examples section.
 431
 432 This version of the program only allows one signer per message but it
 433 will verify multiple signers on received messages. Some S/MIME clients
 434 choke if a message contains multiple signers. It is possible to sign
 435 messages "in parallel" by signing an already signed message.
 436
 437 The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
 438 clients. Strictly speaking these process CMS enveloped data: CMS
 439 encrypted data is used for other purposes.
 440
 441 The B<-resign> option uses an existing message digest when adding a new
 442 signer. This means that attributes must be present in at least one existing
 443 signer using the same message digest or this operation will fail.
 444
 445 The B<-stream> and B<-indef> options enable experimental streaming I/O support.
 446 As a result the encoding is BER using indefinite length constructed encoding
 447 and no longer DER. Streaming is supported for the B<-encrypt> operation and the
 448 B<-sign> operation if the content is not detached.
 449
 450 Streaming is always used for the B<-sign> operation with detached data but
 451 since the content is no longer part of the CMS structure the encoding
 452 remains DER.
 453
 454 =head1 EXIT CODES
 455
 456 =over 4
 457
 458 =item 0
 459
 460 the operation was completely successfully.
 461
 462 =item 1
 463
 464 an error occurred parsing the command options.
 465
 466 =item 2
 467
 468 one of the input files could not be read.
 469
 470 =item 3
 471
 472 an error occurred creating the CMS file or when reading the MIME
 473 message.
 474
 475 =item 4
 476
 477 an error occurred decrypting or verifying the message.
 478
 479 =item 5
 480
 481 the message was verified correctly but an error occurred writing out
 482 the signers certificates.
 483
 484 =back
 485
 486 =head1 COMPATIBILITY WITH PKCS#7 format.
 487
 488 The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
 489 utility supports Cryptographic Message Syntax format. Use of some features
 490 will result in messages which cannot be processed by applications which only
 491 support the older format. These are detailed below.
 492
 493 The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
 494
 495 The B<-outform PEM> option uses different headers.
 496
 497 The B<-compress> option.
 498
 499 The B<-secretkey> option when used with B<-encrypt>.
 500
 501 Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
 502 be processed by the older B<smime> command.
 503
 504 =head1 EXAMPLES
 505
 506 Create a cleartext signed message:
 507
 508  openssl cms -sign -in message.txt -text -out mail.msg \
 509         -signer mycert.pem
 510
 511 Create an opaque signed message
 512
 513  openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
 514         -signer mycert.pem
 515
 516 Create a signed message, include some additional certificates and
 517 read the private key from another file:
 518
 519  openssl cms -sign -in in.txt -text -out mail.msg \
 520         -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
 521
 522 Create a signed message with two signers, use key identifier:
 523
 524  openssl cms -sign -in message.txt -text -out mail.msg \
 525         -signer mycert.pem -signer othercert.pem -keyid
 526
 527 Send a signed message under Unix directly to sendmail, including headers:
 528
 529  openssl cms -sign -in in.txt -text -signer mycert.pem \
 530         -from steve@openssl.org -to someone@somewhere \
 531         -subject "Signed message" | sendmail someone@somewhere
 532
 533 Verify a message and extract the signer's certificate if successful:
 534
 535  openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
 536
 537 Send encrypted mail using triple DES:
 538
 539  openssl cms -encrypt -in in.txt -from steve@openssl.org \
 540         -to someone@somewhere -subject "Encrypted message" \
 541         -des3 user.pem -out mail.msg
 542
 543 Sign and encrypt mail:
 544
 545  openssl cms -sign -in ml.txt -signer my.pem -text \
 546         | openssl cms -encrypt -out mail.msg \
 547         -from steve@openssl.org -to someone@somewhere \
 548         -subject "Signed and Encrypted message" -des3 user.pem
 549
 550 Note: the encryption command does not include the B<-text> option because the
 551 message being encrypted already has MIME headers.
 552
 553 Decrypt mail:
 554
 555  openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
 556
 557 The output from Netscape form signing is a PKCS#7 structure with the
 558 detached signature format. You can use this program to verify the
 559 signature by line wrapping the base64 encoded structure and surrounding
 560 it with:
 561
 562  -----BEGIN PKCS7-----
 563  -----END PKCS7-----
 564
 565 and using the command,
 566
 567  openssl cms -verify -inform PEM -in signature.pem -content content.txt
 568
 569 alternatively you can base64 decode the signature and use
 570
 571  openssl cms -verify -inform DER -in signature.der -content content.txt
 572
 573 Create an encrypted message using 128 bit Camellia:
 574
 575  openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
 576
 577 Add a signer to an existing message:
 578
 579  openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
 580
 581 =head1 BUGS
 582
 583 The MIME parser isn't very clever: it seems to handle most messages that I've
 584 thrown at it but it may choke on others.
 585
 586 The code currently will only write out the signer's certificate to a file: if
 587 the signer has a separate encryption certificate this must be manually
 588 extracted. There should be some heuristic that determines the correct
 589 encryption certificate.
 590
 591 Ideally a database should be maintained of a certificates for each email
 592 address.
 593
 594 The code doesn't currently take note of the permitted symmetric encryption
 595 algorithms as supplied in the SMIMECapabilities signed attribute. this means the
 596 user has to manually include the correct encryption algorithm. It should store
 597 the list of permitted ciphers in a database and only use those.
 598
 599 No revocation checking is done on the signer's certificate.
 600
 601 =head1 HISTORY
 602
 603 The use of multiple B<-signer> options and the B<-resign> command were first
 604 added in OpenSSL 0.9.9
 605
 606
 607 =cut