== 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:

- link:lib/README.adoc[libyubihsm] -- C library to expose low- and high-level functions to
  interact with a YubiHSM

- link:src/README.adoc[yubihsm-shell] -- thin wrapper around `libyubihsm` providing both
  an interactive and command-line interface to a YubiHSM

- link:pkcs11/README.adoc[yubihsm-pkcs11] -- PKCS#11 module using `libyubihsm`

- link:yhwrap/README.adoc[yubihsm-wrap] -- command-line tool to create encrypted objects (wraps) that can be imported in the YubiHSM

- link:ykhsmauth/README.adoc[libykhsmauth] -- C library for using the YubiKey HSM Auth application

- link:yubihsm-auth/README.adoc[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
- zlib

=== Documentation

Documentation for this project and the YubiHSM2 in general can be found on Yubico's https://developers.yubico.com/YubiHSM2/[developers website].

=== pre-commit

This repository uses https://pre-commit.com/[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 https://github.com/Yubico/pkcs11test[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 https://github.com/RWTH-HPC/CMake-codecov[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.
....
