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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
Metadata-Version: 2.1
Name: nitrotool
Version: 0.0.0
Summary: Easy handling of NitroKey HSM USB Smard Card
Home-page: https://github.com/johndoe31415/nitrotool
Author: @johndoe31415
License: GPL-3.0
Description: # nitrotool
Nitrotool is a frontend for [OpenSC](https://github.com/OpenSC/OpenSC) to ease
handling of the NitroKey HSM USB smart card. It might work with other smart
cards as well, I'm not certain. Basically, it is just boilerplate that does
nothing more than what is already described in the [excellent OpenSC
tutorial](https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM) for the Smart
Card HSM. However, there's some annoying issues with that -- multiple tools are
needed (pkcs11-tool, pkcs15-tool, sc-hsm-tool, OpenSSL) and output formats are
sometimes not very user friendly (e.g., public keys are exported as binary DER
blobs instead of PEM files). So I wrote this little frontend to encapsulate
common tasks a bit.
## Hardware
The hardware I'm working with is the [NitroKey HSM](https://shop.nitrokey.com),
which is a quite affordable smart-card based USB HSM. I'm in no way affiliated
with them whatsoever, just think they have a pretty cool product.
## CA management and PKI
Once you've a good grip on keys that are working on your NitroKey, you might
want to use it to create a CA and issue certificates signed by that CA (which
has its key on a hardware token such as the NitroKey HSM). Lucky you, check out
the [x509sak (X.509 Swiss Army Knife)](https://github.com/johndoe31415/x509sak),
the sibling project of nitrotool, which has that exact capability.
## Usage
All commands have comprehensive help pages. You can get a summary of available
commands by typing:
```
$ ./nitrotool
Syntax: ./nitrotool [command] [options]
Available commands:
identify Check if a NitroKey is connected and list all contents
verifypin Try to login a NitroKey by entering a PIN or SO-PIN
checkengine Check if the OpenSSL engine driver works
init Initialize the smartcard for the first time, set default
SO-PIN and PIN
format Reinitialize the smartcard completely (removing all keys
and certificates) and set SO-PIN and PIN back to their
original values
changepin Change device PIN or SO-PIN
explore Explore the smartcard structure interactively
unblock Unblock the transponder's blocked PIN using the SO-PIN
keygen Create a new private keypair on the smartcard
getkey Fetch a public key from the smartcard
removekey Remove a keypair from the smartcard
gencsr Generate a certificate signing request from a HSM-
contained private key
gencrt Generate a self-signed certificate from a HSM-contained
private key
putcrt Put a certificate on the smartcard
Options vary from command to command. To receive further info, type
./nitrotool [command] --help
```
Then, you can lookup individual help pages:
```
$ ./nitrotool keygen --help
usage: ./nitrotool keygen [--id key_id] [--label key_label] [--pin pin]
[--so-path path] [-v] [--help]
keyspec
Create a new private keypair on the smartcard
positional arguments:
keyspec Key specification string to generate. Can be either
'rsa:BITLENGTH' or 'EC:CURVENAME'. Examples are
'rsa:1024', 'EC:brainpool256r1' or 'EC:prime256v1'.
optional arguments:
--id key_id Specifies the key ID to use for generating the new key.
Must be an integer and defaults to 1.
--label key_label Specifies the key label to use for generating the new
key.
--pin pin Specifies the PIN of the smartcard. If this argument is
not given, the command will ask for it interactively.
--so-path path Search path, separated by ':' characters, in which to
look for shared objects like opensc-pkcs11.so. Defaults
to /usr/local/lib:/usr/lib:/usr/lib/x86_64-linux-gnu
-v, --verbose Increase verbosity. Can be specified multiple times.
--help Show this help page.
```
## Example: General Stuff
You can first query a transponder:
```
$ ./nitrotool identify
Using reader with a card: Nitrokey Nitrokey HSM (010000000000000000000000) 00 00
Version : 2.6
Config options :
User PIN reset with SO-PIN enabled
SO-PIN tries left : 15
User PIN tries left : 3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Default SO-PIN: 3537363231383830 Default PIN: 648219
pkcs15-tool --dump
Using reader with a card: Nitrokey Nitrokey HSM (010000000000000000000000) 00 00
PKCS#15 Card [SmartCard-HSM]:
Version : 0
Serial number : DENK#######
Manufacturer ID: www.CardContact.de
Flags :
PIN [UserPIN]
Object Flags : [0x3], private, modifiable
Auth ID : 02
ID : 01
Flags : [0x812], local, initialized, exchangeRefData
Length : min_len:6, max_len:15, stored_len:0
Pad char : 0x00
Reference : 129 (0x81)
Type : ascii-numeric
Path : e82b0601040181c31f0201::
Tries left : 3
PIN [SOPIN]
Object Flags : [0x1], private
ID : 02
Flags : [0x9A], local, unblock-disabled, initialized, soPin
Length : min_len:16, max_len:16, stored_len:0
Pad char : 0x00
Reference : 136 (0x88)
Type : bcd
Path : e82b0601040181c31f0201::
Tries left : 15
```
Then, you could use it to generate a new private key:
```
$ ./nitrotool genkey EC:prime256v1 --label fookey
Using slot 0 with a present token (0x0)
Logging in to "UserPIN (SmartCard-HSM)".
Please enter User PIN:
Key pair generated:
Private Key Object; EC
label: fookey
ID: 01
Usage: sign, derive
Public Key Object; EC EC_POINT 256 bits
EC_POINT: 04410416d236f109229332666236b7af0d46d547cbb125151e1a6a657f2b2b8495b9207d40836ae3f276b55a8989385f46f16006677939b580b66636086dc3f095a4e2
EC_PARAMS: 06082a8648ce3d030107
label: fookey
ID: 01
Usage: verify, derive
```
Check if that worked by identifying again:
```
$ ./nitrotool id
[...]
Private EC Key [fookey]
Object Flags : [0x3], private, modifiable
Usage : [0x10C], sign, signRecover, derive
Access Flags : [0x1D], sensitive, alwaysSensitive, neverExtract, local
FieldLength : 256
Key ref : 1 (0x1)
Native : yes
Auth ID : 01
ID : 01
MD:guid : 7a767d92-49ec-5894-ddf2-ca7dc72ee476
Public EC Key [fookey]
Object Flags : [0x0]
Usage : [0x40], verify
Access Flags : [0x2], extract
FieldLength : 256
Key ref : 0 (0x0)
Native : no
ID : 01
DirectValue : <present>
```
Grab the public key:
```
$ ./nitrotool getpubkey --label fookey
Using slot 0 with a present token (0x0)
Logging in to "UserPIN (SmartCard-HSM)".
Please enter User PIN:
# ECC key:
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFtI28QkikzJmYja3rw1G1UfLsSUV
HhpqZX8rK4SVuSB9QINq4/J2tVqJiThfRvFgBmd5ObWAtmY2CG3D8JWk4g==
-----END PUBLIC KEY-----
```
Or create a CSR from a HSM key:
```
$ ./nitrotool gencsr --pin 648219
engine "pkcs11" set.
-----BEGIN CERTIFICATE REQUEST-----
MIHVMH0CAQAwGzEZMBcGA1UEAwwQTml0cm9LZXkgRXhhbXBsZTBZMBMGByqGSM49
AgEGCCqGSM49AwEHA0IABBbSNvEJIpMyZmI2t68NRtVHy7ElFR4aamV/KyuElbkg
fUCDauPydrVaiYk4X0bxYAZneTm1gLZmNghtw/CVpOKgADAKBggqhkjOPQQDAgNI
ADBFAiBybom3wRlgBDmNsm34rcOol62sgi0BHbz2PqJvwBshpgIhALdHw+PkEFeJ
pQD+3QcftVe9CZJu0uW25MEcg3S/yKOG
-----END CERTIFICATE REQUEST-----
```
## Example: Setting up a NitroKey HSM for SSH authentication
Generate an RSA key. Unfortunately, currently [OpenSSH still does not support
ECDSA with PKCS#11](https://bugzilla.mindrot.org/show_bug.cgi?id=2474). This is
done simply by doing:
```
$ ./nitrotool genkey --id 1 --label my-ssh-key --pin 648219 rsa:2048
Using slot 0 with a present token (0x0)
Key pair generated:
Private Key Object; RSA
label: my-ssh-key
ID: 01
Usage: decrypt, sign, unwrap
Public Key Object; RSA 2048 bits
label: my-ssh-key
ID: 01
Usage: encrypt, verify, wrap
```
Then, extract the public key you just created from the NitroKey in SSH format:
```
$ ./nitrotool getkey --id 1 --key-format ssh --pin 648219
Using slot 0 with a present token (0x0)
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCV6Fqr80gKq+wV+MA0dMltHTuwMwyVLBvLPdtVYdsw4S2YAjfTDnLATFHOhId/fFDMbSv9qH3YI/F8ryXM8MY53J1bd3Vd5iPbnG8/Azk0F5IUw9u/bhL6/39nFWJqSKww68pe4BFtCHMfPLchT9A6lMk0QOe8rU8VNkgcZsMfQ+iDzd5OmEC7JdlJSY7kCSPHkF/SoJLk5BuftV3kVCm2VAhkMgObbNnw3xHoiL0yv/JZyBly+ssDog72EkNvbYL9bvVMk2ZqYhLESPTwMnh7x1DyznlIC2R3XuqKkrQ5ztMblCAli5S7s1yYSKj4jCYzyIZf2nfPoCTTiqNs7Eyd
```
Add that last line to the `~/.ssh/authorized_keys` file on the user/host you
want to authenticate with (i.e., the one with the OpenSSH server).
When you want to login to that server, do:
```
$ ssh -o "PKCS11Provider opensc-pkcs11.so" joe@reliant
Enter PIN for 'UserPIN (SmartCard-HSM)':
Welcome to Ubuntu 17.10 (GNU/Linux 4.13.0 x86_64)
Last login: Sat Apr 7 18:40:52 2018 from 127.0.0.1
reliant joe [~]:
```
You'll notice that you were asked to enter your NitroKey PIN. After entry, it
allows SSH access!
## Dependencies
nitrotool itself only depends on Python3, but assumes you've installed PC/SC,
OpenSC and OpenSSL. It'll use those tools on the command line.
## License
GNU GPL-3.
Keywords: nitrokey hsm smardcard
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: Unix
Description-Content-Type: text/markdown
|
