pyhanko.pdf_utils.crypt module¶
Changed in version 0.3.0: Added support for PDF 2.0 encryption standards and crypt filters.
Utilities for PDF encryption. This module covers all methods outlined in the standard:
Legacy RC4-based encryption (based on PyPDF2 code).
AES-128 encryption with legacy key derivation (partly based on PyPDF2 code).
PDF 2.0 AES-256 encryption.
Public key encryption backed by any of the above.
Following the language in the standard, encryption operations are backed by
subclasses of the SecurityHandler
class, which provides a more or less
generic API.
Danger
The members of this module are all considered internal API, and are therefore subject to change without notice.
Danger
One should also be aware that the legacy encryption scheme implemented here is (very) weak, and we only support it for compatibility reasons. Under no circumstances should it still be used to encrypt new files.
About crypt filters¶
Crypt filters are objects that handle encryption and decryption of streams and
strings, either for all of them, or for a specific subset (e.g. streams
representing embedded files). In the context of the PDF standard, crypt filters
are a notion that only makes sense for security handlers of version 4 and up.
In pyHanko, however, all encryption and decryption operations pass through
crypt filters, and the serialisation/deserialisation logic in
SecurityHandler
and its subclasses transparently deals with staying
backwards compatible with earlier revisions.
Internally, pyHanko loosely distinguishes between implicit and explicit uses of crypt filters:
Explicit crypt filters are used by directly referring to them from the
/Filter
entry of a stream dictionary. These are invoked in the usual stream decoding process.Implicit crypt filters are set by the
/StmF
and/StrF
entries in the security handler’s crypt filter configuration, and are invoked by the object reading/writing procedures as necessary. These filters are invisble to the stream encoding/decoding process: theencoded_data
attribute of an “implicitly encrypted” stream will therefore contain decrypted data ready to be decoded in the usual way.
As long as you don’t require access to encoded object data and/or raw encrypted object data, this distiction should be irrelevant to you as an API user.
-
class
pyhanko.pdf_utils.crypt.
SecurityHandler
(version: pyhanko.pdf_utils.crypt.SecurityHandlerVersion, legacy_keylen, crypt_filter_config: pyhanko.pdf_utils.crypt.CryptFilterConfiguration, encrypt_metadata=True)¶ Bases:
object
Generic PDF security handler interface.
This class contains relatively little actual functionality, except for some common initialisation logic and bookkeeping machinery to register security handler implementations.
- Parameters
version – Indicates the version of the security handler to use, as described in the specification. See
SecurityHandlerVersion
.legacy_keylen – Key length in bytes (only relevant for legacy encryption handlers).
crypt_filter_config –
The crypt filter configuration for the security handler, in the form of a
CryptFilterConfiguration
object.Note
PyHanko implements legacy security handlers (which, according to the standard, aren’t crypt filter-aware) using crypt filters as well, even though they aren’t serialised to the output file.
encrypt_metadata –
Flag indicating whether document (XMP) metadata is to be encrypted.
Warning
Currently, PyHanko does not manage metadata streams, so until that changes, it is the responsibility of the API user to mark metadata streams using the /Identity crypt filter as required.
Nonetheless, the value of this flag is required in key derivation computations, so the security handler needs to know about it.
-
static
register
(cls: Type[pyhanko.pdf_utils.crypt.SecurityHandler])¶ Register a security handler class. Intended to be used as a decorator on subclasses.
See
build()
for further information.- Parameters
cls – A subclass of
SecurityHandler
.
-
static
build
(encrypt_dict: pyhanko.pdf_utils.generic.DictionaryObject) → pyhanko.pdf_utils.crypt.SecurityHandler¶ Instantiate an appropriate
SecurityHandler
from a PDF document’s encryption dictionary.PyHanko will search the registry for a security handler with a name matching the
/Filter
entry. Failing that, a security handler implementing the protocol designated by the/SubFilter
entry (seesupport_generic_subfilters()
) will be chosen.Once an appropriate
SecurityHandler
subclass has been selected, pyHanko will invoke the subclass’sinstantiate_from_pdf_object()
method with the original encryption dictionary as its argument.- Parameters
encrypt_dict – A PDF encryption dictionary.
- Returns
-
classmethod
get_name
() → str¶ Retrieves the name of this security handler.
- Returns
The name of this security handler.
-
classmethod
support_generic_subfilters
() → Set[str]¶ Indicates the generic
/SubFilter
values that this security handler supports.- Returns
A set of generic protocols (indicated in the
/SubFilter
entry of an encryption dictionary) that thisSecurityHandler
class implements. Defaults to the empty set.
-
classmethod
instantiate_from_pdf_object
(encrypt_dict: pyhanko.pdf_utils.generic.DictionaryObject)¶ Instantiate an object of this class using a PDF encryption dictionary as input.
- Parameters
encrypt_dict – A PDF encryption dictionary.
- Returns
-
as_pdf_object
() → pyhanko.pdf_utils.generic.DictionaryObject¶ Serialise this security handler to a PDF encryption dictionary.
- Returns
A PDF encryption dictionary.
-
authenticate
(credential, id1=None) → pyhanko.pdf_utils.crypt.AuthResult¶ Authenticate a credential holder with this security handler.
- Parameters
credential – A credential. The type of the credential is left up to the subclasses.
id1 – The first part of the document ID of the document being accessed.
- Returns
An
AuthResult
object indicating the level of access obtained.
-
get_string_filter
() → pyhanko.pdf_utils.crypt.CryptFilter¶ - Returns
The crypt filter responsible for decrypting strings for this security handler.
-
get_stream_filter
(name=None) → pyhanko.pdf_utils.crypt.CryptFilter¶ - Parameters
name – Optionally specify a crypt filter by name.
- Returns
The default crypt filter responsible for decrypting streams for this security handler, or the crypt filter named
name
, if notNone
.
-
get_file_encryption_key
() → bytes¶
-
class
pyhanko.pdf_utils.crypt.
StandardSecurityHandler
(version: pyhanko.pdf_utils.crypt.SecurityHandlerVersion, revision: pyhanko.pdf_utils.crypt.StandardSecuritySettingsRevision, legacy_keylen, perm_flags: int, odata, udata, oeseed=None, ueseed=None, encrypted_perms=None, encrypt_metadata=True, crypt_filter_config: Optional[pyhanko.pdf_utils.crypt.CryptFilterConfiguration] = None)¶ Bases:
pyhanko.pdf_utils.crypt.SecurityHandler
Implementation of the standard (password-based) security handler.
You shouldn’t have to instantiate
StandardSecurityHandler
objects yourself. For encrypting new documents, usebuild_from_pw()
orbuild_from_pw_legacy()
.For decrypting existing documents, pyHanko will take care of instantiating security handlers through
SecurityHandler.build()
.-
classmethod
get_name
() → str¶ Retrieves the name of this security handler.
- Returns
The name of this security handler.
-
classmethod
build_from_pw_legacy
(rev: pyhanko.pdf_utils.crypt.StandardSecuritySettingsRevision, id1, desired_owner_pass, desired_user_pass=None, keylen_bytes=16, use_aes128=True, perms: int = - 4, crypt_filter_config=None)¶ Initialise a legacy password-based security handler, to attach to a
PdfFileWriter
.Danger
The functionality implemented by this handler is deprecated in the PDF standard. We only provide it for testing purposes, and to interface with legacy systems.
- Parameters
rev – Security handler revision to use, see
StandardSecuritySettingsRevision
.id1 – The first part of the document ID.
desired_owner_pass – Desired owner password.
desired_user_pass – Desired user password.
keylen_bytes – Length of the key (in bytes).
use_aes128 – Use AES-128 instead of RC4 (default:
True
).perms – Permission bits to set (defined as an integer)
crypt_filter_config – Custom crypt filter configuration. PyHanko will supply a reasonable default if none is specified.
- Returns
A
StandardSecurityHandler
instance.
-
classmethod
build_from_pw
(desired_owner_pass, desired_user_pass=None, perms=- 4)¶ Initialise a password-based security handler backed by AES-256, to attach to a
PdfFileWriter
. This handler will use the new PDF 2.0 encryption scheme.- Parameters
desired_owner_pass – Desired owner password.
desired_user_pass – Desired user password.
perms – Desired usage permissions.
- Returns
A
StandardSecurityHandler
instance.
-
static
read_standard_cf_dictionary
(cfdict)¶ Interpret a crypt filter dictionary for the standard security handler.
- Parameters
cfdict – A crypt filter dictionary.
- Returns
An appropriate
CryptFilter
object, orNone
if the crypt filter uses the/None
method.- Raises
NotImplementedError – Raised when the crypt filter’s
/CFM
entry indicates an unknown crypt filter method.
-
classmethod
instantiate_from_pdf_object
(encrypt_dict: pyhanko.pdf_utils.generic.DictionaryObject)¶ Instantiate an object of this class using a PDF encryption dictionary as input.
- Parameters
encrypt_dict – A PDF encryption dictionary.
- Returns
-
as_pdf_object
()¶ Serialise this security handler to a PDF encryption dictionary.
- Returns
A PDF encryption dictionary.
-
authenticate
(credential, id1: Optional[bytes] = None) → pyhanko.pdf_utils.crypt.AuthResult¶ Authenticate a user to this security handler.
- Parameters
credential – The credential to use (a password in this case).
id1 – First part of the document ID. This is mandatory for legacy encryption handlers, but meaningless otherwise.
- Returns
An
AuthResult
object indicating the level of access obtained.
-
get_file_encryption_key
() → bytes¶ Retrieve the (global) file encryption key for this security handler.
- Returns
The file encryption key as a
bytes
object.- Raises
misc.PdfReadError – Raised if this security handler was instantiated from an encryption dictionary and no credential is available.
-
classmethod
-
class
pyhanko.pdf_utils.crypt.
PubKeySecurityHandler
(version: pyhanko.pdf_utils.crypt.SecurityHandlerVersion, pubkey_handler_subfilter: pyhanko.pdf_utils.crypt.PubKeyAdbeSubFilter, legacy_keylen, encrypt_metadata=True, crypt_filter_config: Optional[pyhanko.pdf_utils.crypt.CryptFilterConfiguration] = None, recipient_objs: Optional[list] = None)¶ Bases:
pyhanko.pdf_utils.crypt.SecurityHandler
Security handler for public key encryption in PDF.
As with the standard security handler, you essentially shouldn’t ever have to instantiate these yourself (see
build_from_certs()
).-
static
build_from_certs
(certs: List[asn1crypto.x509.Certificate], keylen_bytes=16, version=<SecurityHandlerVersion.AES256: 5>, use_aes=True, use_crypt_filters=True, perms: int = -4, encrypt_metadata=True, ignore_key_usage=False) → pyhanko.pdf_utils.crypt.PubKeySecurityHandler¶ Create a new public key security handler.
This method takes many parameters, but only
certs
is mandatory. The default behaviour is to create a public key encryption handler where the underlying symmetric encryption is provided by AES-256.- Parameters
certs – The recipients’ certificates.
keylen_bytes – The key length (in bytes). This is only relevant for legacy security handlers.
version – The security handler version to use.
use_aes – Use AES-128 instead of RC4 (only meaningful if the
version
parameter isRC4_OR_AES128
).use_crypt_filters – Whether to use crypt filters. This is mandatory for security handlers of version
RC4_OR_AES128
or higher.perms – Permission flags (as a 4-byte signed integer).
encrypt_metadata –
Whether to encrypt document metadata.
Warning
See
SecurityHandlers
for some background on the way pyHanko interprets this value.ignore_key_usage – If
False
, the keyEncipherment key usage extension is required.
- Returns
An instance of
PubKeySecurityHandler
.
-
classmethod
get_name
() → str¶ Retrieves the name of this security handler.
- Returns
The name of this security handler.
-
classmethod
support_generic_subfilters
() → Set[str]¶ Indicates the generic
/SubFilter
values that this security handler supports.- Returns
A set of generic protocols (indicated in the
/SubFilter
entry of an encryption dictionary) that thisSecurityHandler
class implements. Defaults to the empty set.
-
classmethod
instantiate_from_pdf_object
(encrypt_dict: pyhanko.pdf_utils.generic.DictionaryObject)¶ Instantiate an object of this class using a PDF encryption dictionary as input.
- Parameters
encrypt_dict – A PDF encryption dictionary.
- Returns
-
as_pdf_object
()¶ Serialise this security handler to a PDF encryption dictionary.
- Returns
A PDF encryption dictionary.
-
add_recipients
(certs: List[asn1crypto.x509.Certificate], perms=- 4, ignore_key_usage=False)¶
-
authenticate
(credential: pyhanko.pdf_utils.crypt.EnvelopeKeyDecrypter, id1=None) → pyhanko.pdf_utils.crypt.AuthResult¶ Authenticate a user to this security handler.
- Parameters
credential – The credential to use (an instance of
EnvelopeKeyDecrypter
in this case).id1 – First part of the document ID. Public key encryption handlers ignore this key.
- Returns
An
AuthResult
object indicating the level of access obtained.
-
static
read_pubkey_cf_dictionary
(cfdict, acts_as_default)¶ Read a crypt filter dictionary for a public key security handler.
- Parameters
cfdict – A crypt filter dictionary.
acts_as_default – Indicates whether this filter is intended to be used in
/StrF
or/StmF
.
- Returns
A
CryptFilter
object.
-
get_file_encryption_key
() → bytes¶
-
static
-
class
pyhanko.pdf_utils.crypt.
SecurityHandlerVersion
(value)¶ Bases:
pyhanko.pdf_utils.misc.OrderedEnum
Indicates the security handler’s version.
The enum constants are named more or less in accordance with the cryptographic algorithms they permit.
-
RC4_40
= 1¶
-
RC4_LONGER_KEYS
= 2¶
-
RC4_OR_AES128
= 4¶
-
AES256
= 5¶
-
OTHER
= None¶ Placeholder value for custom security handlers.
-
-
class
pyhanko.pdf_utils.crypt.
StandardSecuritySettingsRevision
(value)¶ Bases:
pyhanko.pdf_utils.misc.OrderedEnum
Indicate the standard security handler revision to emulate.
-
RC4_BASIC
= 2¶
-
RC4_EXTENDED
= 3¶
-
RC4_OR_AES128
= 4¶
-
AES256
= 6¶
-
-
class
pyhanko.pdf_utils.crypt.
PubKeyAdbeSubFilter
(value)¶ Bases:
enum.Enum
Enum describing the different subfilters that can be used for public key encryption in the PDF specification.
-
S3
= '/adbe.pkcs7.s3'¶
-
S4
= '/adbe.pkcs7.s4'¶
-
S5
= '/adbe.pkcs7.s5'¶
-
-
class
pyhanko.pdf_utils.crypt.
CryptFilterConfiguration
(crypt_filters: Optional[Dict[str, pyhanko.pdf_utils.crypt.CryptFilter]] = None, default_stream_filter='/Identity', default_string_filter='/Identity', default_file_filter=None)¶ Bases:
object
Crypt filter store attached to a security handler.
Instances of this class are not designed to be reusable.
- Parameters
crypt_filters – A dictionary mapping names to their corresponding crypt filters.
default_stream_filter – Name of the default crypt filter to use for streams.
default_stream_filter – Name of the default crypt filter to use for strings.
default_file_filter –
Name of the default crypt filter to use for embedded files.
Note
PyHanko currently is not aware of embedded files, so managing these is the API user’s responsibility.
-
filters
()¶ Enumerate all crypt filters in this configuration.
-
set_security_handler
(handler: pyhanko.pdf_utils.crypt.SecurityHandler)¶ Set the security handler on all crypt filters in this configuration.
- Parameters
handler – A
SecurityHandler
instance.
-
get_for_stream
()¶ Retrieve the default crypt filter to use with streams.
- Returns
A
CryptFilter
instance.
-
get_for_string
()¶ Retrieve the default crypt filter to use with strings.
- Returns
A
CryptFilter
instance.
-
get_for_embedded_file
()¶ Retrieve the default crypt filter to use with embedded files.
- Returns
A
CryptFilter
instance.
-
as_pdf_object
()¶ Serialise this crypt filter configuration to a dictionary object, including all its subordinate crypt filters (with the exception of the identity filter, if relevant).
-
default_filters
()¶ Return the “default” filters associated with this crypt filter configuration, i.e. those registered as the defaults for strings and streams, respectively.
These sometimes require special treatment (as per the specification).
- Returns
A set with one or two elements.
-
class
pyhanko.pdf_utils.crypt.
CryptFilter
¶ Bases:
object
Generic abstract crypt filter class.
The superclass only handles the binding with the security handler, and offers some default implementations for serialisation routines that may be overridden in subclasses.
There is generally no requirement for crypt filters to be compatible with any security handler (the leaf classes in this module aren’t), but the API supports mixin usage so code can be shared.
-
property
method
¶ - Returns
The method name (
/CFM
entry) associated with this crypt filter.
-
property
keylen
¶ - Returns
The keylength (in bytes) of the key associated with this crypt filter.
-
encrypt
(key, plaintext: bytes, params=None) → bytes¶ Encrypt plaintext with the specified key.
- Parameters
key – The current local key, which may or may not be equal to this crypt filter’s global key.
plaintext – Plaintext to encrypt.
params – Optional parameters private to the crypt filter, specified as a PDF dictionary. These can only be used for explicit crypt filters; the parameters are then sourced from the corresponding entry in
/DecodeParms
.
- Returns
The resulting ciphertext.
-
decrypt
(key, ciphertext: bytes, params=None) → bytes¶ Decrypt ciphertext with the specified key.
- Parameters
key – The current local key, which may or may not be equal to this crypt filter’s global key.
ciphertext – Ciphertext to decrypt.
params – Optional parameters private to the crypt filter, specified as a PDF dictionary. These can only be used for explicit crypt filters; the parameters are then sourced from the corresponding entry in
/DecodeParms
.
- Returns
The resulting plaintext.
-
as_pdf_object
() → pyhanko.pdf_utils.generic.DictionaryObject¶ Serialise this crypt filter to a PDF crypt filter dictionary.
Note
Implementations are encouraged to use a cooperative inheritance model, where subclasses first call
super().as_pdf_object()
and add the keys they need before returning the result.This makes it easy to write crypt filter mixins that can provide functionality to multiple handlers.
- Returns
A PDF crypt filter dictionary.
Compute the (global) file encryption key for this crypt filter.
- Returns
The key, as a
bytes
object.- Raises
misc.PdfError – Raised if the data needed to derive the key is not present (e.g. because the caller hasn’t authenticated yet).
-
derive_object_key
(idnum, generation) → bytes¶ Derive the encryption key for a specific object, based on the shared file encryption key.
- Parameters
idnum – ID of the object being encrypted.
generation – Generation number of the object being encrypted.
- Returns
The local key to use for this object.
Return the shared file encryption key for this crypt filter, or attempt to compute it using
derive_shared_encryption_key()
if not available.
-
property
-
class
pyhanko.pdf_utils.crypt.
StandardCryptFilter
¶ Bases:
pyhanko.pdf_utils.crypt.CryptFilter
,abc.ABC
Crypt filter for use with the standard security handler.
Compute the (global) file encryption key for this crypt filter.
- Returns
The key, as a
bytes
object.- Raises
misc.PdfError – Raised if the data needed to derive the key is not present (e.g. because the caller hasn’t authenticated yet).
-
as_pdf_object
()¶ Serialise this crypt filter to a PDF crypt filter dictionary.
Note
Implementations are encouraged to use a cooperative inheritance model, where subclasses first call
super().as_pdf_object()
and add the keys they need before returning the result.This makes it easy to write crypt filter mixins that can provide functionality to multiple handlers.
- Returns
A PDF crypt filter dictionary.
-
class
pyhanko.pdf_utils.crypt.
PubKeyCryptFilter
(*, recipients=None, acts_as_default=False, encrypt_metadata=True, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.CryptFilter
,abc.ABC
Crypt filter for use with public key security handler. These are a little more independent than their counterparts for the standard security handlers, since different crypt filters can cater to different sets of recipients.
- Parameters
recipients – List of CMS objects encoding recipient information for this crypt filters.
acts_as_default – Indicates whether this filter is intended to be used in
/StrF
or/StmF
.encrypt_metadata –
Whether this crypt filter should encrypt document-level metadata.
Warning
See
SecurityHandlers
for some background on the way pyHanko interprets this value.
-
add_recipients
(certs: List[asn1crypto.x509.Certificate], perms=- 4, ignore_key_usage=False)¶ Add recipients to this crypt filter. This always adds one full CMS object to the Recipients array
- Parameters
certs – A list of recipient certificates.
perms – The permission bits to assign to the listed recipients.
ignore_key_usage – If
False
, the keyEncipherment key usage extension is required.
-
authenticate
(credential) → pyhanko.pdf_utils.crypt.AuthResult¶ Authenticate to this crypt filter in particular. If used in
/StmF
or/StrF
, you don’t need to worry about calling this method directly.- Parameters
credential – The
EnvelopeKeyDecrypter
to authenticate with.- Returns
An
AuthResult
object indicating the level of access obtained.
Compute the (global) file encryption key for this crypt filter.
- Returns
The key, as a
bytes
object.- Raises
misc.PdfError – Raised if the data needed to derive the key is not present (e.g. because the caller hasn’t authenticated yet).
-
as_pdf_object
()¶ Serialise this crypt filter to a PDF crypt filter dictionary.
Note
Implementations are encouraged to use a cooperative inheritance model, where subclasses first call
super().as_pdf_object()
and add the keys they need before returning the result.This makes it easy to write crypt filter mixins that can provide functionality to multiple handlers.
- Returns
A PDF crypt filter dictionary.
-
class
pyhanko.pdf_utils.crypt.
IdentityCryptFilter
¶ Bases:
pyhanko.pdf_utils.crypt.CryptFilter
Class implementing the trivial crypt filter.
This is a singleton class, so all its instances are identical. Additionally, some of the
CryptFilter
API is nonfunctional. In particular,as_pdf_object()
always raises an error, since the/Identity
filter cannot be serialised.-
method
= '/None'¶
-
keylen
= 0¶
Always returns an empty byte string.
-
derive_object_key
(idnum, generation) → bytes¶ Always returns an empty byte string.
- Parameters
idnum – Ignored.
generation – Ignored.
- Returns
-
as_pdf_object
()¶ Not implemented for this crypt filter.
- Raises
misc.PdfError – Always.
-
encrypt
(key, plaintext: bytes, params=None) → bytes¶ Identity function.
- Parameters
key – Ignored.
plaintext – Returned as-is.
params – Ignored.
- Returns
The original plaintext.
-
decrypt
(key, ciphertext: bytes, params=None) → bytes¶ Identity function.
- Parameters
key – Ignored.
ciphertext – Returned as-is.
params – Ignored.
- Returns
The original ciphertext.
-
-
class
pyhanko.pdf_utils.crypt.
RC4CryptFilterMixin
(*, keylen=5, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.CryptFilter
,abc.ABC
Mixin for RC4-based crypt filters.
- Parameters
keylen – Key length, in bytes. Defaults to 5.
-
method
= '/V2'¶
-
keylen
= None¶
-
encrypt
(key, plaintext: bytes, params=None) → bytes¶ Encrypt data using RC4.
- Parameters
key – Local encryption key.
plaintext – Plaintext to encrypt.
params – Ignored.
- Returns
Ciphertext.
-
decrypt
(key, ciphertext: bytes, params=None) → bytes¶ Decrypt data using RC4.
- Parameters
key – Local encryption key.
ciphertext – Ciphertext to decrypt.
params – Ignored.
- Returns
Plaintext.
-
derive_object_key
(idnum, generation) → bytes¶ Derive the local key for the given object ID and generation number, by calling
legacy_derive_object_key()
.- Parameters
idnum – ID of the object being encrypted.
generation – Generation number of the object being encrypted.
- Returns
The local key.
-
class
pyhanko.pdf_utils.crypt.
AESCryptFilterMixin
(*, keylen, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.CryptFilter
,abc.ABC
Mixin for AES-based crypt filters.
-
keylen
= None¶
-
method
= None¶
-
encrypt
(key, plaintext: bytes, params=None)¶ Encrypt data using AES in CBC mode, with PKCS#7 padding.
- Parameters
key – The key to use.
plaintext – The plaintext to be encrypted.
params – Ignored.
- Returns
The resulting ciphertext, prepended with a 16-byte initialisation vector.
-
decrypt
(key, ciphertext: bytes, params=None) → bytes¶ Decrypt data using AES in CBC mode, with PKCS#7 padding.
- Parameters
key – The key to use.
ciphertext – The ciphertext to be decrypted, prepended with a 16-byte initialisation vector.
params – Ignored.
- Returns
The resulting plaintext.
-
derive_object_key
(idnum, generation) → bytes¶ Derive the local key for the given object ID and generation number.
If the associated handler is of version
SecurityHandlerVersion.AES256
or greater, this method simply returns the global key as-is. If not, the computation is carried out bylegacy_derive_object_key()
.- Parameters
idnum – ID of the object being encrypted.
generation – Generation number of the object being encrypted.
- Returns
The local key.
-
-
class
pyhanko.pdf_utils.crypt.
StandardAESCryptFilter
(*, keylen, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.StandardCryptFilter
,pyhanko.pdf_utils.crypt.AESCryptFilterMixin
AES crypt filter for the standard security handler.
-
class
pyhanko.pdf_utils.crypt.
StandardRC4CryptFilter
(*, keylen=5, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.StandardCryptFilter
,pyhanko.pdf_utils.crypt.RC4CryptFilterMixin
RC4 crypt filter for the standard security handler.
-
class
pyhanko.pdf_utils.crypt.
PubKeyAESCryptFilter
(*, recipients=None, acts_as_default=False, encrypt_metadata=True, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.PubKeyCryptFilter
,pyhanko.pdf_utils.crypt.AESCryptFilterMixin
AES crypt filter for public key security handlers.
-
class
pyhanko.pdf_utils.crypt.
PubKeyRC4CryptFilter
(*, recipients=None, acts_as_default=False, encrypt_metadata=True, **kwargs)¶ Bases:
pyhanko.pdf_utils.crypt.PubKeyCryptFilter
,pyhanko.pdf_utils.crypt.RC4CryptFilterMixin
RC4 crypt filter for public key security handlers.
-
class
pyhanko.pdf_utils.crypt.
EnvelopeKeyDecrypter
(cert: asn1crypto.x509.Certificate)¶ Bases:
object
General credential class for use with public key security handlers.
This allows the key decryption process to happen offline, e.g. on a smart card.
- Parameters
cert – The recipient’s certificate.
-
decrypt
(encrypted_key: bytes, algo_params: asn1crypto.cms.KeyEncryptionAlgorithm) → bytes¶ Invoke the actual key decryption algorithm.
- Parameters
encrypted_key – Payload to decrypt.
algo_params – Specification of the encryption algorithm as a CMS object.
- Returns
The decrypted payload.
-
class
pyhanko.pdf_utils.crypt.
SimpleEnvelopeKeyDecrypter
(cert: asn1crypto.x509.Certificate, private_key: asn1crypto.keys.PrivateKeyInfo)¶ Bases:
pyhanko.pdf_utils.crypt.EnvelopeKeyDecrypter
Implementation of
EnvelopeKeyDecrypter
where the private key is an RSA key residing in memory.- Parameters
cert – The recipient’s certificate.
private_key – The recipient’s private key.
-
static
load
(key_file, cert_file, key_passphrase=None)¶ Load a key decrypter using key material from files on disk.
- Parameters
key_file – File containing the recipient’s private key.
cert_file – File containing the recipient’s certificate.
key_passphrase – Passphrase for the key file, if applicable.
- Returns
An instance of
SimpleEnvelopeKeyDecrypter
.
-
classmethod
load_pkcs12
(pfx_file, passphrase=None)¶ Load a key decrypter using key material from a PKCS#12 file on disk.
- Parameters
pfx_file – Path to the PKCS#12 file containing the key material.
passphrase – Passphrase for the private key, if applicable.
- Returns
An instance of
SimpleEnvelopeKeyDecrypter
.
-
decrypt
(encrypted_key: bytes, algo_params: asn1crypto.cms.KeyEncryptionAlgorithm) → bytes¶ Decrypt the payload using RSA with PKCS#1 v1.5 padding. Other schemes are not (currently) supported by this implementation.
- Parameters
encrypted_key – Payload to decrypt.
algo_params – Specification of the encryption algorithm as a CMS object. Must use
rsaes_pkcs1v15
.
- Returns
The decrypted payload.
-
pyhanko.pdf_utils.crypt.
STD_CF
= '/StdCF'¶ Default name to use for the default crypt filter in the standard security handler.
-
pyhanko.pdf_utils.crypt.
DEFAULT_CRYPT_FILTER
= '/DefaultCryptFilter'¶ Default name to use for the default crypt filter in public key security handlers.
-
pyhanko.pdf_utils.crypt.
IDENTITY
= '/Identity'¶ Name of the identity crypt filter.
-
pyhanko.pdf_utils.crypt.
legacy_derive_object_key
(shared_key: bytes, idnum: int, generation: int, use_aes=False) → bytes¶ Function that does the key derivation for PDF’s legacy security handlers.
- Parameters
shared_key – Global file encryption key.
idnum – ID of the object being written.
generation – Generation number of the object being written.
use_aes – Boolean indicating whether the security handler uses RC4 or AES(-128).
- Returns