Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) #2837

Merged
merged 1 commit into from Jul 24, 2017

Conversation

@milkey-mouse
Copy link
Contributor

@milkey-mouse milkey-mouse commented Jul 16, 2017

I haven't tested the macOS instructions yet, they were made with a careful reading of the security man pages. I also haven't made the equivalent tutorial for the KDE keyring equivalent (KWallet) yet.

@milkey-mouse
Copy link
Contributor Author

@milkey-mouse milkey-mouse commented Jul 16, 2017

If anyone reading this has a Mac and is willing to test the Mac instructions that would help (otherwise I'll have to go down to the Apple store and hope none of their Geniuses™ notice me 😉)

@milkey-mouse milkey-mouse changed the title [WIP] Detail how to use macOS/GNOME keyrings for repo passwords (fixes #392) [WIP] Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) Jul 17, 2017
.. note:: For this to automatically unlock the keychain it must be run
in the ``dbus`` session of an unlocked terminal; for example, running a backup
script as a ``cron`` job might not work unless you also ``export DISPLAY=:0``
so ``secret-tool`` can pick up your open session.

This comment has been minimized.

@enkore

enkore Jul 17, 2017
Contributor

Note: accessing the session bus of a different user, even as root, was made more complex some time ago.

$ cat /etc/dbus-1/session-local.conf 
<busconfig>
<policy context="default">
<allow user="root"/>  <!-- clearly, root needs explicit permission
                           to do anything nowadays -->
</policy>
</busconfig>

env vars: DISPLAY, XAUTHORITY=/home/.../.Xauthority, DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus

This comment has been minimized.

@milkey-mouse

milkey-mouse Jul 17, 2017
Author Contributor

The note that's there already was copied pretty much verbatim from discussion in #392. Should I add another note about this/replace the existing one?

Why would you need to access the session bus of a different user for a backup script anyway? If you had borg create in root's crontab?

This comment has been minimized.

@enkore

enkore Jul 17, 2017
Contributor

Between a rock and a hard place: Document largely undocumented things about a platform which changes on a whim? Or don't document it, but someone(?) who attempts it will find it difficult to do so?

I can't recommend either.

If you had borg create in root's crontab?

Yes; it can also be used to send notifications to the desktop [of a specific user, Linux is not a multi-user OS].

This comment has been minimized.

@jkirk

jkirk Apr 9, 2020

Not sure if this is the best place to comment, but I hope this helps someone who stumbles over this and can point me to the right place where it could be added.

This is how I use GNOME Keyring with borg in a user cron job (as I need a unlocked terminal (which I read as unlocked GNOME session) anyway):

export BORG_PASSCOMMAND='sudo -u $USERNAME DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus secret-tool lookup borg-repository repo-name'
sudo -E borg create /path/to/repo:mybackup-{now} /path/to/backup 

Please note the Important note about permissions. You will have "problems" accessing the repository as the normal user after running sudo -E borg.

The secret key was added as described as user $USERNAME:

secret-tool store borg-repository repo-name --label="Borg Passphrase"
directory and use permissions to keep anyone else from reading it. For
example, first create a key::

dd if=/dev/urandom of=~/.borg-passphrase bs=1024 count=1

This comment has been minimized.

@enkore

enkore Jul 17, 2017
Contributor

Perhaps use hex here as well, to avoid non-printables in the passphrase. Also, any NUL might terminate the passphrase, so there is a relatively good chance that this passphrase is only a few characters long.


Then in an automated script one can put::

export BORG_PASSCOMMAND="cat ~/borg-passphrase"

This comment has been minimized.

@enkore

enkore Jul 17, 2017
Contributor

~/ . b (missing dot after the slash)

v- Personally I'd avoid |project_bla| in new texts, since it makes for rather awkward reading of the source.

This comment has been minimized.

@milkey-mouse

milkey-mouse Jul 17, 2017
Author Contributor

Are all those |project_name|s mostly remnants from the attic fork? I was just using what I saw in the rest of the docs.

This comment has been minimized.

@enkore

enkore Jul 17, 2017
Contributor

I think it was once part of the sphinx quickstart.

@lbeltrame
Copy link

@lbeltrame lbeltrame commented Jul 18, 2017

Note for docs: KWallet users can (assuming it's the KF5 based KWallet) use kwallet-query --read-password <entry name> <wallet name>. Unfortunately at the moment it outputs JSON, so it needs additional processing (via stdout) to extract the password.

@milkey-mouse milkey-mouse force-pushed the milkey-mouse:fix392 branch from 6914606 to 6357e73 Jul 19, 2017
@milkey-mouse
Copy link
Contributor Author

@milkey-mouse milkey-mouse commented Jul 19, 2017

kwallet-query ended up not working on my Kubuntu test VM(?) but kwalletcli works perfectly and should also have backwards compatibility with KDE 4 and earlier, so I ended up just using that.

@milkey-mouse milkey-mouse changed the title [WIP] Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) Jul 19, 2017
export BORG_PASSCOMMAND="security find-generic-password -a $USER -s borg-passphrase"

Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)
GNOME has a keyring daemon similar to that of MacOS. However, it requires a bit more setup

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

Sounds biased… 😉

I.e. do not compare the keyrings and do not evaluate them.


export BORG_PASSCOMMAND="security find-generic-password -a $USER -s borg-passphrase"

Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

The desktop environment does not depend on the distro used, so rather leave the "()" list out. Add "(Linux)" if you want as AFAIK GNOME only runs on Linux.

Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)
GNOME has a keyring daemon similar to that of MacOS. However, it requires a bit more setup
to get the login keyring to work. First ensure ``libpam-gnome-keyring`` is installed and
running on login (skip this step on Fedora, as it is installed by default)::

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

