Nitrokey Setup Notes

This page is intended as the hardware-focused companion to GPG and SSH Key Management.

It may be used to capture project-specific setup notes for supported Nitrokey models, including:

  • initial device initialization

  • PIN and Admin PIN setup

  • retry counter policy

  • touch or presence requirements where supported

  • verification of card visibility using gpg --card-status

Prepare dedicated user group and Polkit policy

Follow the distribution-specific setup for GnuPG, smart cards, PC/SC, and hardware tokens.

Note

Shyft procedures are documented and tested using command-line tools. GUI-based management tools are not required and are not covered by the release-signing procedures.

The standard install will establish a working system, based on command-line tools.

In addition, consider the next steps, that have been proven practical for multipurpose laptops.

On many distributions, pcscd limits smart-card access to the active local console user. This is convenient for desktop use, but it can be unsuitable for dedicated signing accounts, SSH sessions, or machinectl shell user@ sessions, where the user may not be considered the active local seat.

For such cases, create a dedicated group, for example nitrokey, and add a local Polkit rule that allows members of that group to access PC/SC cards.

Access to the hardware token is still protected by the token PIN and, where configured, touch or presence requirements. The Polkit rule only controls whether the user process may communicate with the smart-card service.

To allow signing-user to access the hardware token:

  • create the dedicated group;

  • add the signing user to the group;

  • create a Polkit rule allowing that group access to PC/SC;

  • restart Polkit and pcscd.

sudo groupadd --system nitrokey
sudo usermod -aG nitrokey signing-user
sudoedit /etc/polkit-1/rules.d/49-nitrokey-pcsc.rules
sudo systemctl restart polkit
sudo systemctl restart pcscd.socket pcscd.service

The following rule works on Arch Linux and may require adjustment on other distributions. Verify the action names provided by the local pcsc-lite package before applying the rule:

polkit.addRule(function(action, subject) {
    if ((action.id == "org.debian.pcsc-lite.access_pcsc" ||
         action.id == "org.debian.pcsc-lite.access_card") &&
        subject.isInGroup("nitrokey")) {
        return polkit.Result.YES;
    }
});

After changing group membership, log out and log back in, or start a fresh login session, so the new group membership is visible to the user session. Alternatively, start a new login shell after re-authentication and verify membership using id.

Verify access to the Nitrokey:

id
gpg --card-status

Diagnose PC/SC authorization problems with:

sudo journalctl -u pcscd -f

If access is denied, check that the user is a member of nitrokey and verify that the Polkit action names used in the rule match those provided by the local distribution package:

pkaction | grep -i pcsc
grep -R pcsc /usr/share/polkit-1/actions /etc/polkit-1/rules.d

For release-signing systems, it is recommended to dedicate access to a small number of trusted signing accounts and avoid granting general desktop users membership in the nitrokey group.

Note

Membership in the nitrokey group grants access to communicate with attached smart-card devices through pcscd. It does not bypass PIN, touch, presence, or other protections enforced by the hardware token.

Nitrokey Device Initialization

Device initialization should be performed on a dedicated GPG provisioning workstation.

The provisioning workstation is expected to be:

  • maintained by the organization;

  • used for GPG key ceremonies and Nitrokey provisioning;

  • protected according to the organization’s release-signing procedures.

A Nitrokey should be initialized before any signing, authentication, or encryption subkeys are imported.

Verify factory state

Insert the Nitrokey and verify that the OpenPGP application is visible.

gpg --card-status

Verify that:

  • the OpenPGP application is detected;

  • no project signing keys are present;

  • the device appears to be in the expected state for a newly delivered or factory-reset device.

Enable KDF protection

Enable KDF protection before setting operational PINs.

gpg --card-edit

admin
kdf-setup

KDF protection causes PIN verification to use a derived secret instead of transmitting the PIN directly to the card and is recommended for all newly provisioned devices.

Verify that KDF support is reported by gpg --card-status after enabling it.

Configure user interaction flags

Where supported by the device, enable user interaction requirements for:

  • signing;

  • authentication;

  • encryption.

gpg --card-edit

admin
uif

Configure cryptographic algorithms

Shyft recommends modern elliptic-curve cryptography.

For newly provisioned devices:

  • Signature: Ed25519

  • Authentication: Ed25519

  • Encryption: Curve25519

Configure key attributes before importing or generating operational subkeys.

gpg --card-edit

admin
key-attr

Configure PINs

The User PIN and Admin PIN shall be independent values.

admin
passwd

Configure:

  • Admin PIN

  • User PIN

The factory values are:

  • Admin PIN: 12345678

  • User PIN: 123456

Choose independent replacement values and verify that the card reports successful completion.

The Reset Code is optional.

Shyft procedures rely on the root certification key for recovery and re-issuance of signing and authentication subkeys. A lost PIN or locked device may therefore be handled by device replacement and issuance of new subkeys.

Configure device informal fields

Use gpg --card-edit and configure the card metadata.

Recommended metadata:

  • Name: card holder name

  • URL: project or organization web site

  • Language: en

Let this be the last step of the provisioning of the key, because then the use of configured PINs is also tested.

Verify Provisioned Device

Verify the final device configuration.

gpg --card-status

Verify:

  • card holder information;

  • URL field;

  • language field;

  • KDF enabled;

  • user interaction flags enabled;

  • expected cryptographic algorithms.

The device is now ready for subkey provisioning.