pdftools_sdk.sign.signer

Classes

Signer()

Process signatures and signature fields

class pdftools_sdk.sign.signer.Signer

Bases: _NativeObject

Process signatures and signature fields

__init__()

sign(document: Document, configuration: SignatureConfiguration, stream: io.IOBase, output_options: OutputOptions | None = None) → Document

Add a document signature

Document signatures are sometimes also called approval signatures. This type of signature lets you verify the integrity of the signed part of the document and authenticate the signer’s identity.

The features and format of the signature are defined by the pdftools_sdk.crypto.providers.provider.Provider and the configuration.

Non-critical processing errors raise a pdftools_sdk.sign.signer.Signer.Warning. It is recommended to review the pdftools_sdk.sign.warning_category.WarningCategory and handle them if necessary for the application.

Parameters:

• document (Document) – The input document to sign

• configuration (SignatureConfiguration) – The signature configuration

• stream (io.IOBase) – The stream where the signed document is written

• outputOptions (Optional[OutputOptions]) – Document-level output options not directly related to the signature

Returns:

The signed document

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The input PDF contains unrendered XFA form fields. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• ValueError – If the configuration is invalid, e.g. because the creating provider has been closed.

• ValueError – If the configuration is invalid, e.g. because it has been revoked.

• pdftools_sdk.not_found_error.NotFoundError – If the pdftools_sdk.sign.signature_configuration.SignatureConfiguration.field_name does not exist in document.

• pdftools_sdk.not_found_error.NotFoundError – If an image, a PDF or a font file for the visual appearance could not be found.

• pdftools_sdk.retry_error.RetryError – If an unexpected error occurs that can be resolved by retrying the operation. For example, if a signature service returns an unexpectedly large signature.

• pdftools_sdk.retry_error.RetryError – If a resource required by the cryptographic provider is temporarily unavailable.

• pdftools_sdk.http_error.HttpError – If a network error occurs, e.g. downloading revocation information (OCSP, CRL) or a time-stamp.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – If the cryptographic provider does not support the requested signing algorithm.

• pdftools_sdk.permission_error.PermissionError – If the cryptographic provider does not allow the signing operation.

certify(document: Document, configuration: SignatureConfiguration, stream: io.IOBase, permissions: MdpPermissionOptions | None = None, output_options: OutputOptions | None = None) → Document

Add a document certification signature

This type of signature lets you detect rejected changes specified by the author. These signatures are also called Modification Detection and Prevention (MDP) signatures. The allowed permissions are defined by permissions.

The features and format of the signature are defined by the pdftools_sdk.crypto.providers.provider.Provider and the configuration.

Non-critical processing errors raise a pdftools_sdk.sign.signer.Signer.Warning. It is recommended to review the pdftools_sdk.sign.warning_category.WarningCategory and handle them if necessary for the application.

Parameters:

• document (Document) – The input document to certify

• configuration (SignatureConfiguration) – The signature configuration

• stream (io.IOBase) – The stream where the certified document is written

• permissions (Optional[MdpPermissionOptions]) – The permissions allowed. The default is pdftools_sdk.pdf.mdp_permissions.MdpPermissions.NOCHANGES.

• outputOptions (Optional[OutputOptions]) – Document-level output options not directly related to the document certification

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The input PDF contains unrendered XFA form fields. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• ValueError – If the configuration is invalid, e.g. because the creating provider has been closed.

• pdftools_sdk.not_found_error.NotFoundError – If the pdftools_sdk.sign.signature_configuration.SignatureConfiguration.field_name does not exist in document.

• pdftools_sdk.retry_error.RetryError – If an unexpected error occurs that can be resolved by retrying the operation. For example, if a signature service returns an unexpectedly large signature.

• pdftools_sdk.retry_error.RetryError – If a resource required by the cryptographic provider is temporarily unavailable.

• pdftools_sdk.http_error.HttpError – If a network error occurs, e.g. downloading revocation information (OCSP, CRL) or a time-stamp.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – If the cryptographic provider does not support the requested signing algorithm.

• pdftools_sdk.permission_error.PermissionError – If the cryptographic provider does not allow the signing operation.

add_timestamp(document: Document, configuration: TimestampConfiguration, stream: io.IOBase, output_options: OutputOptions | None = None) → Document

Add a document time-stamp

This type of signature provides evidence that the document existed at a specific time and protects the document’s integrity.

The features and format of the signature are defined by the pdftools_sdk.crypto.providers.provider.Provider and the configuration.

Non-critical processing errors raise a pdftools_sdk.sign.signer.Signer.Warning. It is recommended to review the pdftools_sdk.sign.warning_category.WarningCategory and handle them if necessary for the application.

Parameters:

• document (Document) – The input document to add a time-stamp to

• configuration (TimestampConfiguration) – The time-stamp configuration

• stream (io.IOBase) – The stream where the output document is written

• outputOptions (Optional[OutputOptions]) – Document-level output options not directly related to the document time-stamp

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The input PDF contains unrendered XFA form fields. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• ValueError – If the configuration is invalid, e.g. because the creating provider has been closed.

• pdftools_sdk.not_found_error.NotFoundError – If the pdftools_sdk.sign.signature_configuration.SignatureConfiguration.field_name does not exist in document.

• pdftools_sdk.retry_error.RetryError – If an unexpected error occurs that can be resolved by retrying the operation. For example, if a signature service returns an unexpectedly large signature.

• pdftools_sdk.retry_error.RetryError – If a resource required by the cryptographic provider is temporarily unavailable.

