Add some of the missing CMS API documentation

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

6 files changed, 386 insertions, 0 deletions

diff --git a/doc/man3/CMS_EncryptedData_decrypt.pod b/doc/man3/CMS_EncryptedData_decrypt.pod
new file mode 100644
index 0000000000..17850a98af
--- /dev/null
+++ b/doc/man3/CMS_EncryptedData_decrypt.pod
@@ -0,0 +1,49 @@
+=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
diff --git a/doc/man3/CMS_EncryptedData_encrypt.pod b/doc/man3/CMS_EncryptedData_encrypt.pod
new file mode 100644
index 0000000000..cb2672f629
--- /dev/null
+++ b/doc/man3/CMS_EncryptedData_encrypt.pod
@@ -0,0 +1,65 @@
+=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
diff --git a/doc/man3/CMS_data_create.pod b/doc/man3/CMS_data_create.pod
new file mode 100644
index 0000000000..b64a7a1d46
--- /dev/null
+++ b/doc/man3/CMS_data_create.pod
@@ -0,0 +1,55 @@
+=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
diff --git a/doc/man3/CMS_digest_create.pod b/doc/man3/CMS_digest_create.pod
new file mode 100644
index 0000000000..0eba22cfe6
--- /dev/null
+++ b/doc/man3/CMS_digest_create.pod
@@ -0,0 +1,58 @@
+=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
diff --git a/doc/man3/SMIME_read_ASN1.pod b/doc/man3/SMIME_read_ASN1.pod
new file mode 100644
index 0000000000..5b995f1aee
--- /dev/null
+++ b/doc/man3/SMIME_read_ASN1.pod
@@ -0,0 +1,77 @@
+=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
diff --git a/doc/man3/SMIME_write_ASN1.pod b/doc/man3/SMIME_write_ASN1.pod
new file mode 100644
index 0000000000..5f46ce1b45
--- /dev/null
+++ b/doc/man3/SMIME_write_ASN1.pod
@@ -0,0 +1,82 @@
+=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