Set up PIV Tool

Preparing a YubiKey for Real Use

Change the management key to make sure nobody but you can modify the state of the PIV application on the YubiKey. Make sure to keep a copy of the key around for later use.

All of these invocations leaves traces of keys and pins in the command line history. To avoid this, do not include the argument, then the software prompts for the key/pin to be input, and that response is not included in the command line history. For example, when changing the the management key, simply do not include the management key string. Use -k in the command, rather than -k <string>.

key=$(export LC_CTYPE=C; dd if=/dev/urandom 2>/dev/null | tr -d '[:lower:]' | tr -cd '[:xdigit:]' | fold -w48 | head -1)
echo ${key}
yubico-piv-tool -aset-mgm-key -n${key}

Change the PIN and PUK, as well.

pin=$(export LC_CTYPE=C; dd if=/dev/urandom 2>/dev/null | tr -cd '[:digit:]' | fold -w6 | head -1)
echo ${pin}

puk=$(export LC_CTYPE=C; dd if=/dev/urandom 2>/dev/null | tr -cd '[:digit:]' | fold -w8 | head -1)
echo ${puk}

yubico-piv-tool -achange-pin -P123456 -N${pin}
yubico-piv-tool -achange-puk -P12345678 -N${puk}

Secure Channel Communication

Some YubiKeys with firmware version 5.7.0 and higher have support for encrypted communicating over a secure channel. Encryption in Yubico PIV Tool is based on the SCP11b protocol. To activate Yubico PIV Tool encryption, add the --scp11 flag in the command line tool or open a connection with the encryption boolean, --scp11, set to true when using libykpiv during development. After encryption is activated, all subsequent communication over the same session is encrypted. Note that the SCP11b based implementation entails that the communication is encrypted, but the On-Card certificate (CERT.SD.ECKA) used to setup the encrypted session is not validated. The feature is used mainly to protect sensitive communication between the host and the YubiKey against monitoring over a medium which could potentially be eavesdropped on, such as NFC.

Building on POSIX platforms

Either clone from Git or download and unpackage the tarball, then make sure you have the pre-requisites installed and build following the steps below from the yubico-piv-tool directory.

Please make sure to have recent versions of the following packages installed on your system.

cmake libtool libssl-dev pkg-config check libpcsclite-dev gengetopt
help2man zlib-devel

Help2man is used to generate the manpages. Gengetopt version 2.22.6 or later is needed for command line parameter handling. The Vagrant VM has all these dependencies preinstalled.

Please note that these package names are debian based. Other POSIX platforms might have different names. For example, libssl-dev can probably be replaced with openssl-devel and libpcsclite-dev can probably be replaced by pcsc-lite-devel on a Redhat platform. Also note that Gengetopt might not be available on all platforms and might need to be built from source. See Gengetop Installation.

After installation of all dependencies, run the following:

cd yubico-piv-tool
mkdir build; cd build
cmake ..
make
sudo make install

On macOS, you might need to point out homebrew openssl version when running pkg-config.

PKG_CONFIG_PATH="/usr/local/opt/openssl@1.1/lib/pkgconfig" cmake ..

To statically link to OpenSSL (the libcrypto library), use the cmake option -DOPENSSL_STATIC_LINK=ON.

Do not forget you might need to be root for the last command. On Linux it might be needed to update your linked libraries after install.

sudo ldconfig

The backend to use is decided at compile time, see the summary at the end of the cmake output. Use --with-backend=foo to choose backend, replacing foo with the backend you want to use. The backends available are “pcsc”, “macscard” and “winscard” using the PCSC interface, with slightly different shared library linkage and header file names: “pcsc” is used under GNU-like systems, “macscard” under MacOS X, and “winscard” is used under Windows. In most situations, running cmake should automatically find the proper backend to use.

Building on Windows

Building on Windows requires MSBuild or Visual Studio and the MSVC compiler. It also requires building the binaries from the source release package and not from the source checked out from the repository on GitHub. This is because some files that are part of the command line shell are generated but they cannot, currently, be generated on Windows. Those files are, however, included in the source release package.

On Windows, getopt is needed to read command line arguments. The easiest way to install getopt is with the vcpkg package manager The path to getopt DLL library and include file need to be specified as a command line argument to cmake. Also the path to OpenSSL needs to be specified either as a command line argument to cmake or by setting the environment variable OPENSSL_ROOT_DIR.

The command line examples bellow are for PowerShell and the prerequisites were installed from source (using vcpkg).

env:OPENSSL_ROOT_DIR ="PATH/TO/OPENSSL_DIR"
mkdir build; cd build
cmake -A <ARCH> -DGETOPT_LIB_DIR="PATH/TO/GETOPT_DIR/lib" -DGETOPT_INCLUDE_DIR="PATH/TO/GETOPT_DIR/include ..
cmake --build .

To run the tests, check is used. The path to the check directory needs to be specified as a command line argument to cmake. Also the path to check binaries, OpenSSL binaries, libykpiv.dll and libykcs11.dll ``need to be in the ``PATH.

env:OPENSSL_ROOT_DIR ="PATH/TO/OPENSSL_DIR"
mkdir build; cd build
cmake -A <ARCH> -DGETOPT_LIB_DIR="PATH/TO/GETOPT_DIR/lib" -DGETOPT_INCLUDE_DIR="PATH/TO/GETOPT_DIR/include -DCHECK_PATH="PATH/TO/CHECK_DIR" ..
cmake --build .
$env:Path +=";PATH/TO//CHECK_DIR/bin;PATH/TO/OPENSSL_DIR/bin;PATH/TO/build\lib\Debug;PATH/TO/build\ykcs11\Debug"
ctest.exe -C Debug

For building on 32 bits system, use Win32 as ARCH. For building on 64 bits systems, use x64 as ARCH.

Coverage

Code coverage is provided courtesy of lcov and CMake-codecov This currently only works with make.

Enable coverage with

cmake -DENABLE_COVERAGE=1 ..

You can then build the project normally and run some executables (for example running the tests with make test).

At this point coverage evaluation can be generated with gcov or lcov related targets. For example, this make command generates a single HTML report in ./lcov/html/all_targets/index.html.

make lcov

Portability

The main development platform is Debian GNU/Linux. The project compiles on Windows using MSVC and the PCSC backend. It can also be built for MacOS X, also using the PCSC backend.

Card Holder Unique Identifier

For the application to be usable in windows the object CHUID (Card Holder Unique Identifier) has to be set and unique. The card contents are also aggressively cached so the CHUID has to be changed if the card contents change.