Skip to content

Latest commit

 

History

History
235 lines (189 loc) · 7.8 KB

README.md

File metadata and controls

235 lines (189 loc) · 7.8 KB
Raw

pipeline crates.io rustc

nitrocli

nitrocli is a program that provides a command line interface for interaction with Nitrokey Pro, Nitrokey Storage, and Librem Key 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.:

# Open the nitrokey's encrypted volume.
$ nitrocli storage open

$ nitrocli status
Status:
  model:             Storage
  serial number:     0x00053141
  firmware version:  v0.54
  user retry count:  3
  admin retry count: 3
  Storage:
    SD card ID:        0x05dcad1d
    SD card usage:     24% .. 99% not written
    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.

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:

From Crates.io

nitrocli is published on crates.io and can directly be installed from there:

$ cargo install nitrocli --root=$PWD/nitrocli

From Source

After cloning the repository the build is as simple as running:

$ cargo build --release

It is recommended that the resulting executable be installed in a directory accessible via the PATH environment variable.

With Nix flakes

Running nitrocli

Repository comes with a flake.nix file, so it can be run directly:

$ nix run d-e-s-o/nitrocli
Installing system-wide

nitrocli can be installed by adding the repository flake as an input:

{
  inputs = {
    nitrocli.url = "github:d-e-s-o/nitrocli?dir=contrib/nix";
    ...
  };

  outputs = {
    nitrocli,
    ...
  }: {
    # ...
    # Where modules are defined
    environment.systemPackages = [ nitrocli.defaultPackage ];
  };
  ...
}

Shell Completion

nitrocli comes with completion support for options and arguments to them (for various shells). 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.

$ cargo run --bin=shell-complete bash > nitrocli.bash
$ source nitrocli.bash

The generated completion script (bash specific, in this case) can be installed system-wide as usual and sourced through Bash initialization files, such as ~/.bashrc.

Completion scripts for other shells work in a similar manner. Please refer to the help text (--help) of the shell-complete program for the list of supported shells.

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). 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 scdaemon/GnuPG running shortly afterwards (upstream issue). As a workaround, users can kill scdaemon after calling nitrocli with gpg-connect-agent 'SCD KILLSCD' /bye.

Public API and Stability

nitrocli follows the Semantic Versioning specification 2.0.0. Its public API is defined by the nitrocli(1) man page.

Contributing

Contributions are generally welcome. Please follow the guidelines outlined in CONTRIBUTING.md.

Acknowledgments

Robin Krahl (@robinkrahl) has been a crucial help for the development of nitrocli.

The Nitrokey GmbH has generously provided the necessary hardware in the form of Nitrokey Pro and Nitrokey Storage devices for developing and testing the program.

Purism was kind enough to help development of support for Librem Keys by providing the necessary hardware devices to test on.

License

nitrocli is made available under the terms of the GPLv3.

See the LICENSE file that accompanies this distribution for the full text of the license.

nitrocli complies with version 3.0 of the REUSE specification.