Add X509_NAME_hash_ex() to be able to check if it failed due to unsupported SHA1

[openssl.git] / doc / man3 / CMS_encrypt.pod

diff --git a/doc/man3/CMS_encrypt.pod b/doc/man3/CMS_encrypt.pod
index 1bc9fd041d7f93902a210420aea236626c55c798..cddd89447b473add9463b4981c81869f578b60b9 100644 (file)
--- a/doc/man3/CMS_encrypt.pod
+++ b/doc/man3/CMS_encrypt.pod
@@ -2,20 +2,26 @@
 
 =head1 NAME
 
-CMS_encrypt - create a CMS envelopedData structure
+CMS_encrypt_ex, CMS_encrypt - create a CMS envelopedData structure
 
 =head1 SYNOPSIS
 
  #include <openssl/cms.h>
 
+ CMS_ContentInfo *CMS_encrypt_ex(STACK_OF(X509) *certs, BIO *in,
+                                 const EVP_CIPHER *cipher, unsigned int flags,
+                                 OSSL_LIB_CTX *libctx, const char *propq);
  CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in,
                               const EVP_CIPHER *cipher, unsigned int flags);
 
 =head1 DESCRIPTION
 
-CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
-is a list of recipient certificates. B<in> is the content to be encrypted.
-B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
+CMS_encrypt_ex() creates and returns a CMS EnvelopedData or
+AuthEnvelopedData structure. I<certs> is a list of recipient certificates.
+I<in> is the content to be encrypted. I<cipher> is the symmetric cipher to use.
+I<flags> is an optional set of flags. The library context I<libctx> and the
+property query I<propq> are used internally when retrieving algorithms from
+providers.
 
 Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this
 function.
@@ -24,7 +30,9 @@ EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
 because most clients will support it.
 
 The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
-its parameters.
+its parameters. If the cipher mode is GCM, then an AuthEnvelopedData structure
+containing MAC is used. Otherwise an EnvelopedData structure is used. Currently
+the AES variants with GCM mode are the only supported AEAD algorithms.
 
 Many browsers implement a "sign and encrypt" option which is simply an S/MIME
 envelopedData containing an S/MIME signed message. This can be readily produced
@@ -75,10 +83,14 @@ and CMS_add0_recipient_key().
 The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients
 added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().
 
+CMS_encrypt() is similar to CMS_encrypt_ex() but uses default values
+of NULL for the library context I<libctx> and the property query I<propq>.
+
 =head1 RETURN VALUES
 
-CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error
-occurred. The error can be obtained from ERR_get_error(3).
+CMS_encrypt_ex() and CMS_encrypt() return either a CMS_ContentInfo
+structure or NULL if an error occurred. The error can be obtained from
+ERR_get_error(3).
 
 =head1 SEE ALSO
 
@@ -86,11 +98,13 @@ L<ERR_get_error(3)>, L<CMS_decrypt(3)>
 
 =head1 HISTORY
 
+The function CMS_encrypt_ex() was added in OpenSSL 3.0.
+
 The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
 
-Copyright 2008-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 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