pdftools_sdk.crypto.providers.built_in.provider

Classes

Provider()

The built-in cryptographic provider

class pdftools_sdk.crypto.providers.built_in.provider.Provider

Bases: Provider

The built-in cryptographic provider

The built-in cryptographic provider requires no cryptographic hardware or external service (except for the optional pdftools_sdk.crypto.providers.built_in.provider.Provider.timestamp_url ).

Signing certificates with private keys can be loaded using pdftools_sdk.crypto.providers.built_in.provider.Provider.create_signature_from_certificate() .

Certificates Directory: Additional certificates, e.g. issuer certificates, can be stored in the certificates directory. These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The certificates directory may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.

• Windows: - %LOCALAPPDATA%PDF Tools AGCertificates - %ProgramData%PDF Tools AGCertificates

• Linux: - ~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates - /usr/share/pdf-tools/Certificates

• macOS: - ~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates

__init__()

create_signature_from_certificate(stream: IOBase, password: str | None) → SignatureConfiguration

Create a configuration to sign with a PFX (PKCS#12) soft certificate

The file must contain the certificate itself, all certificates of the trust chain, and the private key.

Parameters:

• stream (io.IOBase) – The signing certificate in PKCS#12 format (.p12, .pfx).

• password (Optional[str]) – The password required to decrypt the private key of the archive.

Return type:

pdftools_sdk.crypto.providers.built_in.signature_configuration.SignatureConfiguration

Raises:

• pdftools_sdk.corrupt_error.CorruptError – The PFX (PKCS#12) archive is corrupt and cannot be read.

• pdftools_sdk.password_error.PasswordError – The password is invalid.

• ValueError – The certificate is not a valid signing certificate

create_timestamp() → TimestampConfiguration

Create a time-stamp configuration

Note that to create time-stamps, the pdftools_sdk.crypto.providers.built_in.provider.Provider.timestamp_url must be set.

Return type:

pdftools_sdk.crypto.providers.built_in.timestamp_configuration.TimestampConfiguration

create_prepared_signature(size: int, format: str, name: str) → SignatureConfiguration

Create a configuration to prepare a signature for an external signature handler

This method is part of a very specialized use case requiring an external signature handler. The process using an external signature handler is:

• pdftools_sdk.crypto.providers.built_in.provider.Provider.create_prepared_signature() : Create the signature configuration.

• pdftools_sdk.sign.signer.Signer.add_prepared_signature() : Create the document with the prepared signature.

• pdftools_sdk.sign.prepared_document.PreparedDocument.get_hash() : Calculate the hash from the document and create the signature using an external signature handler.

• pdftools_sdk.crypto.providers.built_in.provider.Provider.read_external_signature() : Create signature configuration for the external signature.

• pdftools_sdk.sign.signer.Signer.sign_prepared_signature() : Insert the external signature into the document with the prepared signature.

Parameters:

• size (int) – The expected size of the cryptographic signature that will be added later. This is the number of bytes that will be reserved in the prepared signature.

• format (str) – The format (SubFilter) of the cryptographic signature that is added later. For example, “adbe.pkcs7.detached” or “ETSI.CAdES.detached”.

• name (str) – The name of the signer of the cryptographic signature that will be added later.

Return type:

pdftools_sdk.sign.signature_configuration.SignatureConfiguration

read_external_signature(signature: List[int]) → SignatureConfiguration

Read signature created by an external signature handler

See pdftools_sdk.crypto.providers.built_in.provider.Provider.create_prepared_signature() for more information on the signing process using an external signature handler.

Parameters:

signature (List[int]) – This signature must not be larger than the number of bytes reserved in the prepared signature.

Return type:

pdftools_sdk.sign.signature_configuration.SignatureConfiguration

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]