Project:Infrastructure/Nitrokey Pro 2 guide for Gentoo developers

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

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   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!

What you need to begin
You should be on your development machine. You need your GPG fingerprint: it should look something like.

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

Configuration
Make sure that is built with the   and   USE flags.

For OTP, Password Management, smartcard diagnostics and maintenance optionally install or :

Setting PIN, admin PIN and reset code
Plug-in your NitroKey in any USB port and verify it's detected.

If this is new NitroKey, default PIN and Admin PIN are:

Now assign new secrets:

Select 1, enter appropriate current PIN, set new PIN and repeat new PIN. Type  again and do the same for Admin PIN and Reset Code.

Moving OpenPGP keys to the Nitrokey
Each  command toggles sub-key selection by its ordinal number in master key while   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.

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

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

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:

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

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.

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.