- - -

The OnlyKey Command-Line Utility is a command line interface to OnlyKey.

- - - - - - - -

- - - - -

onlykey-cli

- -

OnlyKey-cli - A command line interface to the OnlyKey (Similar functionality to OnlyKey App) that can be used for configuration, scripting, and testing.

- -

Installation

- -

Windows Stand-Alone EXE

No install is required. Download and run the EXE to open OnlyKey CLI interactive mode or run directly from command line like this:

C:\ onlykey-cli.exe getlabels
-

- -

Download here

- -

Windows Install with dependencies

1) Python 3.8 and pip3 are required. To setup a Python environment on Windows we recommend Anaconda https://www.anaconda.com/download/#windows

- -

2) From an administrator command prompt run:

pip3 install hidapi==0.9.0 onlykey
-

- -

You should see a message showing where the executable is installed. This is usually c:\python39\scripts\onlykey-cli.exe

- -

MacOS Install with dependencies

Python 3.8 and pip3 are required. To setup a Python environment on MacOS we recommend Anaconda https://www.anaconda.com/download/#macos

$ brew install libusb
-$ pip3 install onlykey
-

- -

Linux/BSD Install with dependencies

- -

In order for non-root users in Linux to be able to communicate with OnlyKey a udev rule must be created as described here.

- -

Ubuntu Install with dependencies

$ sudo apt update && sudo apt upgrade
-$ sudo apt install python3-pip python3-tk libusb-1.0-0-dev libudev-dev
-$ pip3 install onlykey
-$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/pages/49-onlykey.rules
-$ sudo cp 49-onlykey.rules /etc/udev/rules.d/
-$ sudo udevadm control --reload-rules && udevadm trigger
-

- -

Debian Install with dependencies

$ sudo apt update && sudo apt upgrade
-$ sudo apt install python3-pip python3-tk libusb-1.0-0-dev libudev-dev
-$ pip3 install onlykey
-$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/pages/49-onlykey.rules
-$ sudo cp 49-onlykey.rules /etc/udev/rules.d/
-$ sudo udevadm control --reload-rules && udevadm trigger
-

- -

RedHat Install with dependencies

$ yum update
-$ yum install python3-pip python3-devel python3-tk libusb-devel libudev-devel \
-              gcc redhat-rpm-config
-$ pip3 install onlykey
-$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/pages/49-onlykey.rules
-$ sudo cp 49-onlykey.rules /etc/udev/rules.d/
-$ sudo udevadm control --reload-rules && udevadm trigger
-

- -

Fedora Install with dependencies

$ dnf install python3-pip python3-devel python3-tkinter libusb-devel libudev-devel \
-              gcc redhat-rpm-config
-$ pip3 install onlykey
-$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/pages/49-onlykey.rules
-$ sudo cp 49-onlykey.rules /etc/udev/rules.d/
-$ sudo udevadm control --reload-rules && udevadm trigger
-

- -

OpenSUSE Install with dependencies

$ zypper install python3-pip python3-devel python3-tk libusb-1_0-devel libudev-devel
-$ pip3 install onlykey
-$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/pages/49-onlykey.rules
-$ sudo cp 49-onlykey.rules /etc/udev/rules.d/
-$ sudo udevadm control --reload-rules && udevadm trigger
-

- -

Arch Linux Install with dependencies

$ sudo pacman -Sy git python3-setuptools python3 libusb python3-pip
-$ pip3 install onlykey
-$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/pages/49-onlykey.rules
-$ sudo cp 49-onlykey.rules /etc/udev/rules.d/
-$ sudo udevadm control --reload-rules && udevadm trigger
-

- -

FreeBSD Install with dependencies

- -

See forum thread here

- -

QuickStart

- -

Usage: onlykey-cli [OPTIONS]

- -

Setup Options

- -

init

A command line tool for setting PIN on OnlyKey (Initial Configuration)

- -

General Options

- -

version

Displays the version of the app

- -

fwversion

Displays the version of the OnlyKey firmware

- -

wink

OnlyKey flashes blue (winks), may be used for visual confirmation of connectivity

- -

getlabels

Returns slot labels

- -

settime

A command for setting time on OnlyKey, time is needed for TOTP (Google Authenticator)

- -

getkeylabels

