Skip to content

Latest commit

 

History

History
193 lines (106 loc) · 6.05 KB

USAGE.md

File metadata and controls

193 lines (106 loc) · 6.05 KB
Raw

Command-Line Help for ybdec

This document contains the help content for the ybdec command-line program.

Command Overview:

ybdec

Ybdec is a simple tool that can be used to encrypt and decrypt payloads using asymmetric PIV keys. It's uses P256 keys for HPKE encryption and decryption. The tool can be used as a building block in more advanced systems, for example, as a first factor for opening password managers or storing sensitive data.

Some of the commands require PIV credentials:

  • PIV Management key should be specified in YUBIKEY_MANAGEMENT_KEY variable as a hex encoded string. It is used for administrative operations like key generation and data writing. The default PIV management key is 010203040506070801020304050607080102030405060708 but it's highly recommended to change it. You can do this with yubikey-manager tool from Yubico.

  • PIV PIN code should be specified in YUBIKEY_PIN variable as ASCII string. It's used for normal operations like decryption and sometimes data reading. The default YubiKey PIN is 123456 but it's highly recommended to change it.

Usage: ybdec <COMMAND>

Subcommands:
  • generate — Generate keypair. It will overwrite existing keypair so be careful!
  • pubkey — Export the public key
  • encrypt — Encrypt payload to the public key using HPKE
  • decrypt — Decrypt ECDH encrypted payload using the YubiKey keys
  • stash — Stash data to YubiKey PIV object
  • fetch — Get data from YubiKey slot

ybdec generate

Generate keypair. It will overwrite existing keypair so be careful!

The key type is P256 and it is always PIN protected.

Requires PIV management key in YUBIKEY_MANAGEMENT_KEY environment variable.

Usage: ybdec generate [OPTIONS]

Options:

  • --slot <SLOT> — YubiKey PIV slot

    Default value: 9d

  • --touch-policy <TOUCH_POLICY> — Touch policy for the newly generated key

    Default value: always

    Possible values:

    • default: Use the default touch policy for the slot
    • never: A physical touch is NOT required to perform private key operations
    • always: A physical touch is required to perform any private key operations. The metal contact must be touched during each operation to ensure cardholder participation
    • cached: A physical touch is required to perform any private key operations. Each touch is cached for 15 seconds, during which time multiple private key operations may be performed without additional cardholder interaction. After 15 seconds the cached touch is cleared, and further operations require another physical touch

  • -o, --output <OUTPUT> — Where to save the public key

    Default value: -

ybdec pubkey

Export the public key.

On YubiKeys with firmware >= 5.3.0 this uses the metadata command which is available without PIN.

On older YubiKeys, it tries to recover public key using ECDH and ECDSA operations, so they require PIN in YUBIKEY_PIN environment variable.

The public key is printed in PEM format.

Usage: ybdec pubkey [OPTIONS]

Options:

  • --slot <SLOT> — Which PIV slot to use

    Default value: 9d

  • -o, --output <OUTPUT> — Where to save the public key

    Default value: -

ybdec encrypt

Encrypt payload to the public key using HPKE.

Requires PIN in YUBIKEY_PIN environment variable.

Usage: ybdec encrypt <--to-self [<TO_SELF>]|--to <TO>|--context <CONTEXT>|--input <INPUT>|--output <OUTPUT>>

Options:

  • --to-self <TO_SELF> — Encrypt payload to the YubiKey itself. You can specify the slot, but by default the 9d is used

  • --to <TO> — Encrypt payload to the public key specified in file. The public key should be in PEM format

  • --context <CONTEXT> — Additional context for encryption. You must provide the same context for decryption

    Default value: ``

  • -i, --input <INPUT> — Plaintext path or - for stdin. The encryption doesn't support streaming

    Default value: -

  • -o, --output <OUTPUT> — Ciphertext path or - for stdout. The ciphertext is written in binary format

    Default value: -

ybdec decrypt

Decrypt ECDH encrypted payload using the YubiKey keys.

Requires PIN in YUBIKEY_PIN environment variable.

Usage: ybdec decrypt [OPTIONS]

Options:

  • --slot <SLOT> — Slot to use for decryption

    Default value: 9d

  • --context <CONTEXT> — Additional context for decryption. It should be the same as during encryption

    Default value: ``

  • -i, --input <INPUT> — Ciphertext path or - for stdin. The decryption doesn't support streaming

    Default value: -

  • -o, --output <OUTPUT> — Plaintext path or - for stdout

    Default value: -

ybdec stash

Stash data to YubiKey PIV object.

Requires PIV management key in YUBIKEY_MANAGEMENT_KEY environment variable.

Usage: ybdec stash [OPTIONS]

Options:

  • --slot <SLOT> — The PIV object to use for stashing

    Default value: 0x005FAEAD

  • -i, --input <INPUT> — Path to input data or - for stdin. Maximum size for an object is ~3Kb

    Default value: -

ybdec fetch

Get data from YubiKey slot.

Some slots require PIN in YUBIKEY_PIN environment variable. See The DataTags for more info.

Usage: ybdec fetch [OPTIONS]

Options:

  • --slot <SLOT> — The PIV object to use for reading. Some objects require PIN. For more information, see The DataTags for more information

    Default value: 0x005FAEAD

  • -o, --output <OUTPUT> — Path to output data or - for stdout

    Default value: -

This document was generated automatically by clap-markdown.