python-pkcs11 0.10.1__cp315-cp315-win_amd64.whl

pkcs11/util/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import SupportsInt
+
+
+def biginteger(value: SupportsInt) -> bytes:
+    """
+    Returns a PKCS#11 biginteger bytestream from a Python integer or
+    similar type (e.g. :class:`asn1crypto.core.Integer`).
+
+    :param int value: Value
+    :rtype: bytes
+    """
+
+    value_int = int(value)  # In case it's a asn1 type or similar
+
+    return value_int.to_bytes((value_int.bit_length() + 7) // 8, byteorder="big")

pkcs11/util/dh.py

@@ -0,0 +1,79 @@
+"""
+Key handling utilities for Diffie-Hellman keys.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from asn1crypto.algos import DHParameters
+from asn1crypto.core import Integer
+
+from pkcs11.constants import Attribute
+from pkcs11.util import biginteger
+
+if TYPE_CHECKING:
+    from pkcs11.types import DomainParameters, PublicKey
+
+
+def decode_dh_domain_parameters(der: bytes) -> dict[Attribute, Any]:
+    """
+    Decode DER-encoded Diffie-Hellman domain parameters.
+
+    :param bytes der: DER-encoded parameters
+    :rtype: dict(Attribute,*)
+    """
+
+    params = DHParameters.load(der)
+
+    return {
+        Attribute.BASE: biginteger(params["g"]),
+        Attribute.PRIME: biginteger(params["p"]),
+    }
+
+
+def encode_dh_domain_parameters(obj: DomainParameters) -> bytes:
+    """
+    Encode DH domain parameters into DER-encoded format.
+
+    Calculates the subprime if it isn't available.
+
+    :param DomainParameters obj: domain parameters
+    :rtype: bytes
+    """
+
+    asn1 = DHParameters(
+        {
+            "g": int.from_bytes(obj[Attribute.BASE], byteorder="big"),
+            "p": int.from_bytes(obj[Attribute.PRIME], byteorder="big"),
+        }
+    )
+
+    return asn1.dump()
+
+
+def encode_dh_public_key(key: PublicKey) -> bytes:
+    """
+    Encode DH public key into RFC 3279 DER-encoded format.
+
+    :param PublicKey key: public key
+    :rtype: bytes
+    """
+
+    asn1 = Integer(int.from_bytes(key[Attribute.VALUE], byteorder="big"))
+
+    return asn1.dump()
+
+
+def decode_dh_public_key(der: bytes) -> bytes:
+    """
+    Decode a DH public key from RFC 3279 DER-encoded format.
+
+    Returns a `biginteger` encoded as bytes.
+
+    :param bytes der: DER-encoded public key
+    :rtype: bytes
+    """
+
+    asn1 = Integer.load(der)
+    return biginteger(asn1)

pkcs11/util/dsa.py

@@ -0,0 +1,108 @@
+"""
+Key handling utilities for DSA keys, domain parameters and signatures..
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from asn1crypto.algos import DSASignature
+from asn1crypto.core import Integer
+from asn1crypto.keys import DSAParams
+
+from pkcs11.constants import Attribute
+from pkcs11.util import biginteger
+
+if TYPE_CHECKING:
+    from pkcs11.types import DomainParameters, PublicKey
+
+
+def decode_dsa_domain_parameters(der: bytes) -> dict[Attribute, Any]:
+    """
+    Decode RFC 3279 DER-encoded Dss-Params.
+
+    :param bytes der: DER-encoded parameters
+    :rtype: dict(Attribute,*)
+    """
+
+    params = DSAParams.load(der)
+
+    return {
+        Attribute.BASE: biginteger(params["g"]),
+        Attribute.PRIME: biginteger(params["p"]),
+        Attribute.SUBPRIME: biginteger(params["q"]),
+    }
+
+
+def encode_dsa_domain_parameters(obj: DomainParameters) -> bytes:
+    """
+    Encode RFC 3279 DER-encoded Dss-Params.
+
+    :param DomainParameters obj: domain parameters
+    :rtype: bytes
+    """
+    asn1 = DSAParams(
+        {
+            "g": int.from_bytes(obj[Attribute.BASE], byteorder="big"),
+            "p": int.from_bytes(obj[Attribute.PRIME], byteorder="big"),
+            "q": int.from_bytes(obj[Attribute.SUBPRIME], byteorder="big"),
+        }
+    )
+
+    return asn1.dump()
+
+
+def encode_dsa_public_key(key: PublicKey) -> bytes:
+    """
+    Encode DSA public key into RFC 3279 DER-encoded format.
+
+    :param PublicKey key: public key
+    :rtype: bytes
+    """
+
+    asn1 = Integer(int.from_bytes(key[Attribute.VALUE], byteorder="big"))
+
+    return asn1.dump()
+
+
+def decode_dsa_public_key(der: bytes) -> bytes:
+    """
+    Decode a DSA public key from RFC 3279 DER-encoded format.
+
+    Returns a `biginteger` encoded as bytes.
+
+    :param bytes der: DER-encoded public key
+    :rtype: bytes
+    """
+
+    asn1 = Integer.load(der)
+
+    return biginteger(asn1)
+
+
+def encode_dsa_signature(signature: bytes) -> bytes:
+    """
+    Encode a signature (generated by :meth:`pkcs11.SignMixin.sign`) into
+    DER-encoded ASN.1 (Dss_Sig_Value) format.
+
+    :param bytes signature: signature as bytes
+    :rtype: bytes
+    """
+
+    asn1 = DSASignature.from_p1363(signature)
+
+    return asn1.dump()
+
+
+def decode_dsa_signature(der: bytes) -> bytes:
+    """
+    Decode a DER-encoded ASN.1 (Dss_Sig_Value) signature (as generated by
+    OpenSSL/X.509) into PKCS #11 format.
+
+    :param bytes der: DER-encoded signature
+    :rtype bytes:
+    """
+
+    asn1 = DSASignature.load(der)
+
+    return asn1.to_p1363()

pkcs11/util/ec.py

@@ -0,0 +1,143 @@
+"""
+Key handling utilities for EC keys (ANSI X.62/RFC3279), domain parameter and
+signatures.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from asn1crypto.algos import DSASignature
+from asn1crypto.core import OctetString
+from asn1crypto.keys import (
+    ECDomainParameters,
+    ECPrivateKey,
+    NamedCurve,
+    PublicKeyInfo,
+)
+
+from pkcs11.constants import Attribute, ObjectClass
+from pkcs11.mechanisms import KeyType
+
+if TYPE_CHECKING:
+    from pkcs11.types import PublicKey
+
+
+def encode_named_curve_parameters(oid: str) -> bytes:
+    """
+    Return DER-encoded ANSI X.62 EC parameters for a named curve.
+
+    Curve names are given by object identifier or common name. Names come
+    from `asn1crypto
+    <https://github.com/wbond/asn1crypto/blob/master/asn1crypto/keys.py#L338>`_.
+
+    :param str oid: OID or named curve
+    :rtype: bytes
+    """
+    return ECDomainParameters(
+        name="named",
+        value=NamedCurve.unmap(oid),
+    ).dump()
+
+
+def decode_ec_public_key(
+    der: bytes,
+    encode_ec_point: bool = True,
+) -> dict[Attribute, Any]:
+    """
+    Decode a DER-encoded EC public key as stored by OpenSSL into a dictionary
+    of attributes able to be passed to :meth:`pkcs11.Session.create_object`.
+
+    .. note:: **encode_ec_point**
+
+        For use as an attribute `EC_POINT` should be DER-encoded (True).
+
+        For key derivation implementations can vary.  Since v2.30 the
+        specification says implementations MUST accept a raw `EC_POINT` for
+        ECDH (False), however not all implementations follow this yet.
+
+    :param bytes der: DER-encoded key
+    :param encode_ec_point: See text.
+    :rtype: dict(Attribute,*)
+    """
+    asn1 = PublicKeyInfo.load(der)
+
+    assert asn1.algorithm == "ec", "Wrong algorithm, not an EC key!"
+
+    ecpoint = bytes(asn1["public_key"])
+
+    if encode_ec_point:
+        ecpoint = OctetString(ecpoint).dump()
+
+    return {
+        Attribute.KEY_TYPE: KeyType.EC,
+        Attribute.CLASS: ObjectClass.PUBLIC_KEY,
+        Attribute.EC_PARAMS: asn1["algorithm"]["parameters"].dump(),
+        Attribute.EC_POINT: ecpoint,
+    }
+
+
+def decode_ec_private_key(der: bytes) -> dict[Attribute, Any]:
+    """
+    Decode a DER-encoded EC private key as stored by OpenSSL into a dictionary
+    of attributes able to be passed to :meth:`pkcs11.Session.create_object`.
+
+    :param bytes der: DER-encoded key
+    :rtype: dict(Attribute,*)
+    """
+
+    asn1 = ECPrivateKey.load(der)
+
+    return {
+        Attribute.KEY_TYPE: KeyType.EC,
+        Attribute.CLASS: ObjectClass.PRIVATE_KEY,
+        Attribute.EC_PARAMS: asn1["parameters"].chosen.dump(),
+        Attribute.VALUE: asn1["private_key"].contents,
+    }
+
+
+def encode_ec_public_key(key: PublicKey) -> bytes:
+    """
+    Encode a DER-encoded EC public key as stored by OpenSSL.
+
+    :param PublicKey key: EC public key
+    :rtype: bytes
+    """
+
+    ecparams = ECDomainParameters.load(key[Attribute.EC_PARAMS])
+    ecpoint = bytes(OctetString.load(key[Attribute.EC_POINT]))
+
+    return PublicKeyInfo(
+        {
+            "algorithm": {
+                "algorithm": "ec",
+                "parameters": ecparams,
+            },
+            "public_key": ecpoint,
+        }
+    ).dump()
+
+
+def encode_ecdsa_signature(signature: bytes) -> bytes:
+    """
+    Encode a signature (generated by :meth:`pkcs11.SignMixin.sign`) into
+    DER-encoded ASN.1 (ECDSA_Sig_Value) format.
+
+    :param bytes signature: signature as bytes
+    :rtype: bytes
+    """
+
+    return DSASignature.from_p1363(signature).dump()
+
+
+def decode_ecdsa_signature(der: bytes) -> bytes:
+    """
+    Decode a DER-encoded ASN.1 (ECDSA_Sig_Value) signature (as generated by
+    OpenSSL/X.509) into PKCS #11 format.
+
+    :param bytes der: DER-encoded signature
+    :rtype bytes:
+    """
+
+    asn1 = DSASignature.load(der)
+    return asn1.to_p1363()

pkcs11/util/rsa.py

@@ -0,0 +1,95 @@
+"""
+Key handling utilities for RSA keys (PKCS#1).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from asn1crypto.keys import RSAPrivateKey, RSAPublicKey
+
+from pkcs11.constants import Attribute, MechanismFlag, ObjectClass
+from pkcs11.defaults import DEFAULT_KEY_CAPABILITIES
+from pkcs11.mechanisms import KeyType
+from pkcs11.util import biginteger
+
+if TYPE_CHECKING:
+    from pkcs11.types import PublicKey
+
+
+def decode_rsa_private_key(
+    der: bytes,
+    capabilities: MechanismFlag | int | None = None,
+) -> dict[Attribute, Any]:
+    """
+    Decode a RFC2437 (PKCS#1) DER-encoded RSA private key into a dictionary of
+    attributes able to be passed to :meth:`pkcs11.Session.create_object`.
+
+    :param bytes der: DER-encoded key
+    :param MechanismFlag capabilities: Optional key capabilities
+    :rtype: dict(Attribute,*)
+    """
+    caps: MechanismFlag | int = (
+        DEFAULT_KEY_CAPABILITIES[KeyType.RSA] if capabilities is None else capabilities
+    )
+
+    key = RSAPrivateKey.load(der)
+
+    return {
+        Attribute.CLASS: ObjectClass.PRIVATE_KEY,
+        Attribute.KEY_TYPE: KeyType.RSA,
+        Attribute.MODULUS: biginteger(key["modulus"]),
+        Attribute.PUBLIC_EXPONENT: biginteger(key["public_exponent"]),
+        Attribute.PRIVATE_EXPONENT: biginteger(key["private_exponent"]),
+        Attribute.PRIME_1: biginteger(key["prime1"]),
+        Attribute.PRIME_2: biginteger(key["prime2"]),
+        Attribute.EXPONENT_1: biginteger(key["exponent1"]),
+        Attribute.EXPONENT_2: biginteger(key["exponent2"]),
+        Attribute.COEFFICIENT: biginteger(key["coefficient"]),
+        Attribute.DECRYPT: MechanismFlag.DECRYPT & caps != 0,
+        Attribute.SIGN: MechanismFlag.SIGN & caps != 0,
+        Attribute.UNWRAP: MechanismFlag.UNWRAP & caps != 0,
+    }
+
+
+def decode_rsa_public_key(
+    der: bytes,
+    capabilities: MechanismFlag | int | None = None,
+) -> dict[Attribute, Any]:
+    """
+    Decode a RFC2437 (PKCS#1) DER-encoded RSA public key into a dictionary of
+    attributes able to be passed to :meth:`pkcs11.Session.create_object`.
+
+    :param bytes der: DER-encoded key
+    :param MechanismFlag capabilities: Optional key capabilities
+    :rtype: dict(Attribute,*)
+    """
+    caps: MechanismFlag | int = (
+        DEFAULT_KEY_CAPABILITIES[KeyType.RSA] if capabilities is None else capabilities
+    )
+
+    key = RSAPublicKey.load(der)
+    return {
+        Attribute.CLASS: ObjectClass.PUBLIC_KEY,
+        Attribute.KEY_TYPE: KeyType.RSA,
+        Attribute.MODULUS: biginteger(key["modulus"]),
+        Attribute.PUBLIC_EXPONENT: biginteger(key["public_exponent"]),
+        Attribute.ENCRYPT: MechanismFlag.ENCRYPT & caps != 0,
+        Attribute.VERIFY: MechanismFlag.VERIFY & caps != 0,
+        Attribute.WRAP: MechanismFlag.WRAP & caps != 0,
+    }
+
+
+def encode_rsa_public_key(key: PublicKey) -> bytes:
+    """
+    Encode an RSA public key into PKCS#1 DER-encoded format.
+
+    :param PublicKey key: RSA public key
+    :rtype: bytes
+    """
+    return RSAPublicKey(
+        {
+            "modulus": int.from_bytes(key[Attribute.MODULUS], byteorder="big"),
+            "public_exponent": int.from_bytes(key[Attribute.PUBLIC_EXPONENT], byteorder="big"),
+        }
+    ).dump()

pkcs11/util/x509.py

@@ -0,0 +1,136 @@
+"""
+Certificate handling utilities for X.509 (SSL) certificates.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from asn1crypto.core import OctetString
+from asn1crypto.x509 import Certificate
+
+from pkcs11.constants import Attribute, CertificateType, ObjectClass
+from pkcs11.mechanisms import KeyType
+
+
+def decode_x509_public_key(der: bytes) -> dict[Attribute, Any]:
+    """
+    Decode a DER-encoded X.509 certificate's public key into a set of
+    attributes able to be passed to :meth:`pkcs11.Session.create_object`.
+
+    For PEM-encoded certificates, use :func:`asn1crypto.pem.unarmor`.
+
+    .. warning::
+
+        Does not verify certificate.
+
+    :param bytes der: DER-encoded certificate
+    :rtype: dict(Attribute,*)
+    """
+    x509 = Certificate.load(der)
+    key_info = x509.public_key
+    key = bytes(key_info["public_key"])
+
+    key_type = {
+        "rsa": KeyType.RSA,
+        "dsa": KeyType.DSA,
+        "ec": KeyType.EC,
+    }[key_info.algorithm]
+
+    attrs: dict[Attribute, Any] = {
+        Attribute.CLASS: ObjectClass.PUBLIC_KEY,
+        Attribute.KEY_TYPE: key_type,
+    }
+
+    if key_type is KeyType.RSA:
+        from .rsa import decode_rsa_public_key
+
+        attrs.update(decode_rsa_public_key(key))
+    elif key_type is KeyType.DSA:
+        from .dsa import decode_dsa_domain_parameters, decode_dsa_public_key
+
+        params = key_info["algorithm"]["parameters"].dump()
+
+        attrs.update(decode_dsa_domain_parameters(params))
+        attrs.update(
+            {
+                Attribute.VALUE: decode_dsa_public_key(key),
+            }
+        )
+    elif key_type is KeyType.EC:
+        params = key_info["algorithm"]["parameters"].dump()
+
+        # bytes(key_info['public_key']) returns the binary encoding
+        # of the EC point itself (decoded from its BitString representation in X.509),
+        # but PKCS#11 expects this as a DER OctetString.
+        key = OctetString(key).dump()
+        attrs.update(
+            {
+                Attribute.EC_PARAMS: params,
+                Attribute.EC_POINT: key,
+            }
+        )
+    else:
+        raise AssertionError("Should not be reached")
+
+    return attrs
+
+
+def decode_x509_certificate(
+    der: bytes,
+    extended_set: bool = False,
+) -> dict[Attribute, Any]:
+    """
+    Decode a DER-encoded X.509 certificate into a dictionary of
+    attributes able to be passed to :meth:`pkcs11.Session.create_object`.
+
+    Optionally pass `extended_set` to include additional attributes:
+    start date, end date and key identifiers.
+
+    For PEM-encoded certificates, use :func:`asn1crypto.pem.unarmor`.
+
+    .. warning::
+
+        Does not verify certificate.
+
+    :param bytes der: DER-encoded certificate
+    :param extended_set: decodes more metadata about the certificate
+    :rtype: dict(Attribute,*)
+    """
+    x509 = Certificate.load(der)
+    subject = x509.subject
+    issuer = x509.issuer
+    serial = x509["tbs_certificate"]["serial_number"]
+
+    template: dict[Attribute, Any] = {
+        Attribute.CLASS: ObjectClass.CERTIFICATE,
+        Attribute.CERTIFICATE_TYPE: CertificateType.X_509,
+        Attribute.SUBJECT: subject.dump(),
+        Attribute.ISSUER: issuer.dump(),
+        Attribute.SERIAL_NUMBER: serial.dump(),
+        Attribute.VALUE: x509.dump(),
+    }
+
+    if extended_set:
+        start_date = x509["tbs_certificate"]["validity"]["not_before"].native.date()
+        end_date = x509["tbs_certificate"]["validity"]["not_after"].native.date()
+
+        template.update(
+            {
+                Attribute.START_DATE: start_date,
+                Attribute.END_DATE: end_date,
+            }
+        )
+
+        # FIXME: is this correct?
+        try:
+            template[Attribute.HASH_OF_SUBJECT_PUBLIC_KEY] = x509.key_identifier
+        except KeyError:
+            pass
+
+        try:
+            template[Attribute.HASH_OF_ISSUER_PUBLIC_KEY] = x509.authority_key_identifier
+        except KeyError:
+            pass
+
+    return template