Returns key labels for RSA keys 1-4 and ECC keys 1-16

- -

rng [type]

Access OnlyKey TRNG to generate random numbers:

[type] must be one of the following: -
- hexbytes - Output hex encoded random bytes. Default 8 bytes; Maximum 255 bytes. Specify number of bytes to return with –count i.e. 'onlykey-cli rng hexbytes --count 32'
- feedkernel - Feed random bytes to /dev/random.
-

- -

OnlyKey Preferences Options

- -

idletimeout [num]

OnlyKey locks after ideletimeout is reached (1 – 255 minutes; default = 30; 0 to disable). More info

- -

wipemode [num]

Configure how the OnlyKey responds to -a factory reset. WARNING - Setting to Full Wipe mode cannot be changed. -1 = Sensitive Data Only (default); 2 = Full Wipe (recommended for plausible deniability users) Entire device is wiped. Firmware must be reloaded. More info

- -

keylayout [num]

Set keyboard layout

1 - USA_ENGLISH (Default)
2 - CANADIAN_FRENCH
3 - CANADIAN_MULTILINGUAL
4 - DANISH
5 - FINNISH
6 - FRENCH
7 - FRENCH_BELGIAN
8 - FRENCH_SWISS
9 - GERMAN
10 - GERMAN_MAC
11 - GERMAN_SWISS
12 - ICELANDIC
13 - IRISH
14 - ITALIAN
15 - NORWEGIAN
16 - PORTUGUESE
17 - PORTUGUESE_BRAZILIAN
18 - SPANISH
19 - SPANISH_LATIN_AMERICA
20 - SWEDISH
21 - TURKISH
22 - UNITED_KINGDOM
23 - US_INTERNATIONAL
24 - CZECH
25 - SERBIAN_LATIN_ONLY
26 - HUNGARIAN
27 - DANISH MAC
28 - US_DVORAK

- -

More info

- -

keytypespeed [num]

1 = slowest; 10 = fastest [7 = default] -More info

- -

ledbrightness [num]

1 = dimmest; 10 = brightest [8 = default] -More info

- -

touchsense [num]

Change the OnlyKey’s button touch sensitivity. -WARNING: Setting button’s touch sensitivity lower than 5 is not recommended as this could result in inadvertent button press. -2 = highest sensitivity; 100 = lowest sensitivity [12 = default]

- -

2ndprofilemode [num]

Set during init (Initial Configuration) to set 2nd profile type 1 = standard (default); 2 = plausible deniability

- -

storedkeymode [num]

Enable or disable challenge for stored keys (SSH/PGP) -0 = Challenge Code Required (default); 1 = Button Press Required -More info

- -

derivedkeymode [num]

Enable or disable challenge for stored keys (SSH/PGP) -0 = Challenge Code Required (default); 1 = Button Press Required -More info

- -

hmackeymode [num]

Enable or disable button press for HMAC challenge-response -0 = Button Press Required (default); 1 = Button Press Not Required. -More info

- -

backupkeymode [num]

1 = Lock backup key so this may not be changed on device -WARNING - Once set to “Locked” this cannot be changed unless a factory reset occurs. -More info

- -

sysadminmode

Enable or disable challenge for stored keys (SSH/PGP) -0 = Challenge Code Required (default); 1 = Button Press Required -More info

- -

lockbutton

Enable or disable challenge for stored keys (SSH/PGP) -0 = Challenge Code Required (default); 1 = Button Press Required -More info

- -

Slot Config Options

- -

setslot [id] [type] [value]

[id] must be slot number 1a - 6b for OnlyKey or 1-24 for OnlyKey DUO
[type] must be one of the following: -
- label - set slots (1a - 6b) to have a descriptive label i.e. My Google Acct
- url - URL to login page
- delay1 - set a 0 - 9 second delay
- addchar1 - Additional character before username 1 for TAB, 0 to clear
- username - Username to login
- addchar2 - Additional character after username 1 for TAB, 2 for RETURN
- delay2 - set a 0 - 9 second delay
- password - Password to login
- addchar3 - Additional character after password 1 for TAB, 2 for RETURN
- delay3 - set a 0 - 9 second delay
- addchar4 - Additional character before OTP 1 for TAB
- 2fa - type of two factor authentication -
  - g - Google Authenticator
  - y - Yubico OTP
  - u - U2F
  -
