Add some of the missing CMS API documentation

Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11884)

doc/man3/CMS_EncryptedData_decrypt.pod

+=pod
+
+=head1 NAME
+
+CMS_EncryptedData_decrypt
+- Decrypt CMS EncryptedData
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_EncryptedData_decrypt(CMS_ContentInfo *cms,
+                               const unsigned char *key, size_t keylen,
+                               BIO *dcont, BIO *out, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_EncryptedData_decrypt() decrypts a I<cms> EncryptedData object using the
+symmetric I<key> of size I<keylen> bytes. I<out> is a BIO to write the content
+to and I<flags> is an optional set of flags.
+I<dcont> is used in the rare case where the encrypted content is detached. It
+will normally be set to NULL.
+
+The following flags can be passed in the B<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
+returned.
+
+=head1 RETURN VALUES
+
+CMS_EncryptedData_decrypt() returns 0 if an error occurred otherwise it
+returns 1.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_EncryptedData_encrypt(3)>
+
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/CMS_EncryptedData_encrypt.pod

+=pod
+
+=head1 NAME
+
+CMS_EncryptedData_encrypt_with_libctx, CMS_EncryptedData_encrypt
+- Create CMS EncryptedData
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_EncryptedData_encrypt_with_libctx(BIO *in,
+     const EVP_CIPHER *cipher, const unsigned char *key, size_t keylen,
+     unsigned int flags, OPENSSL_CTX *ctx, const char *propq);
+
+ CMS_ContentInfo *CMS_EncryptedData_encrypt(BIO *in,
+     const EVP_CIPHER *cipher, const unsigned char *key, size_t keylen,
+     unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_EncryptedData_encrypt_with_libctx() creates a B<CMS_ContentInfo> structure
+with a type B<NID_pkcs7_encrypted>. I<in> is a BIO containing the data to
+encrypt using I<cipher> and the encryption key I<key> of size I<keylen> bytes.
+The library context I<libctx> and the property query I<propq> are used when
+retrieving algorithms from providers. I<flags> is a set of optional flags.
+
+The I<flags> field supports the options B<CMS_DETACHED>, B<CMS_STREAM> and
+B<CMS_PARTIAL>. Internally CMS_final() is called unless B<CMS_STREAM> and/or
+B<CMS_PARTIAL> is specified.
+
+The algorithm passed in the I<cipher> parameter must support ASN1 encoding of
+its parameters.
+
+The B<CMS_ContentInfo> structure can be freed using L<CMS_ContentInfo_free(3)>.
+
+CMS_EncryptedData_encrypt() is similar to CMS_EncryptedData_encrypt_with_libctx()
+but uses default values of NULL for the library context I<libctx> and the
+property query I<propq>.
+
+=head1 RETURN VALUES
+
+If the allocation fails, CMS_EncryptedData_encrypt_with_libctx() and
+CMS_EncryptedData_encrypt() return NULL and set an error code that can be
+obtained by L<ERR_get_error(3)>. Otherwise they return a pointer to the newly
+allocated structure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_final(3)>, L<CMS_EncryptedData_decrypt(3)>
+
+head1 HISTORY
+
+The CMS_EncryptedData_encrypt_with_libctx() method was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/CMS_data_create.pod

+=pod
+
+=head1 NAME
+
+CMS_data_create_with_libctx, CMS_data_create
+- Create CMS Data object
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_data_create_with_libctx(BIO *in, unsigned int flags,
+                                              OPENSSL_CTX *libctx,
+                                              const char *propq);
+ CMS_ContentInfo *CMS_data_create(BIO *in, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_data_create_with_libctx() creates a B<CMS_ContentInfo> structure
+with a type B<NID_pkcs7_data>. The data is supplied via the I<in> BIO.
+The library context I<libctx> and the property query I<propq> are used when
+retrieving algorithms from providers. The I<flags> field supports the
+B<CMS_STREAM> flag. Internally CMS_final() is called unless B<CMS_STREAM> is
+specified.
+
+The B<CMS_ContentInfo> structure can be freed using L<CMS_ContentInfo_free(3)>.
+
+CMS_data_create() is similar to CMS_data_create_with_libctx()
+but uses default values of NULL for the library context I<libctx> and the
+property query I<propq>.
+
+=head1 RETURN VALUES
+
+If the allocation fails, CMS_data_create_with_libctx() and CMS_data_create()
+return NULL and set an error code that can be obtained by L<ERR_get_error(3)>.
+Otherwise they return a pointer to the newly allocated structure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_final(3)>
+
+head1 HISTORY
+
+The CMS_data_create_with_libctx() method was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/CMS_digest_create.pod

+=pod
+
+=head1 NAME
+
+CMS_digest_create_with_libctx, CMS_digest_create
+- Create CMS DigestedData object
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_digest_create_with_libctx(BIO *in,
+     const EVP_MD *md, unsigned int flags,
+     OPENSSL_CTX *ctx, const char *propq);
+
+ CMS_ContentInfo *CMS_digest_create(BIO *in, const EVP_MD *md,
+                                    unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_digest_create_with_libctx() creates a B<CMS_ContentInfo> structure
+with a type B<NID_pkcs7_digest>. The data supplied via the I<in> BIO is digested
+using I<md>. The library context I<libctx> and the property query I<propq> are
+used when retrieving algorithms from providers.
+The I<flags> field supports the B<CMS_DETACHED> and B<CMS_STREAM> flags,
+Internally CMS_final() is called unless B<CMS_STREAM> is specified.
+
+The B<CMS_ContentInfo> structure can be freed using L<CMS_ContentInfo_free(3)>.
+
+CMS_digest_create() is similar to CMS_digest_create_with_libctx()
+but uses default values of NULL for the library context I<libctx> and the
+property query I<propq>.
+
+
+=head1 RETURN VALUES
+
+If the allocation fails, CMS_digest_create_with_libctx() and CMS_digest_create()
+return NULL and set an error code that can be obtained by L<ERR_get_error(3)>.
+Otherwise they return a pointer to the newly allocated structure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_final(3)>>
+
+head1 HISTORY
+
+The CMS_digest_create_with_libctx() method was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/SMIME_read_ASN1.pod

+=pod
+
+=head1 NAME
+
+SMIME_read_ASN1_ex, SMIME_read_ASN1
+- parse S/MIME message
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ ASN1_VALUE *SMIME_read_ASN1_ex(BIO *in, BIO **bcont, const ASN1_ITEM *it,
+                                ASN1_VALUE **x);
+ ASN1_VALUE *SMIME_read_ASN1(BIO *in, BIO **bcont, const ASN1_ITEM *it);
+
+=head1 DESCRIPTION
+
+SMIME_read_ASN1_ex() parses a message in S/MIME format.
+
+I<in> is a BIO to read the message from. I<x> can be used to optionally supply
+a previously created I<it> ASN1_VALUE object (such as CMS_ContentInfo or PKCS7),
+it can be set to NULL. Valid values that can be used by ASN.1 structure I<it>
+are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo).
+
+If cleartext signing is used then the content is saved in a memory bio which is
+written to I<*bcont>, otherwise I<*bcont> is set to NULL.
+
+The parsed ASN1_VALUE structure is returned or NULL if an error occurred.
+
+SMIME_read_ASN1() is similar to SMIME_read_ASN1_ex() but sets the value of I<x>
+to NULL.
+
+=head1 NOTES
+
+The higher level functions L<SMIME_read_CMS_ex(3)> and
+L<SMIME_read_PKCS7_ex(3)> should be used instead of SMIME_read_ASN1_ex().
+
+To support future functionality if I<bcont> is not NULL I<*bcont> should be
+initialized to NULL.
+
+=head1 BUGS
+
+The MIME parser used by SMIME_read_ASN1_ex() is somewhat primitive. While it will
+handle most S/MIME messages more complex compound formats may not work.
+
+The use of a memory BIO to hold the signed content limits the size of message
+which can be processed due to memory restraints: a streaming single pass option
+should be available.
+
+=head1 RETURN VALUES
+
+SMIME_read_ASN1_ex() and SMIME_read_ASN1() return a valid B<ASN1_VALUE>
+structure or B<NULL> if an error occurred. The error can be obtained from
+ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<SMIME_read_CMS_ex(3)>,
+L<SMIME_read_PKCS7_ex(3)>,
+L<SMIME_write_ASN1(3)>,
+L<SMIME_write_ASN1_with_libctx(3)>
+
+=head1 HISTORY
+
+The function SMIME_read_ASN1_ex() was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/SMIME_write_ASN1.pod

+=pod
+
+=head1 NAME
+
+SMIME_write_ASN1_with_libctx, SMIME_write_ASN1
+- convert structure to S/MIME format
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ int SMIME_write_ASN1_with_libctx(BIO *out,
+     ASN1_VALUE *val, BIO *data, int flags, int ctype_nid, int econt_nid,
+     STACK_OF(X509_ALGOR) *mdalgs, const ASN1_ITEM *it,
+     OPENSSL_CTX *libctx, const char *propq);
+
+ int SMIME_write_ASN1(BIO *out,
+     ASN1_VALUE *val, BIO *data, int flags, int ctype_nid, int econt_nid,
+     STACK_OF(X509_ALGOR) *mdalgs, const ASN1_ITEM *it);
+
+=head1 DESCRIPTION
+
+SMIME_write_ASN1_with_libctx() adds the appropriate MIME headers to an object
+structure to produce an S/MIME message.
+
+I<out> is the BIO to write the data to. I<value> is the appropriate ASN1_VALUE
+structure (either CMS_ContentInfo or PKCS7). If streaming is enabled then the
+content must be supplied via I<data>.
+I<flags> is an optional set of flags. I<ctype_nid> is the NID of the content
+type, I<econt_nid> is the NID of the embedded content type and I<mdalgs> is a
+list of signed data digestAlgorithms. Valid values that can be used by the
+ASN.1 structure I<it> are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo).
+The library context I<libctx> and the property query I<propq> are used when
+retrieving algorithms from providers.
+
+=head1 NOTES
+
+The higher level functions L<SMIME_write_CMS(3)> and
+L<SMIME_write_PKCS7(3)> should be used instead of SMIME_write_ASN1().
+
+The following flags can be passed in the B<flags> parameter.
+
+If B<CMS_DETACHED> is set then cleartext signing will be used, this option only
+makes sense for SignedData where B<CMS_DETACHED> is also set when the sign()
+method is called.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to
+the content, this only makes sense if B<CMS_DETACHED> is also set.
+
+If the B<CMS_STREAM> flag is set streaming is performed. This flag should only
+be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo
+or PKCS7 creation function.
+
+If cleartext signing is being used and B<CMS_STREAM> not set then the data must
+be read twice: once to compute the signature in sign method and once to output
+the S/MIME message.
+
+If streaming is performed the content is output in BER format using indefinite
+length constructed encoding except in the case of signed data with detached
+content where the content is absent and DER format is used.
+
+=head1 RETURN VALUES
+
+SMIME_write_ASN1_with_libctx() and SMIME_write_ASN1() return 1 for success or
+0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<SMIME_write_CMS(3)>,
+L<SMIME_write_PKCS7(3)>
+
+=head1 COPYRIGHT
+
+Copyright 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

test/evp_test.c

@@ -1183,7 +1183,7 @@ static int mac_test_run_pkey(EVP_TEST *t)
         t->err = "INTERNAL_ERROR";
         goto err;
     }
-    if (!EVP_DigestSignInit_ex(mctx, &pctx, mdname, NULL, key, libctx)) {
+    if (!EVP_DigestSignInit_with_libctx(mctx, &pctx, mdname, libctx, NULL, key)) {
         t->err = "DIGESTSIGNINIT_ERROR";
         goto err;
     }
@@ -2899,13 +2899,13 @@ static int digestsigver_test_parse(EVP_TEST *t,
             return 1;
         }
         if (mdata->is_verify) {
-            if (!EVP_DigestVerifyInit_ex(mdata->ctx, &mdata->pctx,
-                                         name, NULL, pkey, libctx))
+            if (!EVP_DigestVerifyInit_with_libctx(mdata->ctx, &mdata->pctx,
+                                                  name, libctx, NULL, pkey))
                 t->err = "DIGESTVERIFYINIT_ERROR";
             return 1;
         }
-        if (!EVP_DigestSignInit_ex(mdata->ctx, &mdata->pctx,
-                                   name, NULL, pkey, libctx))
+        if (!EVP_DigestSignInit_with_libctx(mdata->ctx, &mdata->pctx,
+                                            name, libctx, NULL, pkey))
             t->err = "DIGESTSIGNINIT_ERROR";
         return 1;
     }

util/libcrypto.num

@@ -4806,9 +4806,9 @@ OSSL_CMP_print_to_bio                   ?	3_0_0	EXIST::FUNCTION:CMP
 OSSL_CMP_print_errors_cb                ?	3_0_0	EXIST::FUNCTION:CMP
 OSSL_CRMF_CERTID_get0_issuer            ?	3_0_0	EXIST::FUNCTION:CRMF
 OSSL_CRMF_CERTID_get0_serialNumber      ?	3_0_0	EXIST::FUNCTION:CRMF
-EVP_DigestSignInit_ex                   ?	3_0_0	EXIST::FUNCTION:
+EVP_DigestSignInit_ex                   ?	3_0_0	NOEXIST::FUNCTION:
 EVP_DigestSignUpdate                    ?	3_0_0	EXIST::FUNCTION:
-EVP_DigestVerifyInit_ex                 ?	3_0_0	EXIST::FUNCTION:
+EVP_DigestVerifyInit_ex                 ?	3_0_0	NOEXIST::FUNCTION:
 EVP_DigestVerifyUpdate                  ?	3_0_0	EXIST::FUNCTION:
 BN_check_prime                          ?	3_0_0	EXIST::FUNCTION:
 EVP_KEYMGMT_is_a                        ?	3_0_0	EXIST::FUNCTION:
@@ -5206,3 +5206,22 @@ PKCS12_SAFEBAG_create_secret            ?	3_0_0	EXIST::FUNCTION:
 PKCS12_add1_attr_by_NID                 ?	3_0_0	EXIST::FUNCTION:
 PKCS12_add1_attr_by_txt                 ?	3_0_0	EXIST::FUNCTION:
 PKCS12_add_secret                       ?	3_0_0	EXIST::FUNCTION:
+SMIME_write_ASN1_with_libctx            ?	3_0_0	EXIST::FUNCTION:
+SMIME_read_ASN1_ex                      ?	3_0_0	EXIST::FUNCTION:
+CMS_ContentInfo_new_with_libctx         ?	3_0_0	EXIST::FUNCTION:CMS
+SMIME_read_CMS_ex                       ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_sign_with_libctx                    ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_data_create_with_libctx             ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_digest_create_with_libctx           ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_EncryptedData_encrypt_with_libctx   ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_encrypt_with_libctx                 ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_EnvelopedData_create_with_libctx    ?	3_0_0	EXIST::FUNCTION:CMS
+CMS_ReceiptRequest_create0_with_libctx  ?	3_0_0	EXIST::FUNCTION:CMS
+EVP_SignFinal_with_libctx               ?	3_0_0	EXIST::FUNCTION:
+EVP_VerifyFinal_with_libctx             ?	3_0_0	EXIST::FUNCTION:
+EVP_DigestSignInit_with_libctx          ?	3_0_0	EXIST::FUNCTION:
+EVP_DigestVerifyInit_with_libctx        ?	3_0_0	EXIST::FUNCTION:
+PKCS7_new_with_libctx                   ?	3_0_0	EXIST::FUNCTION:
+PKCS7_sign_with_libctx                  ?	3_0_0	EXIST::FUNCTION:
+PKCS7_encrypt_with_libctx               ?	3_0_0	EXIST::FUNCTION:
+SMIME_read_PKCS7_ex                     ?	3_0_0	EXIST::FUNCTION:

util/missingcrypto.txt

@@ -309,9 +309,6 @@ CMAC_Init(3)
 CMAC_Update(3)
 CMAC_resume(3)
 CMS_ContentInfo_it(3)
-CMS_EncryptedData_decrypt(3)
-CMS_EncryptedData_encrypt(3)
-CMS_EncryptedData_encrypt_with_libctx(3)
 CMS_EncryptedData_set1_key(3)
 CMS_ReceiptRequest_it(3)
 CMS_RecipientEncryptedKey_cert_cmp(3)
@@ -341,12 +338,8 @@ CMS_add_standard_smimecap(3)
 CMS_data(3)
 CMS_dataFinal(3)
 CMS_dataInit(3)
-CMS_data_create(3)
-CMS_data_create_with_libctx(3)
 CMS_decrypt_set1_key(3)
 CMS_decrypt_set1_password(3)
-CMS_digest_create(3)
-CMS_digest_create_with_libctx(3)
 CMS_digest_verify(3)
 CMS_is_detached(3)
 CMS_set1_signers_certs(3)
@@ -1122,11 +1115,7 @@ SHA1_Transform(3)
 SHA256_Transform(3)
 SHA512_Transform(3)
 SMIME_crlf_copy(3)
-SMIME_read_ASN1(3)
-SMIME_read_ASN1_ex(3)
 SMIME_text(3)
-SMIME_write_ASN1(3)
-SMIME_write_ASN1_with_libctx(3)
 SRP_Verify_A_mod_N(3)
 SRP_Verify_B_mod_N(3)
 SSL_CTX_set0_ctlog_store(3)