pyhanko.sign.pkcs11 module

This module provides PKCS#11 integration for pyHanko, by providing a wrapper for python-pkcs11 that can be seamlessly plugged into a PdfSigner.

class pyhanko.sign.pkcs11.PKCS11Signer(pkcs11_session: Session, cert_label: Optional[str] = None, signing_cert: Optional[Certificate] = None, ca_chain=None, key_label: Optional[str] = None, prefer_pss=False, embed_roots=True, other_certs_to_pull=(), bulk_fetch=True, key_id: Optional[bytes] = None, cert_id: Optional[bytes] = None, use_raw_mechanism=False)

Bases: Signer

Signer implementation for PKCS11 devices.

  • pkcs11_session – The PKCS11 session object to use.

  • cert_label – The label of the certificate that will be used for signing, to be pulled from the PKCS#11 token.

  • cert_id – ID of the certificate object that will be used for signing, to be pulled from the PKCS#11 token.

  • signing_cert – The signer’s certificate. If the signer’s certificate is provided via this parameter, the cert_label and cert_id parameters will not be used to retrieve the signer’s certificate.

  • ca_chain – Set of other relevant certificates (as asn1crypto.x509.Certificate objects).

  • key_label

    The label of the key that will be used for signing. Defaults to the value of cert_label if left unspecified and key_id is also unspecified.


    At least one of key_id, key_label and cert_label must be supplied.

  • key_id – ID of the private key object (optional).

  • other_certs_to_pull – List labels of other certificates to pull from the PKCS#11 device. Defaults to the empty tuple. If None, pull all certificates.

  • bulk_fetch – Boolean indicating the fetching strategy. If True, fetch all certs and filter the unneeded ones. If False, fetch the requested certs one by one. Default value is True, unless other_certs_to_pull has one or fewer elements, in which case it is always treated as False.

  • use_raw_mechanism

    Use the ‘raw’ equivalent of the selected signature mechanism. This is useful when working with tokens that do not support a hash-then-sign mode of operation.


    This functionality is only available for ECDSA at this time. Support for other signature schemes will be added on an as-needed basis.

property cert_registry
property signing_cert
async async_sign_raw(data: bytes, digest_algorithm: str, dry_run=False) bytes

Compute the raw cryptographic signature of the data provided, hashed using the digest algorithm provided.

  • data – Data to sign.

  • digest_algorithm

    Digest algorithm to use.


    If signature_mechanism also specifies a digest, they should match.

  • dry_run – Do not actually create a signature, but merely output placeholder bytes that would suffice to contain an actual signature.


Signature bytes.

async ensure_objects_loaded()

Async method that, when awaited, ensures that objects (relevant certificates, key handles, …) are loaded.

This coroutine is guaranteed to be called & awaited in sign_raw(), but some property implementations may cause object loading to be triggered synchronously (for backwards compatibility reasons). This blocks the event loop the first time it happens.

To avoid this behaviour, asynchronous code should ideally perform await signer.ensure_objects_loaded() after instantiating the signer.


The asynchronous context manager on PKCS11SigningContext takes care of that automatically.

pyhanko.sign.pkcs11.open_pkcs11_session(lib_location: str, slot_no: Optional[int] = None, token_label: Optional[str] = None, token_criteria: Optional[TokenCriteria] = None, user_pin: Optional[Union[str, object]] = None) Session

Open a PKCS#11 session

  • lib_location – Path to the PKCS#11 module.

  • slot_no – Slot number to use. If not specified, the first slot containing a token labelled token_label will be used.

  • token_label

    Deprecated since version 0.14.0: Use token_criteria instead.

    Label of the token to use. If None, there is no constraint.

  • token_criteria – Criteria that the token should match.

  • user_pin

    User PIN to use, or PROTECTED_AUTH. If None, authentication is skipped.


    Some PKCS#11 implementations do not require PIN when the token is opened, but will prompt for it out-of-band when signing. Whether PROTECTED_AUTH or None is used in this case depends on the implementation.


An open PKCS#11 session object.

class pyhanko.sign.pkcs11.PKCS11SigningContext(config: PKCS11SignatureConfig, user_pin: Optional[str] = None)

Bases: object

Context manager for PKCS#11 configurations.

pyhanko.sign.pkcs11.find_token(slots: List[Slot], slot_no: Optional[int] = None, token_criteria: Optional[TokenCriteria] = None) Optional[Token]

Internal helper method to find a token.

  • slots – The list of slots.

  • slot_no – Slot number to use. If not specified, the first slot containing a token satisfying the criteria will be used

  • token_criteria – Criteria the token must satisfy.


A PKCS#11 token object, or None if none was found.

pyhanko.sign.pkcs11.select_pkcs11_signing_params(signature_mechanism: SignedDigestAlgorithm, digest_algorithm: str, use_raw_mechanism: bool) PKCS11SignatureOperationSpec

Internal helper function to set up a PKCS #11 signing operation.

  • signature_mechanism – The signature mechanism to use (as an ASN.1 value)

  • digest_algorithm – The digest algorithm to use

  • use_raw_mechanism – Whether to attempt to use the raw mechanism on pre-hashed data.