1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
== 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
=== 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.
....
|