- totpkey - Google Authenticator key
- addchar5 - Additional character after OTP 2 for RETURN
-

- -

wipeslot [id]

[id] must be slot number 1a - 6b for OnlyKey or 1-24 for OnlyKey DUO

- -

Key Config Options

- -

setkey [key slot] [type] [features] [hex key]

Sets raw private keys and key labels, to set PEM format keys use the OnlyKey App

[key slot] must be key number RSA1 - RSA4, ECC1 - ECC16, HMAC1 - HMAC2
[type] must be one of the following: -
- label - set to have a descriptive key label i.e. My GPG signing key
- x - X25519 Key Type (32 bytes)
- n - NIST256P1 Key Type (32 bytes)
- s - SECP256K1 Key Type (32 bytes)
- 2 - RSA Key Type 2048bits (256 bytes)
- 4 - RSA Key Type 4096bits (512 bytes)
- h - HMAC Key Type (20 bytes)
-
[features] must be one of the following: -
- s - Use for signing
- d - Use for decryption
- b - Use for encryption/decryption of backups
-
For setting keys see examples here.

- -

genkey [key slot] [type] [features]

Generates random private key on device

[key slot] must be key number ECC1 - ECC16 (only ECC keys supported)
[type] must be one of the following: -
- x - X25519 Key Type (32 bytes)
- n - NIST256P1 Key Type (32 bytes)
- s - SECP256K1 Key Type (32 bytes)
-
[features] must be one of the following: -
- s - Use for signing
- d - Use for decryption
- b - Use for encryption/decryption of backups
-
For generating key see example here.

- -

wipekey [key id]

Erases key stored at [key id]

[key id] must be key number RSA1 - RSA4, ECC1 - ECC16, HMAC1 - HMAC2

- -

FIDO2 Config Options

- -

ping

Sends a FIDO2 transaction to the device, which immediately echoes the same data back. This command is defined to be a uniform function for debugging, latency and performance measurements (CTAPHID_PING).

- -

set-pin

Set new FIDO PIN, this is the PIN entered via keyboard and used for FIDO2 register/login (not the OnlyKey PIN entered on device).

- -

change-pin

Change FIDO PIN, this is the PIN entered via keyboard and used for FIDO2 register/login (not the OnlyKey PIN entered on device, to change that PIN use the OnlyKey Desktop App).

- -

credential [operation] [credential ID]

[operation] must be one of the following: -
- info - Display number of existing resident keys and remaining space.
- ls - List resident keys.
- rm [credential ID] - Remove resident keys, example here.
-

- -

reset

Reset wipes all FIDO U2F and FIDO2 credentials!!! It is highly recommended to backup device prior to reset.

- -

Running Command Options

- -

You can run commands in two ways:

- -

1) Directly in terminal

- -

Like this:

- -

$ onlykey-cli getlabels
-
-Slot 1a:
-Slot 1b:
-
-Slot 2a:
-Slot 2b:
-
-Slot 3a:
-Slot 3b:
-
-Slot 4a:
-Slot 4b:
-
-Slot 5a:
-Slot 5b:
-
-Slot 6a:
-Slot 6b:
-
-$ onlykey-cli setslot 1a label ok
-Successfully set Label
-$ onlykey-cli getlabels
-
-Slot 1a: ok
-Slot 1b:
-
-Slot 2a:
-Slot 2b:
-
-Slot 3a:
-Slot 3b:
-
-Slot 4a:
-Slot 4b:
-
-Slot 5a:
-Slot 5b:
-
-Slot 6a:
-Slot 6b:
-
-

- -

2) Interactive Mode

- -

Or you can run commands in an interactive shell like this:

- -

