Standard Security Handler

The standard security handler is the password-based encryption method used by PDFs.

In pdfnaut, the standard security handler relies on user-supplied providers known as crypt providers. The crypt providers available are AES-128 (in CBC mode) and ARC4. A third provider, the Identity provider, is implemented by default and does nothing.

pdfnaut does not include implementations for these providers. You must provide them yourself either manually or by installing one of the following packages:

• pyca/cryptography

• PyCryptodome

When selecting a crypt provider, pdfnaut first checks for the presence of cryptography falling back on PyCryptodome if the former isn’t available. If neither is available, no encryption functionalities will be provided.

To add your own crypt providers, modify one of the values in the CRYPT_PROVIDERS dictionary of pdfnaut.security.providers. The keys available are ARC4, AESV2, and Identity. Identity is already implemented.

pdfnaut.security.providers.load_providers() → dict[str, type[CryptProvider] | None]

class pdfnaut.security.standard_handler.StandardSecurityHandler

Bases: object

An implementation of ISO 32000-2:2020 § 7.6.4 “Standard security handler”.

The standard security handler includes access permissions and allows up to 2 passwords: the owner password, which has all permissions, and the user password, which should only have the permissions specified by the document.

Parameters:

• encryption (PdfDictionary) – The standard encryption dictionary specified in the document’s trailer (see ISO 32000-2:2020 § 7.6.4 “Standard encryption dictionary” for details).

• ids (PdfArray[PdfHexString | bytes]) – The ID array specified in the document’s trailer.

__init__(encryption: PdfDictionary, ids: list[PdfHexString | bytes]) → None

Parameters:

• encryption (PdfDictionary) – The standard encryption dictionary specified in the document’s trailer (see ISO 32000-2:2020 § 7.6.4 “Standard encryption dictionary” for details).

• ids (PdfArray[PdfHexString | bytes]) – The ID array specified in the document’s trailer.

authenticate_owner_password(password: bytes) → tuple[bytes, bool]

Authenticates the provided owner password (or user password if none) according to ISO 32000-2:2020 § 7.6.4.4.6 “Algorithm 7: Authenticating the owner password (Security handlers of revision 4 and earlier)”.

Returns a tuple of two values: the encryption key that should decrypt the document and whether authentication was successful.

authenticate_user_password(password: bytes) → tuple[bytes, bool]

Authenticates the provided user password according to ISO 32000-2:2020 § 7.6.4.4.5 “Algorithm 6: Authenticating the user password (Security handlers of revision 4 and earlier)”.

Returns a tuple of two values: the encryption key that should decrypt the document and whether authentication was successful.

compute_encryption_key(password: bytes) → bytes

Computes an encryption key from password according to ISO 32000-2:2020 § 7.6.4.3.2 “Algorithm 2: Computing a file encryption key in order to encrypt a document (revision 4 and earlier)”.

compute_object_crypt(encryption_key: bytes, contents: PdfStream | PdfHexString | bytes, reference: PdfReference, *, crypt_filter: PdfDictionary | None = None) → tuple[Literal['Identity', 'ARC4', 'AESV2'], bytes, bytes]

Computes all parameters needed to encrypt or decrypt contents according to ISO 32000-2:2020 § 7.6.3.2, “Algorithm 1: Encryption of data using the RC4 and AES algorithms”.

This algorithm is only applicable for Encrypt versions 1 through 4 (deprecated in PDF 2.0). Version 5 uses a simpler algorithm described in ISO 32000-2:2020 § 7.6.3.2.

Parameters:

• encryption_key (bytes) – An encryption key generated by the algorithm implemented in compute_encryption_key().

• contents (PdfStream | PdfHexString | bytes) – The contents to encrypt/decrypt. The type of object will determine what crypt filter will be used for decryption (StmF for streams, StrF for hex and literal strings).

• reference (PdfReference) – The reference of either the object itself (in the case of a stream) or the object containing it (in the case of a string).

• crypt_filter (PdfDictionary, optional, keyword only) – The specific crypt filter to be referenced when decrypting the document. If not specified, the default for this type of contents will be used.

Returns a tuple of 3 values specifying, in order, the crypt method to apply (AES-CBC or ARC4), the key to use with this method, and the data to encrypt or decrypt.

compute_owner_password(owner_password: bytes, user_password: bytes) → bytes

Computes the O (owner_password) value in the Encrypt dictionary according to ISO 32000-2:2020 § 7.6.4.4.2 “Algorithm 3: Computing the encryption dictionary’s O-entry value (revision 4 and earlier)”.

As a fallback in case there is no owner password, a user_password must also be specified.

compute_user_password(password: bytes) → bytes

Computes the U (user password) value in the Encrypt dictionary according to the algorithms for revision 2 (Algorithm 4 in ISO 32000-2:2020 § 7.6.4.4.3) and revisions 3 and 4 (Algorithm 5 in ISO 32000-2:2020 § 7.6.4.4.4).

decrypt_object(encryption_key: bytes, contents: PdfStream | PdfHexString | bytes, reference: PdfReference, *, crypt_filter: PdfDictionary | None = None) → bytes

Decrypts the specified contents according to ISO 32000-2:2020 § 7.6.3.2.

For details on parameters, see compute_object_crypt().

encrypt_object(encryption_key: bytes, contents: PdfStream | PdfHexString | bytes, reference: PdfReference, *, crypt_filter: PdfDictionary | None = None) → bytes

Encrypts the specified contents according to ISO 32000-2:2020 § 7.6.3.2.

For details on parameters, see compute_object_crypt().

property key_length: int

The length of the encryption key in bytes.

pdfnaut.security.standard_handler.pad_password(password: bytes) → bytes

Pads or truncates the input password to exactly 32 bytes.

• If password is longer than 32 bytes, it shall be truncated.

• If password is shorter than 32 bytes, it shall be padded by appending data from PASSWORD_PADDING as needed.