people are confused by message after borg init

[arjunak234]

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

Yes

Is this a BUG / ISSUE report or a QUESTION?

BUG

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

Your borg version (borg -V).

borg 1.1.9

Operating system (distribution) and version.

Debian 10

"encryption" parameter is being ignored during repo init.
borg init TEST --encryption=repokey

Enter new passphrase:
Enter same passphrase again:
Do you want your passphrase to be displayed for verification? [yN]: n

By default repositories initialized with this version will produce security
errors if written to with an older version (up to and including Borg 1.0.8).

If you want to use these older versions, you can disable the check by running:
borg upgrade --disable-tam TEST

See https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability for details about the security implications.

IMPORTANT: you will need both KEY AND PASSPHRASE to access this repo!
Use "borg key export" to export the key, optionally in printable format.
Write down the passphrase. Store both at safe place(s).

[ThomasWaldmann]

So, where exactly is the problem?

[arjunak234]

Doesn't repokey mean i only need the passphrase not key and passphrase?

[ThomasWaldmann]

you always need key and passphrase.

the difference is that for repokey mode, the key is stored in the repo config, while for keyfile mode it is stored in your home directory.

[arjunak234]

"you will need both KEY AND PASSPHRASE" made it sound like the key is stored in home directory.

[ThomasWaldmann]

you read too much between the lines. :)
as you can read in the lines below the one you quoted, it tells you that so you keep both at a safe place.

it would be a pity if you lose the key or passphrase and can't access your repo because of that.

that can also happen if the key is stored in the repo config, just think of a hardware issue or software bug.

[DavidOliver]

New user here. I searched and found this issue after reading https://borgbackup.readthedocs.io/en/1.1-maint/usage/init.html and initialising my first repo with borg init --encryption=repokey as I was also confused/unsure.

"you will need both KEY AND PASSPHRASE to access this repo!" does seem to strongly imply that the key will need to be managed by the user separately to the remote repo (and its config). I believe it would avoid confusion if the message were tweaked based on the encryption option used, or if it were improved to more clearly cover use of both keyrepo and keyfile options.

Edit: or is the idea, even with 'keyrepo', that the user does export and the remotely-stored key? If so, is that to guard against corruption of (just) the key file on the remote, which would render the whole repo (which may otherwise still be readable) unreadable? Apologies if this is a silly question; after reading the documentation I had the idea in my head that I would only need to store the passphrase:

If you want “passphrase-only” security, use one of the repokey modes. The key will be stored inside the repository (in its “config” file).

[ThomasWaldmann]

The "you will need..." phrase is simply a statement of a fact. The repo is encrypted with a key and the key is protected by a passphrase. So you need both of them to be able to use the repo.

This fact is totally independent of the storage location of the key (whether it is local in your home directory or in the repo directory). It also does not say that you need to do something special with the key under normal circumstances, it just tries to say that you must not lose neither the key nor the passphrase under any circumstance (except if you completely delete a repo). This implies that you make a backup and store it safely as it suggests after that phrase.

If you have a better phrase to express that shortly, I am open to suggestions.

[abeluck]

I landed here the same as @DavidOliver.. this was also quite confusing to me. I was pretty sure the key was stored in the repo, but the message made me do a double take and led me here to verify.

Suggestion: leave the phrasing as is, but append a sentence to the effect of "If you used a repokey encryption mode, then the key is stored in the repo but you should back it up separately."

[Lanny]

Found this issue the same way as the others, I guessed that it meant the key was stored with the repo but the message seemed ambiguous

If you have a better phrase to express that shortly, I am open to suggestions.

If the repo is created with a repokey encryption method, something like "This repo's key is stored with the repo, anyone with a copy of the repo can access it using the included key and your passphrase" might be less intimidating, while also giving a heads up about the implications for storing the key with the repo itself.

[carlosaguilarmelchor]

Same for me, I habe been the mast hour looking for a workaround until I came here. The message is not clear.

Worse it is a security issue as it gives a "false impression of security" which is a bad practice. People may think the key is not on the repo and only safely stored locally, which is not the case.

[carlosaguilarmelchor]

Thx for adding it to a milestone!

[aryzing]

Recently started using borg. Despite this issue being closed, I still find the message confusing. Just spent a decent chunk of time trying to figure out what I'm supposed to do with the key when using repokey mode.