$ onlykey-cli
-OnlyKey CLI v1.2.8
-Press the right arrow to insert the suggestion.
-Press Control-C to retry. Control-D to exit.
-
-OnlyKey> getlabels
-
-Slot 1a:
-Slot 1b:
-
-Slot 2a:
-Slot 2b:
-
-Slot 3a:
-Slot 3b:
-
-Slot 4a:
-Slot 4b:
-
-Slot 5a:
-Slot 5b:
-
-Slot 6a:
-Slot 6b:
-
-OnlyKey> setslot 1a label ok
-
-Successfully set Label
-
-OnlyKey> getlabels
-
-Slot 1a: ok
-Slot 1b:
-
-Slot 2a:
-Slot 2b:
-
-Slot 3a:
-Slot 3b:
-
-Slot 4a:
-Slot 4b:
-
-Slot 5a:
-Slot 5b:
-
-Slot 6a:
-Slot 6b:
-
-OnlyKey> setslot 1a url accounts.google.com
-
-Successfully set URL
-
-OnlyKey> setslot 1a addchar1 2
-
-Successfully set Character1
-
-OnlyKey> setslot 1a delay1 2
-
-Successfully set Delay1
-
-OnlyKey> setslot 1a username onlykey.1234
-
-Successfully set Username
-
-OnlyKey> setslot 1a addchar2 2
-
-Successfully set Character2
-
-OnlyKey> setslot 1a delay2 2
-
-Successfully set Delay2
-
-OnlyKey> setslot 1a password
-
-Type Control-T to toggle password visible.
-Password: *********
-Successfully set Password
-
-OnlyKey> setslot 1a addchar3 2
-
-Successfully set Character3
-
-OnlyKey> setslot 1a delay3 2
-
-Successfully set Delay3
-
-OnlyKey> setslot 1a 2fa g
-
-Successfully set 2FA Type
-
-OnlyKey> setslot 1a totpkey
-
-Type Control-T to toggle password visible.
-Password: ********************************
-Successfully set TOTP Key
-
-OnlyKey> setslot 1a addchar4 2
-
-Successfully set Character4
-
-OnlyKey>
-
-Bye!
-

- -

Examples

- -

Writing Private Keys and Passwords

- -

Keys/passwords are masked when entered and should only be set from interactive mode and not directly from terminal. Entering directly from terminal is not secure as command history is stored.

- -

Setkey Examples

- -

To set key a device must first be put into config mode.

- -

Set HMAC key 1 to a custom value

- -

$ onlykey-cli

- -

OnlyKey> setkey HMAC1 h

- -

Type Control-T to toggle password visible. -Password/Key: **************

- -

Successfully set ECC Key

- -

HMAC key must be 20 bytes, h is HMAC type

- -

Set HMAC key 2 to a custom value

- -

$ onlykey-cli

- -

OnlyKey> setkey HMAC2 h

- -

Type Control-T to toggle password visible. -Password/Key: **************

- -

Successfully set ECC Key

- -

HMAC key must be 20 bytes, h is HMAC type

- -

Set ECC key in slot ECC1 to a custom value (Slots ECC1-ECC16 are available for ECC keys. Supported ECC curves X25519(x), NIST256P1(n), SECP256K1(s))

- -

$ onlykey-cli

- -

OnlyKey> setkey ECC1 x

- -

Type Control-T to toggle password visible. -Password/Key: *********************

- -

Successfully set ECC Key

- -

ECC key must be 32 bytes, x is X25519 type

- -

Genkey Examples

- -

To set key a device must first be put into config mode.

- -

Generate ECC key in slot ECC1 to a custom value (Slots ECC1-ECC16 are available for ECC keys. Supported ECC curves X25519(x), NIST256P1(n), SECP256K1(s))

- -

$ onlykey-cli

- -

OnlyKey> genkey ECC1 x

- -

Successfully set ECC Key

- -

Scripting Example

- -

Set time on OnlyKey (required for TOTP)

- -

$ onlykey-cli settime

- -

This can be added to scripts such as the UDEV rule to automatically set time when device is inserted into USB port. See example here

- -

Scripted provisioning of an OnlyKey slots and keys can be done by creating a script that sets multiple values on OnlyKey

- -

List and Remove FIDO2 Resident Key

- -

List current resident keys:

- -

onlykey-cli credential ls
-

- -

Remove a resident key by credential ID

- -

onlykey-cli credential rm eu7LPIjTNwIJt2Ws9LWJlXkiNKaueSEEGteZM2MT/lZtEuYo49V6deCiIRMb6EDC29XG13nBL60+Yx+6hxSUYS1uxX9+AA==
-

- -

Once removed, list current resident keys to verify:

- -

Source

- -

OnlyKey CLI on Github

- - - -

- - Tags: - - - - - - - - - -

- - - - - - - Edit me - - - -