From e0baabd1046087a9f545d9ef65539c23eb91e85f Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Mon, 6 Jan 2020 11:12:50 +0000 Subject: Update the list of unsupported functions After some more research, I decided not to implement some of the methods provided by libnitrokey. This patch adds them to the list of unsupported functions in the readme, and removes them from the list of unimplemented functions in the todo list. --- README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 12a9f6d..d62e38e 100644 --- a/README.md +++ b/README.md @@ -26,13 +26,20 @@ available but still under development. 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. -- cgit v1.2.3 From 2e543445c3059fa9decdbef718caf84696bb8786 Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Tue, 14 Jan 2020 16:15:40 +0100 Subject: Add the fill_sd_card function to Storage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This patch adds support for libnitrokey’s NK_fill_SD_card_with_random_data function. It is executed by the fill_sd_card function of the Storage struct. We also add a new test case that is set to ignore because it takes between 30 and 60 minutes to run. --- CHANGELOG.md | 1 + README.md | 4 ++++ TODO.md | 2 -- src/device/storage.rs | 53 +++++++++++++++++++++++++++++++++++++++++++++++++-- tests/device.rs | 39 +++++++++++++++++++++++++++++++++++++ 5 files changed, 95 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/CHANGELOG.md b/CHANGELOG.md index 419a942..06836d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ SPDX-License-Identifier: CC0-1.0 - Add the `get_sd_card_usage` function to the `Storage` struct. - Add the `OperationStatus` enum and the `get_operation_status` function for the `Storage` struct. +- Add the `fill_sd_card` function to the `Storage` struct. # v0.4.0 (2020-01-02) - Remove the `test-pro` and `test-storage` features. diff --git a/README.md b/README.md index d62e38e..5f775ef 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,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 diff --git a/TODO.md b/TODO.md index 8f9b898..ef2f6d4 100644 --- a/TODO.md +++ b/TODO.md @@ -3,8 +3,6 @@ Copyright (C) 2019 Robin Krahl SPDX-License-Identifier: CC0-1.0 --> -- Add support for the currently unsupported commands: - - `NK_fill_SD_card_with_random_data` - Clear passwords from memory. - Lock password safe in `PasswordSafe::drop()` (see [nitrokey-storage-firmware issue 65][]). diff --git a/src/device/storage.rs b/src/device/storage.rs index 8d45763..deb2844 100644 --- a/src/device/storage.rs +++ b/src/device/storage.rs @@ -8,7 +8,7 @@ use std::ops; use nitrokey_sys; use crate::device::{Device, FirmwareVersion, Model, Status}; -use crate::error::Error; +use crate::error::{CommandError, Error}; use crate::otp::GenerateOtp; use crate::util::{get_command_result, get_cstring, get_last_error}; @@ -700,7 +700,9 @@ impl<'a> Storage<'a> { /// Some commands may start a background operation during which no other commands can be /// executed. This method can be used to check whether such an operation is ongoing. /// - /// Currently, this is only used by the `fill_sd_card` method. + /// Currently, this is only used by the [`fill_sd_card`][] method. + /// + /// [`fill_sd_card`]: #method.fill_sd_card pub fn get_operation_status(&self) -> Result { let status = unsafe { nitrokey_sys::NK_get_progress_bar_value() }; match status { @@ -713,6 +715,53 @@ impl<'a> Storage<'a> { } } + /// Overwrites the SD card with random data. + /// + /// Ths method starts a background operation that overwrites the SD card with random data. + /// While this operation is ongoing, no other commands can be executed. Use the + /// [`get_operation_status`][] function to check the progress of the operation. + /// + /// # Errors + /// + /// - [`InvalidString`][] if one of the provided passwords contains a null byte + /// - [`WrongPassword`][] if the admin password is wrong + /// + /// # Example + /// + /// ```no_run + /// use nitrokey::OperationStatus; + /// + /// let mut manager = nitrokey::take()?; + /// let mut storage = manager.connect_storage()?; + /// storage.fill_sd_card("12345678")?; + /// loop { + /// match storage.get_operation_status()? { + /// OperationStatus::Ongoing(progress) => println!("{}/100", progress), + /// OperationStatus::Idle => { + /// println!("Done!"); + /// break; + /// } + /// } + /// } + /// # Ok::<(), nitrokey::Error>(()) + /// ``` + /// + /// [`get_operation_status`]: #method.get_operation_status + /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString + /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword + pub fn fill_sd_card(&mut self, admin_pin: &str) -> Result<(), Error> { + let admin_pin_string = get_cstring(admin_pin)?; + get_command_result(unsafe { + nitrokey_sys::NK_fill_SD_card_with_random_data(admin_pin_string.as_ptr()) + }) + .or_else(|err| match err { + // libnitrokey’s C API returns a LongOperationInProgressException with the same error + // code as the WrongCrc command error, so we cannot distinguish them. + Error::CommandError(CommandError::WrongCrc) => Ok(()), + err => Err(err), + }) + } + /// Exports the firmware to the unencrypted volume. /// /// This command requires the admin PIN. The unencrypted volume must be in read-write mode diff --git a/tests/device.rs b/tests/device.rs index 7296372..a88c956 100644 --- a/tests/device.rs +++ b/tests/device.rs @@ -652,6 +652,45 @@ fn get_operation_status(device: Storage) { assert_ok!(OperationStatus::Idle, device.get_operation_status()); } +#[test_device] +#[ignore] +fn fill_sd_card(device: Storage) { + // This test takes up to 60 min to execute and is therefore ignored by default. Use `cargo + // test -- --ignored fill_sd_card` to run the test. + + let mut device = device; + assert_ok!((), device.factory_reset(DEFAULT_ADMIN_PIN)); + thread::sleep(time::Duration::from_secs(3)); + assert_ok!((), device.build_aes_key(DEFAULT_ADMIN_PIN)); + + let status = unwrap_ok!(device.get_storage_status()); + assert!(!status.filled_with_random); + + assert_ok!((), device.fill_sd_card(DEFAULT_ADMIN_PIN)); + assert_cmd_err!(CommandError::WrongCrc, device.get_status()); + + let mut status = OperationStatus::Ongoing(0); + let mut last_progress = 0u8; + while status != OperationStatus::Idle { + status = unwrap_ok!(device.get_operation_status()); + if let OperationStatus::Ongoing(progress) = status { + assert!(progress <= 100, "progress = {}", progress); + assert!( + progress >= last_progress, + "progress = {}, last_progress = {}", + progress, + last_progress + ); + last_progress = progress; + + thread::sleep(time::Duration::from_secs(10)); + } + } + + let status = unwrap_ok!(device.get_storage_status()); + assert!(status.filled_with_random); +} + #[test_device] fn export_firmware(device: Storage) { let mut device = device; -- cgit v1.2.3 From 1bc96cf8391977358f77741c63298894f52b7aff Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Tue, 14 Jan 2020 18:01:20 +0100 Subject: Update readme: usage, features, system libnitrokey This patch updates the readme with: - more usage information, especially a pointer to the examples and to nitrocli, - information about the supported features (= everything), - information on how to use the system libnitrokey instead of building it from source. --- README.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 5f775ef..8ce093e 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,28 @@ 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 @@ -92,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://docs.rs/crate/nitrokey/0.4.0/source/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 -- cgit v1.2.3