diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 53 |
1 files changed, 38 insertions, 15 deletions
@@ -1,6 +1,8 @@ # libnitrokey Libnitrokey is a project to communicate with Nitrokey stick devices in clean and easy manner. Written in C++14, testable with `Catch` framework, with C API, Python access (through CFFI and C API, in future with Pybind11). + The development of this project is aimed to make it itself a living documentation of communication protocol between host and the Nitrokey stick device. + A C++14 complying compiler is required. ## Getting sources @@ -17,21 +19,29 @@ git submodule update --init --recursive ``` ## Compilation -To compile library using clang please run `make`. If you have GCC and would like to use it instead you can run: +To compile library using Clang please run `make`. If you have GCC and would like to use it instead you can run: ```bash make CXX=g++ ``` This should create a library file under path build/libnitrokey.so and compile C++ tests in unittest/ directory. ## Using with Python -To use libnitrokey with Python a [CFFI](http://cffi.readthedocs.io/en/latest/overview.html) library is required (either 2.7+ or 3.0+). -Just import it and read the C API header and it is done! You have access to the library. Example code printing HOTP code: +To use libnitrokey with Python a [CFFI](http://cffi.readthedocs.io/en/latest/overview.html) library is required (either 2.7+ or 3.0+). It can be installed with +```bash +sudo pip install cffi # for python 2.x +pip3 install cffi # for python 3.x +``` +Just import it and read the C API header and it is done! You have access to the library. Example code printing HOTP code for both devices (assuming they are both connected): ```python +#!/usr/bin/env python +import cffi + ffi = cffi.FFI() get_string = ffi.string + def get_library(): - fp = 'NK_C_API.h' # path to C API header + fp = 'NK_C_API.h' # path to C API header declarations = [] with open(fp, 'r') as f: @@ -40,23 +50,33 @@ def get_library(): for declaration in declarations: if 'extern' in declaration and not '"C"' in declaration: declaration = declaration.replace('extern', '').strip() - print(declaration) + # print(declaration) ffi.cdef(declaration) - C = ffi.dlopen("build/libnitrokey.so") # path to built library + C = ffi.dlopen("build/libnitrokey.so") # path to built library return C + def get_hotp_code(lib, i): - lib.NK_get_hotp_code(i) + return lib.NK_get_hotp_code(i) + libnitrokey = get_library() -libnitrokey.NK_set_debug(False) # do not show debug messages -libnitrokey.NK_login('P') # connect to Nitrokey Pro device +libnitrokey.NK_set_debug(False) # do not show debug messages +libnitrokey.NK_login('P') # connect to Nitrokey Pro device hotp_slot_1_code = get_hotp_code(libnitrokey, 1) -print (hotp_slot_1_code) - +print('Getting HOTP code from Nitrokey Pro: ') +print(hotp_slot_1_code) +libnitrokey.NK_logout() # disconnect device + +libnitrokey.NK_login('S') # connect to Nitrokey Storage device +hotp_slot_1_code_nitrokey_storage = get_hotp_code(libnitrokey, 1) +print('Getting HOTP code from Nitrokey Storage: ') +print(hotp_slot_1_code_nitrokey_storage) +libnitrokey.NK_logout() # disconnect device ``` +In case one of the devices or no devices are connected, unfriendly message will be printed. All available functions for Python are listed in NK_C_API.h. ## Documentation @@ -68,17 +88,18 @@ Warning! Before you run unittests please either change both your Admin and User ## Python tests Libnitrokey has a couple of tests written in Python under the path: `unittest/test_bindings.py`. The tests themselves show how to handle common requests to device. -To run them please enter `unittest` directory and execute `py.test`. For even better coverage [randomly plugin](https://pypi.python.org/pypi/pytest-randomly) could be installed. +To run them please enter `unittest` directory and execute `py.test -v` (please check the following for [py.test installation](http://doc.pytest.org/en/latest/getting-started.html)). For even better coverage [randomly plugin](https://pypi.python.org/pypi/pytest-randomly) could be installed. ## C++ tests There are also some unit tests implemented in C++: -[test_HOTP.cc](https://github.com/Nitrokey/libnitrokey/blob/master/unittest/test_HOTP.cc) -[test.cc](https://github.com/Nitrokey/libnitrokey/blob/master/unittest/test.cc) +[test_HOTP.cc](https://github.com/Nitrokey/libnitrokey/blob/master/unittest/test_HOTP.cc) (passing) +[test.cc](https://github.com/Nitrokey/libnitrokey/blob/master/unittest/test.cc) (not passing). Unit tests was written and tested with Nitrokey Pro on Ubuntu 16.04. To run them just execute binaries build in unittest/build dir after initial make. You will have to add LD_LIBRARY_PATH variable to environment though, like: ```bash +cd unittests/build LD_LIBRARY_PATH=. ./test_HOTP ``` - +or just execute `./run.sh`. The device's commands are here: [stick10_commands.h](https://github.com/Nitrokey/libnitrokey/blob/hotp_tests/include/stick10_commands.h) for Nitrokey Pro and @@ -100,5 +121,7 @@ firmware code should show how things works: * PIN protected OTP is currently not working, * Factory reset and generating AES key commands are not yet tested neither covered in unittest, * The library is not supporting Nitrokey Storage stick but it should be done in nearest future. The only working function for now (looking by Python unit tests) is getting HOTP code. +* Fix compilation warnings +* Show friendly message when no device is connected and do not abort Other tasks might be listed either in `TODO` file or on project's issues page. |