GoKey USB armory Mk II tutorial
The following instructions summarizes the steps required to use GoKey on a USB armory Mk II.
GoKey is meant to run on a USB armory Mk II device running its Debian base image.
While not mandatory, these instructions cover installation of GoKey with Secure Boot enabled to leverage on all its available security features.
To enable Secure Boot follow these instructions first.
It is recommended to keep the Debian installation on a microSD card and GoKey on the built-in eMMC, this way you can use the microSD to update/re-install GoKey and remove it to just run GoKey from internal storage (changing boot mode).
An OpenPGP key suited for smartcard use is recommended, though any existing key should work fine. There are several resources on-line on OpenPGP key creation and should all be applicable to GoKey (as long as the smartcard specific keytocard command is not used) but rather keys are exported armored and passed via PGP_SECRET_KEY at compile time.
Some good references to start:
Finally always ensure that existing keys are imported with minimal content, an example preparation is the following:
gpg --armor --export-options export-minimal,export-clean --export-secret-key ID
IMPORTANT: Please note that only RSA, ECDSA, ECDH keys are supported. Any other key (such as ElGamal, Ed25519) will not work.
The optional GoKey SSH management interface can be enabled with client
authentication, to this end the client public key can be passed via
SSH_PUBLIC_KEY at compile time.
All the following instructions are meant to be executed on the same USB armory Mk II unit where GoKey will be operating.
-
Configure TamaGo environment variable:
export TAMAGO=/usr/local/tamago-go/bin/go -
If desired, set any of the following optional OpenPGP cardholder information:
export URL=<public key URL>
export NAME=<cardholder name>
export LANGUAGE=<cardholder language>
export SEX=<cardholder sex>
-
Set your exported armored OpenPGP key path:
export PGP_SECRET_KEY=<secret key path> -
Set the path of OpenSSH public key, to enable client authentication:
export SSH_PUBLIC_KEY=<public key path> -
Set the Secure Boot keys path:
export HAB_KEYS=<secure boot keys path> -
Set Secure Non-Volatile Storage with forced SSH authentication:
export SNVS=ssh
git clone https://github.com/usbarmory/GoKey
cd GoKey && make imx_signed
WARNING: the following operations will destroy any previous contents on the internal eMMC card.
The eMMC can be flashed as follows:
sudo dd if=gokey-signed.imx of=/dev/mmcblk1 bs=512 seek=2 conv=fsync
You can now shut down your USB armory Mk II.
-
Ensure that the boot mode selector is set to eMMC.
-
Plug the USB armory Mk II.
-
SSH to 10.0.0.10, you should see this prompt:
help # this help
exit, quit # close session
rand # gather 32 bytes from TRNG via crypto/rand
reboot # restart
status # display smartcard/token status
init # initialize OpenPGP smartcard
lock (all|sig|dec) # OpenPGP key(s) lock
unlock (all|sig|dec) # OpenPGP key(s) unlock, prompts passphrase
rpc # PKCS#11 RPC socket
# use with 'ssh -L p11kit.sock:127.0.0.1:22'
u2f # initialize U2F token w/ user presence test
u2f !test # initialize U2F token w/o user presence test
p # confirm user presence
In case of issues establishing a network connection this page provides some help.
- Initialize the card:
> init
OpenPGP card initialized
---------------------------------------------------- OpenPGP smartcard ----
Initialized ............: true
Secure storage .........: true
Serial number ..........: ABCDEF01
Digital signature count.: 0
Secret key .............: 0011 2233 4455 6677 8899 AABB CCDD EEFF 0011 2233
Signature subkey .......: AABB CCDD EEFF 0011 2233 4455 6677 8899 AABB CCDD
encrypted: true
Decryption subkey ......: 9988 7766 5544 3322 1100 FFEE DDCC BBAA 9988 7766
encrypted: true
Authentication subkey ..: missing
- You can unlock required keys through normal
gnupguse, or do it over SSH as follows:
> unlock dec
Passphrase:
VERIFY: 99 88 77 66 55 44 33 22 11 00 FF EE DD CC BB AA 99 88 77 66 unlocked
If gnupg will later prompt a PIN for a key unlocked through SSH, just pass any 6 characters dummy value (e.g. 111111) as they key is already unlocked. This way plaintext transmission of the passhprase is prevented.
-
Import the associated card public key on your host.
-
Check
gnupgstatus:
gpg --card-status
Reader ...........: USB armory Mk II [Smart Card Control] (ABCDEF01) 00 00
Application ID ...: D276000124010304F5ECD209331C0000
Application type .: OpenPGP
Version ..........: 3.4
Manufacturer .....: F-Secure
Serial number ....: ABCDEF01
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 rsa4096
Max. PIN lengths .: 254 127 127
PIN retry counter : 3 0 0
Signature counter : 0
Signature key ....: AABB CCDD EEFF 0011 2233 4455 6677 8899 AABB CCDD
created ....: 2020-03-06 09:46:18
Encryption key....: 9988 7766 5544 3322 1100 FFEE DDCC BBAA 9988 7766
created ....: 2020-03-06 09:45:53
Authentication key: [none]
General key info..: sub nistp521/66778899AABBCCDD 2020-03-06 Test NIST P-521
sec# nistp521/0102030405060708 created: 2020-03-06 expires: never
ssb> nistp521/DDCCBBAA99887766 created: 2020-03-06 expires: never
card-no: F5EC AABBCCDD
ssb> nistp521/66778899AABBCCDD created: 2020-03-06 expires: never
card-no: F5EC AABBCCDD
ssb# nistp521/0807060504030201 created: 2020-03-06 expires: never
The > after key type tags indicate that the key is stored on a smartcard, therefore such keys can now be used with gnupg through GoKey.
