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-editThis 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
adminin order to give yourself the permission to run administrative commands.gpg/card> admin Admin commands are allowed -
Type
generatein order to start the key generation wizard.gpg/card> generate -
Once that is done, type
quitto 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
gitlocally 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:
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQENBGcXaYYBCADJb80ojN9jwEqW2p0aNEQb83rCm/a+vwZDrnrcl9NEyaQWp4eW
AtKjSMgU/R4s5g7EbbS1wYQo1JOdZrX5vKz07O5C/2c6isT10jqCh0gibdZYxx/E
...
-----END PGP PUBLIC KEY BLOCK-----This is your public GPG key. Copy and paste this into your GitLab/GitHub settings.