YubiHSM Shell

This repository contains most of the components used to interact with the YubiHSM 2 at both a user-facing and programmatic level.

The available components are:

• libyubihsm — C library to expose low- and high-level functions to interact with a YubiHSM

• yubihsm-shell — thin wrapper around libyubihsm providing both an interactive and command-line interface to a YubiHSM

• yubihsm-pkcs11 — PKCS#11 module using libyubihsm

• yubihsm-wrap — command-line tool to create encrypted objects (wraps) that can be imported in the YubiHSM

• libykhsmauth — C library for using the YubiKey HSM Auth application

• yubihsm-auth — command-line tool to use the YubiKey HSM Auth application

Dependencies

• cmake

• cppcheck (optional)

• gcov and lcov (optional)

• gengetopt

• help2man (optional)

• libcrypto

• libcurl

• libedit

• libusb

• libpcsclite-dev

• llvm/clang and friends

• pkg-config

• pre-commit

Documentation

Documentation for this project and the YubiHSM2 in general can be found on Yubico’s developers website.

pre-commit

This repository uses pre-commit.

$ pre-commit install

Building

$ mkdir build && cd build
$ cmake ..
$ make

Note that ninja builds are available as well:

$ mkdir build && cd build
$ cmake -GNinja ..
$ ninja

The binaries will be located in build directory. To install them on the system, run the following command. Note that this step may require admin privileges on some systems (e.g. sudo on Linux)

$ make install

Important

Building from source on Windows should be made with the source from the source release package and not directly from the cloned repository. This is due to the gengetopt library not being available for Windows.

Manpages are built by default using help2man. It is possible to skip this step with:

$ mkdir build && cd build
$ cmake -DWITHOUT_MANPAGES=1 ..
$ make

It is possible to build the libraries and binaries with static linking, this can be enabled with:

$ mkdir build && cd build
$ cmake -DENABLE_STATIC=1 ..
$ make

Linting

There is a cppcheck target that runs the source through cppcheck

$ make cppcheck

Testing

PKCS#11 tests can be run using pkcs11test.

The tool must be already built, and the path to the resulting binary must be in your PATH, or PKCS11TEST_PATH must be set.

The programs found in the /examples directory are also used as tests.

The tests can be run via

$ make test

Or using ctest directly

$ ctest

By default the tests expect a local connector running at http://localhost:12345. A different connector for the tests can be specified by setting the DEFAULT_CONNECTOR_URL environment variable. For example, to run tests using direct USB (i.e., without a connector) use

$ DEFAULT_CONNECTOR_URL="yhusb://" ctest

If you are building yubihsm-shell with ninja, the following is available:

$ ninja test

The test output can be found in …​/yubihsm-shell/build/Testing/Temporary/LastTest{,sFailed}.log.

Direct command-line output can be obtained with

$ ctest -V

Coverage

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

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/lcov related targets. For example

$ make lcov

will generate a single HTML report in ./lcov/html/all_targets/index.html

License

 Copyright 2015-2018 Yubico AB

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.