Enhance passphrase handling (Fixes #8496)

[alighazi288]

Description

This pull request improves the handling of passphrases and adds comprehensive debug information. The main changes include:

• Displaying hex bytes for passphrases in all cases, including ASCII and non-ASCII characters.
• Adding an option to display the hex bytes when the password is used and found incorrect.
• Showing which environment variables were used during passphrase operations.
• Preventing sensitive passphrase information from being logged unintentionally by directing it to sys.stderr.
• Adding tests to verify:
  • Handling of incorrect passphrases.
  • Passphrase verification logic.
  • Debug information display for passphrases.

[codecov]

Codecov Report

Attention: Patch coverage is 73.33333% with 4 lines in your changes missing coverage. Please review.

Project coverage is 81.79%. Comparing base (1559a1e) to head (d09d2d8).
Report is 9 commits behind head on master.

Files with missing lines	Patch %	Lines
src/borg/crypto/key.py	0.00%	2 Missing ⚠️
src/borg/helpers/passphrase.py	84.61%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #8605      +/-   ##
==========================================
- Coverage   81.83%   81.79%   -0.05%     
==========================================
  Files          74       74              
  Lines       13319    13333      +14     
  Branches     1963     1966       +3     
==========================================
+ Hits        10900    10906       +6     
- Misses       1755     1761       +6     
- Partials      664      666       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ThomasWaldmann]

Thanks for the PR! Some feedback.

[alighazi288]

Thank you so much for the feedback! Will try to fix all this by tomorrow!

[ThomasWaldmann]

some feedback.

beside addressing the feedback and writing a unit test, i also recommend that you practically try this code for some scenarios.

E.g.:

Use borg repo-create -e repokey ... - this will ask you to define a passphrase. Answer y or answer n when it asks to display the passphrase.

Use borg repo-list ... to access the repo. It will ask for a passphrase and under normal circumstances, it MUST NOT display what you entered. But there should be a way for optional "passphrase debugging" and it displaying the passphrase and its hex encoding.

Do the same, but use an env var with a correct and with a incorrect passphrase.

[alighazi288]

This is exactly how I've been testing. I was just uncertain whether the requirement was to always show debug information when a wrong passphrase is entered, or if it should be shown "optionally" based on the user's input. I chose to conditionally display it based on the new environment variable BORG_DEBUG_PASSPHRASE.

Now, debugging information (including passphrase and environment variable details) is only shown when the BORG_DEBUG_PASSPHRASE environment variable is set to "YES".

I hope this matches the intended behavior. Looking forward to your thoughts!

[ThomasWaldmann]

good to require that env var, so the stuff isn't printed by default.

[ThomasWaldmann]

consistency / simplification suggestions.

[ThomasWaldmann]

The docs CI failure seems unrelated to your PR changes.

Maybe some stuff in sphinx changed, so it is triggering new warnings.

Guess I need to change so that code unit tests do not depend on docs test.

[alighazi288]

@ThomasWaldmann if this is ready to close, do you have any suggestions for another issue I could work on next?

[ThomasWaldmann]

I've fixed the docs issue in master.

Please update your local master branch, then rebase the PR branch onto master, then force push to github.

In the issue tracker, some stuff is labelled as easy, good first issue or help wanted - choose from these if you feel it is a good fit for you.

[ThomasWaldmann]

found quite some more todo in the tests.

[alighazi288]

I realized I completely forgot to update the tests after changing my implementation—apologies for that oversight! I've reviewed and adjusted everything now, so the tests should align correctly with the updated implementation. Let me know if there's anything else you'd like me to refine.

[ThomasWaldmann]

LGTM!