aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 603994382877fe665acfb69af75ee4333a159b04 (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
# nitrokey-rs

A libnitrokey wrapper for Rust providing access to Nitrokey devices.

[Documentation][]

```toml
[dependencies]
nitrokey = "0.2.1"
```

## Compatibility

The required [`libnitrokey`][] version is built from source.  The host system
must provide `libhidapi-libusb0` in the default library search path.

Currently, this crate provides access to the common features of the Nitrokey
Pro and the Nitrokey Storage:  general configuration, OTP generation and the
password safe.  Basic support for the secure storage on the Nitrokey Storage is
available but still under development.

### Unsupported Functions

The following functions provided by `libnitrokey` are deliberately not
supported by `nitrokey-rs`:

- `NK_get_time()`.  This method is useless as it will always cause a timestamp
  error on the device (see [pull request #114][] for `libnitrokey` for details).
- `NK_get_status()`.  This method only provides a string representation of
  data that can be accessed by other methods (firmware version, serial number,
  configuration).
- `NK_get_status_storage_as_string()`.  This method only provides an incomplete
  string representation of the data returned by `NK_get_status_storage`.

## Tests

This crate has three test suites that can be selected using features.  One test
suite (feature `test-no-device`) assumes that no Nitrokey device is connected.
The two other test suites require a Nitrokey Pro (feature `test-pro`) or a
Nitrokey Storage (feature `test-storage`) to be connected.

Use the `--features` option for Cargo to select one of the test suites.  You
cannot select more than one of the test suites at the same time.  Note that the
test suites that require a Nitrokey device assume that the device’s passwords
are the factory defaults (admin password `12345678` and user password
`123456`).  Running the test suite with a device with different passwords might
lock your device!  Also note that the test suite might delete or overwrite data
on all connected devices.

As the tests currently are not synchronized, you have to make sure that they
are not executed in parallel.  To do so, pass the option `--test-threads 1` to
the test executable.

In conclusion, you can use these commands to run the test suites:

```
$ cargo test --features test-no-device -- --test-threads 1
$ cargo test --features test-pro -- --test-threads 1
$ cargo test --features test-storage -- --test-threads 1
```

The `totp_no_pin` and `totp_pin` tests can occasionally fail due to bad timing.

## Acknowledgments

Thanks to Nitrokey UG for providing a Nitrokey Storage to support the
development of this crate.

## Contact

For bug reports, patches, feature requests or other messages, please send a
mail to [nitrokey-rs-dev@ireas.org][].

## License

This project is licensed under the [MIT License][].  `libnitrokey` is licensed
under the [LGPL-3.0][].

[Documentation]: https://docs.rs/nitrokey
[`libnitrokey`]: https://github.com/nitrokey/libnitrokey
[nitrokey-rs-dev@ireas.org]: mailto:nitrokey-rs-dev@ireas.org
[pull request #114]: https://github.com/Nitrokey/libnitrokey/pull/114
[MIT license]: https://opensource.org/licenses/MIT
[LGPL-3.0]: https://opensource.org/licenses/lgpl-3.0.html