Merge pull request #2587 from enkore/docs/is-openssl

docs/security: OpenSSL usage

docs/internals/security.rst

@@ -254,9 +254,13 @@ on widely used libraries providing them:
   We think this is not an additional risk, since we don't ever
   use OpenSSL's networking, TLS or X.509 code, but only their
   primitives implemented in libcrypto.
-- SHA-256 and SHA-512 from Python's hashlib_ standard library module are used
+- SHA-256 and SHA-512 from Python's hashlib_ standard library module are used.
+  Borg requires a Python built with OpenSSL support (due to PBKDF2), therefore
+  these functions are delegated to OpenSSL by Python.
 - HMAC, PBKDF2 and a constant-time comparison from Python's hmac_ standard
-  library module is used.
+  library module is used. While the HMAC implementation is written in Python,
+  the PBKDF2 implementation is provided by OpenSSL. The constant-time comparison
+  (``compare_digest``) is written in C and part of Python.
 - BLAKE2b is either provided by the system's libb2, an official implementation,
   or a bundled copy of the BLAKE2 reference implementation (written in C).
 
@@ -336,3 +340,28 @@ like remote code execution are inhibited by the design of the protocol:
       general pattern of server-sent responses and are sent instead of response data
       for a request.
 
+The msgpack implementation used (msgpack-python) has a good security track record,
+a large test suite and no issues found by fuzzing. It is based on the msgpack-c implementation,
+sharing the unpacking engine and some support code. msgpack-c has a good track record as well.
+Some issues [#]_ in the past were located in code not included in msgpack-python.
+Borg does not use msgpack-c.
+
+.. [#] - `MessagePack fuzzing <https://blog.gypsyengineer.com/fun/msgpack-fuzzing.html>`_
+       - `Fixed integer overflow and EXT size problem <https://github.com/msgpack/msgpack-c/pull/547>`_
+       - `Fixed array and map size overflow <https://github.com/msgpack/msgpack-c/pull/550>`_
+
+Using OpenSSL
+=============
+
+Borg uses the OpenSSL library for most cryptography (see `Implementations used`_ above).
+OpenSSL is bundled with static releases, thus the bundled copy is not updated with system
+updates.
+
+OpenSSL is a large and complex piece of software and has had its share of vulnerabilities,
+however, it is important to note that Borg links against ``libcrypto`` **not** ``libssl``.
+libcrypto is the low-level cryptography part of OpenSSL,
+while libssl implements TLS and related protocols.
+
+The latter is not used by Borg (cf. `Remote RPC protocol security`_, Borg itself does not implement
+any network access) and historically contained most vulnerabilities, especially critical ones.
+The static binaries released by the project contain neither libssl nor the Python ssl/_ssl modules.

scripts/borg.exe.spec

@@ -16,7 +16,9 @@ a = Analysis([os.path.join(basepath, 'src/borg/__main__.py'), ],
              hiddenimports=['borg.platform.posix'],
              hookspath=[],
              runtime_hooks=[],
-             excludes=[],
+             excludes=[
+                '_ssl', 'ssl',
+             ],
              win_no_prefer_redirects=False,
              win_private_assemblies=False,
              cipher=block_cipher)
@@ -38,3 +40,16 @@ exe = EXE(pyz,
           strip=False,
           upx=True,
           console=True )
+
+if False:
+    # Enable this block to build a directory-based binary instead of
+    # a packed single file. This allows to easily look at all included
+    # files (e.g. without having to strace or halt the built binary
+    # and introspect /tmp).
+    coll = COLLECT(exe,
+                   a.binaries,
+                   a.zipfiles,
+                   a.datas,
+                   strip=False,
+                   upx=True,
+                   name='borg-dir')