Issue #17134: Finalize interface to Windows' certificate store. Cert and

CRL enumeration are now two functions. enum_certificates() also returns
purpose flags as set of OIDs.

Doc/library/ssl.rst

@@ -372,21 +372,45 @@ Certificate handling
 
    .. versionadded:: 3.4
 
-.. function:: enum_cert_store(store_name, cert_type='certificate')
+.. function:: enum_certificates(store_name)
 
    Retrieve certificates from Windows' system cert store. *store_name* may be
    one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
-   stores, too. *cert_type* is either ``certificate`` for X.509 certificates
-   or ``crl`` for X.509 certificate revocation lists.
+   stores, too.
 
-   The function returns a list of (bytes, encoding_type) tuples. The
-   encoding_type flag can be interpreted with :const:`X509_ASN_ENCODING` or
-   :const:`PKCS_7_ASN_ENCODING`.
+   The function returns a list of (cert_bytes, encoding_type, trust) tuples.
+   The encoding_type specifies the encoding of cert_bytes. It is either
+   :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
+   PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set
+   of OIDS or exactly ``True`` if the certificate is trustworthy for all
+   purposes.
+
+   Example::
+
+      >>> ssl.enum_certificates("CA")
+      [(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
+       (b'data...', 'x509_asn', True)]
 
    Availability: Windows.
 
    .. versionadded:: 3.4
 
+.. function:: enum_crls(store_name)
+
+   Retrieve CRLs from Windows' system cert store. *store_name* may be
+   one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
+   stores, too.
+
+   The function returns a list of (cert_bytes, encoding_type, trust) tuples.
+   The encoding_type specifies the encoding of cert_bytes. It is either
+   :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
+   PKCS#7 ASN.1 data.
+
+   Availability: Windows.
+
+   .. versionadded:: 3.4
+
+
 Constants
 ^^^^^^^^^
 
@@ -657,15 +681,6 @@ Constants
 
    .. versionadded:: 3.4
 
-.. data:: X509_ASN_ENCODING
-          PKCS_7_ASN_ENCODING
-
-   Encoding flags for :func:`enum_cert_store`.
-
-   Availability: Windows.
-
-   .. versionadded:: 3.4
-
 
 SSL Sockets
 -----------

Lib/ssl.py

@@ -144,7 +144,7 @@ else:
     _PROTOCOL_NAMES[PROTOCOL_TLSv1_2] = "TLSv1.2"
 
 if sys.platform == "win32":
-    from _ssl import enum_cert_store, X509_ASN_ENCODING, PKCS_7_ASN_ENCODING
+    from _ssl import enum_certificates, enum_crls
 
 from socket import getnameinfo as _getnameinfo
 from socket import socket, AF_INET, SOCK_STREAM, create_connection

Lib/test/test_ssl.py

@@ -528,29 +528,44 @@ class BasicSocketTests(unittest.TestCase):
             self.assertEqual(paths.cafile, CERTFILE)
             self.assertEqual(paths.capath, CAPATH)
 
-
     @unittest.skipUnless(sys.platform == "win32", "Windows specific")
-    def test_enum_cert_store(self):
-        self.assertEqual(ssl.X509_ASN_ENCODING, 1)
-        self.assertEqual(ssl.PKCS_7_ASN_ENCODING, 0x00010000)
-
-        self.assertEqual(ssl.enum_cert_store("CA"),
-            ssl.enum_cert_store("CA", "certificate"))
-        ssl.enum_cert_store("CA", "crl")
-        self.assertEqual(ssl.enum_cert_store("ROOT"),
-            ssl.enum_cert_store("ROOT", "certificate"))
-        ssl.enum_cert_store("ROOT", "crl")
-
-        self.assertRaises(TypeError, ssl.enum_cert_store)
-        self.assertRaises(WindowsError, ssl.enum_cert_store, "")
-        self.assertRaises(ValueError, ssl.enum_cert_store, "CA", "wrong")
-
-        ca = ssl.enum_cert_store("CA")
+    def test_enum_certificates(self):
+        self.assertTrue(ssl.enum_certificates("CA"))
+        self.assertTrue(ssl.enum_certificates("ROOT"))
+
+        self.assertRaises(TypeError, ssl.enum_certificates)
+        self.assertRaises(WindowsError, ssl.enum_certificates, "")
+
+        names = set()
+        ca = ssl.enum_certificates("CA")
         self.assertIsInstance(ca, list)
-        self.assertIsInstance(ca[0], tuple)
-        self.assertEqual(len(ca[0]), 2)
-        self.assertIsInstance(ca[0][0], bytes)
-        self.assertIsInstance(ca[0][1], int)
+        for element in ca:
+            self.assertIsInstance(element, tuple)
+            self.assertEqual(len(element), 3)
+            cert, enc, trust = element
+            self.assertIsInstance(cert, bytes)
+            self.assertIn(enc, {"x509_asn", "pkcs_7_asn"})
+            self.assertIsInstance(trust, (set, bool))
+            if isinstance(trust, set):
+                names.update(trust)
+
+        serverAuth = "1.3.6.1.5.5.7.3.1"
+        self.assertIn(serverAuth, names)
+
+    @unittest.skipUnless(sys.platform == "win32", "Windows specific")
+    def test_enum_crls(self):
+        self.assertTrue(ssl.enum_crls("CA"))
+        self.assertRaises(TypeError, ssl.enum_crls)
+        self.assertRaises(WindowsError, ssl.enum_crls, "")
+
+        crls = ssl.enum_crls("CA")
+        self.assertIsInstance(crls, list)
+        for element in crls:
+            self.assertIsInstance(element, tuple)
+            self.assertEqual(len(element), 2)
+            self.assertIsInstance(element[0], bytes)
+            self.assertIn(element[1], {"x509_asn", "pkcs_7_asn"})
+
 
     def test_asn1object(self):
         expected = (129, 'serverAuth', 'TLS Web Server Authentication',

Misc/NEWS

@@ -59,6 +59,10 @@ Core and Builtins
 Library
 -------
 
+- Issue #17134: Finalize interface to Windows' certificate store. Cert and
+  CRL enumeration are now two functions. enum_certificates() also returns
+  purpose flags as set of OIDs.
+
 - Issue #19555: Restore sysconfig.get_config_var('SO'), with a
   DeprecationWarning pointing people at $EXT_SUFFIX.