Preamble

This guide was copied (and then translated into german) from the official NitroKey documentation.

Prerequisites

In order to use this feature, you need to have the gpg installed on your machine. This can be achieved by installing GnuPG:

On Windows, this can also be done using winget: winget install -e --id GnuPG.GnuPG
On macOS, you can also install GnuPG using Homebrew: brew install gnupg
On your Linux distribution of choice, GnuPG can most likely be installed using the package manager of your distro.

Generating a keypair

In order to create a key on your hardware security key, plug it in, open a new terminal window and enter the following:

gpg --card-edit

This should show you all of the relevant information about your security key. On my NitroKey, for example, the output is as follows:

$ gpg --card-edit

Reader ...........: 20A0:42B2:X:0
Application ID ...: D276000124010304000F43A8ED3F0000
Application type .: OpenPGP
Version ..........: 3.4
Manufacturer .....: Nitrokey
Serial number ....: 43A8ED3F
Name of cardholder: [not set]
Language prefs ...: [not set]
Salutation .......: 
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 0 3
Signature counter : 19
KDF setting ......: off
UIF setting ......: Sign=off Decrypt=off Auth=off
Signature key ....: REDA CTED REDA CTED REDA  CTED REDA CTED REDA CTED
      created ....: 2024-10-22 08:59:50
Encryption key....: REDA CTED REDA CTED REDA  CTED REDA CTED REDA CTED
      created ....: 2024-10-22 08:59:50
Authentication key: REDA CTED REDA CTED REDA  CTED REDA CTED REDA CTED
      created ....: 2024-10-22 08:59:50
General key info..: 
pub  rsa2048/9AA75CA228063515 2024-10-22 Bastian REDACTED (NitroKey) <[email protected]>
sec>  rsa2048/REDACTEDREDACTED  created: 2024-10-22  expires: never     
                                card-no: 000F 43A8ED3F
ssb>  rsa2048/REDACTEDREDACTED  created: 2024-10-22  expires: never     
                                card-no: 000F 43A8ED3F
ssb>  rsa2048/REDACTEDREDACTED  created: 2024-10-22  expires: never     
                                card-no: 000F 43A8ED3F

gpg/card>

Furthermore, this command sends you to the GnuPG command line, which is a separate shell from your usual terminal shell.

Within this shell, do the following:

Type admin in order to give yourself the permission to run administrative commands.
```
gpg/card> admin
Admin commands are allowed
 
```
Type generate in order to start the key generation wizard.
```
gpg/card> generate
```
Once that is done, type quit to exit the shell.
```
gpg/card> quit
```

Using your GPG key for commit signing

In order to use this key for signing git commits, you need two things:

The ID of the key you just created. This is relevant as you can then get your public GPG key using your key ID, but also because you need to configure git locally to use your GPG key, which is selected by its ID.
Your public GPG key. This is relevant as this is what you need to save in your GitLab/GitHub settings in order to mark a GPG key as yours.

Getting your key ID

First, list your generated keys by typing the following:

gpg --list-secret-keys --keyid-format LONG

Here, you will see something like this:

sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
      D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid                   [ultimate] Mr. Robot <your_email>
ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

Identify the sec line and copy the key ID, which begins after the rsaXXXX/; so here, it’s 30F2B65B9246B6CA.

You can then instruct git to use this key for signing your commits by editing the configuration (replacing <ID> with the key ID):

git config --global user.signingkey <ID>

Getting your public GPG key

In order to get your public GPG key from your key ID, type the following (replacing <ID> with the key ID gathered before):

gpg --armor --export <ID>

This will give you something like this:

This is your public GPG key. Copy and paste this into your GitLab/GitHub settings.

Importing your keypair on a new computer

If you want to use your hardware security key on multiple servers, you need to transfer the existing keypair from the computer where you’ve set everything up on (referred to as “creation machine” later on) to all other machines (referred to as “other machine” later on).

To do so, first export your private and public key by running the following commands on the creation machine:

gpg --export <ID> > public_key.asc
gpg --export-secret-key <ID> > private_key.asc

Next, copy the two files onto the other machine, then run the following command:

gpg --import public_key.asc
gpg --import private_key.asc

Then, the keys need to be trusted on the other machine by running the following command:

gpg --edit-key [email protected]

This will open a GPG shell, wherein the following commands need to be executed:

trust # This will ask for the trust level you want to assign to that key, choose "ultimate" by typing "5".
quit

Lastly, get the card status on the other machine to make sure everything worked:

gpg --card-status

With that, your GPG keys should be copied over and can be used on both the creation machine and the other machine.

phntxx

Explorer

Setting up GPG keys on a hardware security key