support PKCS7 certificate parsing (#5371)

* support PKCS7 certificate parsing

* refcounts are different in 1.0.2

* rename the functions

* black

* empty commit

* review feedback

1 files changed, 50 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index b2030609a..164ba376c 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -528,6 +528,56 @@ file suffix.
 
     :return bytes: Serialized PKCS12.
 
+PKCS7
+~~~~~
+
+.. currentmodule:: cryptography.hazmat.primitives.serialization.pkcs7
+
+PKCS7 is a format described in :rfc:`2315`, among other specifications. It can
+contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``,
+``p7m``, or ``p7s`` file suffix but other suffixes are also seen in the wild.
+
+.. note::
+
+    ``cryptography`` only supports parsing certificates from PKCS7 files at
+    this time.
+
+.. function:: load_pem_pkcs7_certificates(data)
+
+    .. versionadded:: 3.1
+
+    Deserialize a PEM encoded PKCS7 blob to a list of certificates. PKCS7 can
+    contain many other types of data, including CRLs, but this function will
+    ignore everything except certificates.
+
+    :param data: The data.
+    :type data: bytes
+
+    :returns: A list of :class:`~cryptography.x509.Certificate`.
+
+    :raises ValueError: If the PKCS7 data could not be loaded.
+
+    :raises cryptography.exceptions.UnsupportedAlgorithm: If the PKCS7 data
+        is of a type that is not supported.
+
+.. function:: load_der_pkcs7_certificates(data)
+
+    .. versionadded:: 3.1
+
+    Deserialize a DER encoded PKCS7 blob to a list of certificates. PKCS7 can
+    contain many other types of data, including CRLs, but this function will
+    ignore everything except certificates.
+
+    :param data: The data.
+    :type data: bytes
+
+    :returns: A list of :class:`~cryptography.x509.Certificate`.
+
+    :raises ValueError: If the PKCS7 data could not be loaded.
+
+    :raises cryptography.exceptions.UnsupportedAlgorithm: If the PKCS7 data
+        is of a type that is not supported.
+
 Serialization Formats
 ~~~~~~~~~~~~~~~~~~~~~