diff options
author | Shane Lontis <shane.lontis@oracle.com> | 2020-08-06 13:56:57 +1000 |
---|---|---|
committer | Shane Lontis <shane.lontis@oracle.com> | 2020-08-09 17:34:52 +1000 |
commit | dda4e259e51aeaf05a2417ef577accf778c9f6f6 (patch) | |
tree | be68845d6f9091a3d9e56219de971bd1e9deeb96 /doc | |
parent | 28ba642779ec5c320fc95515bce17bda5e531105 (diff) | |
download | openssl-dda4e259e51aeaf05a2417ef577accf778c9f6f6.tar.gz |
Add some of the missing CMS API documentation
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11884)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/CMS_EncryptedData_decrypt.pod | 49 | ||||
-rw-r--r-- | doc/man3/CMS_EncryptedData_encrypt.pod | 65 | ||||
-rw-r--r-- | doc/man3/CMS_data_create.pod | 55 | ||||
-rw-r--r-- | doc/man3/CMS_digest_create.pod | 58 | ||||
-rw-r--r-- | doc/man3/SMIME_read_ASN1.pod | 77 | ||||
-rw-r--r-- | doc/man3/SMIME_write_ASN1.pod | 82 |
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 |