search

trustcrypto / python-onlykey

The OnlyKey Python Command-Line Utility is a command line tool targeted towards more advanced users. This can be used for configuration and testing.
https://docs.crp.to/command-line.html
48 stars 23 forks source link

readme

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/master/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/master/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/master/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/master/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/master/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 -Syu git python3-setuptools python3 libusb python3-pip
$ pip3 install onlykey
$ wget https://raw.githubusercontent.com/trustcrypto/trustcrypto.github.io/master/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:

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

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

One of the buttons on OnlyKey can be configured as a lock button. 0 = Disable lockbutton; 1-6 = The selected button More info

Slot Config Options

setslot [id] [type] [value]

wipeslot [id]

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

genkey [key slot] [type] [features]

Generates random private key on device

wipekey [key id]

Erases key stored at [key id]

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]

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.10
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