Sure, there's a message asking the user to back it up, but no explanation as to why or what to do with the backup. It is also confusing that despite being asked to back up the key, it is not required at all to backup or restore files, so what's the point? Another confusing message in the docs is the "leaving your keys inside your car" warning. How can this ever happen in repokey mode?

A better explanation of what is expected from the user as well as how this mode operates that would benefit everyone would be something along the lines of,

In repokey mode, only your passphrase is needed to have full control over a repo. Internally, Borg uses the passphrase to decrypt a key which itself is used to encrypt and decrypt your files. The key is securely stored in encrypted format by means of the passphrase alongside the rest of your files. Borg automatically uses this key when performing cryptographic operations and doesn't require explicit user handling.

Note that since the key is stored inside the repo, an attacker only needs to guess the passphrase to gain full control over the repo. Essentially, repokey mode is analogous to password protection. To require the user present both the key and the passphrase to have access to the repo, use keyfile mode.

In any case, you may want to export this key for ... I still don't get why we'd want to export the key?

Wouldn't an explanation like the above be more helpful?

[ThomasWaldmann]

Well, it actually tells you right there to use "borg key export", so why are you confused what to do? It also tells you to store key and passphrase at a safe place.

I think the main issue here is that people read too much between the lines or assume somehow that this does not make sense. If you don't believe that the backup is necessary, just change one bit of the key in the repo config (or in your home directory) and you will see why you need the backup.

[aryzing]

Thanks @ThomasWaldmann, appreciate the quick response. You're right, it does say to use the export function, and then what? How is it used? What's its purpose? As a user, it is confusing to be asked to export a key that apparently has no use. It is also hard to understand that most of the time, the key is not needed to use Borg. Clarifying these two points would go a long way for UX. Users are also more likely to follow instructions if they understand why they are necessary or why it's in their best interest to do so.

User behavior is hard to predict, and when receiving reports of confusion around a particular area of a product or tool, leaving them unaddressed slows adoption. I know that it would have helped me and those posting here quite a bit.

[ThomasWaldmann]

The key is used all the time by borg for encryption, authentication, for chunk id computations, for the chunker secret. So not sure where you get "it is not needed" from.

How borg key export is used -> we have docs, they have a section for each command.

[bakai-taalaibek]

In two factor authentication, user needs password AND yubikey/key file/TOTP. If he doesn't have his yubikey, he will not be able to access the database. But apparently if I don't save the borg key I will be able to access my backup using my password.

Otherwise do you mean that I have to save the key somewhere and then somehow provide it to borg every time I access my backup?

The borg message is still not clear to me. Looks like you created two factor authentication but glued the yubikey to database by default, but most users don't even know about it.

Let's say I created a backup of my files in a common external HDD. If someone comes in and deletes the key inside the repo, I will not be able to access it?

They fact that I need to find and save every key is very obscure information (where is it, how is it called), it is inconvenient and also very dangerous. Sounds like bad design. I would prefer to ONLY use my password to access the backup.

Otherwise, I would prefer to create borg backup without password and put it in an encrypted storage.

[ThomasWaldmann]

@bakai-taalaibek This has nothing to do with 2FA or yubikey.

One could rather compare:

• borg key passphrase, borg key, access to the borg repo using that key
• GPG key passphrase, GGP key, access to encrypted content using that key
• ssh key passphrase, ssh key, access to other systems using that key

As long as you don't lose any of these keys, it is enough to provide the passphrase (the key will then be located and used automatically).

But if you lose any of these keys, it is game over - just having a passphrase that protected a key that you have lost is obviously not sufficient to do anything.

"Losing" a key can be (for borg):

• losing a keyfile key, because the file is gone (usually stored in home dir)
• losing a repokey key, because the file is gone (usually stored in repo cfg)
• corruption of key material has the same effect as losing the key, could be due to bit flips of storage media, filesystem issues, a bad sector, corruption due to bad RAM, ...

I recently improved the borg init msg, so I suggest you use the most recent borg release and if it is still unclear, open a new ticket or PR.

And btw: NO, that is not bad design, but best practice. That's why the ssh and gpg folks did it the same way as borg (or vice versa).

Just using the passphrase, no key: that mode existed in attic and early borg versions. We got rid of it because you could never change the passphrase if the encryption key is not random, but derived from the passphrase. Considering that a lot of people tend to use too easy passphrases and want to make them better later, that mode was a pretty bad idea as one could not change the passphrase, so would be stuck forever with the too easy one.

I am locking this issue now. Everything notable has been said above and if somebody thinks it can be improved, they can open a new PR or issue with specific suggestions.