Add doc comments to pkcs7.h

aws · Nov 11, 2024 · aa9a47c · aa9a47c
1 parent 02f113e
commit aa9a47c
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 10 deletions.
diff --git a/crypto/pkcs7/bio/cipher.c b/crypto/pkcs7/bio/cipher.c
@@ -325,4 +325,4 @@ const BIO_METHOD *BIO_f_cipher(void) { return &methods_enc; }
 
 int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **ctx) {
   return BIO_ctrl(b, BIO_C_GET_CIPHER_CTX, 0, ctx);
-}
+}
diff --git a/crypto/pkcs7/pkcs7.c b/crypto/pkcs7/pkcs7.c
@@ -844,7 +844,9 @@ BIO *PKCS7_dataInit(PKCS7 *p7, BIO *bio) {
   }
 
   if (bio == NULL) {
+OPENSSL_BEGIN_ALLOW_DEPRECATED
     if (!PKCS7_is_detached(p7) && content && content->length > 0) {
+OPENSSL_END_ALLOW_DEPRECATED
       // |bio |needs a copy of |os->data| instead of a pointer because the data
       // will be used after |os |has been freed
       bio = BIO_new(BIO_s_mem());
@@ -876,7 +878,9 @@ BIO *PKCS7_dataInit(PKCS7 *p7, BIO *bio) {
   return NULL;
 }
 
+OPENSSL_BEGIN_ALLOW_DEPRECATED
 int PKCS7_is_detached(PKCS7 *p7) {
+OPENSSL_END_ALLOW_DEPRECATED
   GUARD_PTR(p7);
   if (PKCS7_type_is_signed(p7)) {
     return (p7->d.sign == NULL || p7->d.sign->contents->d.ptr == NULL);
@@ -946,10 +950,11 @@ STACK_OF(PKCS7_RECIP_INFO) *PKCS7_get_recipient_info(PKCS7 *p7) {
 
 int PKCS7_dataFinal(PKCS7 *p7, BIO *bio) {
   GUARD_PTR(p7);
+  GUARD_PTR(bio);
   int ret = 0;
-  BIO *bio_tmp;
+  BIO *bio_tmp = NULL;
   PKCS7_SIGNER_INFO *si;
-  EVP_MD_CTX *md_ctx, *md_ctx_tmp;
+  EVP_MD_CTX *md_ctx = NULL, *md_ctx_tmp;
   STACK_OF(PKCS7_SIGNER_INFO) *si_sk = NULL;
   ASN1_OCTET_STRING *content = NULL;
 
@@ -993,9 +998,13 @@ int PKCS7_dataFinal(PKCS7 *p7, BIO *bio) {
       break;
     case NID_pkcs7_signed:
       si_sk = p7->d.sign->signer_info;
+OPENSSL_BEGIN_ALLOW_DEPRECATED
       content = PKCS7_get_octet_string(p7->d.sign->contents);
+OPENSSL_END_ALLOW_DEPRECATED
       /* If detached data then the content is excluded */
+OPENSSL_BEGIN_ALLOW_DEPRECATED
       if (PKCS7_type_is_data(p7->d.sign->contents) && PKCS7_is_detached(p7)) {
+OPENSSL_END_ALLOW_DEPRECATED
         ASN1_OCTET_STRING_free(content);
         content = NULL;
         p7->d.sign->contents->d.data = NULL;
@@ -1005,7 +1014,9 @@ int PKCS7_dataFinal(PKCS7 *p7, BIO *bio) {
     case NID_pkcs7_digest:
       content = PKCS7_get_octet_string(p7->d.digest->contents);
       // If detached data, then the content is excluded
+OPENSSL_BEGIN_ALLOW_DEPRECATED
       if (PKCS7_type_is_data(p7->d.digest->contents) && PKCS7_is_detached(p7)) {
+OPENSSL_END_ALLOW_DEPRECATED
         ASN1_OCTET_STRING_free(content);
         content = NULL;
         p7->d.digest->contents->d.data = NULL;
@@ -1063,7 +1074,9 @@ int PKCS7_dataFinal(PKCS7 *p7, BIO *bio) {
     }
   }
 
+OPENSSL_BEGIN_ALLOW_DEPRECATED
   if (!PKCS7_is_detached(p7)) {
+OPENSSL_END_ALLOW_DEPRECATED
     if (content == NULL) {
       goto err;
     }

diff --git a/crypto/pkcs7/pkcs7_test.cc b/crypto/pkcs7/pkcs7_test.cc
@@ -1583,7 +1583,7 @@ TEST(PKCS7Test, DataInitFinal) {
   p7.reset(d2i_PKCS7(nullptr, &p7_ptr, p7_der_len));
   ASSERT_TRUE(p7);
   EXPECT_TRUE(PKCS7_type_is_signed(p7.get()));
-  bio.reset(PKCS7_dataInit(p7.get(), NULL));
+  bio.reset(PKCS7_dataInit(p7.get(), nullptr));
   EXPECT_TRUE(bio);
   EXPECT_TRUE(PKCS7_dataFinal(p7.get(), bio.get()));
 

diff --git a/include/openssl/pkcs7.h b/include/openssl/pkcs7.h
@@ -340,13 +340,25 @@ OPENSSL_EXPORT OPENSSL_DEPRECATED PKCS7 *PKCS7_sign(X509 *sign_cert,
                                                     STACK_OF(X509) *certs,
                                                     BIO *data, int flags);
 
+// PKCS7_is_detached returns 1 if |p7| has attached content and 0 otherwise.
+OPENSSL_EXPORT OPENSSL_DEPRECATED int PKCS7_is_detached(PKCS7 *p7);
 
-// TODO [childw]
-OPENSSL_EXPORT int PKCS7_is_detached(PKCS7 *p7);
-OPENSSL_EXPORT BIO *PKCS7_dataInit(PKCS7 *p7, BIO *bio);
-OPENSSL_EXPORT int PKCS7_dataFinal(PKCS7 *p7, BIO *bio);
-OPENSSL_EXPORT int PKCS7_set_digest(PKCS7 *p7, const EVP_MD *md);
-OPENSSL_EXPORT STACK_OF(PKCS7_RECIP_INFO) *PKCS7_get_recipient_info(PKCS7 *p7);
+// PKCS7_dataInit creates or initializes a BIO chain for reading data from or
+// writing data to |p7|. If |bio| is non-null, it is added to the chain.
+// Otherwise, a new BIO is allocated to anchor the chain.
+OPENSSL_EXPORT OPENSSL_DEPRECATED BIO *PKCS7_dataInit(PKCS7 *p7, BIO *bio);
+
+// PKCS7_dataFinal serializes data written to |bio|'s chain into |p7|. It should
+// only be called on BIO chains created by PKCS7_dataFinal.
+OPENSSL_EXPORT OPENSSL_DEPRECATED int PKCS7_dataFinal(PKCS7 *p7, BIO *bio);
+
+// PKCS7_set_digest sets |p7|'s digest to |md|. It returns 1 on sucess and 0 if
+// |p7| is of the wrong type.
+OPENSSL_EXPORT OPENSSL_DEPRECATED int PKCS7_set_digest(PKCS7 *p7, const EVP_MD *md);
+
+// PKCS7_get_recipient_info returns a point to a stack containing |p7|'s or NULL
+// if none are present.
+OPENSSL_EXPORT OPENSSL_DEPRECATED STACK_OF(PKCS7_RECIP_INFO) *PKCS7_get_recipient_info(PKCS7 *p7);
 
 #if defined(__cplusplus)
 }  // extern C