PDFSign Class

Properties   Methods   Events   Config Settings   Errors  

The PDFSign class signs PDF documents.

Syntax

class securepdf.PDFSign

Remarks

The PDFSign class can sign PDF documents in accordance with a selection of PDF and PAdES signature standards, including basic Adobe signatures (ISO 32000) and PAdES signatures (ETSI EN 319 142-1).

Preparing the Signature

To configure PDFSign to produce the desired signature, first provide the input document as a file (input_file), byte array (input_data), or stream (set_input_stream) and assign your signing certificate to the signing_cert property. Then indicate where to save the output document by setting output_file or calling set_output_stream.

Optionally specify the Signature* properties and the timestamp_server property, and adjust any chain validation parameters as necessary (please see the Chain Validation Setup section for more details). Finally, call the sign method.

PDFSign also provides means to customize the appearance of the signature widget to be shown on the document page. You can create your very own signatures (e.g., in the form of your company's logo) by adjusting the widget properties available in the set_widget_property method. Alternatively, you can choose not to associate any widget with your signature by setting the Invisible widget property to True.

The Signing Process

Depending on the configuration, the signing process may be as straightforward as calculating the document hash and signing it with the private key, or it may involve the advanced chain validation routine. During the latter, the class may contact external revocation (i.e., CRL and OCSP endpoints) and trust sources to establish the validity of the signing certificate.

If an external TSA server was provided via the timestamp_server property, the class will also contact it to timestamp the new signature.

During signing, PDFSign may fire events to notify your code about certain conditions. For example, if the input document is encrypted but no decryption parameters were found in the password or decryption_cert properties, the class will fire either the on_password or on_recipient_info event to tell your code that it needs decryption information to be able to continue with the signing. Additionally, the on_ssl_server_authentication event will fire if one of the HTTP endpoints involved during the operation (which may be a TSA, CRL, OCSP, or Trusted List service) operates over TLS and needs its certificate to be validated.

Basic Adobe Signatures

A basic (also known as legacy) Adobe signature is an original Adobe Acrobat document signature. This is an outdated form of PDF signature - while PAdES is loosely built on it, this signature type does not support extended features and is not compliant with PAdES. Unless the recipient of your signed documents expects you to specifically use this kind of signature, it is unlikely that you will ever need it.

PAdES Signatures and Profiles

In PAdES, a given signature's profile describes the level of "completeness" of the validation material (i.e., certificates, CRLs, and OCSP responses) included in the signature. For example, signatures compliant with the PAdES B-B or PAdES B-T profiles do not require any validation material at all, whereas signatures compliant with the PAdES B-LTA profile must contain complete validation material.

PAdES B-B

The PAdES B-B profile is the baseline profile that uses the PAdES-BES signature level by default, meaning the signature only contains the signing time and signer information.

Use the following code to create a B-B signature: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureProfile = PDFSignSignatureProfiles.pfBaselineB; pdfsign.ValidationPolicy = PDFSignValidationPolicies.vpNone; pdfsign.Sign(); PAdES-EPES

To instead create a PAdES-EPES signature that includes the signature-policy-identifier attribute, set the PolicyHash, PolicyHashAlgorithm, and PolicyId configuration settings before calling the sign method.

This profile, in both the BES and EPES settings, creates a basic signature that remains valid as long as the signing certificate has not expired or been revoked. Signatures at this level need not contain any validation material.

PAdES B-T

The PAdES B-T profile extends the basic BES or EPES signature by adding a signature timestamp. This timestamp certifies that the signature was created at a specific moment in time. Similar to the B-B profile, signatures at this level need not contain any validation material.

Use the following code to create a B-T signature: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureProfile = PDFSignSignatureProfiles.pfBaselineT; pdfsign.TimestampServer = "http://time.certum.pl"; pdfsign.ValidationPolicy = PDFSignValidationPolicies.vpNone; pdfsign.Sign(); PAdES B-LTA

The PAdES B-LTA profile is used to achieve signatures that are equipped with long-term archival (LTA) or long-term validation (LTV) capabilities. It incorporates into the signature all the material required to validate the signature, including signing certificates, timestamping certificates, and revocation information. It also adds a document timestamp, which certifies the integrity of both the document and the complete validation material at a specific moment in time. This guarantees that no relevant certificates were expired or revoked at the signature creation time, and enables the signature to be verified offline.

Creating a B-LTA signature with PDFSign is a two-step process. First sign the document and add a signature timestamp, setting signature_profile appropriately. Then update the signature to take care of the rest (collect and embed the validation material, and add a document timestamp): pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureProfile = PDFSignSignatureProfiles.pfBaselineT; pdfsign.TimestampServer = "http://time.certum.pl"; pdfsign.ValidationPolicy = PDFSignValidationPolicies.vpNone; pdfsign.Sign(); // Update the signature to LTV - this will retrieve the necessary revocation // elements, embed them into the document, and add a document timestamp pdfsign.Reset(); pdfsign.InputFile = "signed.pdf"; pdfsign.OutputFile = "updated.pdf"; pdfsign.TimestampServer = "http://time.certum.pl"; pdfsign.Update(); Note that validation material "completeness" can be subjective and depends on several factors, including:

• The working environment. For example, your organization may explicitly trust its own self-signed TSA certificate. Signatures timestamped with this certificate will be considered B-LTA by your organization, but for any external bodies, those signatures would be rendered as B-LT or even B-B, as they do not know or trust the custom TSA certificate.
• The time that has passed since the last document timestamp. If an archived (B-LTA) document is not re-timestamped before its last timestamp expires, it will drop back to a lower signature level.

Chain Validation Setup

Chain validation is a sophisticated, multi-faceted procedure that involves a lot of variables. Depending on the configuration of your operating environment, the specifics of the PKI framework being used, and the validation policy you need to follow, you may want to adjust your chain validation parameters to best fit your requirements. A summary of these parameters is given below.

Note that these parameters apply to the sign and update methods in PDFSign as well as the verify method in PDFVerify, as all three methods execute the chain validation procedure (if it is enabled).

Validation Policy

The validation_policy property dictates how thoroughly the chain will be validated. It includes options to control which checks the class will perform, allowing you to tailor the validation process to meet your specific security needs. For example, if it is not essential to check each certificate's revocation status, set this property to vpFullNoRevocation.

Revocation

The revocation aspect of chain validation is controlled by the revocation_check property, which allows you to choose between and prioritize revocation origins. Note that OCSP sources are often preferred to CRL endpoints because of their real-time capability and the smaller size of the responses they produce.

Trust

The trust aspect of chain validation is controlled by the trust_sources property, which allows you to specify the locations in which the class will search for trust anchors. Local system stores, your own trusted root certificates (via the trusted_certs property), and Trusted Lists (via the trusted_lists property) are all supported.

Offline Mode

The offline_mode property provides the ability to sign or verify the document without contacting online sources. If this property is enabled, the class will only use known_certs, trusted_certs, data structures within the document itself, and revocation and Trusted List data that it previously saved to its internal cache when looking for missing validation material.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

attachment_count Property

The number of records in the Attachment arrays.

Syntax

def get_attachment_count() -> int: ...
def set_attachment_count(value: int) -> None: ...

attachment_count = property(get_attachment_count, set_attachment_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• attachment_content_type
• attachment_creation_date
• attachment_data
• attachment_description
• attachment_file_name
• attachment_modification_date
• attachment_name
• attachment_size

The array indices start at 0 and end at attachment_count - 1.

attachment_content_type Property

The content type of the attachment.

Syntax

def get_attachment_content_type(attachment_index: int) -> str: ...
def set_attachment_content_type(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

The content type of the attachment.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_creation_date Property

The creation date of the attachment.

Syntax

def get_attachment_creation_date(attachment_index: int) -> str: ...
def set_attachment_creation_date(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

The creation date of the attachment.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_data Property

The raw data of the attachment.

Syntax

def get_attachment_data(attachment_index: int) -> bytes: ...
def set_attachment_data(attachment_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

The raw data of the attachment.

If attachment_output_stream is not set to a valid stream, the class will write to this property when an empty string is passed to the save_attachment method.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_description Property

A textual description of the attachment.

Syntax

def get_attachment_description(attachment_index: int) -> str: ...
def set_attachment_description(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

A textual description of the attachment.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_file_name Property

The path and filename of the attachment.

Syntax

def get_attachment_file_name(attachment_index: int) -> str: ...
def set_attachment_file_name(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

The path and filename of the attachment.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_modification_date Property

The date and time of the file's last modification.

Syntax

def get_attachment_modification_date(attachment_index: int) -> str: ...
def set_attachment_modification_date(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

The date and time of the file's last modification.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_name Property

The name of the attachment.

Syntax

def get_attachment_name(attachment_index: int) -> str: ...
def set_attachment_name(attachment_index: int, value: str) -> None: ...

Default Value

""

Remarks

The name of the attachment.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

attachment_size Property

The attachment's size in bytes.

Syntax

def get_attachment_size(attachment_index: int) -> int: ...

Default Value

0

Remarks

The attachment's size in bytes.

The attachment_index parameter specifies the index of the item in the array. The size of the array is controlled by the attachment_count property.

This property is read-only.

blocked_cert_count Property

The number of records in the BlockedCert arrays.

Syntax

def get_blocked_cert_count() -> int: ...
def set_blocked_cert_count(value: int) -> None: ...

blocked_cert_count = property(get_blocked_cert_count, set_blocked_cert_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• blocked_cert_effective_date
• blocked_cert_encoded
• blocked_cert_expiration_date
• blocked_cert_extended_key_usage
• blocked_cert_fingerprint
• blocked_cert_fingerprint_sha1
• blocked_cert_fingerprint_sha256
• blocked_cert_issuer
• blocked_cert_private_key
• blocked_cert_private_key_available
• blocked_cert_private_key_container
• blocked_cert_public_key
• blocked_cert_public_key_algorithm
• blocked_cert_public_key_length
• blocked_cert_serial_number
• blocked_cert_signature_algorithm
• blocked_cert_store
• blocked_cert_store_password
• blocked_cert_store_type
• blocked_cert_subject
• blocked_cert_subject_alt_names
• blocked_cert_thumbprint_md5
• blocked_cert_thumbprint_sha1
• blocked_cert_thumbprint_sha256
• blocked_cert_usage
• blocked_cert_usage_flags
• blocked_cert_version

The array indices start at 0 and end at blocked_cert_count - 1.

blocked_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_blocked_cert_effective_date(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_blocked_cert_expiration_date(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_blocked_cert_extended_key_usage(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_blocked_cert_fingerprint(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_blocked_cert_fingerprint_sha1(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_blocked_cert_fingerprint_sha256(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_issuer Property

The issuer of the certificate.

Syntax

def get_blocked_cert_issuer(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_blocked_cert_private_key(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The blocked_cert_private_key may be available but not exportable. In this case, blocked_cert_private_key returns an empty string.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_blocked_cert_private_key_available(blocked_cert_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether a blocked_cert_private_key is available for the selected certificate. If blocked_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_blocked_cert_private_key_container(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The name of the blocked_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_public_key Property

The public key of the certificate.

Syntax

def get_blocked_cert_public_key(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_blocked_cert_public_key_algorithm(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_blocked_cert_public_key_length(blocked_cert_index: int) -> int: ...

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_blocked_cert_serial_number(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_blocked_cert_signature_algorithm(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_blocked_cert_store(blocked_cert_index: int) -> bytes: ...
def set_blocked_cert_store(blocked_cert_index: int, value: bytes) -> None: ...

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The blocked_cert_store_type property denotes the type of the certificate store specified by blocked_cert_store. If the store is password-protected, specify the password in blocked_cert_store_password.

blocked_cert_store is used in conjunction with the blocked_cert_subject property to specify client certificates. If blocked_cert_store has a value, and blocked_cert_subject or blocked_cert_encoded is set, a search for a certificate is initiated. Please see the blocked_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

blocked_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_blocked_cert_store_password(blocked_cert_index: int) -> str: ...
def set_blocked_cert_store_password(blocked_cert_index: int, value: str) -> None: ...

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

blocked_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_blocked_cert_store_type(blocked_cert_index: int) -> int: ...
def set_blocked_cert_store_type(blocked_cert_index: int, value: int) -> None: ...

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

blocked_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_blocked_cert_subject_alt_names(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_blocked_cert_thumbprint_md5(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_blocked_cert_thumbprint_sha1(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_blocked_cert_thumbprint_sha256(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_usage Property

The text description of UsageFlags .

Syntax

def get_blocked_cert_usage(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of blocked_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_blocked_cert_usage_flags(blocked_cert_index: int) -> int: ...

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of blocked_cert_usage_flags is a combination of the following flags:

Please see the blocked_cert_usage property for a text representation of blocked_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_version Property

The certificate's version number.

Syntax

def get_blocked_cert_version(blocked_cert_index: int) -> str: ...

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

This property is read-only.

blocked_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_blocked_cert_subject(blocked_cert_index: int) -> str: ...
def set_blocked_cert_subject(blocked_cert_index: int, value: str) -> None: ...

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

blocked_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_blocked_cert_encoded(blocked_cert_index: int) -> bytes: ...
def set_blocked_cert_encoded(blocked_cert_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The blocked_cert_store and blocked_cert_subject properties also may be used to specify a certificate.

When blocked_cert_encoded is set, a search is initiated in the current blocked_cert_store for the private key of the certificate. If the key is found, blocked_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, blocked_cert_subject is set to an empty string.

The blocked_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the blocked_cert_count property.

decryption_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_decryption_cert_effective_date() -> str: ...

decryption_cert_effective_date = property(get_decryption_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

decryption_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_decryption_cert_expiration_date() -> str: ...

decryption_cert_expiration_date = property(get_decryption_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

decryption_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_decryption_cert_extended_key_usage() -> str: ...

decryption_cert_extended_key_usage = property(get_decryption_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

decryption_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_decryption_cert_fingerprint() -> str: ...

decryption_cert_fingerprint = property(get_decryption_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

decryption_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_decryption_cert_fingerprint_sha1() -> str: ...

decryption_cert_fingerprint_sha1 = property(get_decryption_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

decryption_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_decryption_cert_fingerprint_sha256() -> str: ...

decryption_cert_fingerprint_sha256 = property(get_decryption_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

decryption_cert_issuer Property

The issuer of the certificate.

Syntax

def get_decryption_cert_issuer() -> str: ...

decryption_cert_issuer = property(get_decryption_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

decryption_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_decryption_cert_private_key() -> str: ...

decryption_cert_private_key = property(get_decryption_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The decryption_cert_private_key may be available but not exportable. In this case, decryption_cert_private_key returns an empty string.

This property is read-only.

decryption_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_decryption_cert_private_key_available() -> bool: ...

decryption_cert_private_key_available = property(get_decryption_cert_private_key_available, None)

Default Value

FALSE

Remarks

Whether a decryption_cert_private_key is available for the selected certificate. If decryption_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

decryption_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_decryption_cert_private_key_container() -> str: ...

decryption_cert_private_key_container = property(get_decryption_cert_private_key_container, None)

Default Value

""

Remarks

The name of the decryption_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

decryption_cert_public_key Property

The public key of the certificate.

Syntax

def get_decryption_cert_public_key() -> str: ...

decryption_cert_public_key = property(get_decryption_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

decryption_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_decryption_cert_public_key_algorithm() -> str: ...

decryption_cert_public_key_algorithm = property(get_decryption_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

decryption_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_decryption_cert_public_key_length() -> int: ...

decryption_cert_public_key_length = property(get_decryption_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

decryption_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_decryption_cert_serial_number() -> str: ...

decryption_cert_serial_number = property(get_decryption_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

decryption_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_decryption_cert_signature_algorithm() -> str: ...

decryption_cert_signature_algorithm = property(get_decryption_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

decryption_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_decryption_cert_store() -> bytes: ...
def set_decryption_cert_store(value: bytes) -> None: ...

decryption_cert_store = property(get_decryption_cert_store, set_decryption_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The decryption_cert_store_type property denotes the type of the certificate store specified by decryption_cert_store. If the store is password-protected, specify the password in decryption_cert_store_password.

decryption_cert_store is used in conjunction with the decryption_cert_subject property to specify client certificates. If decryption_cert_store has a value, and decryption_cert_subject or decryption_cert_encoded is set, a search for a certificate is initiated. Please see the decryption_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

decryption_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_decryption_cert_store_password() -> str: ...
def set_decryption_cert_store_password(value: str) -> None: ...

decryption_cert_store_password = property(get_decryption_cert_store_password, set_decryption_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

decryption_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_decryption_cert_store_type() -> int: ...
def set_decryption_cert_store_type(value: int) -> None: ...

decryption_cert_store_type = property(get_decryption_cert_store_type, set_decryption_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

decryption_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_decryption_cert_subject_alt_names() -> str: ...

decryption_cert_subject_alt_names = property(get_decryption_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

decryption_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_decryption_cert_thumbprint_md5() -> str: ...

decryption_cert_thumbprint_md5 = property(get_decryption_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

decryption_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_decryption_cert_thumbprint_sha1() -> str: ...

decryption_cert_thumbprint_sha1 = property(get_decryption_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

decryption_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_decryption_cert_thumbprint_sha256() -> str: ...

decryption_cert_thumbprint_sha256 = property(get_decryption_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

decryption_cert_usage Property

The text description of UsageFlags .

Syntax

def get_decryption_cert_usage() -> str: ...

decryption_cert_usage = property(get_decryption_cert_usage, None)

Default Value

""

Remarks

The text description of decryption_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

decryption_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_decryption_cert_usage_flags() -> int: ...

decryption_cert_usage_flags = property(get_decryption_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of decryption_cert_usage_flags is a combination of the following flags:

Please see the decryption_cert_usage property for a text representation of decryption_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

decryption_cert_version Property

The certificate's version number.

Syntax

def get_decryption_cert_version() -> str: ...

decryption_cert_version = property(get_decryption_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

decryption_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_decryption_cert_subject() -> str: ...
def set_decryption_cert_subject(value: str) -> None: ...

decryption_cert_subject = property(get_decryption_cert_subject, set_decryption_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

decryption_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_decryption_cert_encoded() -> bytes: ...
def set_decryption_cert_encoded(value: bytes) -> None: ...

decryption_cert_encoded = property(get_decryption_cert_encoded, set_decryption_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The decryption_cert_store and decryption_cert_subject properties also may be used to specify a certificate.

When decryption_cert_encoded is set, a search is initiated in the current decryption_cert_store for the private key of the certificate. If the key is found, decryption_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, decryption_cert_subject is set to an empty string.

document_cert_count Property

The number of records in the DocumentCert arrays.

Syntax

def get_document_cert_count() -> int: ...

document_cert_count = property(get_document_cert_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• document_cert_effective_date
• document_cert_encoded
• document_cert_expiration_date
• document_cert_extended_key_usage
• document_cert_fingerprint
• document_cert_fingerprint_sha1
• document_cert_fingerprint_sha256
• document_cert_issuer
• document_cert_private_key
• document_cert_private_key_available
• document_cert_private_key_container
• document_cert_public_key
• document_cert_public_key_algorithm
• document_cert_public_key_length
• document_cert_serial_number
• document_cert_signature_algorithm
• document_cert_store
• document_cert_store_password
• document_cert_store_type
• document_cert_subject
• document_cert_subject_alt_names
• document_cert_thumbprint_md5
• document_cert_thumbprint_sha1
• document_cert_thumbprint_sha256
• document_cert_usage
• document_cert_usage_flags
• document_cert_version

The array indices start at 0 and end at document_cert_count - 1.

This property is read-only.

document_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_document_cert_effective_date(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_document_cert_expiration_date(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_document_cert_extended_key_usage(document_cert_index: int) -> str: ...

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_document_cert_fingerprint(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_document_cert_fingerprint_sha1(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_document_cert_fingerprint_sha256(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_issuer Property

The issuer of the certificate.

Syntax

def get_document_cert_issuer(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_document_cert_private_key(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The document_cert_private_key may be available but not exportable. In this case, document_cert_private_key returns an empty string.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_document_cert_private_key_available(document_cert_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether a document_cert_private_key is available for the selected certificate. If document_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_document_cert_private_key_container(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The name of the document_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_public_key Property

The public key of the certificate.

Syntax

def get_document_cert_public_key(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_document_cert_public_key_algorithm(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_document_cert_public_key_length(document_cert_index: int) -> int: ...

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_document_cert_serial_number(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_document_cert_signature_algorithm(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_document_cert_store(document_cert_index: int) -> bytes: ...

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The document_cert_store_type property denotes the type of the certificate store specified by document_cert_store. If the store is password-protected, specify the password in document_cert_store_password.

document_cert_store is used in conjunction with the document_cert_subject property to specify client certificates. If document_cert_store has a value, and document_cert_subject or document_cert_encoded is set, a search for a certificate is initiated. Please see the document_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_document_cert_store_password(document_cert_index: int) -> str: ...

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_document_cert_store_type(document_cert_index: int) -> int: ...

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_document_cert_subject_alt_names(document_cert_index: int) -> str: ...

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_document_cert_thumbprint_md5(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_document_cert_thumbprint_sha1(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_document_cert_thumbprint_sha256(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_usage Property

The text description of UsageFlags .

Syntax

def get_document_cert_usage(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of document_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_document_cert_usage_flags(document_cert_index: int) -> int: ...

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of document_cert_usage_flags is a combination of the following flags:

Please see the document_cert_usage property for a text representation of document_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_version Property

The certificate's version number.

Syntax

def get_document_cert_version(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_document_cert_subject(document_cert_index: int) -> str: ...

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

document_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_document_cert_encoded(document_cert_index: int) -> bytes: ...

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The document_cert_store and document_cert_subject properties also may be used to specify a certificate.

When document_cert_encoded is set, a search is initiated in the current document_cert_store for the private key of the certificate. If the key is found, document_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, document_cert_subject is set to an empty string.

The document_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the document_cert_count property.

This property is read-only.

firewall_auto_detect Property

Whether to automatically detect and use firewall system settings, if available.

Syntax

def get_firewall_auto_detect() -> bool: ...
def set_firewall_auto_detect(value: bool) -> None: ...

firewall_auto_detect = property(get_firewall_auto_detect, set_firewall_auto_detect)

Default Value

FALSE

Remarks

Whether to automatically detect and use firewall system settings, if available.

firewall_type Property

The type of firewall to connect through.

Syntax

def get_firewall_type() -> int: ...
def set_firewall_type(value: int) -> None: ...

firewall_type = property(get_firewall_type, set_firewall_type)

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

firewall_host Property

The name or IP address of the firewall (optional).

Syntax

def get_firewall_host() -> str: ...
def set_firewall_host(value: str) -> None: ...

firewall_host = property(get_firewall_host, set_firewall_host)

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

firewall_password Property

A password if authentication is to be used when connecting through the firewall.

Syntax

def get_firewall_password() -> str: ...
def set_firewall_password(value: str) -> None: ...

firewall_password = property(get_firewall_password, set_firewall_password)

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

firewall_port Property

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

def get_firewall_port() -> int: ...
def set_firewall_port(value: int) -> None: ...

firewall_port = property(get_firewall_port, set_firewall_port)

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

Note: This property is set automatically when firewall_type is set to a valid value. See the description of the firewall_type property for details.

firewall_user Property

A username if authentication is to be used when connecting through a firewall.

Syntax

def get_firewall_user() -> str: ...
def set_firewall_user(value: str) -> None: ...

firewall_user = property(get_firewall_user, set_firewall_user)

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If firewall_host is specified, this property and the firewall_password property are used to connect and authenticate to the given Firewall. If the authentication fails, the class fails with an error.

input_data Property

A byte array containing the PDF document to process.

Syntax

def get_input_data() -> bytes: ...
def set_input_data(value: bytes) -> None: ...

input_data = property(get_input_data, set_input_data)

Remarks

This property is used to assign a byte array containing the PDF document to be processed.

input_file Property

The PDF file to process.

Syntax

def get_input_file() -> str: ...
def set_input_file(value: str) -> None: ...

input_file = property(get_input_file, set_input_file)

Default Value

""

Remarks

This property is used to provide a path to the PDF document to be processed.

known_cert_count Property

The number of records in the KnownCert arrays.

Syntax

def get_known_cert_count() -> int: ...
def set_known_cert_count(value: int) -> None: ...

known_cert_count = property(get_known_cert_count, set_known_cert_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• known_cert_effective_date
• known_cert_encoded
• known_cert_expiration_date
• known_cert_extended_key_usage
• known_cert_fingerprint
• known_cert_fingerprint_sha1
• known_cert_fingerprint_sha256
• known_cert_issuer
• known_cert_private_key
• known_cert_private_key_available
• known_cert_private_key_container
• known_cert_public_key
• known_cert_public_key_algorithm
• known_cert_public_key_length
• known_cert_serial_number
• known_cert_signature_algorithm
• known_cert_store
• known_cert_store_password
• known_cert_store_type
• known_cert_subject
• known_cert_subject_alt_names
• known_cert_thumbprint_md5
• known_cert_thumbprint_sha1
• known_cert_thumbprint_sha256
• known_cert_usage
• known_cert_usage_flags
• known_cert_version

The array indices start at 0 and end at known_cert_count - 1.

known_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_known_cert_effective_date(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_known_cert_expiration_date(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_known_cert_extended_key_usage(known_cert_index: int) -> str: ...

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_known_cert_fingerprint(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_known_cert_fingerprint_sha1(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_known_cert_fingerprint_sha256(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_issuer Property

The issuer of the certificate.

Syntax

def get_known_cert_issuer(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_known_cert_private_key(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The known_cert_private_key may be available but not exportable. In this case, known_cert_private_key returns an empty string.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_known_cert_private_key_available(known_cert_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether a known_cert_private_key is available for the selected certificate. If known_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_known_cert_private_key_container(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The name of the known_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_public_key Property

The public key of the certificate.

Syntax

def get_known_cert_public_key(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_known_cert_public_key_algorithm(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_known_cert_public_key_length(known_cert_index: int) -> int: ...

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_known_cert_serial_number(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_known_cert_signature_algorithm(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_known_cert_store(known_cert_index: int) -> bytes: ...
def set_known_cert_store(known_cert_index: int, value: bytes) -> None: ...

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The known_cert_store_type property denotes the type of the certificate store specified by known_cert_store. If the store is password-protected, specify the password in known_cert_store_password.

known_cert_store is used in conjunction with the known_cert_subject property to specify client certificates. If known_cert_store has a value, and known_cert_subject or known_cert_encoded is set, a search for a certificate is initiated. Please see the known_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

known_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_known_cert_store_password(known_cert_index: int) -> str: ...
def set_known_cert_store_password(known_cert_index: int, value: str) -> None: ...

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

known_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_known_cert_store_type(known_cert_index: int) -> int: ...
def set_known_cert_store_type(known_cert_index: int, value: int) -> None: ...

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

known_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_known_cert_subject_alt_names(known_cert_index: int) -> str: ...

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_known_cert_thumbprint_md5(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_known_cert_thumbprint_sha1(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_known_cert_thumbprint_sha256(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_usage Property

The text description of UsageFlags .

Syntax

def get_known_cert_usage(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of known_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_known_cert_usage_flags(known_cert_index: int) -> int: ...

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of known_cert_usage_flags is a combination of the following flags:

Please see the known_cert_usage property for a text representation of known_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_version Property

The certificate's version number.

Syntax

def get_known_cert_version(known_cert_index: int) -> str: ...

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

This property is read-only.

known_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_known_cert_subject(known_cert_index: int) -> str: ...
def set_known_cert_subject(known_cert_index: int, value: str) -> None: ...

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

known_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_known_cert_encoded(known_cert_index: int) -> bytes: ...
def set_known_cert_encoded(known_cert_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The known_cert_store and known_cert_subject properties also may be used to specify a certificate.

When known_cert_encoded is set, a search is initiated in the current known_cert_store for the private key of the certificate. If the key is found, known_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, known_cert_subject is set to an empty string.

The known_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the known_cert_count property.

offline_mode Property

Whether the class is operating in offline mode.

Syntax

def get_offline_mode() -> bool: ...
def set_offline_mode(value: bool) -> None: ...

offline_mode = property(get_offline_mode, set_offline_mode)

Default Value

FALSE

Remarks

This property indicates whether the class should operate in offline mode.

In offline mode, the class restricts itself from accessing online Trusted Lists and revocation information sources such as CRLs or OCSP responders. It may be useful to set this property to True if there is a need to verify the completeness of the validation information included within the signature or provided via known_certs.

output_data Property

A byte array containing the PDF document after processing.

Syntax

def get_output_data() -> bytes: ...

output_data = property(get_output_data, None)

Remarks

This property is used to read the byte array containing the produced output after the operation has completed. It will only be set if an output file and output stream have not been assigned via output_file and set_output_stream respectively.

This property is read-only.

output_file Property

The path to a local file where the output will be written.

Syntax

def get_output_file() -> str: ...
def set_output_file(value: str) -> None: ...

output_file = property(get_output_file, set_output_file)

Default Value

""

Remarks

This property is used to provide a path where the resulting PDF document will be saved after the operation has completed.

overwrite Property

Whether or not the class should overwrite files.

Syntax

def get_overwrite() -> bool: ...
def set_overwrite(value: bool) -> None: ...

overwrite = property(get_overwrite, set_overwrite)

Default Value

FALSE

Remarks

This property indicates whether or not the class will overwrite output_file, output_data, or the stream set in set_output_stream. If set to False, an error will be thrown whenever output_file, output_data, or the stream set in set_output_stream exists before an operation.

password Property

The password to decrypt the document with.

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

Default Value

""

Remarks

This property is used to provide the user password for decryption. Though it may be different from OwnerPassword, most implementations use the same value for both.

proxy_auth_scheme Property

The type of authorization to perform when connecting to the proxy.

Syntax

def get_proxy_auth_scheme() -> int: ...
def set_proxy_auth_scheme(value: int) -> None: ...

proxy_auth_scheme = property(get_proxy_auth_scheme, set_proxy_auth_scheme)

Default Value

0

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the proxy_user and proxy_password properties are set.

proxy_auth_scheme should be set to authNone (3) when no authentication is expected.

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the class will attempt basic authentication.

If proxy_auth_scheme is set to authDigest (1), digest authentication will be attempted instead.

If proxy_auth_scheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If proxy_auth_scheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

proxy_auto_detect Property

Whether to automatically detect and use proxy system settings, if available.

Syntax

def get_proxy_auto_detect() -> bool: ...
def set_proxy_auto_detect(value: bool) -> None: ...

proxy_auto_detect = property(get_proxy_auto_detect, set_proxy_auto_detect)

Default Value

FALSE

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is False.

proxy_password Property

A password if authentication is to be used for the proxy.

Syntax

def get_proxy_password() -> str: ...
def set_proxy_password(value: str) -> None: ...

proxy_password = property(get_proxy_password, set_proxy_password)

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

proxy_port Property

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

def get_proxy_port() -> int: ...
def set_proxy_port(value: int) -> None: ...

proxy_port = property(get_proxy_port, set_proxy_port)

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy proxy_server (default 80). See the description of the proxy_server property for details.

proxy_server Property

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

def get_proxy_server() -> str: ...
def set_proxy_server(value: str) -> None: ...

proxy_server = property(get_proxy_server, set_proxy_server)

Default Value

""

Remarks

If a proxy proxy_server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the proxy_server property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the proxy_server property is set to the corresponding address. If the search is not successful, an error is returned.

proxy_ssl Property

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

def get_proxy_ssl() -> int: ...
def set_proxy_ssl(value: int) -> None: ...

proxy_ssl = property(get_proxy_ssl, set_proxy_ssl)

Default Value

0

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

proxy_user Property

A username if authentication is to be used for the proxy.

Syntax

def get_proxy_user() -> str: ...
def set_proxy_user(value: str) -> None: ...

proxy_user = property(get_proxy_user, set_proxy_user)

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

revocation_check Property

The kind(s) of revocation check to perform for all chain certificates.

Syntax

def get_revocation_check() -> int: ...
def set_revocation_check(value: int) -> None: ...

revocation_check = property(get_revocation_check, set_revocation_check)

Default Value

6

Remarks

This property is used to specify the revocation sources and preferences the class will use during chain validation. Revocation checking is necessary to ensure the integrity of the chain and to obtain up-to-date certificate validity and trust information.

Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) responses serve the same purpose of ensuring that the certificate has not been revoked by the Certificate Authority (CA) at the time of use. Depending on the circumstances and security policy requirements, either one or both of the revocation information source types may be used.

Possible values are:

This property controls the way revocation checks are performed for every certificate in the chain. Typically, certificates come with two types of revocation information sources: CRLs (Certificate Revocation Lists) and OCSP responses. CRLs are static objects periodically published by the CA at some online location. OCSP responders are active online services maintained by the CA that can provide up-to-date information on certificate statuses in near real time.

There are some conceptual differences between the two. CRLs are normally larger in size. Their use involves some latency because there is normally a delay between the time at which a certificate was revoked and the time at which the subsequent CRL mentioning that revocation is published. The benefits of CRLs are that the same object can provide statuses for all certificates issued by a particular CA, and that the whole technology is much simpler than OCSP (and thus is supported by more CAs).

This property allows the validation course to be adjusted by including or excluding certain types of revocation sources from the validation process. The rcAnyOCSPOrCRL setting (give preference to the faster OCSP route and only demand one source to succeed) is a good choice for most typical validation environments. The rcAll* modes are much stricter, and may be used in scenarios where bulletproof validity information is essential.

Note: If no CRL or OCSP endpoints are provided by the CA, the revocation check will be considered successful. This is because the CA chose not to supply revocation information for its certificates, meaning they are considered irrevocable.

Note: Within each of the above settings, if any retrieved CRL or OCSP response indicates that the certificate has been revoked, the revocation check fails.

signature_author_name Property

The human-readable name of the signer.

Syntax

def get_signature_author_name() -> str: ...
def set_signature_author_name(value: str) -> None: ...

signature_author_name = property(get_signature_author_name, set_signature_author_name)

Default Value

""

Remarks

This property is used to specify the human-readable name of the signer.

Note: This property only applies when creating a new signature.

signature_claimed_signing_time Property

The signature's creation time.

Syntax

def get_signature_claimed_signing_time() -> str: ...
def set_signature_claimed_signing_time(value: str) -> None: ...

signature_claimed_signing_time = property(get_signature_claimed_signing_time, set_signature_claimed_signing_time)

Default Value

""

Remarks

This property is used to specify the signature creation time from the signer's computer. The time should be provided in UTC in yyyyMMddHHmmssZ format.

Note: This property only applies when creating a new signature.

signature_field Property

The index of the empty signature field to sign.

Syntax

def get_signature_field() -> int: ...
def set_signature_field(value: int) -> None: ...

signature_field = property(get_signature_field, set_signature_field)

Default Value

-1

Remarks

This property is used to specify the empty signature field that should be signed. If the default value of -1 is assigned to this property, a new signature field will be created.

Example: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "emptyfield.pdf"; pdfsign.SignatureType = PDFSignSignatureTypes.stEmptyField; pdfsign.Sign(); // Later pdfsign.Reset(); pdfsign.InputFile = "emptyfield.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureField = 0; // Configure signature properties as desired pdfsign.Sign();

signature_hash_algorithm Property

The hash algorithm to be used for signing.

Syntax

def get_signature_hash_algorithm() -> str: ...
def set_signature_hash_algorithm(value: str) -> None: ...

signature_hash_algorithm = property(get_signature_hash_algorithm, set_signature_hash_algorithm)

Default Value

"SHA256"

Remarks

This property is used to specify the hash algorithm to be used for signing.

Possible values are:

• SHA1
• SHA224
• SHA256
• SHA384
• SHA512
• MD5

Note: This property only applies when creating a new signature.

signature_profile Property

The PAdES profile to apply when creating the signature.

Syntax

def get_signature_profile() -> int: ...
def set_signature_profile(value: int) -> None: ...

signature_profile = property(get_signature_profile, set_signature_profile)

Default Value

0

Remarks

This property is used to specify a pre-defined PAdES profile to apply when creating the signature, as defined by ETSI.

Advanced signatures come in many variants, and they are often defined by parties that need to process them or by local standards. Profiles are sets of pre-defined configurations that correspond to particular signature variants. Specifying a profile pre-configures the class to make it produce the signature that matches the configuration corresponding to that profile.

Possible values are:

To apply a custom profile that is not defined by ETSI, set the CustomProfile configuration setting.

Note: This property only applies when creating a new signature.

signature_reason Property

The reason for signing.

Syntax

def get_signature_reason() -> str: ...
def set_signature_reason(value: str) -> None: ...

signature_reason = property(get_signature_reason, set_signature_reason)

Default Value

""

Remarks

This property is used to specify the reason for signing.

Note: This property only applies when creating a new signature.

pdf_signature_count Property

The number of records in the PDFSignature arrays.

Syntax

def get_pdf_signature_count() -> int: ...

pdf_signature_count = property(get_pdf_signature_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• pdf_signature_author_name
• pdf_signature_chain_validation_details
• pdf_signature_chain_validation_result
• pdf_signature_claimed_signing_time
• pdf_signature_coverage_ends_at
• pdf_signature_hash_algorithm
• pdf_signature_profile
• pdf_signature_reason
• pdf_signature_signer_cert_index
• pdf_signature_timestamp_cert_index
• pdf_signature_timestamped
• pdf_signature_type
• pdf_signature_validated_signing_time
• pdf_signature_validation_result
• pdf_signature_widget_height
• pdf_signature_widget_offset_x
• pdf_signature_widget_offset_y
• pdf_signature_widget_pages
• pdf_signature_widget_width

The array indices start at 0 and end at pdf_signature_count - 1.

This property is read-only.

pdf_signature_author_name Property

The human-readable name of the signer.

Syntax

def get_pdf_signature_author_name(pdf_signature_index: int) -> str: ...

Default Value

""

Remarks

The human-readable name of the signer.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_chain_validation_details Property

The details of the certificate chain validation outcome.

Syntax

def get_pdf_signature_chain_validation_details(pdf_signature_index: int) -> int: ...

Default Value

0

Remarks

The details of the certificate chain validation outcome. They may often suggest the reasons that contributed to the overall validation result in pdf_signature_chain_validation_result.

The value of this property is a bitmask of the following flags:

Subscribe to the on_log event to access the detailed validation log. This property is also available as a parameter of the on_signature_processed event.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_chain_validation_result Property

The outcome of the certificate chain validation routine.

Syntax

def get_pdf_signature_chain_validation_result(pdf_signature_index: int) -> int: ...

Default Value

0

Remarks

The outcome of the certificate chain validation routine.

Possible values are:

Subscribe to the on_log event to access the detailed validation log. This property is also available as a parameter of the on_signature_processed event.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_claimed_signing_time Property

The signature's creation time in UTC.

Syntax

def get_pdf_signature_claimed_signing_time(pdf_signature_index: int) -> str: ...

Default Value

""

Remarks

The signature's creation time in UTC.

Use this property to get the signature creation time from the signer's computer. Note that the claimed time, unlike pdf_signature_validated_signing_time, does not originate from a trusted TSA and may be forfeited or wrong.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_coverage_ends_at Property

The offset in the PDF file where the signature coverage ends.

Syntax

def get_pdf_signature_coverage_ends_at(pdf_signature_index: int) -> int: ...

Default Value

0

Remarks

The offset in the PDF file where the signature coverage ends.

PDF generators often use incremental updates to make changes in documents. This may result in the signature only covering a part of the document (one of the past revisions), but not the subsequent changes.

Use this property to identify the offset where the signature coverage ends. One option is to compare it to the length of the whole document to ensure that the signature covers the entire document. Alternatively, use the get_signed_version method to extract the exact revision that was signed.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_hash_algorithm Property

The hash algorithm that was used for signing.

Syntax

def get_pdf_signature_hash_algorithm(pdf_signature_index: int) -> str: ...

Default Value

"SHA256"

Remarks

The hash algorithm that was used for signing.

Possible values are:

• SHA1
• SHA224
• SHA256
• SHA384
• SHA512
• MD5

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_profile Property

The pre-defined PAdES profile that was applied when creating the signature, as defined by ETSI.

Syntax

def get_pdf_signature_profile(pdf_signature_index: int) -> int: ...

Default Value

0

Remarks

The pre-defined PAdES profile that was applied when creating the signature, as defined by ETSI.

Advanced signatures come in many variants, and they are often defined by parties that need to process them or by local standards. Profiles are sets of pre-defined configurations that correspond to particular signature variants.

Possible values are:

Note that when verifying a signature, the LTV modifier may be affected by the validation settings. These include offline_mode (set it to True to obtain the clean LTV capability) and CacheRevocationInfo (set it to False to prevent earlier validations from affecting the current validation).

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_reason Property

The reason for signing.

Syntax

def get_pdf_signature_reason(pdf_signature_index: int) -> str: ...

Default Value

""

Remarks

The reason for signing.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_type Property

The type of the signature that was created.

Syntax

def get_pdf_signature_type(pdf_signature_index: int) -> int: ...

Default Value

0

Remarks

The type of the signature that was created.

Possible values are:

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_signer_cert_index Property

The index of the signer certificate in the DocumentCerts properties.

Syntax

def get_pdf_signature_signer_cert_index(pdf_signature_index: int) -> int: ...

Default Value

-1

Remarks

The index of the signer certificate in the document_certs properties.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_timestamp_cert_index Property

The index of the timestamping certificate in the DocumentCerts properties (if applicable).

Syntax

def get_pdf_signature_timestamp_cert_index(pdf_signature_index: int) -> int: ...

Default Value

-1

Remarks

The index of the timestamping certificate in the document_certs properties (if applicable).

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_timestamped Property

Whether the signature contains an embedded timestamp.

Syntax

def get_pdf_signature_timestamped(pdf_signature_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether the signature contains an embedded timestamp.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_validated_signing_time Property

The certified signing time in UTC.

Syntax

def get_pdf_signature_validated_signing_time(pdf_signature_index: int) -> str: ...

Default Value

""

Remarks

The certified signing time in UTC.

Use this property to obtain the signing time as certified by a timestamp from a trusted timestamping authority. This property is only nonempty if there is a valid timestamp included in the signature.

Note that the validated time, unlike pdf_signature_claimed_signing_time, is the trusted signing time.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_validation_result Property

The outcome of the cryptographic signature validation.

Syntax

def get_pdf_signature_validation_result(pdf_signature_index: int) -> int: ...

Default Value

0

Remarks

The outcome of the cryptographic signature validation.

Possible values are:

This property is also available as the SignatureValidationResult parameter of the on_signature_processed event.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_widget_height Property

The height of the signature widget in points.

Syntax

def get_pdf_signature_widget_height(pdf_signature_index: int) -> str: ...

Default Value

"70"

Remarks

The height of the signature widget in points. Both integer and decimal values are supported.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_widget_offset_x Property

The signature widget offset from the left-hand page border in points.

Syntax

def get_pdf_signature_widget_offset_x(pdf_signature_index: int) -> str: ...

Default Value

"0"

Remarks

The signature widget offset from the left-hand page border in points. Both integer and decimal values are supported.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_widget_offset_y Property

The signature widget offset from the bottom page border in points.

Syntax

def get_pdf_signature_widget_offset_y(pdf_signature_index: int) -> str: ...

Default Value

"0"

Remarks

The signature widget offset from the bottom page border in points. Both integer and decimal values are supported.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_widget_pages Property

The pages that the signature and its widget are placed on.

Syntax

def get_pdf_signature_widget_pages(pdf_signature_index: int) -> str: ...

Default Value

""

Remarks

The pages that the signature and its widget are placed on.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

pdf_signature_widget_width Property

The width of the signature widget in points.

Syntax

def get_pdf_signature_widget_width(pdf_signature_index: int) -> str: ...

Default Value

"70"

Remarks

The width of the signature widget in points. Both integer and decimal values are supported.

The pdf_signature_index parameter specifies the index of the item in the array. The size of the array is controlled by the pdf_signature_count property.

This property is read-only.

signature_type Property

The type of signature to create.

Syntax

def get_signature_type() -> int: ...
def set_signature_type(value: int) -> None: ...

signature_type = property(get_signature_type, set_signature_type)

Default Value

0

Remarks

This property is used to specify the type of the signature.

Possible values are:

Note: This property only applies when creating a new signature.

signature_widget_height Property

The height of the signature widget.

Syntax

def get_signature_widget_height() -> str: ...
def set_signature_widget_height(value: str) -> None: ...

signature_widget_height = property(get_signature_widget_height, set_signature_widget_height)

Default Value

"70"

Remarks

This property is used to specify the height of the signature widget in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

signature_widget_offset_x Property

The signature widget offset from the left-hand page border.

Syntax

def get_signature_widget_offset_x() -> str: ...
def set_signature_widget_offset_x(value: str) -> None: ...

signature_widget_offset_x = property(get_signature_widget_offset_x, set_signature_widget_offset_x)

Default Value

"0"

Remarks

This property is used to specify the signature widget offset from the left-hand page border in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

signature_widget_offset_y Property

The signature widget offset from the bottom page border.

Syntax

def get_signature_widget_offset_y() -> str: ...
def set_signature_widget_offset_y(value: str) -> None: ...

signature_widget_offset_y = property(get_signature_widget_offset_y, set_signature_widget_offset_y)

Default Value

"0"

Remarks

This property is used to specify the signature widget offset from the bottom page border in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

signature_widget_pages Property

The pages to place the signature and its widget on.

Syntax

def get_signature_widget_pages() -> str: ...
def set_signature_widget_pages(value: str) -> None: ...

signature_widget_pages = property(get_signature_widget_pages, set_signature_widget_pages)

Default Value

""

Remarks

This property is used to specify the pages on which the signature and its widget will be placed.

A variety of syntaxes are supported:

• A single page number: 3
• A comma-separated list of page numbers: 1,2,5,7
• The asterisk character (*) indicates that the widget should be placed on all pages in the document.
• The first and last placeholders specify that the signature should be placed on the respective page, independently of its number.

Note: This property only applies when creating a new signature.

signature_widget_width Property

The width of the signature widget.

Syntax

def get_signature_widget_width() -> str: ...
def set_signature_widget_width(value: str) -> None: ...

signature_widget_width = property(get_signature_widget_width, set_signature_widget_width)

Default Value

"70"

Remarks

This property is used to specify the width of the signature widget in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

signing_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_signing_cert_effective_date() -> str: ...

signing_cert_effective_date = property(get_signing_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

signing_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_signing_cert_expiration_date() -> str: ...

signing_cert_expiration_date = property(get_signing_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

signing_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_signing_cert_extended_key_usage() -> str: ...

signing_cert_extended_key_usage = property(get_signing_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

signing_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_signing_cert_fingerprint() -> str: ...

signing_cert_fingerprint = property(get_signing_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

signing_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_signing_cert_fingerprint_sha1() -> str: ...

signing_cert_fingerprint_sha1 = property(get_signing_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

signing_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_signing_cert_fingerprint_sha256() -> str: ...

signing_cert_fingerprint_sha256 = property(get_signing_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

signing_cert_issuer Property

The issuer of the certificate.

Syntax

def get_signing_cert_issuer() -> str: ...

signing_cert_issuer = property(get_signing_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

signing_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_signing_cert_private_key() -> str: ...

signing_cert_private_key = property(get_signing_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The signing_cert_private_key may be available but not exportable. In this case, signing_cert_private_key returns an empty string.

This property is read-only.

signing_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_signing_cert_private_key_available() -> bool: ...

signing_cert_private_key_available = property(get_signing_cert_private_key_available, None)

Default Value

FALSE

Remarks

Whether a signing_cert_private_key is available for the selected certificate. If signing_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

signing_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_signing_cert_private_key_container() -> str: ...

signing_cert_private_key_container = property(get_signing_cert_private_key_container, None)

Default Value

""

Remarks

The name of the signing_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

signing_cert_public_key Property

The public key of the certificate.

Syntax

def get_signing_cert_public_key() -> str: ...

signing_cert_public_key = property(get_signing_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

signing_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_signing_cert_public_key_algorithm() -> str: ...

signing_cert_public_key_algorithm = property(get_signing_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

signing_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_signing_cert_public_key_length() -> int: ...

signing_cert_public_key_length = property(get_signing_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

signing_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_signing_cert_serial_number() -> str: ...

signing_cert_serial_number = property(get_signing_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

signing_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_signing_cert_signature_algorithm() -> str: ...

signing_cert_signature_algorithm = property(get_signing_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

signing_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_signing_cert_store() -> bytes: ...
def set_signing_cert_store(value: bytes) -> None: ...

signing_cert_store = property(get_signing_cert_store, set_signing_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The signing_cert_store_type property denotes the type of the certificate store specified by signing_cert_store. If the store is password-protected, specify the password in signing_cert_store_password.

signing_cert_store is used in conjunction with the signing_cert_subject property to specify client certificates. If signing_cert_store has a value, and signing_cert_subject or signing_cert_encoded is set, a search for a certificate is initiated. Please see the signing_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

signing_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_signing_cert_store_password() -> str: ...
def set_signing_cert_store_password(value: str) -> None: ...

signing_cert_store_password = property(get_signing_cert_store_password, set_signing_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

signing_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_signing_cert_store_type() -> int: ...
def set_signing_cert_store_type(value: int) -> None: ...

signing_cert_store_type = property(get_signing_cert_store_type, set_signing_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

signing_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_signing_cert_subject_alt_names() -> str: ...

signing_cert_subject_alt_names = property(get_signing_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

signing_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_signing_cert_thumbprint_md5() -> str: ...

signing_cert_thumbprint_md5 = property(get_signing_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

signing_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_signing_cert_thumbprint_sha1() -> str: ...

signing_cert_thumbprint_sha1 = property(get_signing_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

signing_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_signing_cert_thumbprint_sha256() -> str: ...

signing_cert_thumbprint_sha256 = property(get_signing_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

signing_cert_usage Property

The text description of UsageFlags .

Syntax

def get_signing_cert_usage() -> str: ...

signing_cert_usage = property(get_signing_cert_usage, None)

Default Value

""

Remarks

The text description of signing_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

signing_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_signing_cert_usage_flags() -> int: ...

signing_cert_usage_flags = property(get_signing_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of signing_cert_usage_flags is a combination of the following flags:

Please see the signing_cert_usage property for a text representation of signing_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

signing_cert_version Property

The certificate's version number.

Syntax

def get_signing_cert_version() -> str: ...

signing_cert_version = property(get_signing_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

signing_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_signing_cert_subject() -> str: ...
def set_signing_cert_subject(value: str) -> None: ...

signing_cert_subject = property(get_signing_cert_subject, set_signing_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

signing_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_signing_cert_encoded() -> bytes: ...
def set_signing_cert_encoded(value: bytes) -> None: ...

signing_cert_encoded = property(get_signing_cert_encoded, set_signing_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The signing_cert_store and signing_cert_subject properties also may be used to specify a certificate.

When signing_cert_encoded is set, a search is initiated in the current signing_cert_store for the private key of the certificate. If the key is found, signing_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, signing_cert_subject is set to an empty string.

timestamp_server Property

The address of the timestamping server.

Syntax

def get_timestamp_server() -> str: ...
def set_timestamp_server(value: str) -> None: ...

timestamp_server = property(get_timestamp_server, set_timestamp_server)

Default Value

""

Remarks

This property is used to specify the address of the TSA (Timestamping Authority) server to use for timestamping the signature (normal signing) or the document (LTV update).

If the timestamping service enforces credential-based user authentication (basic or digest), the credentials can be provided in the same URL. For example: pdfsign.TimestampServer = "http://user:password@timestamp.server.com/TsaService"; If the TSA requires TLS client authentication, provide the client certificate via the TSATLSClientCertStoreType, TSATLSClientCertStore, TSATLSClientCertSubject, and TSATLSClientCertStorePassword configuration settings.

trusted_cert_count Property

The number of records in the TrustedCert arrays.

Syntax

def get_trusted_cert_count() -> int: ...
def set_trusted_cert_count(value: int) -> None: ...

trusted_cert_count = property(get_trusted_cert_count, set_trusted_cert_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• trusted_cert_effective_date
• trusted_cert_encoded
• trusted_cert_expiration_date
• trusted_cert_extended_key_usage
• trusted_cert_fingerprint
• trusted_cert_fingerprint_sha1
• trusted_cert_fingerprint_sha256
• trusted_cert_issuer
• trusted_cert_private_key
• trusted_cert_private_key_available
• trusted_cert_private_key_container
• trusted_cert_public_key
• trusted_cert_public_key_algorithm
• trusted_cert_public_key_length
• trusted_cert_serial_number
• trusted_cert_signature_algorithm
• trusted_cert_store
• trusted_cert_store_password
• trusted_cert_store_type
• trusted_cert_subject
• trusted_cert_subject_alt_names
• trusted_cert_thumbprint_md5
• trusted_cert_thumbprint_sha1
• trusted_cert_thumbprint_sha256
• trusted_cert_usage
• trusted_cert_usage_flags
• trusted_cert_version

The array indices start at 0 and end at trusted_cert_count - 1.

trusted_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_trusted_cert_effective_date(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_trusted_cert_expiration_date(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_trusted_cert_extended_key_usage(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_trusted_cert_fingerprint(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_trusted_cert_fingerprint_sha1(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_trusted_cert_fingerprint_sha256(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_issuer Property

The issuer of the certificate.

Syntax

def get_trusted_cert_issuer(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_trusted_cert_private_key(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The trusted_cert_private_key may be available but not exportable. In this case, trusted_cert_private_key returns an empty string.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_trusted_cert_private_key_available(trusted_cert_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether a trusted_cert_private_key is available for the selected certificate. If trusted_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_trusted_cert_private_key_container(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The name of the trusted_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_public_key Property

The public key of the certificate.

Syntax

def get_trusted_cert_public_key(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_trusted_cert_public_key_algorithm(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_trusted_cert_public_key_length(trusted_cert_index: int) -> int: ...

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_trusted_cert_serial_number(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_trusted_cert_signature_algorithm(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_trusted_cert_store(trusted_cert_index: int) -> bytes: ...
def set_trusted_cert_store(trusted_cert_index: int, value: bytes) -> None: ...

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The trusted_cert_store_type property denotes the type of the certificate store specified by trusted_cert_store. If the store is password-protected, specify the password in trusted_cert_store_password.

trusted_cert_store is used in conjunction with the trusted_cert_subject property to specify client certificates. If trusted_cert_store has a value, and trusted_cert_subject or trusted_cert_encoded is set, a search for a certificate is initiated. Please see the trusted_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

trusted_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_trusted_cert_store_password(trusted_cert_index: int) -> str: ...
def set_trusted_cert_store_password(trusted_cert_index: int, value: str) -> None: ...

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

trusted_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_trusted_cert_store_type(trusted_cert_index: int) -> int: ...
def set_trusted_cert_store_type(trusted_cert_index: int, value: int) -> None: ...

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

trusted_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_trusted_cert_subject_alt_names(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_trusted_cert_thumbprint_md5(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_trusted_cert_thumbprint_sha1(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_trusted_cert_thumbprint_sha256(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_usage Property

The text description of UsageFlags .

Syntax

def get_trusted_cert_usage(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The text description of trusted_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_trusted_cert_usage_flags(trusted_cert_index: int) -> int: ...

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of trusted_cert_usage_flags is a combination of the following flags:

Please see the trusted_cert_usage property for a text representation of trusted_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_version Property

The certificate's version number.

Syntax

def get_trusted_cert_version(trusted_cert_index: int) -> str: ...

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

This property is read-only.

trusted_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_trusted_cert_subject(trusted_cert_index: int) -> str: ...
def set_trusted_cert_subject(trusted_cert_index: int, value: str) -> None: ...

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

trusted_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_trusted_cert_encoded(trusted_cert_index: int) -> bytes: ...
def set_trusted_cert_encoded(trusted_cert_index: int, value: bytes) -> None: ...

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The trusted_cert_store and trusted_cert_subject properties also may be used to specify a certificate.

When trusted_cert_encoded is set, a search is initiated in the current trusted_cert_store for the private key of the certificate. If the key is found, trusted_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, trusted_cert_subject is set to an empty string.

The trusted_cert_index parameter specifies the index of the item in the array. The size of the array is controlled by the trusted_cert_count property.

trusted_lists Property

A list of known Trusted Lists for chain validation.

Syntax

def get_trusted_lists() -> str: ...
def set_trusted_lists(value: str) -> None: ...

trusted_lists = property(get_trusted_lists, set_trusted_lists)

Default Value

"%EUTL%"

Remarks

This property is used to supply a semicolon-separated list of URLs or paths of known Trusted Lists to the class for chain validation.

A Trusted List is an XML document that contains a government-issued list of CAs that have passed regulated compliance checks. When validating the chain, the class will consult the Trusted List to establish certificate trust, ensuring that the CA is legitimate and entitled to issue certificates of the kind being checked.

The default value is the special %EUTL% macro, which, if applicable, instructs the class to check the root certificate against up-to-date versions of the primary EU Trusted Lists from the EU LOTL. Custom values can be appended: component.TrustedLists = "%EUTL%;http://my.company/tsl;c:\tsls\mytsl.xml"; Note: The class will cache all Trusted Lists it downloads and uses during chain validation. This cache is shared between class instances within the same process. If this property contains a URL that is also present in the cache, the class will retrieve the cached data and reuse them in the current validation. If the data are invalid, the class will download a fresh Trusted List and add it to the cache.

trust_sources Property

The trust sources to use during chain validation.

Syntax

def get_trust_sources() -> int: ...
def set_trust_sources(value: int) -> None: ...

trust_sources = property(get_trust_sources, set_trust_sources)

Default Value

3

Remarks

This property is used to specify the sources the class will use to establish certificate trust during chain validation.

Establishing trust for a particular certificate, when either signing or verifying, involves building a chain up to a valid trust anchor. This trust anchor is a root certificate that typically resides on the local system. If the certificate does not eventually chain up to a valid trust anchor, the chain is considered untrusted and therefore invalid.

Possible values are:

validation_flags Property

Additional chain validation settings.

Syntax

def get_validation_flags() -> int: ...
def set_validation_flags(value: int) -> None: ...

validation_flags = property(get_validation_flags, set_validation_flags)

Default Value

0

Remarks

This property is used to specify additional settings that affect the overall flow of the chain validation.

Its value should be provided as a bitmask of the following flags:

validation_policy Property

The level at which to perform chain validation.

Syntax

def get_validation_policy() -> int: ...
def set_validation_policy(value: int) -> None: ...

validation_policy = property(get_validation_policy, set_validation_policy)

Default Value

1

Remarks

This property is used to specify the overall validation policy the class will follow.

Possible values are:

Validation Policy Heuristics

The choice of validation policy will depend on the scenario for which the chain is validated.

Creating a new signature:

• For a basic signature with or without a timestamp, chain validation is not required, so it is recommended to use vpNone. This policy may also be used in test environments or on offline systems.
• For an LTV signature, use vpFull or vpFullNoTrust depending on whether trust checks are necessary in the current environment. If the signature is being created in an environment that does not match the prospective validation environment, consider vpFullNoTrust to validate the chain properly and fully without expecting good trust.

Updating or extending an existing signature:

• When updating a basic signature to LTV, similarly use vpFull or vpFullNoTrust as above.
• When extending an LTV signature, similarly use vpFull or vpFullNoTrust as above.

Validating an existing signature:

• For basic signature validation, use vpFullNoRevocation if trust checks, but not revocation checks, are necessary in the current environment. This policy may also be used on offline systems if the trust anchor is already available to the class.
• For archival validation, use vpFull to validate the chain properly and fully. This policy expects the trust anchor and all the revocation material to be available.

validation_time Property

The time point at which the signature should be validated.

Syntax

def get_validation_time() -> str: ...
def set_validation_time(value: str) -> None: ...

validation_time = property(get_validation_time, set_validation_time)

Default Value

""

Remarks

This property is used to specify the moment in time at which the signature validity should be established. The time should be provided in UTC in yyyyMMddHHmmssZ format.

Leave this property empty to stick to the default time point. The class will then prioritize:

• The signature creation time if the signature contains a signature timestamp (), or
• The local time included in the signature by the signer ().

Note: The validity of the same signature may differ depending on the time point chosen due to temporal changes in chain validities, revocation statuses, and timestamp times.

add_attachment Method

Adds an attachment to a PDF document.

Syntax

def add_attachment(file_name: str, description: str) -> None: ...

Remarks

This method is used to add an attachment (embedded file) to the document specified in input_file, input_data, or set_input_stream and to the attachments properties.

The document containing the newly added attachment will be saved to output_file, output_data, or the stream set in set_output_stream.

The FileName and Description parameters specify the filename and description of the attachment respectively.

Example: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "input_with_attachment.pdf"; pdfsign.Open(); pdfsign.AddAttachment("foo.txt", "desc"); // Alternatively, create a PDFAttachment object and add it to Attachments manually: PDFAttachment attachment = new PDFAttachment(); attachment.FileName = "foo.txt"; // or attachment.DataB = new byte[] { ... }; // or attachment.InputStream = new FileStream(...); attachment.Description = "desc"; pdfsign.Attachments.Add(attachment); // Or using one of the constructors: pdfsign.Attachments.Add(new PDFAttachment("foo.txt", "desc")); pdfsign.Close(); The full list of attachments is contained in the attachments property.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

add_timestamp Method

Adds a document timestamp to a PDF document.

Syntax

def add_timestamp() -> None: ...

Remarks

This method is used to obtain a document timestamp and embed it into the document specified in input_file, input_data, or set_input_stream. The document containing the newly added document timestamp will be saved to output_file, output_data, or the stream set in set_output_stream.

A document timestamp is a fully independent signature that is added to the PDF document after the initial signature. Unlike the main signature, the document timestamp is made by a TSA, and its purpose is to preserve the document's long-term validity. Typically, adding a document timestamp is done close to the expiration date of the certificate that produced the last timestamp (which is either embedded in the main signature, or is a previous document timestamp). An LTV document therefore contains a chain of document timestamps updated periodically to keep its long-term status.

Example: pdfsign.InputFile = "signed.pdf"; pdfsign.OutputFile = "signed_with_dts.pdf"; pdfsign.TimestampServer = "http://time.certum.pl"; pdfsign.AddTimestamp(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

close Method

Closes an opened PDF document.

Syntax

def close() -> None: ...

Remarks

This method is used to close the previously opened document specified in input_file, input_data, or set_input_stream. It should always be preceded by a call to the open method.

Example: component.InputFile = "input.pdf"; component.Open(); // Some operation component.Close();

If any changes are made to the document, they will be saved automatically to output_file, output_data, or the stream set in set_output_stream when this method is called. To configure this saving behavior, set the SaveChanges configuration setting.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

encrypted Method

Checks whether a PDF document is encrypted.

Syntax

def encrypted() -> bool: ...

Remarks

This method is used to determine whether or not the document specified in input_file, input_data, or set_input_stream is encrypted. It will return False if the document is pseudo-encrypted with an empty password.

Example: component.InputFile = "input.pdf"; if (component.Encrypted()) { // Set Password or DecryptionCert } component.Open(); // Some operation component.Close(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

get_page_property Method

Retrieves the value of a page property.

Syntax

def get_page_property(page: int, page_property: str) -> str: ...

Remarks

This method is used to read general information about the pages of the document specified in input_file, input_data, or set_input_stream, such as their dimensions and content positioning details.

The Page parameter specifies the page to read information about (with a valid range from 1 to PageCount), and the PageProperty parameter specifies the page property to read. The latter can take one of the following values:

Note: Each page property is only populated once the document has been loaded, which is reported by the on_document_info event.

Example: int pageCount = 0; component.OnDocumentInfo += (s, e) => { pageCount = e.PageCount; }; component.InputFile = "input.pdf"; component.Open(); for (int i = 1; i <= pageCount; i++) component.GetPageProperty(i, "Height"); component.Close(); The page properties can be used to adjust the position of the signature widget based on the page dimensions. For example: int x = int.Parse(pdfsign.GetPageProperty(1, "Width")) - 100; int y = int.Parse(pdfsign.GetPageProperty(1, "Height")) - 100; pdfsign.SetWidgetProperty("OffsetX", x.ToString()); pdfsign.SetWidgetProperty("OffsetY", y.ToString()); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

get_widget_property Method

Retrieves the value of a signature widget property.

Syntax

def get_widget_property(signature_index: int, widget_property: str) -> str: ...

Remarks

This method is used to retrieve the value of a signature widget property. Together with set_widget_property, this method provides an extensible way of managing the widget settings that are not available through the primary properties of the class. The list of settings below may be extended in the future.

The SignatureIndex parameter is the index of the signature of interest in the signatures properties, and the WidgetProperty parameter specifies the widget property to read. The latter can take one of the following values:

Example: pdfsign.InputFile = "signed.pdf"; pdfsign.Open(); bool invisible = bool.Parse(pdfsign.GetWidgetProperty(0, "Invisible")); pdfsign.Close(); Note: Each widget property is only populated after the document has been signed and the signature widget has been generated.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

interrupt Method

Interrupts the current action.

Syntax

def interrupt() -> None: ...

Remarks

This method interrupts the current action. It can be used, for example, within the on_chain_cert event to abort the chain validation procedure.

If there is no action in progress, this method simply returns, doing nothing.

open Method

Opens a PDF document for processing.

Syntax

def open() -> None: ...

Remarks

This method is used to open the document specified in input_file, input_data, or set_input_stream before performing some operation on it, such as signing or updating. When finished, call close to complete or discard the operation.

It is recommended to use this method (alongside close) when performing multiple operations on the document at once.

Note: This method will populate the attachments, document_certs, and signatures collections with any corresponding objects found in the document.

Automatic Decryption Functionality

If this method is called on an encrypted document, the on_password or on_recipient_info event will fire (depending on the encryption type) as a notification that the document must be decrypted before processing can continue.

Once the correct decryption material is supplied, the class will then attempt to decrypt the document automatically within this method. When this occurs, the decrypted content is kept in memory so that the document's encrypted status is preserved when it is saved later. Use the decrypt method to save a decrypted copy of the document instead.

remove_attachment Method

Removes an attachment from a PDF document.

Syntax

def remove_attachment(index: int) -> None: ...

Remarks

This method is used to remove an attachment from the document specified in input_file, input_data, or set_input_stream and from the attachments properties.

The document without the attachment will be saved to output_file, output_data, or the stream set in set_output_stream.

The Index parameter is the index of the attachment in the attachments properties to be removed.

Example: pdfsign.InputFile = "input_with_attachment.pdf"; pdfsign.OutputFile = "attachment_removed.pdf"; pdfsign.Open(); pdfsign.RemoveAttachment(0); // Alternatively, remove an attachment from Attachments manually: PDFAttachment attachment = pdfsign.Attachments[0]; pdfsign.Attachments.Remove(attachment); pdfsign.Close(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

reset Method

Resets the class.

Syntax

def reset() -> None: ...

Remarks

This method is used to reset the class's properties and configuration settings to their default values.

save_attachment Method

Saves a PDF attachment to a file.

Syntax

def save_attachment(index: int, file_name: str) -> None: ...

Remarks

This method is used to retrieve the contents of an attachment from the document specified in input_file, input_data, or set_input_stream and save it to the file specified by FileName. It does not modify the existence of the attachments properties's contents.

The Index parameter is the index of the attachment in the attachments properties to be saved.

The FileName parameter specifies the filename that the attachment will be saved to.

Example: component.InputFile = "input_with_attachment.pdf"; component.Open(); component.SaveAttachment(0, "a.dat"); component.Close(); Example (saving to a stream): component.InputFile = "input_with_attachment.pdf"; component.Attachments[0].OutputStream = myStream; component.SaveAttachment(0, null); // null means use the OutputStream property if it's set Note: If the document is not already opened, this method will open it, perform the operation, then close it.

set_widget_property Method

Sets the value of a signature widget property.

Syntax

def set_widget_property(widget_property: str, value: str) -> None: ...

Remarks

This method is used to adjust the look of the signature widget when creating a signature. Together with get_widget_property, this method provides an extensible way of managing the widget settings that are not available through the primary properties of the class. The list of settings below may be extended in the future.

The WidgetProperty and Value parameters specify the widget property and value to set respectively. The former can take one of the following values:

Example: pdfsign.SetWidgetProperty("Width", "100"); pdfsign.SetWidgetProperty("Height", "100"); pdfsign.SetWidgetProperty("ShowDate", "false"); pdfsign.SetWidgetProperty("SignerInfo", "Hello\r\nworld!"); pdfsign.SetWidgetProperty("TitleFontSize", "11"); pdfsign.Sign();

sign Method

Signs a PDF document.

Syntax

def sign() -> None: ...

Remarks

This method is used to sign the document specified in input_file, input_data, or set_input_stream. The document will be signed with signing_cert and saved in output_file, output_data, or the stream set in set_output_stream.

Use the following properties to adjust new signature settings:

• signature_author_name
• signature_claimed_signing_time
• signature_hash_algorithm
• signature_profile
• signature_reason
• signature_type
• signature_widget_height
• signature_widget_offset_x
• signature_widget_offset_y
• signature_widget_pages
• signature_widget_width

Use the following properties to adjust chain validation parameters:

• blocked_certs
• known_certs
• offline_mode
• revocation_check
• trusted_certs
• trusted_lists
• trust_sources
• validation_flags
• validation_policy
• validation_time

During signing, the chain validation log will be available via the on_log event if applicable.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

signed Method

Checks whether a PDF document is signed.

Syntax

def signed() -> bool: ...

Remarks

This method is used to determine whether or not the document specified in input_file, input_data, or set_input_stream is signed. It will return False if the document contains only empty signature fields.

Example: pdfverify.InputFile = "input.pdf"; if (pdfverify.Signed()) { // Configure validation-related properties as desired pdfverify.Verify(); } Note: If the document is not already opened, this method will open it, perform the operation, then close it.

update Method

Updates the most recent signature.

Syntax

def update() -> None: ...

Remarks

This method is used to update the most recent signature by embedding newer or missing revocation information into the signed document specified in input_file, input_data, or set_input_stream. The updated document will be saved to output_file, output_data, or the stream set in set_output_stream.

Updating a signature starts with its cryptographic validation. Before any new validation material is inserted, the signature's integrity must be validated. If the signature is found to be correct, the class will proceed with chain validation and the retrieval of any missing chain elements. If the signature is cryptographically wrong, the class will throw an exception.

The update approach is typically used to extend the validity of an LTV signature. For LTA signatures, updating is typically accompanied with a document timestamping operation. Set timestamp_server to have the class obtain and embed a document timestamp automatically.

Further validation material and document timestamps may be added to a document over time to maintain its authenticity and integrity.

Use the following properties to adjust chain validation parameters:

• blocked_certs
• known_certs
• offline_mode
• revocation_check
• trusted_certs
• trusted_lists
• trust_sources
• validation_flags
• validation_policy
• validation_time

Note: To choose a different signature to update, set the UpdateIndex configuration setting.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

on_chain_cert Event

Fired when the class encounters a chain certificate.

Syntax

class PDFSignChainCertEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def validation_time() -> str: ...

  @property
  def validation_result() -> int: ...
  @validation_result.setter
  def validation_result(value) -> None: ...

  @property
  def validation_details() -> int: ...
  @validation_details.setter
  def validation_details(value) -> None: ...

# In class PDFSign:
@property
def on_chain_cert() -> Callable[[PDFSignChainCertEventParams], None]: ...
@on_chain_cert.setter
def on_chain_cert(event_hook: Callable[[PDFSignChainCertEventParams], None]) -> None: ...

Remarks

This event is fired once for each certificate encountered during chain validation to report that it is about to be processed. The class will try to retrieve all required chain certificates automatically.

The CertEncoded parameter specifies the PEM (Base64-encoded) public certificate.

The CertSubject and CertIssuer parameters specify the distinguished names of the certificate owner and issuer respectively.

The ValidationTime parameter specifies the time point (in UTC) at which the certificate validity was established.

The ValidationResult parameter reports the outcome of the individual certificate validation and can be one of the following values:

In the case of a failure, the ValidationDetails parameter provides more details on its reasons. Its value is a bitmask of the following flags:

Overridable Chain Validation

While the class will follow the validation rules defined by the X.509 standard to the best of its ability, minor technical issues may arise when validating the chain. The ValidationResult and ValidationDetails parameters can be overridden to relax such requirements on a per-certificate basis.

For example, set ValidationResult to cvrValid and ValidationDetails to 0 in order to:

• Ignore CA or TLS key usage requirements
• Ignore the AuthorityKeyId extension in certificate-issuing CAs (helps with incorrectly renewed certificates)
• Ignore the Basic Constraints or Name Constraints extensions of CA certificates
• Tolerate some weaker algorithms
• Implicitly trust self-signed certificates
• Skip validity period checks for trusted certificates (helps with older devices that have expired root certificates)
• Ignore chain loops (helps with buggy CAs that include subchains that sign themselves)

Based on the adjusted validity of the certificate that is currently being processed, the class will continue or abort the chain validation procedure accordingly as if it had arrived at the chosen validation result itself.

Note: The user code is ultimately responsible for certificate validity decisions made via these two parameters. If their values are modified within this event, the resulting chain validation procedure may deviate from the standard.

on_document_info Event

Fired when the document has been loaded into memory.

Syntax

class PDFSignDocumentInfoEventParams(object):
  @property
  def page_count() -> int: ...

  @property
  def signature_count() -> int: ...

# In class PDFSign:
@property
def on_document_info() -> Callable[[PDFSignDocumentInfoEventParams], None]: ...
@on_document_info.setter
def on_document_info(event_hook: Callable[[PDFSignDocumentInfoEventParams], None]) -> None: ...

Remarks

This event is fired once per document processing routine to report that the document has been processed and loaded into memory.

The handler for this event is a good place to check the document structure and access document-related information such as page number and document file details. These may be useful when preparing the signature. For example, the get_page_property method can be used to find the optimal position for the signature widget.

The PageCount parameter reports the number of pages in the document.

The SignatureCount parameter reports the number of signatures in the document.

This event is fired when the open method is called, but only after on_password or on_recipient_info is fired (if applicable) and the document has been decrypted.

on_error Event

Fired when information is available about errors during data delivery.

Syntax

class PDFSignErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class PDFSign:
@property
def on_error() -> Callable[[PDFSignErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[PDFSignErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_log Event

Fired once for each log message.

Syntax

class PDFSignLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class PDFSign:
@property
def on_log() -> Callable[[PDFSignLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[PDFSignLogEventParams], None]) -> None: ...

Remarks

This event is fired once for each log message generated by the class. The verbosity is controlled by the LogLevel configuration setting.

The LogLevel parameter indicates the detail level of the message. Possible values are:

The Message parameter is the log message.

The LogType parameter identifies the type of log entry. Possible values are:

• CertValidator
• Font
• HTTP
• PDFInvalidSignature
• PDFRevocationInfo
• Timestamp
• TSL

on_password Event

Fired when the class detects that the PDF document is encrypted with a password.

Syntax

class PDFSignPasswordEventParams(object):
  @property
  def available() -> bool: ...

  @property
  def cancel() -> bool: ...
  @cancel.setter
  def cancel(value) -> None: ...

# In class PDFSign:
@property
def on_password() -> Callable[[PDFSignPasswordEventParams], None]: ...
@on_password.setter
def on_password(event_hook: Callable[[PDFSignPasswordEventParams], None]) -> None: ...

Remarks

This event is fired during document processing to report that the document is encrypted with a password. It may be used to supply the correct decryption password to the password property.

The Available parameter indicates whether the decryption password is already available to the class or still needs to be set. If this parameter is set to False, the correct password must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the class will stop firing this event to request a password.

on_recipient_info Event

Fired for each recipient certificate of the encrypted PDF document.

Syntax

class PDFSignRecipientInfoEventParams(object):
  @property
  def issuer() -> str: ...

  @property
  def serial_number() -> str: ...

  @property
  def subject_key_identifier() -> str: ...

  @property
  def available() -> bool: ...

  @property
  def cancel() -> bool: ...
  @cancel.setter
  def cancel(value) -> None: ...

# In class PDFSign:
@property
def on_recipient_info() -> Callable[[PDFSignRecipientInfoEventParams], None]: ...
@on_recipient_info.setter
def on_recipient_info(event_hook: Callable[[PDFSignRecipientInfoEventParams], None]) -> None: ...

Remarks

This event is fired during document processing for each recipient certificate that the document has been encrypted for (if applicable). It may be used to identify the certificate(s) to load and supply to the decryption_cert property.

The Issuer parameter specifies the subject of the issuer certificate.

The SerialNumber parameter specifies the serial number of the encryption certificate.

The SubjectKeyIdentifier parameter specifies the X.509 subjectKeyIdentifier extension value of the encryption certificate, encoded as a hex string.

The Available parameter indicates whether the decryption certificate is already available to the class or still needs to be set. If this parameter is set to False, the correct certificate must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the class will stop firing this event to request a certificate.

Note: The document may be encrypted with more than one certificate (or have "more than one recipient"), in which case each certificate will cause its own invocation of this event.

on_signature_info Event

Fired when the class finds a signature in the document.

Syntax

class PDFSignSignatureInfoEventParams(object):
  @property
  def signature_index() -> int: ...

  @property
  def validate_signature() -> bool: ...
  @validate_signature.setter
  def validate_signature(value) -> None: ...

  @property
  def validate_chain() -> bool: ...
  @validate_chain.setter
  def validate_chain(value) -> None: ...

# In class PDFSign:
@property
def on_signature_info() -> Callable[[PDFSignSignatureInfoEventParams], None]: ...
@on_signature_info.setter
def on_signature_info(event_hook: Callable[[PDFSignSignatureInfoEventParams], None]) -> None: ...

Remarks

This event is fired once for each signature found in the document to report that the signature specified by SignatureIndex is about to be validated.

The SignatureIndex parameter is the index of the signature in the signatures properties.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. The ValidateSignature and ValidateChain parameters determine whether each stage should be included in the validation. They can be overridden to modify the validation policy on a per-signature basis, allowing signatures to be verified individually instead of all at once (via verify). To skip validation entirely, set both parameters to False.

Use the following properties to adjust chain validation parameters:

• blocked_certs
• known_certs
• offline_mode
• revocation_check
• trusted_certs
• trusted_lists
• trust_sources
• validation_flags
• validation_policy
• validation_time

on_signature_processed Event

Fired after a signature has been processed.

Syntax

class PDFSignSignatureProcessedEventParams(object):
  @property
  def signature_index() -> int: ...

  @property
  def signature_validation_result() -> int: ...

  @property
  def chain_validation_result() -> int: ...

  @property
  def chain_validation_details() -> int: ...

# In class PDFSign:
@property
def on_signature_processed() -> Callable[[PDFSignSignatureProcessedEventParams], None]: ...
@on_signature_processed.setter
def on_signature_processed(event_hook: Callable[[PDFSignSignatureProcessedEventParams], None]) -> None: ...

Remarks

This event is fired once for each signature found in the document to report that the signature specified by SignatureIndex has completed validation. It is fired after on_signature_info if that event's ValidateSignature parameter is set to True.

The SignatureIndex parameter is the index of the signature in the signatures properties.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. Separate validation results are reported for each in the SignatureValidationResult and ChainValidationResult parameters.

The former reports the validity of the signature and can be one of the following values:

The latter reports the validity of the chain and can be one of the following values:

In the case of a failure, the ChainValidationDetails parameter provides more details on its reasons. Its value is a bitmask of the following flags:

Note: SignatureValidationResult, ChainValidationResult, and ChainValidationDetails are also available as properties in the PDFSignature type.

on_ssl_server_authentication Event

Fired after the server presents its certificate to the client.

Syntax

class PDFSignSSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def status() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class PDFSign:
@property
def on_ssl_server_authentication() -> Callable[[PDFSignSSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[PDFSignSSLServerAuthenticationEventParams], None]) -> None: ...

Remarks

This event is fired during timestamping or chain validation after the server presents its SSL/TLS certificate to the class. It only applies if the TSA, CRL, OCSP, or Trusted List endpoint operates over HTTPS.

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When the Accept parameter is False, the Status parameter shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

on_ssl_status Event

Fired when secure connection progress messages are available.

Syntax

class PDFSignSSLStatusEventParams(object):
  @property
  def message() -> str: ...

# In class PDFSign:
@property
def on_ssl_status() -> Callable[[PDFSignSSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[PDFSignSSLStatusEventParams], None]) -> None: ...

Remarks

This event is fired during timestamping or chain validation for informational and logging purposes only. This event tracks the progress of the SSL/TLS connection. It only applies if the TSA, CRL, OCSP, or Trusted List endpoint operates over HTTPS.

PDFSign Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

PDFSign Config Settings

Base Config Settings

PDFSign Errors

PDFSign Errors

PDF Errors

Parsing Errors

The class may also return one of the following error codes, which are inherited from other classes.

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors