.. piv-setup.rst .. _piv-setup: ================ 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 ``. .. code-block:: 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. .. code-block:: pin=$(export LC_CTYPE=C; dd if=/dev/urandom 2>/dev/null | tr -cd '[:digit:]' | fold -w6 | head -1) echo ${pin} .. code-block:: puk=$(export LC_CTYPE=C; dd if=/dev/urandom 2>/dev/null | tr -cd '[:digit:]' | fold -w8 | head -1) echo ${puk} .. code-block:: 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. .. code:: 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: .. code:: 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``. .. code:: 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. .. code:: 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``). .. code:: env:OPENSSL_ROOT_DIR ="PATH/TO/OPENSSL_DIR" mkdir build; cd build cmake -A -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``. .. code:: env:OPENSSL_ROOT_DIR ="PATH/TO/OPENSSL_DIR" mkdir build; cd build cmake -A -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 .. code:: 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``. .. code:: 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.