Added description for C API functions, updated README.md

Signed-off-by: Szczepan Zalega <szczepan@nitrokey.com>

2 files changed, 268 insertions, 18 deletions

diff --git a/NK_C_API.h b/NK_C_API.h
index 2db6c01..c675998 100644
--- a/NK_C_API.h
+++ b/NK_C_API.h
@@ -9,44 +9,287 @@
 extern "C"
 {
 //Make sure each function's declaration is in one line (for automatic python declaration processing)
+
+/**
+ * Set debug level of messages written on stderr
+ * @param state state=True - all messages, state=False - only errors level
+ */
 extern void NK_set_debug(bool state);
+
+/**
+ * Connect to device of given model. Currently library can be connected only to one device at once.
+ * @param device_model 'S': Nitrokey Storage, 'P': Nitrokey Pro
+ * @return command processing error code
+ */
 extern int NK_login(const char *device_model);
+
+/**
+ * Disconnect from the device.
+ * @return command processing error code
+ */
 extern int NK_logout();
+
+/**
+ * Return the debug status string. Debug purposes.
+ * @return command processing error code
+ */
 extern const char * NK_status();
+
+/**
+ * Get last command processing status. Useful for commands which returns the results of their own and could not return
+ * an error code.
+ * @return previous command processing error code
+ */
 extern uint8_t NK_get_last_command_status();
+
+/**
+ * Lock device - cancel any user device unlocking.
+ * @return command processing error code
+ */
 extern int NK_lock_device();
+
+/**
+ * Authenticates the user on USER privilages with user_password and sets user's temporary password on device to user_temporary_password.
+ * @param user_password current user password
+ * @param user_temporary_password user temporary password to be set on device for further communication (authentication command)
+ * @return command processing error code
+ */
 extern int NK_user_authenticate(const char* user_password, const char* user_temporary_password);
+
+/**
+ * Authenticates the user on ADMIN privilages with admin_password and sets user's temporary password on device to admin_temporary_password.
+ * @param admin_password current administrator PIN
+ * @param admin_temporary_password admin temporary password to be set on device for further communication (authentication command)
+ * @return command processing error code
+ */
 extern int NK_first_authenticate(const char* admin_password, const char* admin_temporary_password);
+
+/**
+ * Execute a factory reset.
+ * @param admin_password current administrator PIN
+ * @return command processing error code
+ */
 extern int NK_factory_reset(const char* admin_password);
+
+/**
+ * Generates AES key on the device
+ * @param admin_password current administrator PIN
+ * @return command processing error code
+ */
 extern int NK_build_aes_key(const char* admin_password);
+
+/**
+ * Unlock user PIN locked after 3 incorrect codes tries.
+ * @param admin_password current administrator PIN
+ * @return command processing error code
+ */
 extern int NK_unlock_user_password(const char* admin_password);
+
+/**
+ * Write general config to the device
+ * @param numlock set True to send OTP code after double pressing numlock
+ * @param capslock set True to send OTP code after double pressing capslock
+ * @param scrolllock set True to send OTP code after double pressing scrolllock
+ * @param enable_user_password set True to enable OTP PIN protection (request PIN each OTP code request)
+ * @param delete_user_password set True to disable OTP PIN protection (request PIN each OTP code request)
+ * @param admin_temporary_password current admin temporary password
+ * @return
+ */
 extern int NK_write_config(bool numlock, bool capslock, bool scrolllock, bool enable_user_password, bool delete_user_password, const char *admin_temporary_password);
+
+/**
+ * Get currently set config - status of function Numlock/Capslock/Scrollock OTP sending and PIN protected OTP
+ * @return  uint8_t general_config[5]:
+ *            uint8_t numlock;
+              uint8_t capslock;
+              uint8_t scrolllock;
+              uint8_t enable_user_password;
+              uint8_t delete_user_password;
+
+ */
 extern uint8_t* NK_read_config();
-//otp
+
+//OTP
+
+/**
+ * Get name of given TOTP slot
+ * @param slot_number TOTP slot number, slot_number<15
+ * @return the name of the slot
+ */
 extern const char * NK_get_totp_slot_name(uint8_t slot_number);
+
+/**
+ *
+ * @param slot_number HOTP slot number, slot_number<3
+ * @return the name of the slot
+ */
 extern const char * NK_get_hotp_slot_name(uint8_t slot_number);
+
+/**
+ * Erase HOTP slot data from the device
+ * @param slot_number HOTP slot number, slot_number<3
+ * @param temporary_password admin temporary password
+ * @return command processing error code
+ */
 extern int NK_erase_hotp_slot(uint8_t slot_number, const char *temporary_password);
+
+/**
+ * Erase TOTP slot data from the device
+ * @param slot_number TOTP slot number, slot_number<15
+ * @param temporary_password admin temporary password
+ * @return command processing error code
+ */
 extern int NK_erase_totp_slot(uint8_t slot_number, const char *temporary_password);
+
+/**
+ * Write HOTP slot data to the device
+ * @param slot_number HOTP slot number, slot_number<3
+ * @param slot_name desired slot name
+ * @param secret 160-bit (20 characters) secret
+ * @param hotp_counter starting value of HOTP counter
+ * @param use_8_digits should returned codes be 6 (false) or 8 digits (true)
+ * @param temporary_password admin temporary password
+ * @return command processing error code
+ */
 extern int NK_write_hotp_slot(uint8_t slot_number, const char *slot_name, const char *secret, uint8_t hotp_counter, bool use_8_digits, const char *temporary_password);
+
+/**
+ * Write TOTP slot data to the device
+ * @param slot_number TOTP slot number, slot_number<15
+ * @param slot_name desired slot name
+ * @param secret 160-bit (20 characters) secret
+ * @param time_window time window for this TOTP
+ * @param use_8_digits should returned codes be 6 (false) or 8 digits (true)
+ * @param temporary_password admin temporary password
+ * @return command processing error code
+ */
 extern int NK_write_totp_slot(uint8_t slot_number, const char *slot_name, const char *secret, uint16_t time_window, bool use_8_digits, const char *temporary_password);
+
+/**
+ * Get HOTP code from the device
+ * @param slot_number HOTP slot number, slot_number<3
+ * @return HOTP code
+ */
 extern uint32_t NK_get_hotp_code(uint8_t slot_number);
+
+/**
+ * Get HOTP code from the device (PIN protected)
+ * @param slot_number HOTP slot number, slot_number<3
+ * @param user_temporary_password user temporary password if PIN protected OTP codes are enabled,
+ * otherwise should be set to empty string - ''
+ * @return HOTP code
+ */
 extern uint32_t NK_get_hotp_code_PIN(uint8_t slot_number, const char* user_temporary_password);
+
+/**
+ * Get TOTP code from the device
+ * @param slot_number TOTP slot number, slot_number<15
+ * @param challenge TOTP challenge
+ * @param last_totp_time last time
+ * @param last_interval last interval
+ * @return TOTP code
+ */
 extern uint32_t NK_get_totp_code(uint8_t slot_number, uint64_t challenge, uint64_t last_totp_time, uint8_t last_interval);
+
+/**
+ * Get TOTP code from the device (PIN protected)
+ * @param slot_number TOTP slot number, slot_number<15
+ * @param challenge TOTP challenge
+ * @param last_totp_time last time
+ * @param last_interval last interval
+ * @param user_temporary_password
+ * @return TOTP code
+ */
 extern uint32_t NK_get_totp_code_PIN(uint8_t slot_number, uint64_t challenge, uint64_t last_totp_time, uint8_t last_interval, const char* user_temporary_password);
+
+/**
+ * Set time on the device (for TOTP requests)
+ * @param time seconds in unix epoch (from 01.01.1970)
+ * @return command processing error code
+ */
 extern int NK_totp_set_time(uint64_t time);
+
 extern int NK_totp_get_time();
 //passwords
+/**
+ * Change administrator PIN
+ * @param current_PIN current PIN
+ * @param new_PIN new PIN
+ * @return command processing error code
+ */
 extern int NK_change_admin_PIN(char *current_PIN, char *new_PIN);
+
+/**
+ * Change user PIN
+ * @param current_PIN current PIN
+ * @param new_PIN new PIN
+ * @return command processing error code
+*/
 extern int NK_change_user_PIN(char *current_PIN, char *new_PIN);
+
+
+/**
+ * Get retry count of user PIN
+ * @return user PIN retry count
+ */
 extern uint8_t NK_get_user_retry_count();
+
+/**
+ * Get retry count of admin PIN
+ * @return admin PIN retry count
+ */
 extern uint8_t NK_get_admin_retry_count();
 //password safe
+
+/**
+ * Enable password safe access
+ * @param user_pin current user PIN
+ * @return command processing error code
+ */
 extern int NK_enable_password_safe(const char *user_pin);
+
+/**
+ * Get password safe slots' status
+ * @return uint8_t[16] slot statuses - each byte represents one slot with 0 (not programmed) and 1 (programmed)
+ */
 extern uint8_t * NK_get_password_safe_slot_status();
+
+/**
+ * Get password safe slot name
+ * @param slot_number password safe slot number, slot_number<16
+ * @return slot name
+ */
 extern const char *NK_get_password_safe_slot_name(uint8_t slot_number);
+
+/**
+ * Get password safe slot login
+ * @param slot_number password safe slot number, slot_number<16
+ * @return login from the PWS slot
+ */
 extern const char *NK_get_password_safe_slot_login(uint8_t slot_number);
+
+/**
+ * Get the password safe slot password
+ * @param slot_number password safe slot number, slot_number<16
+ * @return password from the PWS slot
+ */
 extern const char *NK_get_password_safe_slot_password(uint8_t slot_number);
+
+/**
+ * Write password safe data to the slot
+ * @param slot_number password safe slot number, slot_number<16
+ * @param slot_name name of the slot
+ * @param slot_login login string
+ * @param slot_password password string
+ * @return command processing error code
+ */
 extern int NK_write_password_safe_slot(uint8_t slot_number, const char *slot_name, const char *slot_login, const char *slot_password);
+
+/**
+ * Erase the password safe slot from the device
+ * @param slot_number password safe slot number, slot_number<16
+ * @return command processing error code
+ */
 extern int NK_erase_password_safe_slot(uint8_t slot_number);
 }
 
