Changes in docs to facilitate appropriate crypto use

[py0xc3]

At first, thanks for maintaining this great tool!

Have you checked borgbackup docs, FAQ, and open Github issues?

Yes.

Is this a BUG / ISSUE report or a QUESTION?

Issue report about content in the docs.

System information. For client/server mode post info for both machines.

Not relevant. Issue is only related to the content of the docs.

Your borg version (borg -V).

Latest Borg docs.

Operating system (distribution) and version.

Not relevant. The issue is general.

Hardware / network configuration, and filesystems used.

Not relevant. Issue is only related to the content of the docs.

How much data is handled by borg?

Not relevant. Issue is only related to the content of the docs.

Full borg commandline that lead to the problem (leave away excludes and passwords)

Not relevant. Issue is only related to the content of the docs.

Describe the problem you're observing.

Issue is not critical / low priority.

I suggest two minor changes in the docs:

1. The docs page about Security -> Cryptography in Borg contains the following two comments:

... HMAC-SHA-256 uses 256 bit keys, while BLAKE2b-256 uses 512 bit keys.

The latter is secure not only because BLAKE2b itself is not susceptible to length extension, but also since it truncates the hash output from 512 bits to 256 bits, which would make the construction safe even if BLAKE2b were broken regarding length extension or similar attacks.

Although this is correct, it is highly suggestive: When encryption/authentication is enabled, Borg uses HMAC-SHA256 and not only SHA256. As long as it is used in conjunction with HMAC, there is no risk concerning length extension attacks against SHA256: with HMAC, SHA256 runs twice sequentially with different input each. The length extension resistance created by the first run and the concatenation before the 2nd is comparable to Blake2b's truncation (if truncation will become necessary for Blake2, which I think is not realistic).

Both HMAC-SHA256 and Blake2b are sufficiently secure, and will output a resilient, suitable 256 bit key for AES. Users might be encouraged to use the algorithm that is fastest on their system, which is Blake2b on most 64 bit architectures but possibly HMAC-SHA256 if Intel SHA extensions are available (the number of systems with these extensions is increasing). Maybe the paragraph should be adjusted to focus that? My point is that many systems may experience a strong increase in performance with the SHA extensions, which makes Borg more competitive against other solutions that incorporate no hardware-accelerated algorithms... making the user more happy :) Generally, a noteworthy advantage I see is that I can configure Borg in a way that all MAC/integrity algorithms are hardware-accelerated: we may share this information in the docs? Btw, the hardware support also increases security against several attacks.

Although I also prefer Blake2b in terms of security, an opponent could argue that SHA256 with HMAC has undergone one of the strongest cryptanalyses among hash algorithms. But this is a discussion that maybe belongs to somewhere else :) For here, I would say both are equally secure while any security difference is probabilistic and partly even academic. The user should focus on other things.

2. The docs page about init contains the comment:

(except AMD Ryzen and future CPUs with SHA extensions),

Does Borg / hashlib already support the Intel SHA extensions? Unfortunately, I have not yet hardware with which I can test it.

As this is not yet supported by all SHA256 implementations, it would be nice to make clear if the extensions can be already used.

---

Generally, the Borg docs are great, very detailed and precise. But some information might be a bit more tailored to average users, who might also use Borg (and who might not all be private users).

If you want, I can write an adjustment for your consideration.

Can you reproduce the problem? If so, describe how. If not, describe troubleshooting steps you took before opening the issue.

Not relevant. Issue is only related to the content of the docs.

Include any warning/errors/backtraces from the system logs

None.

[ThomasWaldmann]

Thanks for the feedback! Can you please make a PR against master branch for the docs change?

About the hw accelerated speed: we use OpenSSL (sometimes also Python stdlib, or OpenSSL via Python stdlib).

In the latest code there is borg benchmark cpu which shows some speed values. In its output, it is usually quite obvious what's hw accelerated and what not.

E.g. from a Apple M1 cpu:

 % borg benchmark cpu
Chunkers =======================================================
buzhash,19,23,21,4095    1GB        1.146s
fixed,1048576            1GB        0.033s
Non-cryptographic checksums / hashes ===========================
crc32 (zlib, used)       1GB        0.036s <--- heavily tuned zlib (by Apple?)
crc32 (libdeflate)       1GB        0.126s
xxh64                    1GB        0.076s
Cryptographic hashes / MACs ====================================
hmac-sha256              1GB        0.436s <--- guess via ARM NEON extensions?
blake2b-256              1GB        1.579s
Encryption =====================================================
aes-256-ctr-hmac-sha256  1GB        0.665s <--- both hw accelerated
aes-256-ctr-blake2b      1GB        1.800s <--- one hw accelerated
aes-256-ocb              1GB        0.653s <--- hw accelerated
chacha20-poly1305        1GB        0.774s <--- software, but fast software
KDFs (slow is GOOD, use argon2!) ===============================
pbkdf2                   5          0.085s
argon2                   5          0.184s
Compression ====================================================
lz4          0.1GB      0.012s
zstd,1       0.1GB      0.024s
zstd,3       0.1GB      0.025s
zstd,5       0.1GB      0.204s
zstd,10      0.1GB      0.726s
zstd,16      0.1GB      6.859s
zstd,22      0.1GB      6.879s
zlib,0       0.1GB      0.034s
zlib,6       0.1GB      1.940s
zlib,9       0.1GB      1.865s
lzma,0       0.1GB      10.950s
lzma,6       0.1GB      24.281s
lzma,9       0.1GB      18.531s
msgpack ========================================================
msgpack      100k Items 0.050s

[py0xc3]

Thanks for the feedback! Can you please make a PR against master branch for the docs change?

I will prepare something in the next few days and make a PR.

hmac-sha256              1GB        0.436s <--- guess via ARM NEON extensions?
blake2b-256              1GB        1.579s

I don't know much about Apple's M1, but the sha256 is definitely accelerated. Thanks for the information!

[py0xc3]

I made a draft for the security.rst; it is to solve the confusion that people can experience if they see, e.g., the English SHA2 page (which can be easily misinterpreted in terms of SHA2 being generally vulnerable), and to focus and to help users to choose the best primitive.

The init.rst.inc seems to be already changed in the master branch; the comment about the Intel SHA extensions has been removed. A comment about which authentication primitive to choose makes maybe sense there as well? Or a link to security.rst?

e.g.,

  The authentication primitive should be chosen based upon SHA hardware support:
  AMD Ryzen and new 12th+ Generation Intel Core processors (beginning with 
  the Alder Lake architecture) support SHA extensions and are likely to perform
  best with HMAC-SHA-256. Among ARM processors, support for SHA extensions varies.
  64-bit CPUs without SHA extensions are likely to perform best with BLAKE2b.

The init.rst.inc seems to be auto-generated, so the PR does not contain changes in this file.

[ThomasWaldmann]

I guess in future people will just run borg benchmark cpu before choosing.

Just guessing based on CPU and docs can be wrong, esp. if there are big differences in the software layer (as I noticed for crc32 speed on misc. platforms).

[ThomasWaldmann]

BTW, if you like to review crypto stuff, could you have a look at the new crypto done in master branch?

[py0xc3]

BTW, if you like to review crypto stuff, could you have a look at the new crypto done in master branch?

I can spare a little more time at the end of May. Do you have something specific in mind?

[ThomasWaldmann]

#6463 <- that's the future crypto (and we'll get rid of AES-CTR).