Introduce support for FIDO2 to protect keys

Use FIDO2 devices with hmac-secret extension to generate
key encryption key (KEK) instead of passphrase processed
with argon2.

Signed-off-by: Łukasz Stelmach <[email protected]>

Author: steelman

scripts/shell_completions/bash/borg

@@ -85,7 +85,7 @@ _borg()
                 local opts="-a --match-archives ${archive_filter_opts} ${common_opts}"
                 ;;
             *' repo-create '*)
-                local opts="--other-repo --from-borg1 -e --encryption --copy-crypt-key ${common_opts}"
+                local opts="--other-repo --from-borg1 -e --encryption --copy-crypt-key --fido2-device ${common_opts}"
                 ;;
             *' repo-list '*)
                 local opts="--short --format --json ${common_opts} -a --match-archives ${archive_filter_opts} --deleted"
@@ -136,8 +136,9 @@ _borg()
                 ;;
             # umount
             #   no specific options
-            # key change-passphrase
-            #   no specific options
+            *' change-passphrase '*)
+                local opts="${common_opts} --fido2-device"
+                ;;
             *' change-location '*)
                 local opts="${common_opts} keyfile repokey --keep"
                 ;;

scripts/shell_completions/zsh/_borg

@@ -412,6 +412,7 @@ _borg-key() {
     case $line[1] in
     (change-passphrase)
       _arguments -s -w -S : \
+        '--fido2-device=[select a FIDO2 device, use "fido2-token -L" to list available devices]:devpath:_files -P /dev/ -W /dev' \
         $common_options
       ;;
     (export)
@@ -556,6 +557,7 @@ _borg-repo-create() {
 
   _arguments -s -w -S : \
     '(-e --encryption)'{-e,--encryption}'=[select encryption key mode (required)]:MODE:(none authenticated authenticated-blake2 keyfile-aes-ocb repokey-aes-ocb keyfile-chacha20-poly1305 repokey-chacha20-poly1305 keyfile-blake2-aes-ocb repokey-blake2-aes-ocb keyfile-blake2-chacha20-poly1305 repokey-blake2-chacha20-poly1305)' \
+    '--fido2-device=[select a FIDO2 device, use "fido2-token -L" to list available devices]:devpath:_files -P /dev/ -W /dev' \
     $common_repo_options \
     '--make-parent-dirs[create parent directories]'
 }

src/borg/archiver/key_cmds.py

@@ -23,7 +23,7 @@ def do_change_passphrase(self, args, repository, manifest):
         key = manifest.key
         if not hasattr(key, "change_passphrase"):
             raise CommandError("This repository is not encrypted, cannot change the passphrase.")
-        key.change_passphrase()
+        key.change_passphrase(args)
         logger.info("Key updated")
         if hasattr(key, "find_key"):
             # print key location to make backing it up easier
@@ -241,6 +241,14 @@ def build_parser_keys(self, subparsers, common_parser, mid_common_parser):
             help="change repository passphrase",
         )
         subparser.set_defaults(func=self.do_change_passphrase)