diff --git a/README.md b/README.md
index 1cc42ad..dca1b29 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
 # 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.
 
-Warning! Before you run unittests please either change both your Admin and User PINs on your Nitrostick to defaults (12345678 and 123456 respectively) or change the values in tests source code. If its too late, you can always reset your Nitrokey using instructions from [homepage](
-https://www.nitrokey.com/de/documentation/how-reset-nitrokey).
-
+## Getting sources
+This repository uses `git submodules`.
 To clone please use git's --recursive option like in:
 ```bash
 git clone --recursive https://github.com/Nitrokey/libnitrokey.git
@@ -13,31 +14,37 @@ git clone https://github.com/Nitrokey/libnitrokey.git
 cd libnitrokey
 git submodule update --init --recursive
 ```
+## Documentation
+There is no documentation yet, but it is meant to be included in the sources (and generated with doxygen like application if requested).
+Please check NK_C_API.h for high level commands and include/NitrokeyManager.h for lower level. All devices' commands are listed along with packet format in include/stick10_commands.h and include/stick20_commands.h respectively for Nitrokey Pro and Nitrokey Storage products.
+
+#Tests
+Warning! Before you run unittests please either change both your Admin and User PINs on your Nitrostick to defaults (12345678 and 123456 respectively) or change the values in tests source code. If you do not change them the tests might lock your device. If its too late, you can always reset your Nitrokey using instructions from [homepage](https://www.nitrokey.com/de/documentation/how-reset-nitrokey).
+
+## 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.
 
-Libnitrokey do not have at the moment any documentation. Most helpful for
-now would be unittests [currently hotp_tests branch - still in
-development, but they should show how to handle operations with Nitrokeys and
-they should be frequently updated]:
-[test_HOTP.cc](https://github.com/Nitrokey/libnitrokey/blob/hotp_tests/unittest/test_HOTP.cc)
-[test.cc](https://github.com/Nitrokey/libnitrokey/blob/hotp_tests/unittest/test.cc)
-Unit tests was written with Nitrokey Pro on Ubuntu 15.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:
+## 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)
+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
 LD_LIBRARY_PATH=. ./test_HOTP
 ```
 
-The commands are here:
+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
 [stick20_commands.h](https://github.com/Nitrokey/libnitrokey/blob/hotp_tests/include/stick20_commands.h)
 for Nitrokey Storage [which includes Nitrokey Pro commands set].
 
-For the documentation of how it works one could check readme for
-nitrokey-app project on Github:
-[Nitrokey-app - internals](https://github.com/Nitrokey/nitrokey-app/blob/master/README.md#internals) - some typos might be in links there, but one can traverse to destination manually by looking at url.
+The documentation of how it works could be found in nitrokey-app project's README on Github:
+[Nitrokey-app - internals](https://github.com/Nitrokey/nitrokey-app/blob/master/README.md#internals) - some typos might be in links there, but one can traverse to destination manually by looking at URL.
 
-One could check which commands are needed for particular operation with
-running nitrokey-app in debug mode [-d switch] and checking the logs
-[right click on tray icon and then 'Debug']. Also crosschecking with
+To peek/debug communication with device running nitrokey-app in debug mode [-d switch] and checking the logs
+[right click on tray icon and then 'Debug'] might be helpful. Also crosschecking with
 firmware code should show how things works:
 [report_protocol.c](https://github.com/Nitrokey/nitrokey-pro-firmware/blob/master/src/keyboard/report_protocol.c)
 [for Nitrokey Pro, for Storage similarly].