pygamlastan.crypto¶

Cryptographic operations: key management, signing, verification, encryption, decryption, canonicalization, and PKCS#11/HSM signing. See the Signing, verification, and encryption guide for worked examples. Errors raise pygamlastan.SamlCryptoError.

Keys¶

class pygamlastan.crypto.KeysManager¶

Holds private/public keys and trusted certificates.

static build_sp(private_key_pem: bytes, idp_certificate_pem: bytes) → KeysManager¶: SP setup: the SP signing key plus the trusted IdP certificate.

static build_idp(private_key_pem: bytes) → KeysManager¶: IdP setup: the IdP signing key.

add_key_pem(pem: bytes, usage: str = 'sign', password: str | None = None) → None¶: Load a PEM private key and add it. usage is one of "sign", "verify", "encrypt", "decrypt", "any".

add_trusted_cert(cert: bytes) → None¶: Add a trusted certificate (PEM or DER) used to verify signatures.

is_empty() → bool¶

Signing¶

class pygamlastan.crypto.SamlSigner(keys: KeysManager)¶

Sign with file-based keys from a KeysManager.

static from_pem(private_key_pem: bytes, password: str | None = None) → SamlSigner¶: Build a signer directly from a signing private key PEM.

static with_pkcs11(signer: Pkcs11Signer, keys: KeysManager | None = None) → SamlSigner¶: Build an HSM-backed signer. keys may be omitted: the certificate is taken from the signature template.

sign_enveloped(xml_with_template: str) → str¶: Apply an enveloped XML-DSig signature to a document that already carries a <ds:Signature> template.

sign_redirect_query(query_string: bytes, algorithm_uri: str, unsafe_allow_weak_sha1: bool = False) → bytes¶: Sign a HTTP-Redirect query string; returns the raw signature bytes. SHA-1 algorithms are rejected unless unsafe_allow_weak_sha1=True is explicit.

signature_method_uri() → str¶

is_hsm_backed() → bool¶

Verification¶

class pygamlastan.crypto.SamlVerifier(keys: KeysManager)¶

Verify signatures against keys/trusted certs in a KeysManager.

static from_cert(cert: bytes) → SamlVerifier¶: Build a verifier trusting a single certificate (PEM or DER). The certificate’s public key is registered as a verification key and as a trust anchor.

verify_enveloped(signed_xml: str) → VerifyResult¶

verify_redirect_query(query_string: bytes, signature: bytes, algorithm_uri: str, unsafe_allow_weak_sha1: bool = False) → bool¶: Verify a HTTP-Redirect query signature. SHA-1 algorithms are rejected unless unsafe_allow_weak_sha1=True is explicit.

set_skip_time_checks(skip: bool, unsafe_allow_skip_time_checks: bool = False) → None¶: skip=True raises unless unsafe_allow_skip_time_checks=True is explicit.

set_trusted_keys_only(trusted: bool, unsafe_allow_untrusted_keys: bool = False) → None¶: trusted=False raises unless unsafe_allow_untrusted_keys=True is explicit.

set_strict_verification(strict: bool, unsafe_allow_non_strict: bool = False) → None¶: strict=False raises unless unsafe_allow_non_strict=True is explicit.

set_hmac_min_out_len(bits: int) → None¶

class pygamlastan.crypto.VerifyResult¶

The outcome of SamlVerifier.verify_enveloped(). Truthy when valid.

is_valid() → bool¶

reason: str | None¶: The failure reason when invalid, else None.

signed_reference_ids() → list[str]¶: The reference ids whose digest was actually verified (with a leading # stripped). Pass these to pygamlastan.profiles.process_response() as verified_signed_ids.

signing_cert_chain() → list[bytes]¶: The DER X.509 chain (leaf first) of the signing key, when valid.

Encryption¶

class pygamlastan.crypto.SamlEncryptor(keys: KeysManager)¶

static for_certificate(cert_der: bytes) → SamlEncryptor¶: Encrypt to a recipient certificate (the per-request PEFIM flow).

encrypt(template_xml: str, plaintext: bytes) → str¶

class pygamlastan.crypto.SamlDecryptor(keys: KeysManager)¶

decrypt(encrypted_xml: str) → str¶

decrypt_to_bytes(encrypted_xml: str) → bytes¶

Canonicalization¶

pygamlastan.crypto.canonicalize(xml: str, mode: str = 'exclusive', inclusive_prefixes: list[str] | None = None) → bytes¶: Canonicalize xml. mode is "exclusive", "inclusive", "exclusive-with-comments" or "inclusive-with-comments".

pygamlastan.crypto.exc_c14n(xml: str, inclusive_prefixes: list[str] | None = None) → bytes¶: Exclusive C14N shorthand.

PKCS#11 / HSM¶

class pygamlastan.crypto.Pkcs11Provider(module_path: str)¶

Load a PKCS#11 module (a shared library, e.g. SoftHSM2 or kryoptic).

open_session(pin: str) → Pkcs11Session¶: Open and log in to a session with the given user PIN.

class pygamlastan.crypto.Pkcs11Session¶

signer(key_label: str, algorithm: str) → Pkcs11Signer¶: Create a signer bound to the private key identified by key_label. algorithm is a name such as "rsa-sha256" or "ecdsa-p256-sha256".

class pygamlastan.crypto.Pkcs11Signer(session: Pkcs11Session, key_label: str, algorithm: str)¶: A signer whose private key stays on the token. Pass it to SamlSigner.with_pkcs11().