Stacking
PL/EN
Start
ksef2
GitHub

ksef2.xades

Public XAdES helpers for certificate-based KSeF authentication.

v0.22.2 · b4b3eb9
On this page

Public XAdES helpers for certificate-based KSeF authentication.

Classes

LocalSigner

Import: from ksef2.xades import LocalSigner

class LocalSigner
python
LocalSigner(cert: Certificate, private_key: XAdESPrivateKey)
python

Signs XML locally with a certificate and private key.

Parameters

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

Methods

LocalSigner.sign

def sign(xml_bytes: bytes) -> bytes
python

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

Parameters

  • xml_bytes (bytes) — XML document to sign.

Returns

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

Functions

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
python

Build the XML payload that is signed for XAdES authentication.

Parameters

  • 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.

Returns

  • 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]
python

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}

Parameters

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

Returns

  • 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]
python

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

Parameters

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

Returns

  • 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]
python

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

Parameters

  • 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.

Returns

  • 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.

Raises

  • 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
python

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

Parameters

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

Returns

  • 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
)
python

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
python

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

Parameters

  • 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.

Returns

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

Raises

  • 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
python

Sign XML with an enveloped XAdES-B signature.

Parameters

  • 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.

Returns

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

Constants

XAdESPrivateKey

Import: from ksef2.xades import XAdESPrivateKey

XAdESPrivateKey = RSAPrivateKey | EllipticCurvePrivateKey
python