arno
/
YubiKey-Guide
mirror of https://github.com/drduh/YubiKey-Guide.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Automate PIN and card operations

Browse Source
pull/425/head
drduh 2 months ago
parent b2959d075b
commit a1081d20ac
1 changed files with 88 additions and 120 deletions
Show Stats Download Patch File Download Diff File

208
README.md
Unescape View File

@ -20,12 +20,12 @@ To suggest an improvement, send a pull request or open an [issue](https://github
- [Create Certify key](#create-certify-key) - [Create Certify key](#create-certify-key)
- [Create Subkeys](#create-subkeys) - [Create Subkeys](#create-subkeys)
- [Verify keys](#verify-keys) - [Verify keys](#verify-keys)
- [Backup private keys](#backup-private-keys) - [Backup keys](#backup-keys)
- [Export public key](#export-public-key) - [Export public key](#export-public-key)
- [Configure YubiKey](#configure-yubikey) - [Configure YubiKey](#configure-yubikey)
* [Enable KDF](#enable-kdf) * [Enable KDF](#enable-kdf)
* [Change PIN](#change-pin) * [Change PIN](#change-pin)
* [Set information](#set-information) * [Set attributes](#set-attributes)
- [Transfer Subkeys](#transfer-subkeys) - [Transfer Subkeys](#transfer-subkeys)
* [Signature key](#signature-key) * [Signature key](#signature-key)
* [Encryption key](#encryption-key) * [Encryption key](#encryption-key)
@ -81,7 +81,8 @@ A dedicated, secure operating environment is recommended to generate cryptograph
The following is a general ranking of environments least to most hospitable to generating materials: The following is a general ranking of environments least to most hospitable to generating materials:
1. Daily, currently in use operating system with unrestricted network access 1. Public, shared or other computer owned by someone else
1. Daily-use personal operating system with unrestricted network access
1. Virtualized operating system with limited capabilities (using [virt-manager](https://virt-manager.org/), VirtualBox or VMware, for example) 1. Virtualized operating system with limited capabilities (using [virt-manager](https://virt-manager.org/), VirtualBox or VMware, for example)
1. Dedicated and hardened [Debian](https://www.debian.org/) or [OpenBSD](https://www.openbsd.org/) installation 1. Dedicated and hardened [Debian](https://www.debian.org/) or [OpenBSD](https://www.openbsd.org/) installation
1. Ephemeral [Debian Live](https://www.debian.org/CD/live/) or [Tails](https://tails.boum.org/index.en.html) booted without primary storage attached 1. Ephemeral [Debian Live](https://www.debian.org/CD/live/) or [Tails](https://tails.boum.org/index.en.html) booted without primary storage attached
@ -440,7 +441,7 @@ Display the password, then memorize or write it in a secure location, ideally se
echo $PASS echo $PASS
``` ```
This repository includes a [`passphrase.html`](passphrase.html) file which can be printed and filled out by hand to assist with passphrase transcription. This repository includes a [`passphrase.html`](https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/passphrase.html) file which can be printed and filled out by hand to assist with passphrase transcription. Save the raw file and open it with a browser to print.
# Create Certify key # Create Certify key
@ -500,7 +501,7 @@ ssb rsa4096/0x30CBE8C4B085B9F7 2024-01-01 [E] [expires: 2026-01-01]
ssb rsa4096/0xAD9E24E1B8CB9600 2024-01-01 [A] [expires: 2026-01-01] ssb rsa4096/0xAD9E24E1B8CB9600 2024-01-01 [A] [expires: 2026-01-01]
``` ```
# Backup private keys # Backup keys
Save a copy of the Certify key and Subkeys: Save a copy of the Certify key and Subkeys:
@ -512,6 +513,9 @@ gpg --output $GNUPGHOME/$KEYID-Certify.key \
gpg --output $GNUPGHOME/$KEYID-Subkeys.key \ gpg --output $GNUPGHOME/$KEYID-Subkeys.key \
--batch --pinentry-mode=loopback --passphrase "$PASS" \ --batch --pinentry-mode=loopback --passphrase "$PASS" \
--armor --export-secret-subkeys $KEYID --armor --export-secret-subkeys $KEYID
gpg --output $GNUPGHOME/$KEYID.asc \
--armor --export $KEYID
``` ```
Create an **encrypted** backup on portable storage to be kept offline in a secure and durable location. Create an **encrypted** backup on portable storage to be kept offline in a secure and durable location.
@ -841,8 +845,14 @@ Key Derived Function (KDF) enables YubiKey to store the hash of PIN, preventing
**Note** This feature may not be compatible with older GnuPG versions, especially mobile clients. These incompatible clients will not function because the PIN will always be rejected. **Note** This feature may not be compatible with older GnuPG versions, especially mobile clients. These incompatible clients will not function because the PIN will always be rejected.
Enable KDF using the default Admin pin of `12345678`:
```console ```console
gpg/card> kdf-setup gpg --command-fd=0 --pinentry-mode=loopback --card-edit <<EOF
admin
kdf-setup
12345678
EOF
``` ```
This step must be completed before changing PINs or moving keys or an error will occur: `gpg: error for setup KDF: Conditions of use not satisfied` This step must be completed before changing PINs or moving keys or an error will occur: `gpg: error for setup KDF: Conditions of use not satisfied`
@ -855,9 +865,9 @@ Entering the *PIN* incorrectly three times will cause the PIN to become blocked.
Entering the *Admin PIN* or *Reset Code* incorrectly three times destroys all GnuPG data on the card. Entering the *Admin PIN* or *Reset Code* incorrectly three times destroys all GnuPG data on the card.
Name | Default Value | Use Name | Default Value | Capability
-----------|---------------|------------------------------------------------------------- -----------|---------------|-------------------------------------------------------------
PIN | `123456` | cryptographic operations (decrypt, sign, authenticate) PIN PIN | `123456` | cryptographic operations (decrypt, sign, authenticate)
Admin PIN | `12345678` | reset PIN, change Reset Code, add keys and owner information Admin PIN | `12345678` | reset PIN, change Reset Code, add keys and owner information
Reset Code | None | reset PIN ([more information](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055)) Reset Code | None | reset PIN ([more information](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055))
@ -865,160 +875,118 @@ Reset Code | None | reset PIN ([more information](https://forum.yubico.
A maximum of 127 ASCII characters are allowed. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for more information. A maximum of 127 ASCII characters are allowed. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for more information.
Update PINs: Determine the desired PIN values and set them manually, or generate them randomly:
```console ```console
gpg/card> passwd ADMIN_PIN=$(LC_ALL=C tr -dc '0-9' < /dev/urandom | \
gpg: OpenPGP card no. D2760001240102010006055532110000 detected fold -w 30 | sed "-es/./ /"{1..26..5} | \
cut -c2- | tr " " "-" | head -1)
1 - change PIN USER_PIN=$(LC_ALL=C tr -dc '0-9' < /dev/urandom | \
2 - unblock PIN fold -w 15 | sed "-es/./ /"{1..26..5} | \
3 - change Admin PIN cut -c2- | tr " " "-" | head -1)
4 - set the Reset Code
Q - quit
Your selection? 3 echo "Admin PIN: $ADMIN_PIN\nUser PIN: $USER_PIN"
PIN changed. ```
1 - change PIN Update the admin PIN:
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? 1 ```console
PIN changed. gpg --command-fd=0 --pinentry-mode=loopback --change-pin <<EOF
3
12345678
$ADMIN_PIN
$ADMIN_PIN
q
EOF
```
1 - change PIN Update the user PIN:
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? q ```console
gpg --command-fd=0 --pinentry-mode=loopback --change-pin <<EOF
1
123456
$USER_PIN
$USER_PIN
q
EOF
``` ```
**Note** The number of retry attempts can be changed later with the following command, documented [here](https://docs.yubico.com/software/yubikey/tools/ykman/OpenPGP_Commands.html#ykman-openpgp-access-set-retries-options-pin-retries-reset-code-retries-admin-pin-retries): **Note** The number of retry attempts can be changed later with the following command, documented [here](https://docs.yubico.com/software/yubikey/tools/ykman/OpenPGP_Commands.html#ykman-openpgp-access-set-retries-options-pin-retries-reset-code-retries-admin-pin-retries):
```bash ```console
ykman openpgp access set-retries 5 5 5 -f -a YOUR_ADMIN_PIN ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
``` ```
## Set information ## Set attributes
While still in administrative mode: Set the [smart card attributes](https://gnupg.org/howtos/card-howto/en/smartcard-howto-single.html):
```console ```console
gpg/card> list gpg --command-fd=0 --pinentry-mode=loopback --edit-card <<EOF
admin
gpg/card> name login
Cardholder's surname: User example@yubikey
Cardholder's given name: YubiKey $ADMIN_PIN
name
gpg/card> lang User
Language preferences: en YubiKey
quit
gpg/card> login EOF
Login data (account name): yubikey@example
gpg/card> quit
``` ```
# Transfer Subkeys # Transfer Subkeys
**Important** Verify a backup of Subkeys was made before proceeding. Transferring keys to YubiKey is a one-way operation: `keytocard` converts the local, on-disk key into a stub, which means the on-disk copy is no longer usable to transfer to subsequent YubiKeys. **Important** Verify a backup of Subkeys was made before proceeding. Transferring keys to YubiKey is a one-way operation: `keytocard` converts the local, on-disk key into a stub, which means the on-disk copy is no longer usable to transfer to subsequent YubiKeys.
The currently selected key(s) are indicated with an `*` symbol. The currently selected key(s) are indicated with an `*` symbol. When transferring keys, only one subkey must be selected at a time.
When transferring keys, only one subkey must be selected at a time.
```console
gpg --edit-key $KEYID
```
The Certify key passphrase and Admin PIN are required to transfer keys. The Certify key passphrase and Admin PIN are required to transfer keys.
## Signature key ## Signature key
Type `key 1` to select the first key and `keytocard` to transfer it, then `1` as the destination: Transfer the first key:
```console ```console
gpg> key 1 gpg --command-fd=0 --pinentry-mode=loopback --edit-key $KEYID <<EOF
key 1
sec rsa4096/0xF0F2CFEB04341FB5 keytocard
created: 2024-01-01 expires: never usage: C 1
trust: ultimate validity: ultimate $PASS
ssb* rsa4096/0xB3CD10E502E19637 $ADMIN_PIN
created: 2024-01-01 expires: 2026-01-01 usage: S save
ssb rsa4096/0x30CBE8C4B085B9F7 EOF
created: 2024-01-01 expires: 2026-01-01 usage: E
ssb rsa4096/0xAD9E24E1B8CB9600
created: 2024-01-01 expires: 2026-01-01 usage: A
[ultimate] (1). YubiKey User <yubikey@example>
gpg> keytocard
Please select where to store the key:
(1) Signature key
(3) Authentication key
Your selection? 1
``` ```
## Encryption key ## Encryption key
Type `key 1` again to deselect the first key and `key 2` to select the next key, then `keytocard` to transfer it, then `2` as the destination: Repeat the process for the second key:
```console ```console
gpg> key 1 gpg --command-fd=0 --pinentry-mode=loopback --edit-key $KEYID <<EOF
key 2
gpg> key 2 keytocard
2
sec rsa4096/0xF0F2CFEB04341FB5 $PASS
created: 2024-01-01 expires: never usage: C $ADMIN_PIN
trust: ultimate validity: ultimate save
ssb rsa4096/0xB3CD10E502E19637 EOF
created: 2024-01-01 expires: 2026-01-01 usage: S
ssb* rsa4096/0x30CBE8C4B085B9F7
created: 2024-01-01 expires: 2026-01-01 usage: E
ssb rsa4096/0xAD9E24E1B8CB9600
created: 2024-01-01 expires: 2026-01-01 usage: A
[ultimate] (1). YubiKey User <yubikey@example>
gpg> keytocard
Please select where to store the key:
(2) Encryption key
Your selection? 2
``` ```
## Authentication key ## Authentication key
Type `key 2` again to deselect the second key and `key 3` to select the third key, then `keytocard` to transfer it, then `3` as the destination: Repeat the process for the third key:
```console ```console
gpg> key 2 gpg --command-fd=0 --pinentry-mode=loopback --edit-key $KEYID <<EOF
key 3
gpg> key 3 keytocard
3
sec rsa4096/0xF0F2CFEB04341FB5 $PASS
created: 2024-01-01 expires: never usage: C $ADMIN_PIN
trust: ultimate validity: ultimate save
ssb rsa4096/0xB3CD10E502E19637 EOF
created: 2024-01-01 expires: 2026-01-01 usage: S
ssb rsa4096/0x30CBE8C4B085B9F7
created: 2024-01-01 expires: 2026-01-01 usage: E
ssb* rsa4096/0xAD9E24E1B8CB9600
created: 2024-01-01 expires: 2026-01-01 usage: A
[ultimate] (1). YubiKey User <yubikey@example>
gpg> keytocard
Please select where to store the key:
(3) Authentication key
Your selection? 3
```
Save and quit:
```console
gpg> save
``` ```
# Verify transfer # Verify transfer

Write Preview
Loading…
Cancel
Save