Crate nitrokey

Expand description

Provides access to a Nitrokey device using the native libnitrokey API.

§Usage

Operations on the Nitrokey require different authentication levels. Some operations can be performed without authentication, some require user access, and some require admin access. This is modelled using the types User and Admin.

You can only connect to one Nitrokey at a time. Use the global take function to obtain an reference to the Manager singleton that keeps track of the connections. Then use the connect method to connect to any Nitrokey device. The method will return a DeviceWrapper that abstracts over the supported Nitrokey devices. You can also use connect_model, connect_librem, connect_pro or connect_storage to connect to a specific device.

To get a list of all connected Nitrokey devices, use the list_devices function. You can then connect to one of the connected devices using the connect_path function of the Manager struct.

You can call authenticate_user or authenticate_admin to get an authenticated device that can perform operations that require authentication. You can use device to go back to the unauthenticated device.

This makes sure that you can only execute a command if you have the required access rights. Otherwise, your code will not compile. The only exception are the methods to generate one-time passwords – get_hotp_code and get_totp_code. Depending on the stick configuration, these operations are available without authentication or with user authentication.

§Background operations

Some commands may start background operations. During such an operation, every new command will cause a WrongCrc error. To check whether a background operation is currently running, use the get_operation_status method.

Background operations are only available on the Nitrokey Storage. Currently, fill_sd_card is the only command that triggers a background operation.

§Examples

Connect to any Nitrokey and print its serial number:

use nitrokey::Device;

let mut manager = nitrokey::take()?;
let device = manager.connect()?;
println!("{}", device.get_serial_number()?);

Configure an HOTP slot:

use nitrokey::{Authenticate, ConfigureOtp, OtpMode, OtpSlotData};

let mut manager = nitrokey::take()?;
let device = manager.connect()?;
let slot_data = OtpSlotData::new(1, "test", "01234567890123456689", OtpMode::SixDigits);
match device.authenticate_admin("12345678") {
    Ok(mut admin) => {
        match admin.write_hotp_slot(slot_data, 0) {
            Ok(()) => println!("Successfully wrote slot."),
            Err(err) => eprintln!("Could not write slot: {}", err),
        }
    },
    Err((_, err)) => eprintln!("Could not authenticate as admin: {}", err),
}

Generate an HOTP one-time password:

use nitrokey::{Device, GenerateOtp};

let mut manager = nitrokey::take()?;
let mut device = manager.connect()?;
match device.get_hotp_code(1) {
    Ok(code) => println!("Generated HOTP code: {}", code),
    Err(err) => eprintln!("Could not generate HOTP code: {}", err),
}

Structs§

Admin: A Nitrokey device with admin authentication.
Config: The configuration for a Nitrokey.
DeviceInfo: Connection information for a Nitrokey device.
FirmwareVersion: A firmware version for a Nitrokey device.
Librem: A Librem Key device without user or admin authentication.
Manager: A manager for connections to Nitrokey devices.
OtpSlotData: The configuration for an OTP slot.
PasswordSafe: A password safe on a Nitrokey device.
PasswordSlot: A slot of a PasswordSafe.
Pro: A Nitrokey Pro device without user or admin authentication.
SdCardData: Information about the SD card in a Storage device.
SerialNumber: Serial number of a Nitrokey device.
Status: The status information common to all Nitrokey devices.
Storage: A Nitrokey Storage device without user or admin authentication.
StorageProductionInfo: Production information for a Storage device.
StorageStatus: The status of a Nitrokey Storage device.
User: A Nitrokey device with user authentication.
Version: A version of the libnitrokey library.
VolumeStatus: The status of a volume on a Nitrokey Storage device.

Enums§

CommandError: An error reported by the Nitrokey device in the response packet.
CommunicationError: A device communication error.
DeviceWrapper: A wrapper for a Nitrokey device of unknown type.
Error: An error returned by the nitrokey crate.
LibraryError: A library usage error.
LogLevel: Log level for libnitrokey.
Model: Available Nitrokey models.
OperationStatus: The progress of a background operation on the Nitrokey.
OtpMode: Modes for one-time password generation.
VolumeMode: The access mode of a volume on the Nitrokey Storage.

Constants§

DEFAULT_ADMIN_PIN: The default admin PIN for all Nitrokey devices.
DEFAULT_USER_PIN: The default user PIN for all Nitrokey devices.
SLOT_COUNTDeprecated: The number of slots in a PasswordSafe.

Traits§

Authenticate: Provides methods to authenticate as a user or as an admin using a PIN. The authenticated methods will consume the current device instance. On success, they return the authenticated device. Otherwise, they return the current unauthenticated device and the error code.
ConfigureOtp: Provides methods to configure and erase OTP slots on a Nitrokey device.
Device: A Nitrokey device.
GenerateOtp: Provides methods to generate OTP codes and to query OTP slots on a Nitrokey device.
GetPasswordSafe: Provides access to a PasswordSafe.

Functions§

force_take: Try to take an instance of the connection manager, ignoring a poisoned cache.
get_library_version: Returns the libnitrokey library version.
list_devices: List all connected Nitrokey devices.
set_debug: Enables or disables debug output. Calling this method with true is equivalent to setting the log level to Debug; calling it with false is equivalent to the log level Error (see set_log_level).
set_log_level: Sets the log level for libnitrokey. All log messages are written to the standard error stream. Setting the log level enables all log messages on the same or on a higher log level.
take: Try to take an instance of the connection manager.
take_blocking: Take an instance of the connection manager, blocking until an instance is available.

Crate nitrokeyCopy item path