sslcontext 2.0.0__tar.gz → 2.1.0__tar.gz

{sslcontext-2.0.0 → sslcontext-2.1.0}/CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 Nothing yet.
 
+## [2.1.0] - 2026-10-19
+
+### Added
+
+- A PKCS#12 bundle (`.p12`/`.pfx`) is accepted wherever a certificate is
+  (`certificate=`, `load_pem()`), decrypted with `password=`; encrypted DER
+  (PKCS#8) private keys are decrypted with `password=` as PEM ones are.
+- A password may be `bytes`, or a file holding it (a path object, or anything
+  with `open()` or `read()`; its first line), read only when needed.
+
 ## [2.0.0] - 2026-10-19
 
 ### Added
@@ -82,5 +92,6 @@ Nothing yet.
   `openssl-engine` and `openssl-engine-capi` are superseded: OpenSSL 4 removed
   the ENGINE API they were built on.
 
-[Unreleased]: https://github.com/jose-pr/sslcontext/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/jose-pr/sslcontext/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/jose-pr/sslcontext/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/jose-pr/sslcontext/releases/tag/v2.0.0

{sslcontext-2.0.0 → sslcontext-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sslcontext
-Version: 2.0.0
+Version: 2.1.0
 Summary: Client certificates from OS keystores (Windows CNG, macOS Keychain, PKCS#11 smart cards) in a standard ssl.SSLContext, chosen as the browser would
 Project-URL: Homepage, https://github.com/jose-pr/sslcontext/
 Project-URL: Documentation, https://jose-pr.github.io/sslcontext/

{sslcontext-2.0.0 → sslcontext-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sslcontext"
-version = "2.0.0"
+version = "2.1.0"
 authors = [{ name = "Jose A." }]
 description = "Client certificates from OS keystores (Windows CNG, macOS Keychain, PKCS#11 smart cards) in a standard ssl.SSLContext, chosen as the browser would"
 readme = "README.md"

{sslcontext-2.0.0 → sslcontext-2.1.0}/src/sslcontext/AGENTS.md

@@ -216,10 +216,17 @@ def load_pem(
 
 Makes `certificate` (+ chain) and `key` the context's identity; nothing is
 written to disk. `certificate` is the leaf then its chain: PEM holding them
-in order, one DER certificate, or a list of sources in that order. `key` is
-a PEM or DER private key (or a `cryptography` key); omitted, it is read from
-the first certificate source (a combined PEM). `password` decrypts an
-encrypted key; see [PINs and passwords](#pins-and-passwords-sslcontext).
+in order, one DER certificate, or a list of sources in that order; or one
+PKCS#12 bundle (`.p12`/`.pfx`, recognised by its DER shape, whatever the file
+is called), loaded as `load_pkcs12` loads it, with `password` and without
+`key` (a `key`, or a bundle in a list, is a `ValueError`). `key` is a PEM or
+DER private key (DER: PKCS#8, encrypted or not, or the traditional RSA/EC
+form) or a `cryptography` key; omitted, it is read from the first
+certificate source (a combined PEM). `password` decrypts an encrypted key or
+bundle; see [PINs and passwords](#pins-and-passwords-sslcontext).
+`create_context(certificate=..., password=...)` and `system_context` take the
+same, so `create_context(certificate="client.p12", password="...")` is an
+mTLS context.
 
 ```python
 def load_pkcs12(
@@ -330,7 +337,7 @@ class PinRequest:
 
 PinCallback = Callable[[PinRequest], str | Prompt | None]
 PinSource = str | Prompt | PinCallback | None
-PasswordSource = str | bytes | Callable[[], str | bytes | None] | None
+PasswordSource = str | bytes | os.PathLike | <has open()> | <has read()> | Callable[[], str | bytes | None] | None
 ```
 
 A backend's `pin=` takes a `PinSource`: the PIN; `KEYSTORE_PROMPT`; a
@@ -346,10 +353,13 @@ handshake (or the listing) and propagates from `identities()`. A callback
 returning anything else raises `TypeError` (the message never includes the
 value). `PinRequest` never holds a PIN.
 
-Loaders take a `PasswordSource` for encrypted keys: a value, or a callable
-that is called only if the key turns out to be encrypted (returning `None`
-fails with `CredentialError`). OpenSSL's terminal passphrase prompt is never
-used.
+Loaders take a `PasswordSource` for encrypted keys and PKCS#12 bundles: the
+password as `str` (UTF-8) or `bytes` (a `str` is always the password itself,
+never a path); a file holding it (`os.PathLike`, or an object with `open()`
+or `read()`: its first line, without the line ending, as OpenSSL's `-passin
+file:` reads it); or a callable. A file or callable is consulted only if the
+key turns out to be encrypted (a callable returning `None` fails with
+`CredentialError`). OpenSSL's terminal passphrase prompt is never used.
 
 ```python
 def ask(request: sslcontext.PinRequest):
@@ -591,7 +601,7 @@ All in `sslcontext.exceptions`, re-exported from the root.
 | Class | Bases | Raised when |
 | --- | --- | --- |
 | `SSLContextError` | `Exception` | base of everything below |
-| `UnsupportedOpenSSLError` | `SSLContextError` | the interpreter's OpenSSL cannot be driven: LibreSSL, OpenSSL < 1.1.1, a static `_ssl` that hides its symbols, or an unrecognised `SSLContext` layout |
+| `UnsupportedOpenSSLError` | `SSLContextError` | the interpreter's TLS library cannot be driven: OpenSSL < 1.1.1, a static `_ssl` that hides its symbols, or an unrecognised `SSLContext` or LibreSSL structure layout |
 | `CredentialError` | `SSLContextError`, `ValueError` | malformed certificate/key, wrong password, key/certificate mismatch |
 | `IdentityNotFoundError` | `SSLContextError`, `LookupError` | no keystore entry matched a query |
 | `KeystoreError` | `SSLContextError`, `OSError` | the keystore refused or failed an operation |

{sslcontext-2.0.0 → sslcontext-2.1.0}/src/sslcontext/_asn1.py

@@ -9,6 +9,7 @@ __all__ = [
     "DIGEST_INFO_PREFIX",
     "certificate_usages",
     "ecdsa_der",
+    "is_pkcs12",
 ]
 
 # RFC 8017 section 9.2, note 1: DER of DigestInfo up to the digest bytes.
@@ -102,3 +103,16 @@ def certificate_usages(der: bytes) -> tuple:
                 octets = der[bits_start + 1 : bits_end]  # after the unused-bits count
                 usage = sum(octet << (8 * i) for i, octet in enumerate(octets[:2]))
     return extended, usage
+
+
+def is_pkcs12(data: bytes) -> bool:
+    """Whether DER ``data`` is a PKCS#12 bundle: ``SEQUENCE { INTEGER 3, ... }``
+    (a certificate's SEQUENCE starts with another SEQUENCE)."""
+    try:
+        tag, start, _ = _element(data, 0)
+        if tag != 0x30:
+            return False
+        inner, inner_start, inner_end = _element(data, start)
+    except (IndexError, ValueError):
+        return False
+    return inner == 0x02 and data[inner_start:inner_end] == b"\x03"

{sslcontext-2.0.0 → sslcontext-2.1.0}/src/sslcontext/_load.py

@@ -12,7 +12,8 @@ from ._openssl import _keys
 from ._openssl._errors import drain_errors
 from ._openssl._objects import read_certificates, read_pkcs12, read_private_key
 from ._openssl._signing import make_private_key
-from ._pin import PasswordSource, resolve_password
+from ._asn1 import is_pkcs12
+from ._pin import PasswordSource, deferred, resolve_password
 from ._sources import CertificatesLike, KeyLike, read_source, read_sources
 from .exceptions import CredentialError
 
@@ -38,7 +39,7 @@ def read_key_with(lib: OpenSSL, data: bytes, password: PasswordSource) -> int:
     A callable is not called for an unencrypted key, so it never prompts
     needlessly; when it gives nothing, an encrypted key fails at once.
     """
-    if not callable(password):
+    if not deferred(password):
         return read_private_key(lib, data, resolve_password(password))
     try:
         return read_private_key(lib, data, None)
@@ -108,18 +109,28 @@ def load_pem(
     holding them in order, one DER certificate, or a list of sources (each
     PEM or DER) in that order, in any form :data:`CertificatesLike` names
     (text, bytes, paths, objects with ``open()``, ``cryptography``
-    certificates). ``key`` is a PEM or DER private key, likewise, or a
-    ``cryptography`` private key; when omitted it is read from the first
-    certificate source, which then holds both. ``password`` (a value, or a
-    callable asked only if the key turns out encrypted) decrypts an encrypted
-    key. Nothing is written to disk.
+    certificates). It may instead be one PKCS#12 bundle (``.p12``/``.pfx``),
+    loaded as :func:`load_pkcs12` loads it, with no ``key``. ``key`` is a
+    PEM or DER private key (DER: PKCS#8, encrypted or not, or traditional),
+    likewise, or a ``cryptography`` private key; when omitted it is read from
+    the first certificate source, which then holds both. ``password`` (a
+    value, or a callable asked only if the key or bundle turns out
+    encrypted) decrypts it. Nothing is written to disk.
 
     Raises :class:`CredentialError` for malformed data, a wrong password, or a
     key that does not match the certificate; ``OSError`` when a named file
     cannot be read.
     """
-    lib = openssl()
     blobs = read_sources(certificate, "certificate")
+    if any(is_pkcs12(blob) for blob in blobs):
+        if len(blobs) != 1 or key is not None:
+            raise ValueError(
+                "a PKCS#12 bundle holds its own key and chain: pass it alone, "
+                "without key"
+            )
+        load_pkcs12(context, blobs[0], password)
+        return
+    lib = openssl()
     key_data = blobs[0] if key is None else read_source(key, "key")
     certificates: list = []
     try:
@@ -148,7 +159,7 @@ def load_pkcs12(
     """
     data = read_source(data, "data")
     lib = openssl()
-    if callable(password):
+    if deferred(password):
         try:
             key, certificate, chain = read_pkcs12(lib, bytes(data), None)
         except CredentialError:

{sslcontext-2.0.0 → sslcontext-2.1.0}/src/sslcontext/_openssl/_api.py

@@ -44,6 +44,7 @@ _SIGNATURES: dict[str, tuple[str, Any, tuple[Any, ...]]] = {
     "PEM_read_bio_PrivateKey": ("crypto", _P, (_P, _P, _P, c_char_p)),
     "d2i_X509_bio": ("crypto", _P, (_P, _P)),
     "d2i_PrivateKey_bio": ("crypto", _P, (_P, _P)),
+    "d2i_PKCS8PrivateKey_bio": ("crypto", _P, (_P, _P, _P, c_char_p)),
     "d2i_PKCS12_bio": ("crypto", _P, (_P, _P)),
     "i2d_X509": ("crypto", c_int, (_P, _PP)),
     "CRYPTO_free": ("crypto", None, (_P, c_char_p, c_int)),

{sslcontext-2.0.0 → sslcontext-2.1.0}/src/sslcontext/_openssl/_objects.py

@@ -75,6 +75,11 @@ def read_private_key(lib: OpenSSL, data: bytes, password: bytes | None) -> int:
             key = lib.PEM_read_bio_PrivateKey(bio, None, None, password or b"")
         else:
             key = lib.d2i_PrivateKey_bio(bio, None)
+    if not key and password is not None and _PEM_ANY not in data:
+        # DER has no header saying it is encrypted: try encrypted PKCS#8.
+        lib.ERR_clear_error()
+        with _MemoryBIO(lib, data) as bio:
+            key = lib.d2i_PKCS8PrivateKey_bio(bio, None, None, password)
     if not key:
         raise CredentialError(f"cannot read the private key: {drain_errors(lib)}")
     return key

{sslcontext-2.0.0 → sslcontext-2.1.0}/src/sslcontext/_pin.py

@@ -9,8 +9,9 @@ dialog, a PIN pad) is used only when the caller returns or passes
 from __future__ import annotations
 
 import enum
+import os
 from dataclasses import dataclass
-from typing import Callable, Optional, Union
+from typing import Any, Callable, Optional, Union
 
 __all__ = [
     "KEYSTORE_PROMPT",
@@ -63,8 +64,12 @@ PinSource = Union[str, Prompt, PinCallback, None]
 """A PIN, :data:`KEYSTORE_PROMPT`, a :data:`PinCallback`, or ``None`` (no PIN:
 fail instead of asking anyone)."""
 
-PasswordSource = Union[str, bytes, Callable[[], Union[str, bytes, None]], None]
-"""A password, a callable returning one (or ``None`` to decline), or ``None``."""
+PasswordSource = Union[
+    str, bytes, "os.PathLike[str]", Any, Callable[[], Union[str, bytes, None]], None
+]
+"""A password (``str`` or ``bytes``), a file holding it (``os.PathLike``, or
+an object with ``open()`` or ``read()``: its first line, without the line
+ending), a callable returning one (or ``None`` to decline), or ``None``."""
 
 
 def resolve_pin(source: PinSource, request: PinRequest) -> Union[str, Prompt, None]:
@@ -90,12 +95,32 @@ def resolve_pin(source: PinSource, request: PinRequest) -> Union[str, Prompt, No
     return answer
 
 
+def _is_file(source: Any) -> bool:
+    return isinstance(source, os.PathLike) or any(
+        callable(getattr(source, name, None)) for name in ("open", "read")
+    )
+
+
+def deferred(source: PasswordSource) -> bool:
+    """Whether ``source`` is consulted only when a password turns out needed."""
+    return callable(source) or _is_file(source)
+
+
 def resolve_password(source: PasswordSource) -> Optional[bytes]:
     """The password ``source`` gives, as bytes; ``None`` means none."""
-    if callable(source):
+    if callable(source) and not _is_file(source):
         source = source()
     if source is None or isinstance(source, bytes):
         return source
+    if isinstance(source, (bytearray, memoryview)):
+        return bytes(source)
     if isinstance(source, str):
         return source.encode("utf-8")
-    raise TypeError(f"a password must be str or bytes, not {type(source).__name__}")
+    if _is_file(source):
+        from ._sources import read_source
+
+        line = read_source(source, "password").split(b"\n", 1)[0]
+        return line[:-1] if line.endswith(b"\r") else line
+    raise TypeError(
+        f"a password must be str, bytes, a file or a callable, not {type(source).__name__}"
+    )

{sslcontext-2.0.0 → sslcontext-2.1.0}/tests/test_sources.py

@@ -124,3 +124,123 @@ def test_wrong_uses_are_refused():
         sslcontext.create_context(ca=[])
     with pytest.raises(TypeError, match="not int"):
         sslcontext.create_context(ca=42)
+
+
+@pytest.mark.parametrize(
+    "bundle",
+    [DATA / "client-rsa.p12", str(DATA / "client-rsa.p12"), data("client-rsa.p12")],
+    ids=["pathlike", "str-path", "bytes"],
+)
+def test_a_pkcs12_bundle_is_a_certificate(tls_server, bundle):
+    context = sslcontext.create_context(ca=CA, certificate=bundle, password="test")
+    assert tls_server.handshake(context).client_cn == "client-rsa"
+
+
+def test_a_pkcs12_password_callback_and_the_system_context(tls_server):
+    asked = []
+
+    def password():
+        asked.append(1)
+        return "test"
+
+    context = sslcontext.system_context(
+        ca=CA, certificate=DATA / "client-rsa.p12", password=password
+    )
+    assert tls_server.handshake(context).client_cn == "client-rsa"
+    assert asked == [1]
+
+
+def test_pkcs12_misuse_is_refused():
+    with pytest.raises(sslcontext.CredentialError, match="wrong password"):
+        sslcontext.create_context(certificate=DATA / "client-rsa.p12", password="no")
+    with pytest.raises(ValueError, match="PKCS#12"):
+        sslcontext.create_context(
+            certificate=DATA / "client-rsa.p12", key=DATA / "client-rsa.key"
+        )
+    with pytest.raises(ValueError, match="PKCS#12"):
+        sslcontext.create_context(
+            certificate=[DATA / "client-rsa.p12", DATA / "ca.pem"], password="test"
+        )
+
+
+def test_an_encrypted_der_key_takes_the_password(tls_server):
+    context = sslcontext.create_context(
+        ca=CA,
+        certificate=DATA / "client-ec.pem",
+        key=DATA / "client-ec.enc.der",
+        password="test",
+    )
+    assert tls_server.handshake(context).client_cn == "client-ec"
+    for wrong in (None, "no"):
+        with pytest.raises(sslcontext.CredentialError):
+            sslcontext.create_context(
+                certificate=DATA / "client-ec.pem",
+                key=DATA / "client-ec.enc.der",
+                password=wrong,
+            )
+
+
+def test_a_plain_der_key_never_asks_for_a_password(tls_server):
+    context = sslcontext.create_context(
+        ca=CA,
+        certificate=DATA / "client-ec.pem",
+        key=DATA / "client-ec.der",
+        password=lambda: pytest.fail("asked for a password"),
+    )
+    assert tls_server.handshake(context).client_cn == "client-ec"
+
+
+class _Reader:
+    def __init__(self, data):
+        self.data = data
+        self.reads = 0
+
+    def read(self):
+        self.reads += 1
+        return self.data
+
+
+@pytest.mark.parametrize(
+    "make",
+    [
+        lambda tmp: tmp / "pw.txt",
+        lambda tmp: str(tmp / "pw.txt"),
+        lambda tmp: _Opener(tmp / "pw.txt"),
+        lambda tmp: _Reader(b"test\r\nsecond line ignored\n"),
+        lambda tmp: b"test",
+        lambda tmp: bytearray(b"test"),
+    ],
+    ids=["pathlike", "str-is-the-password", "opener", "reader", "bytes", "bytearray"],
+)
+def test_passwords_from_values_and_files(tls_server, tmp_path, make):
+    (tmp_path / "pw.txt").write_bytes(b"test\n")
+    source = make(tmp_path)
+    if isinstance(source, str):  # a str is always the password itself
+        with pytest.raises(sslcontext.CredentialError):
+            sslcontext.create_context(
+                certificate=DATA / "client-rsa.p12", password=source
+            )
+        return
+    for certificate, key in (
+        (DATA / "client-rsa.p12", None),
+        (DATA / "client-ec.pem", DATA / "client-ec.enc.der"),
+        (DATA / "client-ec.pem", DATA / "client-ec.enc.key"),
+    ):
+        context = sslcontext.create_context(
+            ca=CA, certificate=certificate, key=key, password=source
+        )
+        assert tls_server.handshake(context).client_cn in ("client-rsa", "client-ec")
+
+
+def test_a_password_file_is_read_only_when_needed():
+    reader = _Reader(b"test")
+    sslcontext.create_context(
+        certificate=DATA / "client-ec.pem", key=DATA / "client-ec.key", password=reader
+    )
+    assert reader.reads == 0
+    sslcontext.create_context(
+        certificate=DATA / "client-ec.pem",
+        key=DATA / "client-ec.enc.key",
+        password=reader,
+    )
+    assert reader.reads == 1