• pdftools_sdk.http_error.HttpError – If a network error occurs, e.g. downloading revocation information (OCSP, CRL) or a time-stamp.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – If the cryptographic provider does not support the requested signing algorithm.

• pdftools_sdk.permission_error.PermissionError – If the cryptographic provider does not allow the signing operation.

add_signature_field(document: Document, options: SignatureFieldOptions, stream: io.IOBase, output_options: OutputOptions | None = None) → Document

Add an unsigned signature field

Add an unsigned signature field that can later be signed (see pdftools_sdk.pdf.unsigned_signature_field.UnsignedSignatureField).

Non-critical processing errors raise a pdftools_sdk.sign.signer.Signer.Warning. It is recommended to review the pdftools_sdk.sign.warning_category.WarningCategory and handle them if necessary for the application.

Parameters:

• document (Document) – The input document to add the signature field to

• options (SignatureFieldOptions) – The options for the unsigned signature field

• stream (io.IOBase) – The stream where the output document is written

• outputOptions (Optional[OutputOptions]) – Document-level output options not directly related to the signature field

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The input PDF contains unrendered XFA form fields. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• pdftools_sdk.exists_error.ExistsError – The pdftools_sdk.sign.signature_field_options.SignatureFieldOptions.field_name exists already in the input document.

add_prepared_signature(document: Document, configuration: SignatureConfiguration, stream: io.IOBase, output_options: OutputOptions | None = None) → PreparedDocument

Add a prepared signature

Adding a prepared signature is only required in very particular or specialized use cases. This method is the same as pdftools_sdk.sign.signer.Signer.sign, but without actually creating the cryptographic signature. The cryptographic signature can be inserted later using pdftools_sdk.sign.signer.Signer.sign_prepared_signature.

While the configuration can be created by any pdftools_sdk.crypto.providers.provider.Provider, it is typically created by pdftools_sdk.crypto.providers.built_in.provider.Provider.create_prepared_signature.

Parameters:

• document (Document) – The input document to add the prepared signature

• configuration (SignatureConfiguration) – The signature configuration

• stream (io.IOBase) – The stream where the output document is written

• outputOptions (Optional[OutputOptions]) – Document-level output options not directly related to preparing the signature

Return type:

PreparedDocument

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The input PDF contains unrendered XFA form fields. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• ValueError – If the configuration is invalid, e.g. because the creating provider has been closed

• pdftools_sdk.not_found_error.NotFoundError – If the pdftools_sdk.sign.signature_configuration.SignatureConfiguration.field_name does not exist in document.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – If the cryptographic provider does not support the requested signing algorithm.

• pdftools_sdk.http_error.HttpError – If a network error occurs, e.g. downloading revocation information (OCSP, CRL).

sign_prepared_signature(document: Document, configuration: SignatureConfiguration, stream: io.IOBase) → Document

Sign a prepared signature

Sign a document that contains a prepared signature created using pdftools_sdk.sign.signer.Signer.add_prepared_signature. Note that the configuration must be compatible to the configuration used when preparing the signature.

Parameters:

• document (Document) – The input document to sign

• configuration (SignatureConfiguration) – The signature configuration

• stream (io.IOBase) – The stream where the signed document is written

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• ValueError – If the document does not contain a prepared signature created by pdftools_sdk.sign.signer.Signer.add_prepared_signature

• ValueError – If the configuration is invalid, e.g. because the creating provider has been closed.

• pdftools_sdk.retry_error.RetryError – If an unexpected error occurs that can be resolved by retrying the operation. For example, if a signature service returns an unexpectedly large signature.

• pdftools_sdk.retry_error.RetryError – If a resource required by the cryptographic provider is temporarily unavailable.

• pdftools_sdk.http_error.HttpError – If a network error occurs, e.g. downloading revocation information (OCSP, CRL) or a time-stamp.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – If the cryptographic provider does not support the requested signing algorithm.

• pdftools_sdk.permission_error.PermissionError – If the cryptographic provider does not allow the signing operation.

process(document: Document, stream: io.IOBase, output_options: OutputOptions | None = None, provider: Provider | None = None) → Document

Process a document

Apply document-level processing options without any signature operation. For example:

• To encrypt or decrypt PDF documents that may be signed (see the samples “Encrypt” and “Decrypt”).

• To remove signatures and unsigned signature fields (see pdftools_sdk.sign.output_options.OutputOptions.remove_signatures).

• To add validation information to existing signatures (see pdftools_sdk.sign.output_options.OutputOptions.add_validation_information).

Non-critical processing errors raise a pdftools_sdk.sign.signer.Signer.Warning. It is recommended to review the pdftools_sdk.sign.warning_category.WarningCategory and handle them if necessary for the application.

Parameters:

• document (Document) – The input document to process

• stream (io.IOBase) – The stream where the output document is written

• outputOptions (Optional[OutputOptions]) – The document-level processing options

• provider (Optional[Provider]) – The cryptographic provider to use to add validation information to existing signatures of input document (see pdftools_sdk.sign.output_options.OutputOptions.add_validation_information). Can be None if no validation information is added or to use the default provider.

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• OSError – Writing to the stream failed.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The input PDF contains unrendered XFA form fields. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• pdftools_sdk.http_error.HttpError – If a network error occurs, e.g. downloading revocation information (OCSP, CRL).

add_warning_handler(handler: WarningFunc) → None

Add handler for the WarningFunc event.

Parameters:

handler – Event handler. If a handler is added that is already registered, it is ignored.

remove_warning_handler(handler: WarningFunc) → None

Remove registered handler of the WarningFunc event.

Parameters:

handler – Event handler that shall be removed. If a handler is not registered, it is ignored.