diff options
author | Robin Krahl <robin.krahl@ireas.org> | 2020-01-14 19:21:26 +0100 |
---|---|---|
committer | Daniel Mueller <deso@posteo.net> | 2020-01-15 12:08:15 -0800 |
commit | 1e07212370806f3ea4ff7a6f66e5716b60ab1f77 (patch) | |
tree | c562f40b9888b9daf62a9d9a42eeef8bfa35413f /nitrokey/README.md | |
parent | 5251aa2d1665ee12245d5d5fe09c1f207272978f (diff) | |
download | nitrocli-1e07212370806f3ea4ff7a6f66e5716b60ab1f77.tar.gz nitrocli-1e07212370806f3ea4ff7a6f66e5716b60ab1f77.tar.bz2 |
Bump nitrokey dependency to version 0.5.1
This change updates the version of the nitrokey crate that we use to
0.5.1. As part of that, it replaces occurrences of Storage::get_status
with Storage::get_storage_status as the method has been renamed.
Import subrepo nitrokey/:nitrokey at 817409140a8778215d2d65d614d3672166fff576
Diffstat (limited to 'nitrokey/README.md')
-rw-r--r-- | nitrokey/README.md | 42 |
1 files changed, 32 insertions, 10 deletions
diff --git a/nitrokey/README.md b/nitrokey/README.md index 12a9f6d..9001193 100644 --- a/nitrokey/README.md +++ b/nitrokey/README.md @@ -7,32 +7,48 @@ SPDX-License-Identifier: CC0-1.0 A libnitrokey wrapper for Rust providing access to Nitrokey devices. -[Documentation][] +## Usage + +For usage information, have a look at the [API reference][API reference] and at +the [examples][] in the `examples` directory. You can also have a look at the +[`nitrocli`][] crate, a command-line interface for Nitrokey devices that uses +this crate. ## Compatibility -The required [`libnitrokey`][] version is built from source. The host system +This crate provides access to all features of the [`libnitrokey`][] C API for +both the Nitrokey Pro and the Nitrokey Storage: general configuration, one-time +password generation, the password safe and the secure storage on the Nitrokey +Storage. + +The required `libnitrokey` version is built from source. The host system must provide `libhidapi-libusb0` (Linux) or `libhidapi` (non-Linux) in the default library search path. Depending on your system, you might also have to install the [Nitrokey udev rules][]. -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. +If you want to use a precompiled version of `libnitrokey`, you can set the +`USE_SYSTEM_LIBNITROKEY` environment variable during build. In this case, +`libnitrokey` must be available in the library search path. ### Unsupported Functions The following functions provided by `libnitrokey` are deliberately not supported by `nitrokey-rs`: +- `NK_connect_with_ID`, `NK_list_devices_by_cpuID`. These functions can be + replaced by calls to `NK_connect_with_path` and `NK_list_devices`, which + also have a cleaner API. +- `NK_enable_firmware_update_pro`, `NK_change_firmware_password_pro`. These + functions execute commands that are not yet supported by the Nitrokey Pro + firmware. - `NK_get_device_model`. We know which model we connected to, so we can provide this information without calling `libnitrokey`. -- `NK_is_AES_supported`. This method is no longer needed for Nitrokey devices - with a recent firmware version. +- `NK_is_AES_supported`. This function is no longer needed for Nitrokey + devices with a recent firmware version. +- `NK_send_startup`. Currently, this function is redundant to `NK_get_time`. - `NK_set_unencrypted_volume_rorw_pin_type_user`, `NK_set_unencrypted_read_only`, `NK_set_unencrypted_read_write`. These - methods are only relevant for older firmware versions (pre-v0.51). As the + functions are only relevant for older firmware versions (pre-v0.51). As the Nitrokey Storage firmware can be updated easily, we do not support these outdated versions. - `NK_totp_get_time`, `NK_status`. These functions are deprecated. @@ -57,6 +73,10 @@ an AES key has been built. Some tests will overwrite the data stored on the Nitrokey device or perform a factory reset. Never execute the tests if you don’t want to destroy all data on any connected Nitrokey device! +The test suite contains some test that take very long to execute, for example +filling the SD card of a Nitrokey Storage with random data. These tests are +ignored per default. Use `cargo test -- --ignored` to execute the tests. + ## Acknowledgments Thanks to Nitrokey UG for providing two Nitrokey devices to support the @@ -81,7 +101,9 @@ in the `LICENSES` directory. `libnitrokey` is licensed under the [LGPL-3.0][]. `nitrokey-rs` complies with [version 3.0 of the REUSE specification][reuse]. -[Documentation]: https://docs.rs/nitrokey +[API reference]: https://docs.rs/nitrokey +[examples]: https://git.ireas.org/nitrokey-rs/tree/examples +[`nitrocli`]: https://github.com/d-e-s-o/nitrocli/tree/master/nitrocli [Nitrokey udev rules]: https://www.nitrokey.com/documentation/frequently-asked-questions-faq#openpgp-card-not-available [`libnitrokey`]: https://github.com/nitrokey/libnitrokey [`nitrokey-test`]: https://github.com/d-e-s-o/nitrokey-test |