+        subparser.add_argument(
+            "--fido2-device",
+            metavar="DEVICE",
+            dest="fido2_device",
+            default=None,
+            help="select fido2 device to protect the repository key, use ``fido2-token -L`` "
+            "to list available devices.",
+        )
 
         change_location_epilog = process_epilog(
             """

src/borg/archiver/repo_create_cmd.py

@@ -229,3 +229,10 @@ def build_parser_repo_create(self, subparsers, common_parser, mid_common_parser)
             help="copy the crypt_key (used for authenticated encryption) from the key of the other repo "
             "(default: new random key).",
         )
+        subparser.add_argument(
+            "--fido2-device",
+            metavar="DEVICE",
+            dest="fido2_device",
+            help="select fido2 device to protect the repository key, use ``fido2-token -L`` "
+            "to list available devices.",
+        )

src/borg/constants.py

@@ -157,6 +157,8 @@
     "pbkdf2": "sha256",
     # encrypt-then-MAC, kdf: argon2, encryption: chacha20, authentication: poly1305
     "argon2": "argon2 chacha20-poly1305",
+    # Fido2 hmac-secret
+    "fido2": "fido2 hmac-secret chacha20-poly1305",
 }
 
 

src/borg/crypto/key.py

@@ -32,6 +32,8 @@
 from .low_level import AES256_CTR_HMAC_SHA256, AES256_CTR_BLAKE2b, AES256_OCB, CHACHA20_POLY1305
 from . import low_level
 
+from ..fido2 import has_fido2, Fido2Operations
+
 # workaround for lost passphrase or key in "authenticated" or "authenticated-blake2" mode
 AUTHENTICATED_NO_KEY = "authenticated_no_key" in workarounds
 
@@ -388,6 +390,7 @@ class FlexiKey:
     def detect(cls, repository, manifest_data, *, other=False):
         key = cls(repository)
         target = key.find_key()
+        # TODO: ask for "PIN" when applicable
         prompt = "Enter passphrase for key %s: " % target
         passphrase = Passphrase.env_passphrase(other=other)
         if passphrase is None:
@@ -442,6 +445,8 @@ def decrypt_key_file(self, data, passphrase):
                 return self.decrypt_key_file_pbkdf2(encrypted_key, passphrase)
             elif encrypted_key.algorithm == "argon2 chacha20-poly1305":
                 return self.decrypt_key_file_argon2(encrypted_key, passphrase)
+            elif encrypted_key.algorithm == "fido2 hmac-secret chacha20-poly1305":
+                return self.decrypt_key_file_fido2(encrypted_key, passphrase)
             else:
                 raise UnsupportedKeyFormatError()
 
@@ -501,11 +506,26 @@ def decrypt_key_file_argon2(self, encrypted_key, passphrase):
         except low_level.IntegrityError:
             return None
 
-    def encrypt_key_file(self, data, passphrase, algorithm):
+    def decrypt_key_file_fido2(self, encrypted_key, pin):
+        device = Fido2Operations.find_device(encrypted_key.fido2_credential_id)
+        operations = Fido2Operations(device, pin)
+        secret = operations.use_hmac_hash(
+            encrypted_key.salt,
+            encrypted_key.fido2_credential_id,
+        )
+        ae_cipher = CHACHA20_POLY1305(key=secret, iv=0, header_len=0, aad_offset=0)
+        try:
+            return ae_cipher.decrypt(encrypted_key.data)
+        except low_level.IntegrityError:
+            return None
+
+    def encrypt_key_file(self, data, passphrase, algorithm, args):
         if algorithm == "sha256":
             return self.encrypt_key_file_pbkdf2(data, passphrase)
         elif algorithm == "argon2 chacha20-poly1305":
             return self.encrypt_key_file_argon2(data, passphrase)
+        elif algorithm == "fido2 hmac-secret chacha20-poly1305":
+            return self.encrypt_key_file_fido2(data, passphrase, args)
         else:
             raise ValueError(f"Unexpected algorithm: {algorithm}")
 
@@ -531,22 +551,48 @@ def encrypt_key_file_argon2(self, data, passphrase):
         )
         return msgpack.packb(encrypted_key.as_dict())
 
-    def _save(self, passphrase, algorithm):
+    def encrypt_key_file_fido2(self, data, pin, args):
+        operations = Fido2Operations(args.fido2_device, pin)
+        credential_id, salt, secret = operations.generate_hmac_hash(user=self.repository_id)
+        ae_cipher = CHACHA20_POLY1305(key=secret, iv=0, header_len=0, aad_offset=0)
+        encrypted_key = EncryptedKey(
+            version=1,
+            algorithm="fido2 hmac-secret chacha20-poly1305",
+            salt=salt,
+            data=ae_cipher.encrypt(data),
+            fido2_credential_id=credential_id,
+        )
+        return msgpack.packb(encrypted_key.as_dict())
+
+    def _save(self, passphrase, algorithm, args):
         key = Key(
             version=2,
             repository_id=self.repository_id,
             crypt_key=self.crypt_key,
             id_key=self.id_key,
             chunk_seed=self.chunk_seed,
         )
-        data = self.encrypt_key_file(msgpack.packb(key.as_dict()), passphrase, algorithm)
+        data = self.encrypt_key_file(msgpack.packb(key.as_dict()), passphrase, algorithm, args)
         key_data = "\n".join(textwrap.wrap(binascii.b2a_base64(data).decode("ascii")))
         return key_data
 
-    def change_passphrase(self, passphrase=None):
-        if passphrase is None:
-            passphrase = Passphrase.new(allow_empty=True)
-        self.save(self.target, passphrase, algorithm=self._encrypted_key_algorithm)
+    def change_passphrase(self, args, passphrase=None):
+        if args.fido2_device:
+            operations = Fido2Operations(args.fido2_device)
+            if operations.has_client_pin:
+                # TODO: try to be more descriptive about the device
+                passphrase = Passphrase.new(pin_prompt=f"Enter PIN for {args.fido2_device}: ", only_new=True)
+            else:
+                passphrase = Passphrase('')
+            key_algorithm = KEY_ALGORITHMS["fido2"]
+        else:
+            if passphrase is None:
+                passphrase = Passphrase.new(allow_empty=True, only_new=True)
+            key_algorithm = self._encrypted_key_algorithm
+            # If fido2 was used before change it to argon2
+            if key_algorithm == KEY_ALGORITHMS["fido2"]:
+                key_algorithm = KEY_ALGORITHMS["argon2"]
+        self.save(self.target, passphrase, algorithm=key_algorithm, args=args)
 
     @classmethod
     def create(cls, repository, args, *, other_key=None):
@@ -569,10 +615,15 @@ def create(cls, repository, args, *, other_key=None):
             key.init_from_given_data(crypt_key=crypt_key, id_key=other_key.id_key, chunk_seed=other_key.chunk_seed)
         else:
             key.init_from_random_data()
-        passphrase = Passphrase.new(allow_empty=True)
+        if args.fido2_device:
+            key_algorithm = KEY_ALGORITHMS["fido2"]
+            passphrase = Passphrase.new(pin_prompt="Enter PIN for {args.fido2_device}: ")
+        else:
+            key_algorithm = KEY_ALGORITHMS["argon2"]
+            passphrase = Passphrase.new(allow_empty=True)
         key.init_ciphers()
         target = key.get_new_target(args)
-        key.save(target, passphrase, create=True, algorithm=KEY_ALGORITHMS["argon2"])
+        key.save(target, passphrase, key_algorithm, args, create=True)
         logger.info('Key in "%s" created.' % target)
         logger.info("Keep this key safe. Your data will be inaccessible without it.")
         return key
@@ -700,8 +751,8 @@ def load(self, target, passphrase):
             self.target = target
         return success
 
-    def save(self, target, passphrase, algorithm, create=False):
-        key_data = self._save(passphrase, algorithm)
+    def save(self, target, passphrase, algorithm, args, create=False):
+        key_data = self._save(passphrase, algorithm, args)
         if self.STORAGE == KeyBlobStorage.KEYFILE:
             if create and os.path.isfile(target):
                 # if a new keyfile key repository is created, ensure that an existing keyfile of another
@@ -788,8 +839,8 @@ def load(self, target, passphrase):
         self.logically_encrypted = False
         return success
 
-    def save(self, target, passphrase, algorithm, create=False):
-        super().save(target, passphrase, algorithm, create=create)
+    def save(self, target, passphrase, algorithm, args, create=False):
+        super().save(target, passphrase, algorithm, args, create=create)
         self.logically_encrypted = False
 
     def init_ciphers(self, manifest_data=None):