path: root/README.md
diff options
authorRobin Krahl <robin.krahl@ireas.org>2018-05-19 19:09:42 +0000
committerRobin Krahl <me@robin-krahl.de>2018-05-19 21:10:43 +0200
commita8517d9707e5ef313d6f4d69b51d21251c82ea91 (patch)
tree6769c8a1bfcdd2e0abcafdc95e8940f9212208ae /README.md
Initial commit
Diffstat (limited to 'README.md')
1 files changed, 64 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1cd8e24
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# nitrokey-rs
+A libnitrokey wrapper for Rust providing access to Nitrokey devices.
+nitrokey = "0.1.0"
+## Compatibility
+In order to use this crate, a [`libnitrokey`][] installation is required
+(both development headers and library). The crate is developed using version
+3.2, but any newer version should work too.
+As I only have access to a Nitrokey Pro, this crate only provides support for
+the Nitrokey Pro methods. If you want to contribute for the Nitrokey Storage,
+please send a mail to [nitrokey-rs-dev@ireas.org][].
+### Unsupported Functions
+The following functions provided by `libnitrokey` are deliberately not
+supported by `nitrokey-rs`:
+- `NK_get_time()`. This method is useless as it will always cause a timestamp
+ error on the device (see [pull request #114][] for `libnitrokey` for details).
+- `NK_get_status()`. This method only provides a string representation of
+ data that can be accessed by other methods (firmware version, seriel number,
+ configuration).
+## Tests
+The default test suite assumes that no Nitrokey device is connected and only
+performs minor sanity checks. There is another test suite that assumes that a
+Nitrokey Pro is connected (admin password `12345678`, user password `123456`).
+To execute this test suite, run `cargo test --no-default-features --features
+test-pro -- --test-threads 1`. Note that this test suite might lock your stick
+if you have different passwords!
+The `totp` and `totp_pin` tests can occasionally fail due to bad timing. Also
+make sure to run the tests sequentially (`--test-threads 1`), otherwise they
+might interfere.
+The `get_major_firmware_version` test will fail for newer `libnitrokey`
+versions as it relies on buggy behavior in version 3.2.
+## Contact
+For bug reports, patches, feature requests or other messages, please send a
+mail to [nitrokey-rs-dev@ireas.org][].
+## License
+This project is licensed under the [MIT License][]. `libnitrokey` is licensed
+under the [LGPL-3.0][].
+[Documentation]: https://docs.rs/nitrokey
+[`libnitrokey`]: https://github.com/nitrokey/libnitrokey
+[nitrokey-rs-dev@ireas.org]: mailto:nitrokey-rs-dev@ireas.org
+[pull request #114]: https://github.com/Nitrokey/libnitrokey/pull/114
+[MIT license]: https://opensource.org/licenses/MIT
+[LGPL-3.0]: https://opensource.org/licenses/lgpl-3.0.html