Add How to restore from backup / create backup Nitrokey

[schaarsc]

File: [nitrokey3/linux/openpgp-keygen-backup.rst] https://docs.nitrokey.com/nitrokey3/linux/openpgp-keygen-backup.html

I'd like to suggest to add also some documentation how to restore from backup and how to install on a second backup nitrokey.

some points worth mentioning

• create backup nitrokey
  • how to switch between nitrokeys? how to update private-key stubs?
  • is it possible to "create" two nitrokeys one after the other, if during keytocard private-key stubs are not created (to replace the private key)?
  • is ADSK a valid strategy? Is there enough space on Nitrokey for this, according to documentation only 3 keys can be stored SC/E/A?
• in case of loss, install backup on new nitrokey
  • find the private-key stubs with --with-keygrip and delete
  • I had to use gpg --batch --import private.key, without batch I'd get sec#

Note:
this new page could be embedded in a series of pages related to how-to-recover-from-loss-or-damage. based on the forum posts, there appears to be a need for entry level documentation how to work with security tokens and the different strategies for backup and recovery (FIDO, PIV, secrets, PGP)

[schaarsc]

some ideas...

you can use asciidoctor to create a html page:

= Nitrokey Backup and Recovery
:toc:

== OpenPGP

=== Create Key

If a key is created directly on the device, then this key is lost if the device is lost.
The private part of the key will never leave the device.

As a consequence the key must be created outside the device and then transferred, see https://docs.nitrokey.com/nitrokey3/linux/openpgp-keygen-backup

Store the key in a save place. 

=== Restore key

During the transfer to the device (described in the previous section) a key stub is created
in ~/.gnupg/private-keys-v1.d/. This stub holds some information about the key, for example the
fact that it is stored on a specific Nitrokey. These files need to be removed.

Once the files are removed, proceed to transfer the key to the backup Nitrokey, see https://docs.nitrokey.com/nitrokey3/linux/openpgp-keygen-backup

=== Working with multiple Nitrokeys

It is possible to install pgp-keys on multiple Nitrokeys and use them on the same computer.
For this to work the key stub (created during the key transfer) corresponding to the Nitrokey must be available.

. after keytocard, identify the stubs by their keygrip
+
----
gpg -K --with-keygrip <email>
----
+
. rename the stubs, main key and sub-keys
+
----
mv ~/.gnupg/private-keys-v1.d/<keygrip>.key ~/.gnupg/private-keys-v1.d/<keygrip>-blue.key
----
+
. repeat the keytocard procedure for the second Nitrokey
. rename the stubs, main key and sub-keys of the second Nitrokey
+
----
mv ~/.gnupg/private-keys-v1.d/<keygrip>.key ~/.gnupg/private-keys-v1.d/<keygrip>-green.key
----
+
. create scripts to change the symlinks, depending on the device you want to use
+
.~/.gnupg/private-keys-v1.d/nitrokey-blue.sh
----
cd ~/.gnupg/private-keys-v1.d/
ln -sf <keygrip main>-blue.key <keygrip main>.key
ln -sf <keygrip sub1>-blue.key <keygrip sub1>.key
ln -sf <keygrip sub2>-blue.key <keygrip sub2>.key
----
+
.~/.gnupg/private-keys-v1.d/nitrokey-green.sh
----
cd ~/.gnupg/private-keys-v1.d/
ln -sf <keygrip main>-green.key <keygrip main>.key
ln -sf <keygrip sub1>-green.key <keygrip sub1>.key
ln -sf <keygrip sub2>-green.key <keygrip sub2>.key
----


== FIDO2: webauthn, passkey

Since this method is using asymetric encryption and the private key can never leave the device,
you must use a second device as a backup or you will loose access if the device is lost (if this is the only login method available).

Most web sites offer methods to regain access after a password is forgotten, those methods do also apply here, if you did not
register a second (backup) Nitrokey.

== FIDO2: ssh

There is no way to backup ssh keys using key types ecdsa-sk / ed25519-sk, the secrets can never be extracted from the device.
For this use case always use two devices, in case one gets stolen or is lost.

=== Create keys

First Nitrokey
----
ssh-keygen -f ~/.ssh/nitrokey-green -t ed25519-sk
----

Backup Nitrokey
----
ssh-keygen -f ~/.ssh/nitrokey-blue -t ed25519-sk
----

=== Working with multiple Nitrokeys

Since the ssh keys are independent of each other, they can be used as you would use any other keys.

. add public key to authorized_keys
. login using `-i` to decide which one to use

==== Alternative

. add public key to authorized_keys
. in .ssh/config use a link, for example .ssh/nitrokey
+
.~/.ssh/config
----
Host *
  IdentityFile ~/.ssh/nitrokey
----
+
. create scripts to change the symlinks, depending on the device you want to use
+
.~/.ssh/nitrokey-blue.sh
----
cd ~/.ssh
ln -fs nitrokey-blue.pub nitrokey.pub
ln -fs nitrokey-blue     nitrokey
----
+
.~.ssh/nitrokey-green.sh
----
cd ~/.ssh
ln -fs nitrokey-green.pub nitrokey.pub
ln -fs nitrokey-green     nitrokey
----


== Automate working with two Nitrokeys

If you use two Nitrokeys, then switching between keys can be automated for the use cases "FIDO2 ssh" and "OpenPGP".
The use case "FIDO2 webauthn" does not require automation on your side, since this is done on server side.

=== udev

Extend the existing NItrokey3 udev rule by adding
----
, TAG+="systemd" , ENV{SYSTEMD_USER_WANTS}+="nk3-hotplug@$name.service"
----

this will create a systemd device unit and also trigger nk3-hotplug.service if a user has one installed 
in its local systemd configuration `$HOME/.config/systemd/user/`

=== systemd service

Users can now decide if they want to opt-in to the automatic switch of Nitrokey ssh and openpgp configurations
by creating a `[email protected]` and reusing the link approach described above.

.~/.config/systemd/user/[email protected]
----
[Unit]
Description=runs each time a NK3 is inserted
[Service]
Type=oneshot
ExecStart=/home/<replace-with-user>/.ssh/nk3-hotplug.sh %I
ExecStart=/home/<replace-with-user>/.gnupg/private-keys-v1.d/nk3-hotplug.sh %I
----

.~/.ssh/nk3-hotplug.sh
----
#!/usr/bin/bash

DEVICE_UUID=` nitropy nk3 list 2>/dev/null  |grep ${1:?device name missing} |awk '{print $4}' `

cd $(dirname $(realpath $0))

case $DEVICE_UUID
in
<set device UUID here>)
echo "set ssh links to blue"
./nitrokey-blue.sh
;;
<set device UUID here>)
echo "set ssh links to green"
./nitrokey-green.sh
;;
*)
echo "unknown device"
;;
esac
----

.~/.gnupg/private-keys-v1.d/nk3-hotplug.sh
----
#!/usr/bin/bash

DEVICE_UUID=` nitropy nk3 list 2>/dev/null  |grep ${1:?device name missing} |awk '{print $4}' `

cd $(dirname $(realpath $0))

case $DEVICE_UUID
in
<set device UUID here>)
echo "set pgp links to blue"
./nitrokey-blue.sh
;;
<set device UUID here>)
echo "set pgp links to green"
./nitrokey-green.sh
;;
*)
echo "unknown device"
;;
esac
----