blob: e6500f07408882cfd3e4202c751aa7967cc0828c (
plain)
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
|
[](https://gitlab.com/d-e-s-o/nitrocli/commits/master)
[](https://crates.io/crates/nitrocli)
[](https://blog.rust-lang.org/2020/03/12/Rust-1.42.html)
nitrocli
========
- [Changelog](CHANGELOG.md)
**nitrocli** is a program that provides a command line interface for
interaction with [Nitrokey Pro][nitrokey-pro] and [Nitrokey
Storage][nitrokey-storage] devices.
The following commands are currently supported:
- list: List all attached Nitrokey devices.
- status: Report status information about the Nitrokey.
- lock: Lock the Nitrokey.
- config: Access the Nitrokey's configuration
- get: Read the current configuration.
- set: Change the configuration.
- encrypted: Work with the Nitrokey Storage's encrypted volume.
- open: Open the encrypted volume. The user PIN needs to be entered.
- close: Close the encrypted volume.
- hidden: Work with the Nitrokey Storage's hidden volume.
- create: Create a hidden volume.
- open: Open a hidden volume with a password.
- close: Close a hidden volume.
- otp: Access one-time passwords (OTP).
- get: Generate a one-time password.
- set: Set an OTP slot.
- status: List all OTP slots.
- clear: Delete an OTP slot.
- pin: Manage the Nitrokey's PINs.
- clear: Remove the user and admin PIN from gpg-agent's cache.
- set: Change the admin or the user PIN.
- unblock: Unblock and reset the user PIN.
- pws: Access the password safe (PWS).
- get: Query the data on a PWS slot.
- set: Set the data on a PWS slot.
- status: List all PWS slots.
- clear: Delete a PWS slot.
- unencrypted: Work with the Nitrokey Storage's unencrypted volume.
- set: Change the read-write mode of the unencrypted volume.
Usage
-----
Usage is as simple as providing the name of the respective command as a
parameter (note that some commands are organized through subcommands,
which are required as well), e.g.:
```bash
# Open the nitrokey's encrypted volume.
$ nitrocli storage open
$ nitrocli status
Status:
model: Storage
serial number: 0x00053141
firmware version: 0.47
user retry count: 3
admin retry count: 3
Storage:
SD card ID: 0x05dcad1d
firmware: unlocked
storage keys: created
volumes:
unencrypted: active
encrypted: active
hidden: inactive
# Close it again.
$ nitrocli storage close
```
More examples, a more detailed explanation of the purpose, the potential
subcommands, as well as the parameters of each command are provided in
the [`man` page](doc/nitrocli.1.pdf).
Installation
------------
In addition to Rust itself and Cargo, its package management tool, the
following dependencies are required:
- **hidapi**: In order to provide USB access this library is used.
- **GnuPG**: The `gpg-connect-agent` program allows the user to enter
PINs.
#### Via Packages
Packages are available for:
- Arch Linux: [`nitrocli`][nitrocli-arch] in the Arch User Repository
- Debian: [`nitrocli`][nitrocli-debian] (since Debian Buster)
- Gentoo Linux: [`app-crypt/nitrocli`][nitrocli-gentoo] ebuild
- Ubuntu: [`nitrocli`][nitrocli-ubuntu] (since Ubuntu 19.04)
#### From Crates.io
**nitrocli** is [published][nitrocli-cratesio] on crates.io and can
directly be installed from there:
```bash
$ cargo install nitrocli --root=$PWD/nitrocli
```
#### From Source
After cloning the repository the build is as simple as running:
```bash
$ cargo build --release
```
It is recommended that the resulting executable be installed in a
directory accessible via the `PATH` environment variable.
#### Bash Completion
**nitrocli** comes with Bash completion support for options and
arguments to them. A completion script can be generated via the
`shell-complete` utility program and then only needs to be sourced to
make the current shell provide context-sensitive tab completion support.
```bash
$ cargo run --bin=shell-complete > nitrocli.bash
$ source nitrocli.bash
```
The generated completion script can be installed system-wide as usual
and sourced through Bash initialization files, such as `~/.bashrc`.
Known Problems
--------------
- Due to a problem with the default `hidapi` version on macOS, users are
advised to build and install [`libnitrokey`][] from source and then
set the `USE_SYSTEM_LIBNITROKEY` environment variable when building
`nitrocli` using one of the methods described above.
- `nitrocli` cannot connect to a Nitrokey device that is currently being
accessed by `nitrokey-app` ([upstream issue][libnitrokey#32]). To
prevent this problem, quit `nitrokey-app` before using `nitrocli`.
- Applications using the Nitrokey device (such as `nitrocli` or
`nitrokey-app`) cannot easily share access with an instance of GnuPG
running shortly afterwards ([upstream issue][libnitrokey#137]).
Public API and Stability
------------------------
**nitrocli** follows the [Semantic Versioning specification 2.0.0][semver].
Its public API is defined by the [nitrocli(1) `man` page](doc/nitrocli.1.pdf).
Contributing
------------
Contributions are generally welcome. Please follow the guidelines
outlined in [CONTRIBUTING.md](doc/CONTRIBUTING.md).
Acknowledgments
---------------
Robin Krahl ([@robinkrahl](https://github.com/robinkrahl)) has been
a crucial help for the development of **nitrocli**.
The [Nitrokey UG][nitrokey-ug] has generously provided the necessary
hardware for developing and testing the program.
License
-------
**nitrocli** is made available under the terms of the
[GPLv3][gplv3-tldr].
See the [LICENSE](LICENSE) file that accompanies this distribution for
the full text of the license.
`nitrocli` complies with [version 3.0 of the REUSE specification][reuse].
[`libnitrokey`]: https://github.com/nitrokey/libnitrokey
[nitrokey-ug]: https://www.nitrokey.com
[nitrokey-pro]: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
[nitrokey-storage]: https://shop.nitrokey.com/shop/product/nitrokey-storage-2-56
[nitrocli-arch]: https://aur.archlinux.org/packages/nitrocli
[nitrocli-cratesio]: https://crates.io/crates/nitrocli
[nitrocli-debian]: https://packages.debian.org/stable/nitrocli
[nitrocli-gentoo]: https://packages.gentoo.org/packages/app-crypt/nitrocli
[nitrocli-ubuntu]: https://packages.ubuntu.com/search?keywords=nitrocli
[gplv3-tldr]: https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)
[libnitrokey#32]: https://github.com/Nitrokey/libnitrokey/issues/32
[libnitrokey#137]: https://github.com/Nitrokey/libnitrokey/issues/137
[reuse]: https://reuse.software/practices/3.0/
[semver]: https://semver.org
|
