mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-18 13:44:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add some of the missing CMS API documentation

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11884)
This commit is contained in:
Shane Lontis 2020-08-06 13:56:57 +10:00
parent 28ba642779
commit dda4e259e5
9 changed files with 412 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
doc/man3/CMS_EncryptedData_decrypt.pod Normal file
View File

@ -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

65
doc/man3/CMS_EncryptedData_encrypt.pod Normal file
View File

@ -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

55
doc/man3/CMS_data_create.pod Normal file
View File

@ -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

58
doc/man3/CMS_digest_create.pod Normal file
View File

@ -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

77
doc/man3/SMIME_read_ASN1.pod Normal file
View File

@ -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

82
doc/man3/SMIME_write_ASN1.pod Normal file
View File

@ -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

10
test/evp_test.c
View File

@ -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;
}

23
util/libcrypto.num
View File

@ -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:

11
util/missingcrypto.txt
View File

@ -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)