PKCS7SignatureBuilder now supports three serializations (#5497)

* PKCS7SignatureBuilder now supports three serializations

PEM, DER, and SMIME. SMIME embeds the S/MIME headers and has the
detached signature concept.

* thanks libre

Author: reaperhulk

docs/hazmat/primitives/asymmetric/serialization.rst

@@ -620,7 +620,7 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
         ... ).add_signer(
         ...     cert, key, hashes.SHA256()
         ... ).sign(
-        ...     serialization.Encoding.PEM, options
+        ...     serialization.Encoding.SMIME, options
         ... )
         b'...'
 
@@ -649,8 +649,9 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
 
     .. method:: sign(encoding, options, backend=None)
 
-        :param encoding: :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`
-            or :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`.
+        :param encoding: :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+            :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`,
+            or :attr:`~cryptography.hazmat.primitives.serialization.Encoding.SMIME`.
 
         :param options: A list of
             :class:`~cryptography.hazmat.primitives.serialization.pkcs7.PKCS7Options`.
@@ -670,19 +671,19 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
 
         The text option adds ``text/plain`` headers to an S/MIME message when
         serializing to
-        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`.
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.SMIME`.
         This option is disallowed with ``DER`` serialization.
 
     .. attribute:: Binary
 
-        S/MIME signing normally converts line endings (LF to CRLF). When
+        Signing normally converts line endings (LF to CRLF). When
         passing this option the data will not be converted.
 
     .. attribute:: DetachedSignature
 
         Don't embed the signed data within the ASN.1. When signing with
-        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` this
-        also results in the data being added as clear text before the
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.SMIME`
+        this also results in the data being added as clear text before the
         PEM encoded structure.
 
     .. attribute:: NoCapabilities
@@ -891,6 +892,12 @@ Serialization Encodings
         The format used by elliptic curve point encodings. This is a binary
         format.
 
+    .. attribute:: SMIME
+
+        .. versionadded:: 3.2
+
+        An output format used for PKCS7. This is a text format.
+
 
 Serialization Encryption Types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/_cffi_src/openssl/pkcs7.py

@@ -60,6 +60,7 @@
 PKCS7 *PKCS7_sign(X509 *, EVP_PKEY *, Cryptography_STACK_OF_X509 *,
                    BIO *, int);
 int SMIME_write_PKCS7(BIO *, PKCS7 *, BIO *, int);
+int PEM_write_bio_PKCS7_stream(BIO *, PKCS7 *, BIO *, int);
 PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *, X509 *, EVP_PKEY *,
                                          const EVP_MD *, int);
 int PKCS7_final(PKCS7 *, BIO *, int);

src/cryptography/hazmat/backends/openssl/backend.py

@@ -2735,11 +2735,17 @@ def pkcs7_sign(self, builder, encoding, options):
                 final_flags |= self._lib.PKCS7_BINARY
 
         bio_out = self._create_mem_bio_gc()
-        if encoding is serialization.Encoding.PEM:
+        if encoding is serialization.Encoding.SMIME:
             # This finalizes the structure
             res = self._lib.SMIME_write_PKCS7(
                 bio_out, p7, bio.bio, final_flags
             )
+        elif encoding is serialization.Encoding.PEM:
+            res = self._lib.PKCS7_final(p7, bio.bio, final_flags)
+            self.openssl_assert(res == 1)
+            res = self._lib.PEM_write_bio_PKCS7_stream(
+                bio_out, p7, bio.bio, final_flags
+            )
         else:
             assert encoding is serialization.Encoding.DER
             # We need to call finalize here becauase i2d_PKCS7_bio does not

src/cryptography/hazmat/primitives/serialization/base.py

@@ -49,6 +49,7 @@ class Encoding(Enum):
     OpenSSH = "OpenSSH"
     Raw = "Raw"
     X962 = "ANSI X9.62"
+    SMIME = "S/MIME"
 
 
 class PrivateFormat(Enum):

src/cryptography/hazmat/primitives/serialization/pkcs7.py

@@ -71,11 +71,14 @@ def sign(self, encoding, options, backend=None):
         options = list(options)
         if not all(isinstance(x, PKCS7Options) for x in options):
             raise ValueError("options must be from the PKCS7Options enum")
-        if (
-            encoding is not serialization.Encoding.PEM
-            and encoding is not serialization.Encoding.DER
+        if encoding not in (
+            serialization.Encoding.PEM,
+            serialization.Encoding.DER,
+            serialization.Encoding.SMIME,
         ):
-            raise ValueError("Must be PEM or DER from the Encoding enum")
+            raise ValueError(
+                "Must be PEM, DER, or SMIME from the Encoding enum"
+            )
 
         # Text is a meaningless option unless it is accompanied by
         # DetachedSignature
@@ -88,12 +91,12 @@ def sign(self, encoding, options, backend=None):
                 "DetachedSignature"
             )
 
-        if (
-            PKCS7Options.Text in options
-            and encoding is serialization.Encoding.DER
+        if PKCS7Options.Text in options and encoding in (
+            serialization.Encoding.DER,
+            serialization.Encoding.PEM,
         ):
             raise ValueError(
-                "The Text option does nothing when serializing to DER"
+                "The Text option is only available for SMIME serialization"
             )
 
         # No attributes implies no capabilities so we'll error if you try to