ksef2.xades

Public XAdES helpers for certificate-based KSeF authentication.

Klasy

LocalSigner

Import: from ksef2.xades import LocalSigner

class LocalSigner

LocalSigner(cert: Certificate, private_key: XAdESPrivateKey)

Signs XML locally with a certificate and private key.

Parametry

• cert (Certificate) — Certificate embedded in the signature.
• private_key (XAdESPrivateKey) — RSA or EC private key used for signing.

Metody

LocalSigner.sign

def sign(xml_bytes: bytes) -> bytes

Sign XML bytes with the certificate and key held by this signer.

Parametry

• xml_bytes (bytes) — XML document to sign.

Zwraca

• bytes — UTF-8 XML bytes containing the enveloped XAdES signature.

Funkcje

build_auth_token_request_xml

Import: from ksef2.xades import build_auth_token_request_xml

def build_auth_token_request_xml(
    challenge: str,
    nip: str,
    subject_identifier_type: str = 'certificateSubject',
) -> bytes

Build the XML payload that is signed for XAdES authentication.

Parametry

• challenge (str) — Challenge value returned by KSeF.
• nip (str) — Taxpayer NIP used in the authentication context.
• subject_identifier_type (str) — Subject identifier type written to the XML.

Zwraca

• bytes — UTF-8 XML bytes matching the KSeF auth-token schema.

generate_personal_test_certificate

Import: from ksef2.xades import generate_personal_test_certificate

def generate_personal_test_certificate(
    pesel: str,
    nip: str | None = None,
) -> tuple[Certificate, RSAPrivateKey]

Generate a self-signed RSA-2048 certificate for a person (XAdES auth).

The DN uses the personal certificate format: 2.5.4.5=TINPL-{PESEL}, CN=KSeF SDK Test, C=PL

Optionally includes NIP for company representatives: 2.5.4.97=VATPL-{NIP}

Parametry

• pesel (str) — PESEL embedded in the certificate subject.
• nip (str | None) — NIP to add for a company representative; None to omit it.

Zwraca

• tuple[Certificate, RSAPrivateKey] — A tuple of the certificate and its private key.

generate_test_certificate

Import: from ksef2.xades import generate_test_certificate

def generate_test_certificate(nip: str) -> tuple[Certificate, RSAPrivateKey]

Generate a self-signed RSA-2048 certificate for XAdES auth on the TEST environment.

The DN uses the company-seal format matching the Java/C# reference implementations: 2.5.4.97=VATPL-{NIP}, CN=KSeF SDK Test, C=PL

Parametry

• nip (str) — NIP embedded in the certificate subject.

Zwraca

• tuple[Certificate, RSAPrivateKey] — A tuple of the certificate and its private key.

load_certificate_and_key_from_p12

Import: from ksef2.xades import load_certificate_and_key_from_p12

def load_certificate_and_key_from_p12(
    source: bytes | str | Path,
    *,
    password: bytes | None = None,
) -> tuple[Certificate, XAdESPrivateKey]

Load a certificate and RSA or EC private key from a PKCS#12 (.p12 / .pfx) file.

Parametry

• source (bytes | str | Path) — Raw PKCS#12 bytes, or a path (str / Path) to the .p12 / .pfx file.
• password (bytes | None) — Decryption password for the archive, or None if unencrypted.

Zwraca

• Certificate — A (cert, private_key) tuple ready to pass to
• XAdESPrivateKey — AuthClient.with_xades.

Note

If you have separate .pem and .key files downloaded directly from MCU, prefer load_certificate_from_pem + load_private_key_from_pem — no conversion needed.

Zgłasza

• ValueError — If the archive does not contain a certificate.
• TypeError — If the decoded key is not an RSA or EC private key.

load_certificate_from_pem

Import: from ksef2.xades import load_certificate_from_pem

def load_certificate_from_pem(source: bytes | str | Path) -> Certificate

Load an X.509 certificate from PEM data or a PEM file path.

Parametry

• source (bytes | str | Path) — PEM-encoded bytes, or a path (str / Path) to a .pem / .crt file.

Zwraca

• Certificate — The certificate, ready to pass to client.authentication.with_xades().

Example

from ksef2 import Client, Environment
from ksef2.xades import load_certificate_from_pem, load_private_key_from_pem

cert = load_certificate_from_pem("cert.pem")
key = load_private_key_from_pem("key.pem")

auth = Client(Environment.DEMO).authentication.with_xades(
    nip="1234567890", cert=cert, private_key=key
)

load_private_key_from_pem

Import: from ksef2.xades import load_private_key_from_pem

def load_private_key_from_pem(
    source: bytes | str | Path,
    *,
    password: bytes | None = None,
) -> XAdESPrivateKey

Load an RSA or EC private key from PEM data or a PEM file path.

Parametry

• source (bytes | str | Path) — PEM-encoded bytes, or a path (str / Path) to a .pem / .key file.
• password (bytes | None) — Decryption password if the key is encrypted, otherwise None.

Zwraca

• An (XAdESPrivateKey) — ~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey or
• XAdESPrivateKey — ~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey.

Zgłasza

• TypeError — If the decoded key is not an RSA or EC private key.

sign_xades

Import: from ksef2.xades import sign_xades

def sign_xades(
    xml_bytes: bytes,
    cert: Certificate,
    private_key: XAdESPrivateKey,
) -> bytes

Sign XML with an enveloped XAdES-B signature.

Parametry

• xml_bytes (bytes) — XML document to sign.
• cert (Certificate) — Certificate that should be embedded in the signature.
• private_key (XAdESPrivateKey) — RSA or EC private key used for signing.

Zwraca

• bytes — UTF-8 XML bytes containing the enveloped XAdES signature.

Stałe

XAdESPrivateKey

Import: from ksef2.xades import XAdESPrivateKey

XAdESPrivateKey = RSAPrivateKey | EllipticCurvePrivateKey