ztman

README

ztman

Lightweight alternative to YubiKey Manager CLI for managing YubiKey PIV application.

To Do

• Sign macOS binaries, see https://github.com/mitchellh/gon
• Autotests
• Integration with ztca & ztunnel

Installation

Download from official releases.

MacOS

No additional packages are required.

Linux

To build and run on Linux, PCSC lite is required. To install on Debian-based distros, run:

sudo apt-get install libpcsclite-dev

On Fedora/CentOS:

sudo yum install pcsc-lite-devel

On FreeBSD:

sudo pkg install pcsc-lite

Windows

No prerequisites are needed. However, to use YubiKey for mTLS, SSH, etc. you need to install the official YubiKey Smart Card Minidriver as it adds additional smart functionality.

Usage

If launched without additional parameters or by double-click on the binary, ztman will interactively prompt for all required parameters. Alternatively, it can be launched from CLI with -f/--force argument along with other necessary parameters for non-interactive session.

Currently proposed usage workflow consists of 4 steps. Slot 9a is used for demonstration purposes. For more information see PIV Certificate Slots.

1. Initial configuration. Reset the PIV application, set new PIN and PUK. Randomly generated management key will be stored on the card, protected by PIN. For more information see PIV Admin Access.

ztman reset --pin $PIN --puk $PUK

1. Generate key pair and attestation statements for the given slot. For more information see PIV Attestation.

# will generate the following files
#
# piv-attestation-intermediate.crt  intermediate attestation certificate
# piv-attestation.crt               attestation certificate
# piv-ssh.pub                       public key in OpenSSH format
# piv.pub                           public key
# piv.csr                           certificate signing request

ztman attest --pin $PIN --slot 9a

1. Request certificate from your CA using CSR and/or attestation statements. For more information see ztca.

2. Import certificate

ztman import --pin $PIN --slot 9a --cert ~/ztman/9a/piv.crt

If you need to configure another slot, repeat steps 2-4 accordingly.

If a certificate has expired, it is safer to follow steps 3-4 without re-generating the key pair, which might cause troubles e.g. in cases when the same slot is used for making SSH connections.

Finally, you can get current status of the PIV application by running

ztman info