doc/man3/CMS_decrypt.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 CMS_decrypt, CMS_decrypt_set1_pkey_and_peer,
   6 CMS_decrypt_set1_pkey, CMS_decrypt_set1_password
   7 - decrypt content from a CMS envelopedData structure
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/cms.h>
  12
  13  int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,
  14                  BIO *dcont, BIO *out, unsigned int flags);
  15  int CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms,
  16                  EVP_PKEY *pk, X509 *cert, X509 *peer);
  17  int CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert);
  18  int CMS_decrypt_set1_password(CMS_ContentInfo *cms,
  19                                unsigned char *pass, ossl_ssize_t passlen);
  20
  21 =head1 DESCRIPTION
  22
  23 CMS_decrypt() extracts the decrypted content from a CMS EnvelopedData
  24 or AuthEnvelopedData structure.
  25 It uses CMS_decrypt_set1_pkey() to decrypt the content
  26 with the recipient private key I<pkey> if I<pkey> is not NULL.
  27 In this case, the associated certificate is recommended to provide in I<cert> -
  28 see the NOTES below.
  29 I<out> is a BIO to write the content to and
  30 I<flags> is an optional set of flags.
  31 If I<pkey> is NULL the function assumes that decryption was already done
  32 (e.g., using CMS_decrypt_set1_pkey() or CMS_decrypt_set1_password()) and just
  33 provides the content unless I<cert>, I<dcont>, and I<out> are NULL as well.
  34 The I<dcont> parameter is used in the rare case where the encrypted content
  35 is detached. It will normally be set to NULL.
  36
  37 CMS_decrypt_set1_pkey_and_peer() decrypts the CMS_ContentInfo structure I<cms>
  38 using the private key I<pkey>, the corresponding certificate I<cert>, which is
  39 recommended but may be NULL, and the (optional) originator certificate I<peer>.
  40 On success, it also records in I<cms> the decryption key I<pkey>, and then
  41 should be followed by C<CMS_decrypt(cms, NULL, NULL, dcont, out, flags)>.
  42 This call deallocates any decryption key stored in I<cms>.
  43
  44 CMS_decrypt_set1_pkey() is the same as
  45 CMS_decrypt_set1_pkey_and_peer() with I<peer> being NULL.
  46
  47 CMS_decrypt_set1_password() decrypts the CMS_ContentInfo structure I<cms>
  48 using the secret I<pass> of length I<passlen>.
  49 On success, it also records in I<cms> the decryption key used, and then
  50 should be followed by C<CMS_decrypt(cms, NULL, NULL, dcont, out, flags)>.
  51 This call deallocates any decryption key stored in I<cms>.
  52
  53 =head1 NOTES
  54
  55 Although the recipients certificate is not needed to decrypt the data it is
  56 needed to locate the appropriate (of possible several) recipients in the CMS
  57 structure.
  58
  59 If I<cert> is set to NULL all possible recipients are tried. This case however
  60 is problematic. To thwart the MMA attack (Bleichenbacher's attack on
  61 PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
  62 not. If no recipient succeeds then a random symmetric key is used to decrypt
  63 the content: this will typically output garbage and may (but is not guaranteed
  64 to) ultimately return a padding error only. If CMS_decrypt() just returned an
  65 error when all recipient encrypted keys failed to decrypt an attacker could
  66 use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
  67 then the above behaviour is modified and an error B<is> returned if no
  68 recipient encrypted key can be decrypted B<without> generating a random
  69 content encryption key. Applications should use this flag with
  70 B<extreme caution> especially in automated gateways as it can leave them
  71 open to attack.
  72
  73 It is possible to determine the correct recipient key by other means (for
  74 example looking them up in a database) and setting them in the CMS structure
  75 in advance using the CMS utility functions such as CMS_set1_pkey(),
  76 or use CMS_decrypt_set1_password() if the recipient has a symmetric key.
  77 In these cases both I<cert> and I<pkey> should be set to NULL.
  78
  79 To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
  80 and CMS_RecipientInfo_decrypt() should be called before CMS_decrypt() and
  81 I<cert> and I<pkey> set to NULL.
  82
  83 The following flags can be passed in the I<flags> parameter.
  84
  85 If the B<CMS_TEXT> flag is set MIME headers for type C<text/plain> are deleted
  86 from the content. If the content is not of type C<text/plain> then an error is
  87 returned.
  88
  89 =head1 RETURN VALUES
  90
  91 CMS_decrypt(), CMS_decrypt_set1_pkey_and_peer(),
  92 CMS_decrypt_set1_pkey(), and CMS_decrypt_set1_password()
  93 return either 1 for success or 0 for failure.
  94 The error can be obtained from ERR_get_error(3).
  95
  96 =head1 BUGS
  97
  98 The B<set1_> part of these function names is misleading
  99 and should better read: B<with_>.
 100
 101 The lack of single pass processing and the need to hold all data in memory as
 102 mentioned in CMS_verify() also applies to CMS_decrypt().
 103
 104 =head1 SEE ALSO
 105
 106 L<ERR_get_error(3)>, L<CMS_encrypt(3)>
 107
 108 =head1 HISTORY
 109
 110 CMS_decrypt_set1_pkey_and_peer() and CMS_decrypt_set1_password()
 111 were added in OpenSSL 3.0.
 112
 113 =head1 COPYRIGHT
 114
 115 Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
 116
 117 Licensed under the Apache License 2.0 (the "License").  You may not use
 118 this file except in compliance with the License.  You can obtain a copy
 119 in the file LICENSE in the source distribution or at
 120 L<https://www.openssl.org/source/license.html>.
 121
 122 =cut