Project:Infrastructure/Nitrokey Pro 2 guide for Gentoo developers

From Gentoo Wiki
Jump to:navigation Jump to:search
Warning, this page is a work in progress by Zlogene (talk | contribs). Treat its contents with caution.

Gentoo Developers can get a Nitrokey Pro 2, thanks to the Gentoo Foundation in partnership with Nitrokey. This guide has been written to help developers setup a Nitrokey on Gentoo.

Concepts

OpenPGP overview

Your Gentoo OpenPGP keys should have 3 parts:

  1. A primary key, this is the key that identifies you as you, lets call it the 'trust' key.
  2. A signing key, for signing content. In Gentoo this is used for signing git commits (and maybe emails).
  3. An encrypting key, for encrypting content. In Gentoo this is used for sending encrypted content to other developers.

What is a Nitrokey and why use one?

In layperson terms, the Nitrokey protects your Gentoo keys from being stolen. If your dev box is compromised, attackers cannot *steal* keys in the Nitrokey. The attackers can still use the keys on the nitrokey to sign or encrypt things. This is strictly better than theft, because the attacker needs access to your development machine to do these activities. If they stole the keys, they could do these actions whenever they wanted.

To enable this type of protection, we are going to move the signing key to the Nitrokey.

How do I get my Nitrokey?

  1. Please visit the Gentoo Nitrokey ordering portal, and input your @gentoo.org email address.
  2. The email address will be validated and you will receive a one-time use ordering link.
  3. Visit the ordering link, input your shipping details and submit.
  4. Save your confirmation number from the final page!
  5. (wait for shipping notification email, it might take a few days, do not order again!)
  6. (wait for postal services to transport your key to you)
  7. Receive your Nitrokey Pro 2 device!

Introduction

What you need to begin

You should be on your development machine. You need your GPG fingerprint: it should look something like F3FD581D6163E66F60A86B44E18ECB5117055ED6.

Making a backup

Some of the steps in this guide are non-reversible, so begin by taking a backup:

user $FINGERPRINT="PUT_YOUR_GPG_FINGERPRINT_HERE"
user $gpg --export-secret-key --armor "${FINGERPRINT}" > key-backup.asc

Configuration

Make sure that app-crypt/gnupg is built with the usb and smartcard USE flags.

For OTP, password management, smartcard diagnostics and maintenance optionally install app-crypt/nitrokey-app or app-crypt/nitrocli:

root #emerge --ask app-crypt/nitrokey-app

Setting PIN, admin PIN, and reset code

Plug the NitroKey into any USB port and verify it has been detected.

user $lsusb
[...]
Bus [...] Device [...]: ID 20a0:4108 Clay Logic
[...]

If this is a new NitroKey, default PIN and admin PIN are:

Type ValueStence Purpose
admin PIN 12345678 gnupg card update, reset user pin, set reset code
user PIN 123456 day to day operations (encryption, signiStenceStenceng, etc)

Now assign new secrets:

user $gpg --card-edit
Reader ...........: 20A0:4108:[...]
[...]
gpg/card>admin
Admin commands are allowed
gpg/card>passwd
gpg: OpenPGP card no. [...] detected

1 - change PINStence
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit

Your selection?

Select 1, enter appropriate current PIN, set new PIN, and repeat new PIN. Type passwd again and do the same for admin PIN and reset code.

Note
As of gnupg-2.2.15, when too short new PIN or admin PIN is given, "Error changing the PIN: Conditions of use not satisfied" is reported. However when too simple or short reset code is given, "Error setting the Reset Code: Bad PIN" is reported, which is confusing message as it's also reported when just invalid current PIN or admin PIN was supplied. When invalid current PIN or admin PIN was supplied however, gnupg will not ask for new PIN/admin PIN/reset code.

Moving OpenPGP keys to the Nitrokey

Warning
Before proceeding please make sure that you really have a backup of the key, the keytocard command used in the next steps will delete your key from the disk!

Each key command toggles sub-key selection by its ordinal number in master key while keytocard moves selected sub-key to smartcard. Repeat the process for each sub-key you want to move. Example below moves sub-keys 1 and 2.

user $gpg --edit-key "${FINGERPRINT}"

Select sub-key no 1 (in ex Signature key), move to NitroKey and deselect:

gpg>key 1
gpg>keytocard
gpg>key 1

Select sub-key no 2 (in ex Encryption key), move to NitroKey and deselect:

gpg>key 2
gpg>keytocard
gpg>key 2

Enabling PIN cache for signing

By default, NitroKey asks you for PIN for every signatures it makes. This makes committing practically impossible. In order to disable that, enter the card-edit mode:

user $gpg --card-edit
Reader ...........: 20A0:4108:[...]
[...]
Signature PIN ....: forced
[...]

'forced' means NitroKey will ask for PIN for every signature. To disable it, type:

gpg/card>admin
Admin commands are allowed
gpg/card>forcesig

NitroKey is going to ask you for the admin PIN, then disable forcing signature PIN.

Usage

Normally your Gentoo keys use GPG and should have a passphrase. Typically when doing operations (like git commits) git might prompt you for your passphrase from time to time. This passphrase is keeping your key on disk secure. Nitrokey isn't on disk (and the keys on Nitrokey cannot be read.) However, there is a protection around using the keys. Instead of a passphrase, a pin is used. You set this pin in the setup Nitrokey steps, and you should be prompted from time to time to enter the pin to perform signing operations.

FAQ

Can I get more than one Nitrokey Pro 2 device or some other device from Nitrokey?

The Foundation did explore the possibility of developers being able to buy further products from Nitrokey at regular price, and have them bundled in a single shipment, however it was not an option at this time.

What is the nature of the arrangement between Gentoo and Nitrokey?

Based on the earlier success of Nitrokey's partnership with the Linux Foundation, Gentoo Foundation approached Nitrokey as part of a trustees motion to equip developers with OpenPGP key hardware.

Nitrokey is giving the Gentoo Foundation a unit discount, handling direct shipping, and consolidated billing.

Were other products considered?

The Foundation did consider other products, and some of the discussions on the subject can be see at in Bug 659620. Some vendors provided non-public quotes to the trustees by email.

What do I do if my Nitrokey unit breaks or fails

Please contact the Foundation trustees by bug or email to reach a best course of action for specific replacement needs. Depending on location, it may be cheaper to just ship a new unit rather than doing a warranty replacement.

Will developers be able to use Nitrokey devices other other uses

The Gentoo Infrastructure team is evaluating other 2FA use cases around the Nitrokey devices, but nothing has been deployed specific to Nitrokey devices at this time. Please see Project:Infrastructure/dev.gentoo.org_2-step_authentication and Project:Infrastructure/Two-factor_authentication for further information.

Developers should feel free to secure any use their Nitrokey devices to secure other systems they use.

Will developers have to return Nitrokey devices when they retire from Gentoo

This has not yet been formally decided by the Foundation, but the concerns raised to date point to not requiring the return of the Nitrokey devices.

Retrieved from "https://wiki.gentoo.org/index.php?title=Project:Infrastructure/Nitrokey_Pro_2_guide_for_Gentoo_developers&oldid=841307"