diff options
Diffstat (limited to 'nitrokey-sys/libnitrokey-v3.5/NK_C_API.h')
| -rw-r--r-- | nitrokey-sys/libnitrokey-v3.5/NK_C_API.h | 1014 |
1 files changed, 0 insertions, 1014 deletions
diff --git a/nitrokey-sys/libnitrokey-v3.5/NK_C_API.h b/nitrokey-sys/libnitrokey-v3.5/NK_C_API.h deleted file mode 100644 index d5c54a3..0000000 --- a/nitrokey-sys/libnitrokey-v3.5/NK_C_API.h +++ /dev/null @@ -1,1014 +0,0 @@ -/* - * Copyright (c) 2015-2018 Nitrokey UG - * - * This file is part of libnitrokey. - * - * libnitrokey is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * any later version. - * - * libnitrokey is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with libnitrokey. If not, see <http://www.gnu.org/licenses/>. - * - * SPDX-License-Identifier: LGPL-3.0 - */ - -#ifndef LIBNITROKEY_NK_C_API_H -#define LIBNITROKEY_NK_C_API_H - -#include <stdbool.h> -#include <stdint.h> - -#include "deprecated.h" - -#ifdef _MSC_VER -#define NK_C_API __declspec(dllexport) -#else -#define NK_C_API -#endif - -/** - * \file - * - * C API for libnitrokey - * - * \mainpage - * - * **libnitrokey** provides access to Nitrokey Pro and Nitrokey Storage devices. - * This documentation describes libnitrokey’s C API. For a list of the - * available functions, see the NK_C_API.h file. - * - * \section getting_started Example - * - * \code{.c} - * #include <stdio.h> - * #include <stdlib.h> - * #include <libnitrokey/NK_C_API.h> - * - * int main(void) - * { - * if (NK_login_auto() != 1) { - * fprintf(stderr, "No Nitrokey found.\n"); - * return 1; - * } - * - * NK_device_model model = NK_get_device_model(); - * printf("Connected to "); - * switch (model) { - * case NK_PRO: - * printf("a Nitrokey Pro"); - * break; - * case NK_STORAGE: - * printf("a Nitrokey Storage"); - * break; - * default: - * printf("an unsupported Nitrokey"); - * break; - * } - * - * char* serial_number = NK_device_serial_number(); - * if (serial_number) - * printf(" with serial number %s\n", serial_number); - * else - * printf(" -- could not query serial number!\n"); - * free(serial_number); - * - * NK_logout(); - * return 0; - * } - * \endcode - */ - -#ifdef __cplusplus -extern "C" { -#endif - - /** - * The number of slots in the password safe. - */ - extern const uint8_t NK_PWS_SLOT_COUNT; - - static const int MAXIMUM_STR_REPLY_LENGTH = 8192; - - /** - * The Nitrokey device models supported by the API. - */ - enum NK_device_model { - /** - * Use, if no supported device is connected - */ - NK_DISCONNECTED = 0, - /** - * Nitrokey Pro. - */ - NK_PRO = 1, - /** - * Nitrokey Storage. - */ - NK_STORAGE = 2 - }; - - /** - * The connection info for a Nitrokey device as a linked list. - */ - struct NK_device_info { - /** - * The model of the Nitrokey device. - */ - enum NK_device_model model; - /** - * The USB device path for NK_connect_with_path. - */ - char* path; - /** - * The serial number. - */ - char* serial_number; - /** - * The pointer to the next element of the linked list or null - * if this is the last element in the list. - */ - struct NK_device_info* next; - }; - - /** - * Stores the common device status for all Nitrokey devices. - */ - struct NK_status { - /** - * The major firmware version, e. g. 0 in v0.40. - */ - uint8_t firmware_version_major; - /** - * The minor firmware version, e. g. 40 in v0.40. - */ - uint8_t firmware_version_minor; - /** - * The serial number of the smart card. - */ - uint32_t serial_number_smart_card; - /** - * The HOTP slot to generate a password from if the numlock - * key is pressed twice (slot 0-1, or any other value to - * disable the function). - */ - uint8_t config_numlock; - /** - * The HOTP slot to generate a password from if the capslock - * key is pressed twice (slot 0-1, or any other value to - * disable the function). - */ - uint8_t config_capslock; - /** - * The HOTP slot to generate a password from if the scrolllock - * key is pressed twice (slot 0-1, or any other value to - * disable the function). - */ - uint8_t config_scrolllock; - /** - * Indicates whether the user password is required to generate - * an OTP value. - */ - bool otp_user_password; - }; - - /** - * Stores the status of a Storage device. - */ - struct NK_storage_status { - /** - * Indicates whether the unencrypted volume is read-only. - */ - bool unencrypted_volume_read_only; - /** - * Indicates whether the unencrypted volume is active. - */ - bool unencrypted_volume_active; - /** - * Indicates whether the encrypted volume is read-only. - */ - bool encrypted_volume_read_only; - /** - * Indicates whether the encrypted volume is active. - */ - bool encrypted_volume_active; - /** - * Indicates whether the hidden volume is read-only. - */ - bool hidden_volume_read_only; - /** - * Indicates whether the hidden volume is active. - */ - bool hidden_volume_active; - /** - * The major firmware version, e. g. 0 in v0.40. - */ - uint8_t firmware_version_major; - /** - * The minor firmware version, e. g. 40 in v0.40. - */ - uint8_t firmware_version_minor; - /** - * Indicates whether the firmware is locked. - */ - bool firmware_locked; - /** - * The serial number of the SD card in the Storage stick. - */ - uint32_t serial_number_sd_card; - /** - * The serial number of the smart card in the Storage stick. - */ - uint32_t serial_number_smart_card; - /** - * The number of remaining login attempts for the user PIN. - */ - uint8_t user_retry_count; - /** - * The number of remaining login attempts for the admin PIN. - */ - uint8_t admin_retry_count; - /** - * Indicates whether a new SD card was found. - */ - bool new_sd_card_found; - /** - * Indicates whether the SD card is filled with random characters. - */ - bool filled_with_random; - /** - * Indicates whether the stick has been initialized by generating - * the AES keys. - */ - bool stick_initialized; - }; - - /** - * Data about the usage of the SD card. - */ - struct NK_SD_usage_data { - /** - * The minimum write level, as a percentage of the total card - * size. - */ - uint8_t write_level_min; - /** - * The maximum write level, as a percentage of the total card - * size. - */ - uint8_t write_level_max; - }; - - - struct NK_storage_ProductionTest{ - uint8_t FirmwareVersion_au8[2]; - uint8_t FirmwareVersionInternal_u8; - uint8_t SD_Card_Size_u8; - uint32_t CPU_CardID_u32; - uint32_t SmartCardID_u32; - uint32_t SD_CardID_u32; - uint8_t SC_UserPwRetryCount; - uint8_t SC_AdminPwRetryCount; - uint8_t SD_Card_ManufacturingYear_u8; - uint8_t SD_Card_ManufacturingMonth_u8; - uint16_t SD_Card_OEM_u16; - uint16_t SD_WriteSpeed_u16; - uint8_t SD_Card_Manufacturer_u8; - }; - - NK_C_API int NK_get_storage_production_info(struct NK_storage_ProductionTest * out); - - -/** - * Set debug level of messages written on stderr - * @param state state=True - most messages, state=False - only errors level - */ - NK_C_API void NK_set_debug(bool state); - - /** - * Set debug level of messages written on stderr - * @param level (int) 0-lowest verbosity, 5-highest verbosity - */ - NK_C_API void NK_set_debug_level(const int level); - - /** - * Get the major library version, e. g. the 3 in v3.2. - * @return the major library version - */ - NK_C_API unsigned int NK_get_major_library_version(); - - /** - * Get the minor library version, e. g. the 2 in v3.2. - * @return the minor library version - */ - NK_C_API unsigned int NK_get_minor_library_version(); - - /** - * Get the library version as a string. This is the output of - * `git describe --always` at compile time, for example "v3.3" or - * "v3.3-19-gaee920b". - * The return value is a string literal and must not be freed. - * @return the library version as a string - */ - NK_C_API const char* NK_get_library_version(); - - /** - * Connect to device of given model. Currently library can be connected only to one device at once. - * @param device_model char 'S': Nitrokey Storage, 'P': Nitrokey Pro - * @return 1 if connected, 0 if wrong model or cannot connect - */ - NK_C_API int NK_login(const char *device_model); - - /** - * Connect to device of given model. Currently library can be connected only to one device at once. - * @param device_model NK_device_model: NK_PRO: Nitrokey Pro, NK_STORAGE: Nitrokey Storage - * @return 1 if connected, 0 if wrong model or cannot connect - */ - NK_C_API int NK_login_enum(enum NK_device_model device_model); - - /** - * Connect to first available device, starting checking from Pro 1st to Storage 2nd. - * @return 1 if connected, 0 if wrong model or cannot connect - */ - NK_C_API int NK_login_auto(); - - /** - * Disconnect from the device. - * @return command processing error code - */ - NK_C_API int NK_logout(); - - /** - * Query the model of the connected device. - * Returns the model of the connected device or NK_DISCONNECTED. - * - * @return true if a device is connected and the out argument has been set - */ - NK_C_API enum NK_device_model NK_get_device_model(); - - /** - * Return the debug status string. Debug purposes. This function is - * deprecated in favor of NK_get_status_as_string. - * @return string representation of the status or an empty string - * if the command failed - */ - DEPRECATED - NK_C_API char * NK_status(); - - /** - * Return the debug status string. Debug purposes. - * @return string representation of the status or an empty string - * if the command failed - */ - NK_C_API char * NK_get_status_as_string(); - - /** - * Get the stick status common to all Nitrokey devices and return the - * command processing error code. If the code is zero, i. e. the - * command was successful, the storage status is written to the output - * pointer's target. The output pointer must not be null. - * - * @param out the output pointer for the status - * @return command processing error code - */ - NK_C_API int NK_get_status(struct NK_status* out); - - /** - * Return the device's serial number string in hex. - * @return string device's serial number in hex - */ - NK_C_API char * NK_device_serial_number(); - - /** - * 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 - */ - NK_C_API uint8_t NK_get_last_command_status(); - - /** - * Lock device - cancel any user device unlocking. - * @return command processing error code - */ - NK_C_API 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 char[25] current user password - * @param user_temporary_password char[25] user temporary password to be set on device for further communication (authentication command) - * @return command processing error code - */ - NK_C_API 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 char[25] current administrator PIN - * @param admin_temporary_password char[25] admin temporary password to be set on device for further communication (authentication command) - * @return command processing error code - */ - NK_C_API int NK_first_authenticate(const char* admin_password, const char* admin_temporary_password); - - /** - * Execute a factory reset. - * @param admin_password char[20] current administrator PIN - * @return command processing error code - */ - NK_C_API int NK_factory_reset(const char* admin_password); - - /** - * Generates AES key on the device - * @param admin_password char[20] current administrator PIN - * @return command processing error code - */ - NK_C_API int NK_build_aes_key(const char* admin_password); - - /** - * Unlock user PIN locked after 3 incorrect codes tries. - * @param admin_password char[20] current administrator PIN - * @return command processing error code - */ - NK_C_API int NK_unlock_user_password(const char *admin_password, const char *new_user_password); - - /** - * Write general config to the device - * @param numlock set value in range [0-1] to send HOTP code from slot 'numlock' after double pressing numlock - * or outside the range to disable this function - * @param capslock similar to numlock but with capslock - * @param scrolllock similar to numlock but with scrolllock - * @param enable_user_password set True to enable OTP PIN protection (require PIN each OTP code request) - * @param delete_user_password (unused) - * @param admin_temporary_password current admin temporary password - * @return command processing error code - */ - NK_C_API int NK_write_config(uint8_t numlock, uint8_t capslock, uint8_t 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 is enabled PIN protected OTP - * @see NK_write_config - * @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; - - */ - NK_C_API uint8_t* NK_read_config(); - - //OTP - - /** - * Get name of given TOTP slot - * @param slot_number TOTP slot number, slot_number<15 - * @return char[20] the name of the slot - */ - NK_C_API char * NK_get_totp_slot_name(uint8_t slot_number); - - /** - * - * @param slot_number HOTP slot number, slot_number<3 - * @return char[20] the name of the slot - */ - NK_C_API 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 - */ - NK_C_API 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 - */ - NK_C_API 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, 0-numbered - * @param slot_name char[15] desired slot name. C string (requires ending '\0'; 16 bytes). - * @param secret char[40] 160-bit or 320-bit (currently Pro v0.8 only) secret as a hex string. C string (requires ending '\0'; 41 bytes). - * See NitrokeyManager::is_320_OTP_secret_supported. - * @param hotp_counter uint32_t starting value of HOTP counter - * @param use_8_digits should returned codes be 6 (false) or 8 digits (true) - * @param use_enter press ENTER key after sending OTP code using double-pressed scroll/num/capslock - * @param use_tokenID @see token_ID - * @param token_ID @see https://openauthentication.org/token-specs/, 'Class A' section - * @param temporary_password char[25] admin temporary password - * @return command processing error code - */ - NK_C_API int NK_write_hotp_slot(uint8_t slot_number, const char *slot_name, const char *secret, uint64_t hotp_counter, - bool use_8_digits, bool use_enter, bool use_tokenID, const char *token_ID, - const char *temporary_password); - - /** - * Write TOTP slot data to the device - * @param slot_number TOTP slot number, slot_number<15, 0-numbered - * @param slot_name char[15] desired slot name. C string (requires ending '\0'; 16 bytes). - * @param secret char[40] 160-bit or 320-bit (currently Pro v0.8 only) secret as a hex string. C string (requires ending '\0'; 41 bytes). - * See NitrokeyManager::is_320_OTP_secret_supported. - * @param time_window uint16_t time window for this TOTP - * @param use_8_digits should returned codes be 6 (false) or 8 digits (true) - * @param use_enter press ENTER key after sending OTP code using double-pressed scroll/num/capslock - * @param use_tokenID @see token_ID - * @param token_ID @see https://openauthentication.org/token-specs/, 'Class A' section - * @param temporary_password char[20] admin temporary password - * @return command processing error code - */ - NK_C_API int NK_write_totp_slot(uint8_t slot_number, const char *slot_name, const char *secret, uint16_t time_window, - bool use_8_digits, bool use_enter, bool use_tokenID, const char *token_ID, - const char *temporary_password); - - /** - * Get HOTP code from the device - * @param slot_number HOTP slot number, slot_number<3 - * @return HOTP code - */ - NK_C_API char * 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 char[25] user temporary password if PIN protected OTP codes are enabled, - * otherwise should be set to empty string - '' - * @return HOTP code - */ - NK_C_API char * 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 -- unused - * @param last_totp_time last time -- unused - * @param last_interval last interval --unused - * @return TOTP code - */ - NK_C_API char * 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 -- unused - * @param last_totp_time last time -- unused - * @param last_interval last interval -- unused - * @param user_temporary_password char[25] user temporary password if PIN protected OTP codes are enabled, - * otherwise should be set to empty string - '' - * @return TOTP code - */ - NK_C_API char * 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 - */ - NK_C_API int NK_totp_set_time(uint64_t time); - - /** - * Set the device time used for TOTP to the given time. Contrary to - * {@code set_time(uint64_t)}, this command fails if {@code old_time} - * > {@code time} or if {@code old_time} is zero (where {@code - * old_time} is the current time on the device). - * - * @param time new device time as Unix timestamp (seconds since - * 1970-01-01) - * @return command processing error code - */ - NK_C_API int NK_totp_set_time_soft(uint64_t time); - - // NK_totp_get_time is deprecated -- use NK_totp_set_time_soft instead - DEPRECATED - NK_C_API int NK_totp_get_time(); - - //passwords - /** - * Change administrator PIN - * @param current_PIN char[25] current PIN - * @param new_PIN char[25] new PIN - * @return command processing error code - */ - NK_C_API int NK_change_admin_PIN(const char *current_PIN, const char *new_PIN); - - /** - * Change user PIN - * @param current_PIN char[25] current PIN - * @param new_PIN char[25] new PIN - * @return command processing error code - */ - NK_C_API int NK_change_user_PIN(const char *current_PIN, const char *new_PIN); - - - /** - * Get retry count of user PIN - * @return user PIN retry count - */ - NK_C_API uint8_t NK_get_user_retry_count(); - - /** - * Get retry count of admin PIN - * @return admin PIN retry count - */ - NK_C_API uint8_t NK_get_admin_retry_count(); - //password safe - - /** - * Enable password safe access - * @param user_pin char[30] current user PIN - * @return command processing error code - */ - NK_C_API 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) - */ - NK_C_API 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 - */ - NK_C_API 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 - */ - NK_C_API 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 - */ - NK_C_API 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 char[11] name of the slot - * @param slot_login char[32] login string - * @param slot_password char[20] password string - * @return command processing error code - */ - NK_C_API 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 - */ - NK_C_API int NK_erase_password_safe_slot(uint8_t slot_number); - - /** - * Check whether AES is supported by the device - * @return 0 for no and 1 for yes - */ - NK_C_API int NK_is_AES_supported(const char *user_password); - - /** - * Get device's major firmware version - * @return major part of the version number (e.g. 0 from 0.48, 0 from 0.7 etc.) - */ - NK_C_API uint8_t NK_get_major_firmware_version(); - - /** - * Get device's minor firmware version - * @return minor part of the version number (e.g. 7 from 0.7, 48 from 0.48 etc.) - */ - NK_C_API uint8_t NK_get_minor_firmware_version(); - - /** - * Function to determine unencrypted volume PIN type - * @param minor_firmware_version - * @return Returns 1, if set unencrypted volume ro/rw pin type is User, 0 otherwise. - */ - NK_C_API int NK_set_unencrypted_volume_rorw_pin_type_user(); - - - /** - * This command is typically run to initiate - * communication with the device (altough not required). - * It sets time on device and returns its current status - * - a combination of set_time and get_status_storage commands - * Storage only - * @param seconds_from_epoch date and time expressed in seconds - */ - NK_C_API int NK_send_startup(uint64_t seconds_from_epoch); - - /** - * Unlock encrypted volume. - * Storage only - * @param user_pin user pin 20 characters - * @return command processing error code - */ - NK_C_API int NK_unlock_encrypted_volume(const char* user_pin); - - /** - * Locks encrypted volume - * @return command processing error code - */ - NK_C_API int NK_lock_encrypted_volume(); - - /** - * Unlock hidden volume and lock encrypted volume. - * Requires encrypted volume to be unlocked. - * Storage only - * @param hidden_volume_password 20 characters - * @return command processing error code - */ - NK_C_API int NK_unlock_hidden_volume(const char* hidden_volume_password); - - /** - * Locks hidden volume - * @return command processing error code - */ - NK_C_API int NK_lock_hidden_volume(); - - /** - * Create hidden volume. - * Requires encrypted volume to be unlocked. - * Storage only - * @param slot_nr slot number in range 0-3 - * @param start_percent volume begin expressed in percent of total available storage, int in range 0-99 - * @param end_percent volume end expressed in percent of total available storage, int in range 1-100 - * @param hidden_volume_password 20 characters - * @return command processing error code - */ - NK_C_API int NK_create_hidden_volume(uint8_t slot_nr, uint8_t start_percent, uint8_t end_percent, - const char *hidden_volume_password); - - /** - * Make unencrypted volume read-only. - * Device hides unencrypted volume for a second therefore make sure - * buffers are flushed before running. - * Does nothing if firmware version is not matched - * Firmware range: Storage v0.50, v0.48 and below - * Storage only - * @param user_pin 20 characters User PIN - * @return command processing error code - */ - NK_C_API int NK_set_unencrypted_read_only(const char *user_pin); - - /** - * Make unencrypted volume read-write. - * Device hides unencrypted volume for a second therefore make sure - * buffers are flushed before running. - * Does nothing if firmware version is not matched - * Firmware range: Storage v0.50, v0.48 and below - * Storage only - * @param user_pin 20 characters User PIN - * @return command processing error code - */ - NK_C_API int NK_set_unencrypted_read_write(const char *user_pin); - - /** - * Make unencrypted volume read-only. - * Device hides unencrypted volume for a second therefore make sure - * buffers are flushed before running. - * Does nothing if firmware version is not matched - * Firmware range: Storage v0.49, v0.51+ - * Storage only - * @param admin_pin 20 characters Admin PIN - * @return command processing error code - */ - NK_C_API int NK_set_unencrypted_read_only_admin(const char* admin_pin); - - /** - * Make unencrypted volume read-write. - * Device hides unencrypted volume for a second therefore make sure - * buffers are flushed before running. - * Does nothing if firmware version is not matched - * Firmware range: Storage v0.49, v0.51+ - * Storage only - * @param admin_pin 20 characters Admin PIN - * @return command processing error code - */ - NK_C_API int NK_set_unencrypted_read_write_admin(const char* admin_pin); - - /** - * Make encrypted volume read-only. - * Device hides encrypted volume for a second therefore make sure - * buffers are flushed before running. - * Firmware range: v0.49 only, future (see firmware release notes) - * Storage only - * @param admin_pin 20 characters - * @return command processing error code - */ - NK_C_API int NK_set_encrypted_read_only(const char* admin_pin); - - /** - * Make encrypted volume read-write. - * Device hides encrypted volume for a second therefore make sure - * buffers are flushed before running. - * Firmware range: v0.49 only, future (see firmware release notes) - * Storage only - * @param admin_pin 20 characters - * @return command processing error code - */ - NK_C_API int NK_set_encrypted_read_write(const char* admin_pin); - - /** - * Exports device's firmware to unencrypted volume. - * Storage only - * @param admin_pin 20 characters - * @return command processing error code - */ - NK_C_API int NK_export_firmware(const char* admin_pin); - - /** - * Clear new SD card notification. It is set after factory reset. - * Storage only - * @param admin_pin 20 characters - * @return command processing error code - */ - NK_C_API int NK_clear_new_sd_card_warning(const char* admin_pin); - - /** - * Fill SD card with random data. - * Should be done on first stick initialization after creating keys. - * Storage only - * @param admin_pin 20 characters - * @return command processing error code - */ - NK_C_API int NK_fill_SD_card_with_random_data(const char* admin_pin); - - /** - * Change update password. - * Update password is used for entering update mode, where firmware - * could be uploaded using dfu-programmer or other means. - * Storage only - * @param current_update_password 20 characters - * @param new_update_password 20 characters - * @return command processing error code - */ - NK_C_API int NK_change_update_password(const char* current_update_password, - const char* new_update_password); - - /** - * Enter update mode. Needs update password. - * When device is in update mode it no longer accepts any HID commands until - * firmware is launched (regardless of being updated or not). - * Smartcard (through CCID interface) and its all volumes are not visible as well. - * Its VID and PID are changed to factory-default (03eb:2ff1 Atmel Corp.) - * to be detected by flashing software. Result of this command can be reversed - * by using 'launch' command. - * For dfu-programmer it would be: 'dfu-programmer at32uc3a3256s launch'. - * Storage only - * @param update_password 20 characters - * @return command processing error code - */ - NK_C_API int NK_enable_firmware_update(const char* update_password); - - /** - * Get Storage stick status as string. - * Storage only - * @return string with devices attributes - */ - NK_C_API char* NK_get_status_storage_as_string(); - - /** - * Get the Storage stick status and return the command processing - * error code. If the code is zero, i. e. the command was successful, - * the storage status is written to the output pointer's target. - * The output pointer must not be null. - * - * @param out the output pointer for the storage status - * @return command processing error code - */ - NK_C_API int NK_get_status_storage(struct NK_storage_status* out); - - /** - * Get SD card usage attributes. Usable during hidden volumes creation. - * If the command was successful (return value 0), the usage data is - * written to the output pointer’s target. The output pointer must - * not be null. - * Storage only - * @param out the output pointer for the usage data - * @return command processing error code - */ - NK_C_API int NK_get_SD_usage_data(struct NK_SD_usage_data* out); - - /** - * Get SD card usage attributes as string. - * Usable during hidden volumes creation. - * Storage only - * @return string with SD card usage attributes - */ - NK_C_API char* NK_get_SD_usage_data_as_string(); - - /** - * Get progress value of current long operation. - * Storage only - * @return int in range 0-100 or -1 if device is not busy or -2 if an - * error occured - */ - NK_C_API int NK_get_progress_bar_value(); - -/** - * Returns a list of connected devices' id's, delimited by ';' character. Empty string is returned on no device found. - * Each ID could consist of: - * 1. SC_id:SD_id_p_path (about 40 bytes) - * 2. path (about 10 bytes) - * where 'path' is USB path (bus:num), 'SC_id' is smartcard ID, 'SD_id' is storage card ID and - * '_p_' and ':' are field delimiters. - * Case 2 (USB path only) is used, when the device cannot be asked about its status data (e.g. during a long operation, - * like clearing SD card. - * Internally connects to all available devices and creates a map between ids and connection objects. - * Side effects: changes active device to last detected Storage device. - * Storage only - * @example Example of returned data: '00005d19:dacc2cb4_p_0001:0010:02;000037c7:4cf12445_p_0001:000f:02;0001:000c:02' - * @return string delimited id's of connected devices - */ - NK_C_API char* NK_list_devices_by_cpuID(); - - /** - * Returns a linked list of all connected devices, or null if no devices - * are connected or an error occured. The linked list must be freed by - * calling NK_free_device_info. - * @return a linked list of all connected devices - */ - NK_C_API struct NK_device_info* NK_list_devices(); - - /** - * Free a linked list returned by NK_list_devices. - * @param the linked list to free or null - */ - NK_C_API void NK_free_device_info(struct NK_device_info* device_info); - -/** - * Connects to the device with given ID. ID's list could be created with NK_list_devices_by_cpuID. - * Requires calling to NK_list_devices_by_cpuID first. Connecting to arbitrary ID/USB path is not handled. - * On connection requests status from device and disconnects it / removes from map on connection failure. - * Storage only - * @param id Target device ID (example: '00005d19:dacc2cb4_p_0001:0010:02') - * @return 1 on successful connection, 0 otherwise - */ - NK_C_API int NK_connect_with_ID(const char* id); - - /** - * Connects to a device with the given path. The path is a USB device - * path as returned by hidapi. - * @param path the device path - * @return 1 on successful connection, 0 otherwise - */ - NK_C_API int NK_connect_with_path(const char* path); - - /** - * Blink red and green LED alternatively and infinitely (until device is reconnected). - * @return command processing error code - */ - NK_C_API int NK_wink(); - - - /** - * Enable update mode on Nitrokey Pro. - * Supported from v0.11. - * @param update_password 20 bytes update password - * @return command processing error code - */ - NK_C_API int NK_enable_firmware_update_pro(const char* update_password); - - /** - * Change update-mode password on Nitrokey Pro. - * Supported from v0.11. - * @param current_firmware_password 20 bytes update password - * @param new_firmware_password 20 bytes update password - * @return command processing error code - */ - NK_C_API int NK_change_firmware_password_pro(const char *current_firmware_password, const char *new_firmware_password); - - -// as in ReadSlot::ResponsePayload -struct ReadSlot_t { - uint8_t slot_name[15]; - uint8_t _slot_config; - uint8_t slot_token_id[13]; - uint64_t slot_counter; -}; - - -NK_C_API int NK_read_HOTP_slot(const uint8_t slot_num, struct ReadSlot_t* out); - -#ifdef __cplusplus -} -#endif - -#endif //LIBNITROKEY_NK_C_API_H |