Mhh, I doubt Fedora is the only distro where this is the case. Maybe delete that sentence or make it more general ("In some ditros this is done by default.")

Or just change the wording in general: "If XY is not installed, then you have to install it first."

This comment has been minimized.

@milkey-mouse

milkey-mouse Jul 19, 2017
Author Contributor

I put that there in the first place because it was kind of a PITA to get it working/get working instructions on Debian and Ubuntu (which don't have it installed by default), so I wanted to save the users some time. If I'm dropping all mentions of which distros have what DEs and what package managers they use I might as well drop this too, though; the remedy if it's not installed is only two commands.

Then add a secret to the login keyring::

sudo apt install libsecret-tools # Ubuntu, Debian
sudo yum install libsecret-tools # Fedora, RHEL

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

New RHEL/Fedora-based distros should use "dnf". Please change it, the syntax stays the same.

This comment has been minimized.

@enkore

enkore Jul 19, 2017
Contributor

Consider removing installation instructions for other software entirely - it's always going to change slightly and there will always be distros left out. Just saying what is needed should be sufficient to install it.

directory and use permissions to keep anyone else from reading it. For
example, first create a key::

head -c 1024 /dev/urandom | xxd -p > ~/.borg-passphrase

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

Do you rally want to use binary stuff as your passphrase? IMHO the output should be filtered, so only ASCII (or similar) characters are used. At some day you may want to enter the passphrase manually.

If xxd is the thing doing this, then let's just say me that it is not installed by default for me. (Fedora 26 here) Better use a compatible command.

This comment has been minimized.

@milkey-mouse

milkey-mouse Jul 19, 2017
Author Contributor

xxd should be converting it to hex here. I thought (mistakenly) that it was in coreutils and I could assume people would have it installed.

As for why I was using 30 chars, it was the boundary for a line break in xxd, and I was averse to having newlines in the password. Of course, I could have fixed it with a simple tr, but that would have complicated the instructions for not much benefit. In hindsight, I don't see why I was so dead-set on not having newlines in the password anyway...

I'll change that to use base64, which is actually in GNU coreutils (and seems to exist on Mac, too).


sudo apt install libsecret-tools # Ubuntu, Debian
sudo yum install libsecret-tools # Fedora, RHEL
head -c 30 /dev/urandom | xxd -p | secret-tool store borg-repository repo-name --label="Borg Passphrase"

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

You may also mention that of course you can also do it with graphical tools (Seahorse in GNOME).

This comment has been minimized.

@milkey-mouse

milkey-mouse Jul 19, 2017
Author Contributor

It's harder to write tutorials for how to do it in a GUI IMO. Also if they copy-paste these instructions the user can't accidentally use the wrong folder or anything (it will always put them in the defaults for secret-tool).

This comment has been minimized.

@rugk

rugk Jul 21, 2017
Contributor

Yeah, but you could just mention that it is alos possible with the GUI, so users not liking the terminal don't get angry. 😉

Seriously, they should just know that it is possible. Mention the application name(s) as I made in my comment, e.g., if you want to give a hint how to do it. That's all.

head -c 30 /dev/urandom | xxd -p | secret-tool store borg-repository repo-name --label="Borg Passphrase"

If a dialog box pops up prompting you to pick a password for a new keychain, use your
login password. If there is a checkbox for automatically unlocking on login, check it.

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

Maybe: "check it, if you ant that to be the case." OR "check it, if you want automatic updates in the background without interrupting you." or something similar.

__ https://github.com/borgbackup/borg/pull/2837#discussion_r127641330

Using ``BORG_PASSCOMMAND`` with KWallet (Kubuntu, other KDE systems)
KDE also has a similar keychain feature in a program called KWallet. The command-line

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

Again this comparison… Just don't talk of "similar" here. (I could probably accept "also".) That does not matter for the user anyway – they do not want to know how/whether these things are similar, 😃

passphrase and store it in your "wallet"::

sudo apt install kwalletcli # might not be installed by default
head -c 30 /dev/urandom | xxd -p | kwalletcli -Pe borg-passphrase -f Passwords

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

xxd…


export BORG_PASSCOMMAND="kwalletcli -e borg-passphrase -f Passwords"

Using keyfile-based encryption with a blank passphrase

This comment has been minimized.

@rugk

rugk Jul 19, 2017
Contributor

I'd say this suggestion should be mentioned before all the keychain stuff as it is simple, general and something a user would appreciate/should think about before potentially getting into more difficult stuff.

This comment has been minimized.

@milkey-mouse

milkey-mouse Jul 19, 2017
Author Contributor

I had the file-based option at the very beginning, which IMO is less hacky than the keyfile-based encryption, but on second thought it would make sense to have the keyfile option before the keychain stuff.

@milkey-mouse milkey-mouse force-pushed the milkey-mouse:fix392 branch from f73fda3 to e4fa8cd Jul 19, 2017
@milkey-mouse milkey-mouse force-pushed the milkey-mouse:fix392 branch from e4fa8cd to 756dea7 Jul 19, 2017
@milkey-mouse
Copy link
Contributor Author

@milkey-mouse milkey-mouse commented Jul 19, 2017

collapsed changesets

@ThomasWaldmann
Copy link
Member

@ThomasWaldmann ThomasWaldmann commented Jul 19, 2017

@milkey-mouse it is good to collapse some changesets at the end (after all review is finished and at least one core dev approved), but if you do it in the middle of review, you require reviewers to re-read all the stuff just to find out whether the feedback got actually into the changeset. It easier to review incremental diffs, fixup changesets.

@enkore enkore merged commit 77797a2 into borgbackup:master Jul 24, 2017
1 check passed
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@enkore
Copy link
Contributor

@enkore enkore commented Jul 24, 2017

Thanks!

@milkey-mouse milkey-mouse deleted the milkey-mouse:fix392 branch Jul 25, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants