=head1 NAME
-CMS_decrypt - decrypt content from a CMS envelopedData structure
+CMS_decrypt, CMS_decrypt_set1_pkey_and_peer,
+CMS_decrypt_set1_pkey, CMS_decrypt_set1_password
+- decrypt content from a CMS envelopedData structure
=head1 SYNOPSIS
int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,
BIO *dcont, BIO *out, unsigned int flags);
+ int CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms,
+ EVP_PKEY *pk, X509 *cert, X509 *peer);
+ int CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert);
+ int CMS_decrypt_set1_password(CMS_ContentInfo *cms,
+ unsigned char *pass, ossl_ssize_t passlen);
=head1 DESCRIPTION
-CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
-structure. B<pkey> is the private key of the recipient, B<cert> is the
-recipient's certificate, B<out> is a BIO to write the content to and
-B<flags> is an optional set of flags.
-
-The B<dcont> parameter is used in the rare case where the encrypted content
+CMS_decrypt() extracts the decrypted content from a CMS EnvelopedData
+or AuthEnvelopedData structure.
+It uses CMS_decrypt_set1_pkey() to decrypt the content
+with the recipient private key I<pkey> if I<pkey> is not NULL.
+In this case, the associated certificate is recommended to provide in I<cert> -
+see the NOTES below.
+I<out> is a BIO to write the content to and
+I<flags> is an optional set of flags.
+If I<pkey> is NULL the function assumes that decryption was already done
+(e.g., using CMS_decrypt_set1_pkey() or CMS_decrypt_set1_password()) and just
+provides the content unless I<cert>, I<dcont>, and I<out> are NULL as well.
+The I<dcont> parameter is used in the rare case where the encrypted content
is detached. It will normally be set to NULL.
+CMS_decrypt_set1_pkey_and_peer() decrypts the CMS_ContentInfo structure I<cms>
+using the private key I<pkey>, the corresponding certificate I<cert>, which is
+recommended but may be NULL, and the (optional) originator certificate I<peer>.
+On success, it also records in I<cms> the decryption key I<pkey>, and then
+should be followed by C<CMS_decrypt(cms, NULL, NULL, dcont, out, flags)>.
+This call deallocates any decryption key stored in I<cms>.
+
+CMS_decrypt_set1_pkey() is the same as
+CMS_decrypt_set1_pkey_and_peer() with I<peer> being NULL.
+
+CMS_decrypt_set1_password() decrypts the CMS_ContentInfo structure I<cms>
+using the secret I<pass> of length I<passlen>.
+On success, it also records in I<cms> the decryption key used, and then
+should be followed by C<CMS_decrypt(cms, NULL, NULL, dcont, out, flags)>.
+This call deallocates any decryption key stored in I<cms>.
+
=head1 NOTES
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the CMS
structure.
-If B<cert> is set to NULL all possible recipients are tried. This case however
+If I<cert> is set to NULL all possible recipients are tried. This case however
is problematic. To thwart the MMA attack (Bleichenbacher's attack on
PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
not. If no recipient succeeds then a random symmetric key is used to decrypt
It is possible to determine the correct recipient key by other means (for
example looking them up in a database) and setting them in the CMS structure
-in advance using the CMS utility functions such as CMS_set1_pkey(). In this
-case both B<cert> and B<pkey> should be set to NULL.
+in advance using the CMS utility functions such as CMS_set1_pkey(),
+or use CMS_decrypt_set1_password() if the recipient has a symmetric key.
+In these cases both I<cert> and I<pkey> should be set to NULL.
To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
and CMS_RecipientInfo_decrypt() should be called before CMS_decrypt() and
-
B<cert> and B<pkey> set to NULL.
+
I<cert> and I<pkey> set to NULL.
-The following flags can be passed in the B<flags> parameter.
+The following flags can be passed in the I<flags> parameter.
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
-from the content. If the content is not of type B<text/plain> then an error is
+If the B<CMS_TEXT> flag is set MIME headers for type C<text/plain> are deleted
+from the content. If the content is not of type C<text/plain> then an error is
returned.
=head1 RETURN VALUES
-CMS_decrypt() returns either 1 for success or 0 for failure.
-The error can be obtained from ERR_get_error(3)
+CMS_decrypt(), CMS_decrypt_set1_pkey_and_peer(),
+CMS_decrypt_set1_pkey(), and CMS_decrypt_set1_password()
+return either 1 for success or 0 for failure.
+The error can be obtained from ERR_get_error(3).
=head1 BUGS
+The B<set1_> part of these function names is misleading
+and should better read: B<with_>.
+
The lack of single pass processing and the need to hold all data in memory as
mentioned in CMS_verify() also applies to CMS_decrypt().
L<ERR_get_error(3)>, L<CMS_encrypt(3)>
+=head1 HISTORY
+
+CMS_decrypt_set1_pkey_and_peer() and CMS_decrypt_set1_password()
+were added in OpenSSL 3.0.
+
=head1 COPYRIGHT
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+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>.
projects / openssl.git / blobdiff