Add license, ASN.1 doc comments

aws · Aug 28, 2024 · 578d967 · 578d967
1 parent 5ff6e4d
commit 578d967
Show file tree

Hide file tree

Showing 3 changed files with 109 additions and 4 deletions.
diff --git a/crypto/pkcs7/internal.h b/crypto/pkcs7/internal.h
@@ -35,6 +35,19 @@ DECLARE_ASN1_FUNCTIONS(PKCS7_SIGN_ENVELOPE)
 
 DEFINE_STACK_OF(PKCS7)
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-11.1
+//
+//   SignedAndEnvelopedData ::= SEQUENCE {
+//     version Version,
+//     recipientInfos RecipientInfos,
+//     digestAlgorithms DigestAlgorithmIdentifiers,
+//     encryptedContentInfo EncryptedContentInfo,
+//     certificates
+//        [0] IMPLICIT ExtendedCertificatesAndCertificates
+//          OPTIONAL,
+//     crls
+//       [1] IMPLICIT CertificateRevocationLists OPTIONAL,
+//     signerInfos SignerInfos }
 struct pkcs7_sign_envelope_st {
     ASN1_INTEGER *version;
     STACK_OF(PKCS7_RECIP_INFO) *recipientinfo;
@@ -45,11 +58,31 @@ struct pkcs7_sign_envelope_st {
     STACK_OF(PKCS7_SIGNER_INFO) *signer_info;
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-6.7
+//
+//   IssuerAndSerialNumber ::= SEQUENCE {
+//     issuer Name,
+//     serialNumber CertificateSerialNumber }
 struct pkcs7_issuer_and_serial_st {
     X509_NAME *issuer;
     ASN1_INTEGER *serial;
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-9.2
+//
+//   SignerInfo ::= SEQUENCE {
+//     version Version,
+//     issuerAndSerialNumber IssuerAndSerialNumber,
+//     digestAlgorithm DigestAlgorithmIdentifier,
+//     authenticatedAttributes
+//       [0] IMPLICIT Attributes OPTIONAL,
+//     digestEncryptionAlgorithm
+//       DigestEncryptionAlgorithmIdentifier,
+//     encryptedDigest EncryptedDigest,
+//     unauthenticatedAttributes
+//       [1] IMPLICIT Attributes OPTIONAL }
+//
+//   EncryptedDigest ::= OCTET STRING
 struct pkcs7_signer_info_st {
     ASN1_INTEGER *version;
     PKCS7_ISSUER_AND_SERIAL *issuer_and_serial;
@@ -58,38 +91,81 @@ struct pkcs7_signer_info_st {
     X509_ALGOR *digest_enc_alg;
     ASN1_OCTET_STRING *enc_digest;
     STACK_OF(X509_ATTRIBUTE) *unauth_attr;
-    EVP_PKEY *pkey;
+    EVP_PKEY *pkey; // NOTE: |pkey| is not seriliazed.
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-10.2
+//
+//   RecipientInfo ::= SEQUENCE {
+//     version Version,
+//     issuerAndSerialNumber IssuerAndSerialNumber,
+//     keyEncryptionAlgorithm
+//
+//       KeyEncryptionAlgorithmIdentifier,
+//     encryptedKey EncryptedKey }
+//
+//   EncryptedKey ::= OCTET STRING
 struct pkcs7_recip_info_st {
     ASN1_INTEGER *version;
     PKCS7_ISSUER_AND_SERIAL *issuer_and_serial;
     X509_ALGOR *key_enc_algor;
     ASN1_OCTET_STRING *enc_key;
-    X509 *cert;
+    X509 *cert; // NOTE: |cert| is not serialized
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-10.1
+//
+//   EncryptedContentInfo ::= SEQUENCE {
+//     contentType ContentType,
+//     contentEncryptionAlgorithm
+//       ContentEncryptionAlgorithmIdentifier,
+//     encryptedContent
+//       [0] IMPLICIT EncryptedContent OPTIONAL }
+//
+//   EncryptedContent ::= OCTET STRING
 struct pkcs7_enc_content_st {
     ASN1_OBJECT *content_type;
     X509_ALGOR *algorithm;
     ASN1_OCTET_STRING *enc_data;
-    const EVP_CIPHER *cipher;
+    const EVP_CIPHER *cipher;   // NOTE: |cipher| is not serialized
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-10.1
+//
+//    EnvelopedData ::= SEQUENCE {
+//      version Version,
+//      recipientInfos RecipientInfos,
+//      encryptedContentInfo EncryptedContentInfo }
+//
+//    RecipientInfos ::= SET OF RecipientInfo
 struct pkcs7_envelope_st {
   ASN1_INTEGER *version;
   PKCS7_ENC_CONTENT *enc_data;
   STACK_OF(PKCS7_RECIP_INFO) *recipientinfo;
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-12
+//
+//   DigestedData ::= SEQUENCE {
+//     version Version,
+//     digestAlgorithm DigestAlgorithmIdentifier,
+//     contentInfo ContentInfo,
+//     digest Digest }
+//
+//   Digest ::= OCTET STRING
 struct pkcs7_digest_st {
     ASN1_INTEGER *version;
     X509_ALGOR *digest_alg;
     PKCS7 *contents;
     ASN1_OCTET_STRING *digest;
-    const EVP_MD *md;
+    const EVP_MD *md;   // NOTE: |md| is not serialized
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-13
+//
+//   EncryptedData ::= SEQUENCE {
+//     version Version,
+//     encryptedContentInfo EncryptedContentInfo }
 struct pkcs7_encrypt_st {
     ASN1_INTEGER *version;
     PKCS7_ENC_CONTENT *enc_data;

diff --git a/crypto/pkcs7/pkcs7_asn1.c b/crypto/pkcs7/pkcs7_asn1.c
@@ -1,3 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0 OR ISC
+
 #include <openssl/pkcs7.h>
 
 #include <openssl/asn1t.h>

diff --git a/include/openssl/pkcs7.h b/include/openssl/pkcs7.h
@@ -108,6 +108,14 @@ OPENSSL_EXPORT int PKCS7_get_PEM_CRLs(STACK_OF(X509_CRL) *out_crls,
 // API. It intentionally does not implement the whole thing, only the minimum
 // needed to build cryptography.io and CRuby.
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-7
+//
+//   ContentInfo ::= SEQUENCE {
+//     contentType ContentType,
+//     content
+//       [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL }
+//
+//   ContentType ::= OBJECT IDENTIFIER
 struct pkcs7_st {
   // Unlike OpenSSL, the following fields are immutable. They filled in when the
   // object is parsed and ignored in serialization.
@@ -124,6 +132,24 @@ struct pkcs7_st {
   } d;
 };
 
+// ASN.1 defined here https://datatracker.ietf.org/doc/html/rfc2315#section-9.1
+//
+//   SignedData ::= SEQUENCE {
+//     version Version,
+//     digestAlgorithms DigestAlgorithmIdentifiers,
+//     contentInfo ContentInfo,
+//     certificates
+//        [0] IMPLICIT ExtendedCertificatesAndCertificates
+//          OPTIONAL,
+//     crls
+//       [1] IMPLICIT CertificateRevocationLists OPTIONAL,
+//     signerInfos SignerInfos }
+//
+//   DigestAlgorithmIdentifiers ::=
+//
+//     SET OF DigestAlgorithmIdentifier
+//
+//   SignerInfos ::= SET OF SignerInfo
 struct pkcs7_signed_st {
   ASN1_INTEGER *version;
   STACK_OF(X509_ALGOR) *md_algs;