OTP

OATH is an organization that provides open authentication standards, including Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP).

Canary, Pigeon, and Epoxy all implement HOTP and TOTP.

Firmware version 3.0.x and earlier can store up to 100 OATH credentials. From firmware version 3.1.1, there is no fixed credential limit. The actual number of credentials depends on available device storage, and no more credentials can be added when the storage is full.

Firmware version 3.1.1 and later also provide two HMAC-SHA1 challenge-response slots for applications such as KeePassXC. A host can send a challenge of up to 64 bytes using OATH/PCSC commands, and the device returns the raw 20-byte HMAC-SHA1 response. Keys are write-only and cannot be read through the configuration interface.

Configure and Use OATH

Use CanoKey Console or ckman to manage OATH credentials.

CanoKey Console

The web version of CanoKey Console requires Chrome or a Chromium-based browser.

  1. Open the OATH page in CanoKey Console and connect the CanoKey.
  2. Select + at the top of the page, then choose to scan a QR code with the camera, scan a QR code on the screen, or enter the credential manually.
  3. For manual entry, provide the issuer, account, secret, type, algorithm, number of digits, and other required fields, then confirm the addition.

TOTP codes are displayed automatically. For a touch-protected TOTP credential, select the touch icon and then touch the CanoKey. To view an HOTP code, select the refresh icon beside the credential. The counter advances each time an HOTP code is calculated, so avoid calculating a code repeatedly.

ckman

After installing CanoKey Manager, use ckman to manage OATH credentials. The following examples connect through a smart-card reader whose name contains Canokeys. If your system reports a different reader name, adjust the --reader argument accordingly.

If the authentication service provides an otpauth:// URI, import it directly:

ckman --reader "Canokeys" oath accounts uri "otpauth://totp/EXAMPLE.COM:username?secret=SOMESECRET&issuer=EXAMPLE.COM&algorithm=SHA1&digits=6&period=30"

You can also provide each credential parameter separately. The following command adds a TOTP credential that uses SHA-1, six digits, and a 30-second period:

ckman --reader "Canokeys" oath accounts add \
  --oath-type TOTP \
  --algorithm SHA1 \
  --digits 6 \
  --period 30 \
  --issuer "EXAMPLE.COM" \
  "username" "SOMESECRET"

List the OATH credentials stored on the device:

ckman --reader "Canokeys" oath accounts list

Calculate codes for all TOTP credentials:

ckman --reader "Canokeys" oath accounts code

You can also provide a name to calculate or delete a specific credential:

ckman --reader "Canokeys" oath accounts code "EXAMPLE.COM:username"
ckman --reader "Canokeys" oath accounts delete "EXAMPLE.COM:username"

Run ckman oath accounts add --help for HOTP, touch confirmation, and other available options.

Optional: Enable HOTP Keyboard Output on Touch

To make CanoKey type an HOTP code when touched, configure it in CanoKey Console:

  1. Open the Admin page and connect the CanoKey.
  2. Select AUTHENTICATE and enter the Admin PIN.
  3. Enable HOTP on touch under Config.
  4. Open the OATH page and select the star icon beside the desired HOTP credential to make it the default.
  5. Disconnect and reinsert the CanoKey.

After configuration, touch the CanoKey to type the code generated by the default HOTP credential.