Implement SASLprep (RFC 4013) for AES-256 password normalization

[adityamoolya]

pypdf fails to decrypt AES-256 encrypted PDFs when the password contains unicode
characters, even if the password is correct.

There is a TODO in pypdf/_encryption.py at line 1009 inside verify_v5:

-TODO: use SASLprep process

The PDF specification for AES-256 (Revision 5/6) requires passwords to be normalized
using SASLprep (RFC 4013) before UTF-8 encoding. Currently _encode_password tries
latin-1 first then falls back to utf-8 without any SASLprep normalization, so the
byte representation does not match what a spec-compliant PDF creator produced.

I tried to reproduce this and confirmed it fails. i've attached the script i used :

Environment

Which environment were you using when you encountered the problem?

$ python -m platform
Linux-6.19.14-200.fc43.x86_64-x86_64-with-glibc2.42

$ python -c "import pypdf;print(pypdf._debug_versions)"
pypdf==6.11.0, crypt_provider=('cryptography', '47.0.0'), PIL=12.2.0

Code + PDF

This is a minimal, complete example that shows the issue:

import pikepdf
from pypdf import PdfReader, PasswordType

pdf = pikepdf.Pdf.new()
pdf.save("sample.pdf")

with pikepdf.open("sample.pdf") as pdf:
    pdf.save(
        "encrypted_unicode.pdf",
        encryption=pikepdf.Encryption(
            owner="owner",
            user="pässwört",
            R=6
        )
    )

reader = PdfReader("encrypted_unicode.pdf")
result = reader.decrypt("pässwört")
print(result)
# Output:  0 (PasswordType.NOT_DECRYPTED) , produced this with current script
# Expected: 1 (PasswordType.USER_PASSWORD) , produced this result when user="password"

Possible Fix

The fix would likely go in _encode_password , normalize the password using
SASLprep before UTF-8 encoding, but only for AES-256 encryption revisions
(R=5/6).

Python's standard library exposes stringprep tables but does not provide a
complete RFC 4013 SASLprep implementation.

Before working on it, I wanted to ask which direction would be preferred:

• adding a lightweight dependency such as saslprep
• or implementing a minimal RFC 4013-compatible normalization layer maybe using
  unicodedata + stringprep to keep pypdf dependency-free

[stefan6419846]

Thanks for opening this issue. I am open to merging a corresponding PR.

Regarding your questions: PyPI does not seem to have a package named saslprep. If there is a freely licensed, actively maintained and lightweight library available which already does this, making it an optional dependency and using it sounds like the best idea. (Maybe cryptography and pycryptodome already provide this?) Having to maintain a custom implementation and shipping yet another set of Unicode data files should be avoided.

[adityamoolya]

I just checked, neither cryptography nor pycryptodome provide SASLprep, and there's no actively maintained standalone package on PyPI for it either as you said. Python's stdlib already ships everything we need. The stringprep (https://docs.python.org/3/library/stringprep.html) module contains all the RFC 3454 lookup tables and unicodedata (https://docs.python.org/3/library/unicodedata.html) provides NFKC normalization. So there are no new dependencies and no shipped Unicode data files, just a function that wires the existing stdlib tables together per the RFC 4013 algorithm.

The plan is to add a module level _saslprep() function implementing the four RFC 4013 steps using only stdlib, and modify _encode_password to apply SASLprep only for V>=5 (AES-256, R5/R6) and only for str inputs. The existing V<=4 Latin-1 path stays untouched.

One thing I wanted to flag before writing the PR: should SASLprep errors in _encode_password be swallowed silently to handle real-world PDFs encrypted without proper normalization, or should they propagate strictly?

[stefan6419846]

Thanks for the explanation.

should SASLprep errors in _encode_password be swallowed silently to handle real-world PDFs encrypted without proper normalization, or should they propagate strictly?

If we are able to properly detect these cases, we should follow what I started with decrypt_object and introduce a keyword-only strict parameter, originally derived from the strict value of the reader/writer. This means, raise an error in strict mode and issue a warning in non-strict mode.

[adityamoolya]

Understood, will follow the same strict pattern. Will start to work on a PR.