You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Nicolas Stalder f24d2da2a6 Merge branch 'rgerganov-kbd' 3 weeks ago
solo Apply black/isort fixes 3 weeks ago
.editorconfig Initial commit 1 year ago
.envrc Start refactor 1 year ago
.flake8 Fix broken or_die function, linting, `make tag` 1 year ago
.gitignore Update .gitignore 1 year ago
CHANGELOG.md Update CHANGELOG.md 4 months ago
LICENSE-APACHE Initial commit 1 year ago
LICENSE-MIT Initial commit 1 year ago
Makefile Code style fixes, Releasing section in README.md 8 months ago
README.md Update README.md 8 months ago
dev-requirements.txt Fix `key verify`, `make-credential` 6 months ago
pyproject.toml Bump to v0.0.21 using fido2 >= v0.8 6 months ago

README.md

Python tool and library for SoloKeys

Getting Started

We require Python >= 3.6 and corresponding pip3 command.

We intend to support Linux, Windows and macOS. Other platforms aren’t supported by the FIDO2 library we rely on.

To get started, run pip3 install solo-python, this installs both the solo library and the solo interface.

Possible issues:

For development, we suggest you run make init instead, which

  • sets up a virtual environment
  • installs development requirements such as black
  • installs solo as symlink using our packaging tool flit, including all runtime dependencies listed in pyproject.toml

One way to ensure the virtual environment is active is to use direnv.

Solo Tool

For help, run solo --help after installation. The tool has a hierarchy of commands and subcommands.

Example:

solo ls  # lists all Solo keys connected to your machine
solo version  # outputs version of installed `solo` library and tool

solo key wink  # blinks the LED
solo key verify  # checks whether your Solo is genuine
solo key rng hexbytes  # outputs some random hex bytes generated on your key
solo key version  # outputs the version of the firmware on your key

Firmware Update

Upon release of signed firmware updates in solokeys/solo, to update the firmware on your Solo to the latest version:

  • update your solo tool if necessary via pip3 install --upgrade solo-python
  • plug in your key, keeping the button pressed until the LED flashes yellow
  • run solo key update

For possibly helpful additional information, see https://github.com/solokeys/solo/issues/113.

Library Usage

The previous solotool.py has been refactored into a library with associated CLI tool called solo.

It is still work in progress, example usage:

import solo

client = solo.client.find()

client.wink()

random_bytes = client.get_rng(32)
print(random_bytes.hex())

Comprehensive documentation coming, for now these are the main components

  • solo.client: connect to Solo Hacker and Solo Secure keys in firmware or bootloader mode
  • solo.dfu: connect to Solo Hacker in dfu mode (disabled on Solo Secure keys)
  • solo.cli: implementation of the solo command line interface

Challenge-Response

By abuse of the hmac-secret extension, we can generate static challenge responses, which are scoped to a credential. A use case might be e.g. unlocking a LUKS-encrypted drive.

DANGER The generated reponses depend on both the key and the credential. There is no way to extract or backup from the physical key, so if you intend to use the “response” as a static password, make sure to store it somewhere separately, e.g. on paper.

DANGER Also, if you generate a new credential with the same (host, user_id) pair, it will likely overwrite the old credential, and you lose the capability to generate the original responses too.

DANGER This functionality has not been sufficiently debugged, please generate GitHub issues if you detect anything.

There are two steps:

  1. Generate a credential. This can be done with solo key make-credential, storing the (hex-encoded) generated credential_id for the next step.
  2. Pick a challenge, and generate the associated response. This can be done with solo key challenge-response <credential_id> <challenge>.

License

Licensed under either of

at your option.

Contributing

Any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Code is to be formatted and linted according to Black and our Flake8 configuration Run make check to test compliance, run make fix to apply some automatic fixes.

We keep a CHANGELOG.

Releasing

For maintainers:

  • adjust solo/VERSION file as appropriate
  • add entry or entries to CHANGELOG.md (no need to repeat commit messages, but point out major changes in such a way that a user of the library has an easy entrypoint to follow development)
  • run make check and/or make fix to ensure code consistency
  • run make build to double check
  • run make publish (assumes a ~/.pypirc file with entry [pypi]), or flit publish manually
  • run make tag to tag the release and push it