pdftools_sdk.crypto.providers.pkcs11.session

Classes

Session(handle)

A session to a cryptographic device (HSM, USB token, etc.) to perform cryptographic operations
class pdftools_sdk.crypto.providers.pkcs11.session.Session(handle)[source]

Bases: Provider

A session to a cryptographic device (HSM, USB token, etc.) to perform cryptographic operations

The session can be used to create signature configuration to sign documents.

To acquire a session, the following steps must be performed:

login(password: str | None) → None[source]

Log in user into the cryptographic device

Login is typically required to enable cryptographic operations. Furthermore, some of the device’s objects such as certificates or private keys might only be visible when logged in.

Note that many devices are locked after a number of failed login attempts. Therefore, it is crucial to not retry this method using the same password after a failed attempt.

Parameters:

password (Optional[str]) – The user’s password

Raises:
create_signature(certificate: Certificate) → SignatureConfiguration[source]

Create a signature configuration based on signing certificate

Parameters:

certificate (pdftools_sdk.crypto.providers.certificate.Certificate) – The signing certificate from pdftools_sdk.crypto.providers.pkcs11.session.Session.certificates

Return type:

pdftools_sdk.crypto.providers.pkcs11.signature_configuration.SignatureConfiguration

Raises:

  • ValueError – If the certificate is not a valid signing certificate.

  • ValueError – If the certificate has expired.

create_signature_from_name(name: str) → SignatureConfiguration[source]

Create a signature configuration based on certificate name

Parameters:

name (str) – The name of the signing certificate (pdftools_sdk.crypto.providers.certificate.Certificate.name )

Return type:

pdftools_sdk.crypto.providers.pkcs11.signature_configuration.SignatureConfiguration

Raises:
create_signature_from_key_id(id: List[int], certificate: IOBase) → SignatureConfiguration[source]

Create a signature configuration based on the private key’s ID and an external certificate

Create a signature configuration where only the private key is contained in the PKCS#11 device and the signing certificate is provided externally. This is intended for PKCS#11 devices that can only store private keys, e.g. the Google Cloud Key Management (KMS).

The private key object is identified using its ID, i.e. the CKA_ID object attribute in the PKCS#11 store.

The certificates of the trust chain should be added using pdftools_sdk.crypto.providers.pkcs11.signature_configuration.SignatureConfiguration.add_certificate() .

Parameters:

  • id (List[int]) – The ID of the private key object in the PKCS#11 store

  • certificate (io.IOBase) – The signing certificate in either PEM (.pem, ASCII text) or DER (.cer, binary) form

Return type:

pdftools_sdk.crypto.providers.pkcs11.signature_configuration.SignatureConfiguration

Raises:

  • pdftools_sdk.not_found_error.NotFoundError – If the private key cannot be found in the PKCS#11 store

  • ValueError – If the certificate is not a valid signing certificate

  • ValueError – If the key specification matches more than one key

create_signature_from_key_label(label: str, certificate: IOBase) → SignatureConfiguration[source]

Create a signature configuration based on the private key’s label (name) and an external certificate

Create a signature configuration where only the private key is contained in the PKCS#11 device and the signing certificate is provided externally. This is intended for PKCS#11 devices that can only store private keys, e.g. the Google Cloud Key Management (KMS).

The private key object is identified using its label, i.e. the CKA_LABEL object attribute in the PKCS#11 store.

The certificates of the trust chain should be added using pdftools_sdk.crypto.providers.pkcs11.signature_configuration.SignatureConfiguration.add_certificate() .

Parameters:

  • label (str) – The label of the private key object in the PKCS#11 store

  • certificate (io.IOBase) – The signing certificate in either PEM (.pem, ASCII text) or DER (.cer, binary) form

Return type:

pdftools_sdk.crypto.providers.pkcs11.signature_configuration.SignatureConfiguration

Raises:

  • pdftools_sdk.not_found_error.NotFoundError – If the private key cannot be found in the PKCS#11 store

  • ValueError – If the certificate is not a valid signing certificate

  • ValueError – If the key specification matches more than one key

create_timestamp() → TimestampConfiguration[source]

Create a time-stamp configuration

Note that to create time-stamps, the pdftools_sdk.crypto.providers.pkcs11.session.Session.timestamp_url must be set.

Return type:

pdftools_sdk.crypto.providers.pkcs11.timestamp_configuration.TimestampConfiguration

property timestamp_url: str | None

The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired

The TSA must support the time-stamp protocol as defined in RFC 3161.

The property’s value must be a URL with the following elements:

http[s]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›]

Where:

  • http/https: Protocol for connection to TSA.

  • ‹user›:‹password› (optional): Credentials for connection to TSA (basic authorization).

  • ‹host›: Hostname of TSA.

  • ‹port›: Port for connection to TSA.

  • ‹resource›: The resource.

Applying a time-stamp requires an online connection to a time server; the firewall must be configured accordingly. If a web proxy is used (see pdftools_sdk.sdk.Sdk.proxy ), make sure the following MIME types are supported:

  • application/timestamp-query

  • application/timestamp-reply

Returns:

Optional[str]

property certificates: CertificateList

The cerfificates of the device

The certificates available in this device. Note that some certificates or their private keys (see pdftools_sdk.crypto.providers.certificate.Certificate.has_private_key ) might only be visible after pdftools_sdk.crypto.providers.pkcs11.session.Session.login() .

Returns:

pdftools_sdk.crypto.providers.certificate_list.CertificateList