From: Shane Lontis Date: Thu, 6 Aug 2020 03:56:57 +0000 (+1000) Subject: Add some of the missing CMS API documentation X-Git-Tag: openssl-3.0.0-alpha7~619 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=dda4e259e51aeaf05a2417ef577accf778c9f6f6;p=thirdparty%2Fopenssl.git Add some of the missing CMS API documentation Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/11884) --- diff --git a/doc/man3/CMS_EncryptedData_decrypt.pod b/doc/man3/CMS_EncryptedData_decrypt.pod new file mode 100644 index 00000000000..17850a98af3 --- /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 + + 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 EncryptedData object using the +symmetric I of size I bytes. I is a BIO to write the content +to and I is an optional set of flags. +I 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 parameter. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B 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, L + + +=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. + +=cut diff --git a/doc/man3/CMS_EncryptedData_encrypt.pod b/doc/man3/CMS_EncryptedData_encrypt.pod new file mode 100644 index 00000000000..cb2672f6299 --- /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 + + 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 structure +with a type B. I is a BIO containing the data to +encrypt using I and the encryption key I of size I bytes. +The library context I and the property query I are used when +retrieving algorithms from providers. I is a set of optional flags. + +The I field supports the options B, B and +B. Internally CMS_final() is called unless B and/or +B is specified. + +The algorithm passed in the I parameter must support ASN1 encoding of +its parameters. + +The B structure can be freed using L. + +CMS_EncryptedData_encrypt() is similar to CMS_EncryptedData_encrypt_with_libctx() +but uses default values of NULL for the library context I and the +property query I. + +=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. Otherwise they return a pointer to the newly +allocated structure. + +=head1 SEE ALSO + +L, L, L + +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. + +=cut diff --git a/doc/man3/CMS_data_create.pod b/doc/man3/CMS_data_create.pod new file mode 100644 index 00000000000..b64a7a1d465 --- /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 + + 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 structure +with a type B. The data is supplied via the I BIO. +The library context I and the property query I are used when +retrieving algorithms from providers. The I field supports the +B flag. Internally CMS_final() is called unless B is +specified. + +The B structure can be freed using L. + +CMS_data_create() is similar to CMS_data_create_with_libctx() +but uses default values of NULL for the library context I and the +property query I. + +=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. +Otherwise they return a pointer to the newly allocated structure. + +=head1 SEE ALSO + +L, L + +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. + +=cut diff --git a/doc/man3/CMS_digest_create.pod b/doc/man3/CMS_digest_create.pod new file mode 100644 index 00000000000..0eba22cfe68 --- /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 + + 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 structure +with a type B. The data supplied via the I BIO is digested +using I. The library context I and the property query I are +used when retrieving algorithms from providers. +The I field supports the B and B flags, +Internally CMS_final() is called unless B is specified. + +The B structure can be freed using L. + +CMS_digest_create() is similar to CMS_digest_create_with_libctx() +but uses default values of NULL for the library context I and the +property query I. + + +=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. +Otherwise they return a pointer to the newly allocated structure. + +=head1 SEE ALSO + +L, L> + +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. + +=cut diff --git a/doc/man3/SMIME_read_ASN1.pod b/doc/man3/SMIME_read_ASN1.pod new file mode 100644 index 00000000000..5b995f1aeea --- /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 + + 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 is a BIO to read the message from. I can be used to optionally supply +a previously created I 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 +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 +to NULL. + +=head1 NOTES + +The higher level functions L and +L should be used instead of SMIME_read_ASN1_ex(). + +To support future functionality if I 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 +structure or B if an error occurred. The error can be obtained from +ERR_get_error(3). + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=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. + +=cut diff --git a/doc/man3/SMIME_write_ASN1.pod b/doc/man3/SMIME_write_ASN1.pod new file mode 100644 index 00000000000..5f46ce1b455 --- /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 + + 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 is the BIO to write the data to. I is the appropriate ASN1_VALUE +structure (either CMS_ContentInfo or PKCS7). If streaming is enabled then the +content must be supplied via I. +I is an optional set of flags. I is the NID of the content +type, I is the NID of the embedded content type and I is a +list of signed data digestAlgorithms. Valid values that can be used by the +ASN.1 structure I are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo). +The library context I and the property query I are used when +retrieving algorithms from providers. + +=head1 NOTES + +The higher level functions L and +L should be used instead of SMIME_write_ASN1(). + +The following flags can be passed in the B parameter. + +If B is set then cleartext signing will be used, this option only +makes sense for SignedData where B is also set when the sign() +method is called. + +If the B flag is set MIME headers for type B are added to +the content, this only makes sense if B is also set. + +If the B flag is set streaming is performed. This flag should only +be set if B was also set in the previous call to a CMS_ContentInfo +or PKCS7 creation function. + +If cleartext signing is being used and B 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, +L, +L + +=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. + +=cut diff --git a/test/evp_test.c b/test/evp_test.c index 30a0aa11efb..bff1ecb5588 100644 --- a/test/evp_test.c +++ b/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; } diff --git a/util/libcrypto.num b/util/libcrypto.num index 813c86b4c19..8cfe55f4fa7 100644 --- a/util/libcrypto.num +++ b/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: diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index ce036226f11..3e8c62c6104 100644 --- a/util/missingcrypto.txt +++ b/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)