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: pkcs11.types.Session, cert_label: Optional[str] = None, signing_cert: Optional[asn1crypto.x509.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:
pyhanko.sign.signers.pdf_cms.Signer
Signer implementation for PKCS11 devices.
- Parameters
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
andcert_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 andkey_id
is also unspecified.Note
At least one of
key_id
,key_label
andcert_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. IfFalse
, fetch the requested certs one by one. Default value isTrue
, unlessother_certs_to_pull
has one or fewer elements, in which case it is always treated asFalse
.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.
Note
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.
- Parameters
data – Data to sign.
digest_algorithm –
Digest algorithm to use.
Warning
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.
- Returns
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.
Note
The asynchronous context manager on
PKCS11SigningContext
takes care of that automatically.
- pyhanko.sign.pkcs11.open_pkcs11_session(lib_location, slot_no=None, token_label=None, user_pin=None) pkcs11.types.Session
Open a PKCS#11 session
- Parameters
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 – Label of the token to use. If
None
, there is no constraint.user_pin –
User PIN to use.
Note
Some PKCS#11 implementations do not require PIN when the token is opened, but will prompt for it out-of-band when signing.
- Returns
An open PKCS#11 session object.
- class pyhanko.sign.pkcs11.PKCS11SigningContext(config: pyhanko.config.PKCS11SignatureConfig, user_pin: Optional[str] = None)
Bases:
object
Context manager for PKCS#11 configurations.