C API for libnitrokey. More...

#include <stdbool.h>
#include <stdint.h>
#include "deprecated.h"

Include dependency graph for NK_C_API.h:

Data Structures
struct	NK_device_info
	The connection info for a Nitrokey device as a linked list. More...

struct	NK_status
	Stores the common device status for all Nitrokey devices. More...

struct	NK_storage_status
	Stores the status of a Storage device. More...

struct	NK_SD_usage_data
	Data about the usage of the SD card. More...

struct	NK_config
	The general configuration of a Nitrokey device. More...

struct	NK_storage_ProductionTest

struct	ReadSlot_t

struct	GetRandom_t

Enumerations
enum	NK_device_model { NK_DISCONNECTED = 0 , NK_PRO = 1 , NK_STORAGE = 2 , NK_LIBREM = 3 }
	The Nitrokey device models supported by the API. More...

Functions
NK_C_API int	NK_get_storage_production_info (struct NK_storage_ProductionTest *out)

NK_C_API void	NK_set_debug (bool state)
	Set debug level of messages written on stderr.

NK_C_API void	NK_set_debug_level (const int level)
	Set debug level of messages written on stderr.

NK_C_API void	NK_set_log_function (NK_log_function fn)
	Set a custom log function.

NK_C_API unsigned int	NK_get_major_library_version ()
	Get the major library version, e.

NK_C_API unsigned int	NK_get_minor_library_version ()
	Get the minor library version, e.

NK_C_API const char *	NK_get_library_version ()
	Get the library version as a string.

NK_C_API int	NK_login (const char *device_model)
	Connect to device of given model.

NK_C_API int	NK_login_enum (enum NK_device_model device_model)
	Connect to device of given model.

NK_C_API int	NK_login_auto ()
	Connect to first available device, starting checking from Pro 1st to Storage 2nd.

NK_C_API int	NK_logout ()
	Disconnect from the device.

NK_C_API enum NK_device_model	NK_get_device_model ()
	Query the model of the connected device.

DEPRECATED NK_C_API char *	NK_status ()
	Return the debug status string.

NK_C_API char *	NK_get_status_as_string ()
	Return the debug status string.

NK_C_API int	NK_get_status (struct NK_status *out)
	Get the stick status common to all Nitrokey devices and return the command processing error code.

NK_C_API char *	NK_device_serial_number ()
	Return the device's serial number string in hex.

NK_C_API uint32_t	NK_device_serial_number_as_u32 ()
	Return the device's serial number string as an integer.

NK_C_API uint8_t	NK_get_last_command_status ()
	Get last command processing status.

NK_C_API int	NK_lock_device ()
	Lock device - cancel any user device unlocking.

NK_C_API int	NK_user_authenticate (const char user_password, const char user_temporary_password)
	Authenticates the user on USER privilages with user_password and sets user's temporary password on device to user_temporary_password.

NK_C_API int	NK_first_authenticate (const char admin_password, const char admin_temporary_password)
	Authenticates the user on ADMIN privilages with admin_password and sets user's temporary password on device to admin_temporary_password.

NK_C_API int	NK_factory_reset (const char *admin_password)
	Execute a factory reset.

NK_C_API int	NK_build_aes_key (const char *admin_password)
	Generates AES key on the device.

NK_C_API int	NK_unlock_user_password (const char admin_password, const char new_user_password)
	Unlock user PIN locked after 3 incorrect codes tries.

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)
	Write general config to the device.

NK_C_API int	NK_write_config_struct (struct NK_config config, const char *admin_temporary_password)
	Write general config to the device.

NK_C_API uint8_t *	NK_read_config ()
	Get currently set config - status of function Numlock/Capslock/Scrollock OTP sending and is enabled PIN protected OTP The return value must be freed using NK_free_config.

NK_C_API void	NK_free_config (uint8_t *config)
	Free a value returned by NK_read_config.

NK_C_API int	NK_read_config_struct (struct NK_config *out)
	Get currently set config and write it to the given pointer.

NK_C_API char *	NK_get_totp_slot_name (uint8_t slot_number)
	Get name of given TOTP slot.

NK_C_API char *	NK_get_hotp_slot_name (uint8_t slot_number)

NK_C_API int	NK_erase_hotp_slot (uint8_t slot_number, const char *temporary_password)
	Erase HOTP slot data from the device.

NK_C_API int	NK_erase_totp_slot (uint8_t slot_number, const char *temporary_password)
	Erase TOTP slot data from the device.

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 HOTP slot data to the device.

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)
	Write TOTP slot data to the device.

NK_C_API char *	NK_get_hotp_code (uint8_t slot_number)
	Get HOTP code from the device.

NK_C_API char *	NK_get_hotp_code_PIN (uint8_t slot_number, const char *user_temporary_password)
	Get HOTP code from the device (PIN protected)

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.

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)
	Get TOTP code from the device (PIN protected)

NK_C_API int	NK_totp_set_time (uint64_t time)
	Set time on the device (for TOTP requests)

NK_C_API int	NK_totp_set_time_soft (uint64_t time)
	Set the device time used for TOTP to the given time.

DEPRECATED NK_C_API int	NK_totp_get_time ()

NK_C_API int	NK_change_admin_PIN (const char current_PIN, const char new_PIN)
	Change administrator PIN.

NK_C_API int	NK_change_user_PIN (const char current_PIN, const char new_PIN)
	Change user PIN.

NK_C_API uint8_t	NK_get_user_retry_count ()
	Get retry count of user PIN.

NK_C_API uint8_t	NK_get_admin_retry_count ()
	Get retry count of admin PIN.

NK_C_API int	NK_enable_password_safe (const char *user_pin)
	Enable password safe access.

NK_C_API uint8_t *	NK_get_password_safe_slot_status ()
	Get password safe slots' status The return value must be freed using NK_free_password_safe_slot_status.

NK_C_API void	NK_free_password_safe_slot_status (uint8_t *status)
	Free a value returned by NK_get_password_safe_slot_status.

NK_C_API char *	NK_get_password_safe_slot_name (uint8_t slot_number)
	Get password safe slot name.

NK_C_API char *	NK_get_password_safe_slot_login (uint8_t slot_number)
	Get password safe slot login.

NK_C_API char *	NK_get_password_safe_slot_password (uint8_t slot_number)
	Get the password safe slot password.

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)
	Write password safe data to the slot.

NK_C_API int	NK_erase_password_safe_slot (uint8_t slot_number)
	Erase the password safe slot from the device.

NK_C_API int	NK_is_AES_supported (const char *user_password)
	Check whether AES is supported by the device.

NK_C_API uint8_t	NK_get_major_firmware_version ()
	Get device's major firmware version.

NK_C_API uint8_t	NK_get_minor_firmware_version ()
	Get device's minor firmware version.

NK_C_API int	NK_set_unencrypted_volume_rorw_pin_type_user ()
	Function to determine unencrypted volume PIN type.

NK_C_API int	NK_send_startup (uint64_t seconds_from_epoch)
	This command is typically run to initiate communication with the device (altough not required).

NK_C_API int	NK_unlock_encrypted_volume (const char *user_pin)
	Unlock encrypted volume.

NK_C_API int	NK_lock_encrypted_volume ()
	Locks encrypted volume.

NK_C_API int	NK_unlock_hidden_volume (const char *hidden_volume_password)
	Unlock hidden volume and lock encrypted volume.

NK_C_API int	NK_lock_hidden_volume ()
	Locks hidden volume.

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)
	Create hidden volume.

DEPRECATED NK_C_API int	NK_set_unencrypted_read_only (const char *user_pin)
	Make unencrypted volume read-only.

DEPRECATED NK_C_API int	NK_set_unencrypted_read_write (const char *user_pin)
	Make unencrypted volume read-write.

NK_C_API int	NK_set_unencrypted_read_only_admin (const char *admin_pin)
	Make unencrypted volume read-only.

NK_C_API int	NK_set_unencrypted_read_write_admin (const char *admin_pin)
	Make unencrypted volume read-write.

NK_C_API int	NK_set_encrypted_read_only (const char *admin_pin)
	Make encrypted volume read-only.

NK_C_API int	NK_set_encrypted_read_write (const char *admin_pin)
	Make encrypted volume read-write.

NK_C_API int	NK_export_firmware (const char *admin_pin)
	Exports device's firmware to unencrypted volume.

NK_C_API int	NK_clear_new_sd_card_warning (const char *admin_pin)
	Clear new SD card notification.

NK_C_API int	NK_fill_SD_card_with_random_data (const char *admin_pin)
	Fill SD card with random data.

NK_C_API int	NK_change_update_password (const char current_update_password, const char new_update_password)
	Change update password.

NK_C_API int	NK_enable_firmware_update (const char *update_password)
	Enter update mode.

NK_C_API char *	NK_get_status_storage_as_string ()
	Get Storage stick status as string.

NK_C_API int	NK_get_status_storage (struct NK_storage_status *out)
	Get the Storage stick status and return the command processing error code.

NK_C_API int	NK_get_SD_usage_data (struct NK_SD_usage_data *out)
	Get SD card usage attributes.

NK_C_API char *	NK_get_SD_usage_data_as_string ()
	Get SD card usage attributes as string.

NK_C_API int	NK_get_progress_bar_value ()
	Get progress value of current long operation.

NK_C_API char *	NK_list_devices_by_cpuID ()

NK_C_API struct NK_device_info *	NK_list_devices ()
	Returns a linked list of all connected devices, or null if no devices are connected or an error occured.

NK_C_API void	NK_free_device_info (struct NK_device_info *device_info)
	Free a linked list returned by NK_list_devices.

NK_C_API int	NK_connect_with_ID (const char *id)
	Connects to the device with given ID.

NK_C_API int	NK_connect_with_path (const char *path)
	Connects to a device with the given path.

NK_C_API int	NK_wink ()
	Blink red and green LED alternatively and infinitely (until device is reconnected).

NK_C_API int	NK_enable_firmware_update_pro (const char *update_password)
	Enable update mode on Nitrokey Pro.

NK_C_API int	NK_change_firmware_password_pro (const char current_firmware_password, const char new_firmware_password)
	Change update-mode password on Nitrokey Pro.

NK_C_API int	NK_get_random (const uint8_t len, struct GetRandom_t *out)

NK_C_API int	NK_read_HOTP_slot (const uint8_t slot_num, struct ReadSlot_t *out)

Variables
NK_C_API typedef void(*	NK_log_function )(int, const char *)
	Callback function for NK_set_log_function.

const uint8_t	NK_PWS_SLOT_COUNT
	The number of slots in the password safe.

Detailed Description

C API for libnitrokey.

Enumeration Type Documentation

◆ NK_device_model

enum NK_device_model

The Nitrokey device models supported by the API.

Enumerator
NK_DISCONNECTED	Use, if no supported device is connected.
NK_PRO	Nitrokey Pro.
NK_STORAGE	Nitrokey Storage.
NK_LIBREM	Librem Key.

Function Documentation

◆ NK_build_aes_key()

NK_C_API int NK_build_aes_key ( const char * admin_password )

Generates AES key on the device.

Parameters

admin_password char[20] current administrator PIN

Returns: command processing error code

◆ NK_change_admin_PIN()

NK_C_API int NK_change_admin_PIN	(	const char *	current_PIN,
		const char *	new_PIN )

Change administrator PIN.

Parameters

current_PIN	char[25] current PIN
new_PIN	char[25] new PIN

Returns: command processing error code

◆ NK_change_firmware_password_pro()

NK_C_API int NK_change_firmware_password_pro	(	const char *	current_firmware_password,
		const char *	new_firmware_password )

Change update-mode password on Nitrokey Pro.

Supported from v0.11.

Parameters

current_firmware_password	20 bytes update password
new_firmware_password	20 bytes update password

Returns: command processing error code

◆ NK_change_update_password()

NK_C_API int NK_change_update_password	(	const char *	current_update_password,
		const char *	new_update_password )

Change update password.

Update password is used for entering update mode, where firmware could be uploaded using dfu-programmer or other means. Storage only

Parameters

current_update_password	20 characters
new_update_password	20 characters

Returns: command processing error code

◆ NK_change_user_PIN()

NK_C_API int NK_change_user_PIN	(	const char *	current_PIN,
		const char *	new_PIN )

Change user PIN.

Parameters

current_PIN	char[25] current PIN
new_PIN	char[25] new PIN

Returns: command processing error code

◆ NK_clear_new_sd_card_warning()

NK_C_API int NK_clear_new_sd_card_warning ( const char * admin_pin )

Clear new SD card notification.

It is set after factory reset. Storage only

Parameters

admin_pin 20 characters

Returns: command processing error code

◆ NK_connect_with_ID()

NK_C_API int NK_connect_with_ID ( const char * id )

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

Parameters

id	Target device ID (example: '00005d19:dacc2cb4_p_0001:0010:02')

Returns: 1 on successful connection, 0 otherwise

◆ NK_connect_with_path()

NK_C_API int NK_connect_with_path ( const char * path )

Connects to a device with the given path.

The path is a USB device path as returned by hidapi.

Parameters

path	the device path

Returns: 1 on successful connection, 0 otherwise

◆ NK_create_hidden_volume()

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 )

Create hidden volume.

Requires encrypted volume to be unlocked. Storage only

Parameters

slot_nr	slot number in range 0-3
start_percent	volume begin expressed in percent of total available storage, int in range 0-99
end_percent	volume end expressed in percent of total available storage, int in range 1-100
hidden_volume_password	20 characters

Returns: command processing error code

◆ NK_device_serial_number()

NK_C_API char * NK_device_serial_number ( )

Return the device's serial number string in hex.

Returns: string device's serial number in hex

◆ NK_device_serial_number_as_u32()

NK_C_API uint32_t NK_device_serial_number_as_u32 ( )

Return the device's serial number string as an integer.

Use NK_last_command_status to check for an error if this function returns zero.

Returns: device's serial number as an integer

◆ NK_enable_firmware_update()

NK_C_API int NK_enable_firmware_update ( const char * 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

Parameters

update_password 20 characters

Returns: command processing error code

◆ NK_enable_firmware_update_pro()

NK_C_API int NK_enable_firmware_update_pro ( const char * update_password )

Enable update mode on Nitrokey Pro.

Supported from v0.11.

Parameters

update_password 20 bytes update password

Returns: command processing error code

◆ NK_enable_password_safe()

NK_C_API int NK_enable_password_safe ( const char * user_pin )

Enable password safe access.

Parameters

user_pin char[30] current user PIN

Returns: command processing error code

◆ NK_erase_hotp_slot()

NK_C_API int NK_erase_hotp_slot	(	uint8_t	slot_number,
		const char *	temporary_password )

Erase HOTP slot data from the device.

Parameters

slot_number	HOTP slot number, slot_number<3
temporary_password	admin temporary password

Returns: command processing error code

◆ NK_erase_password_safe_slot()

NK_C_API int NK_erase_password_safe_slot ( uint8_t slot_number )

Erase the password safe slot from the device.

Parameters

slot_number password safe slot number, slot_number<16

Returns: command processing error code

◆ NK_erase_totp_slot()

NK_C_API int NK_erase_totp_slot	(	uint8_t	slot_number,
		const char *	temporary_password )

Erase TOTP slot data from the device.

Parameters

slot_number	TOTP slot number, slot_number<15
temporary_password	admin temporary password

Returns: command processing error code

◆ NK_export_firmware()

NK_C_API int NK_export_firmware ( const char * admin_pin )

Exports device's firmware to unencrypted volume.

Storage only

Parameters

admin_pin 20 characters

Returns: command processing error code

◆ NK_factory_reset()

NK_C_API int NK_factory_reset ( const char * admin_password )

Execute a factory reset.

Parameters

admin_password char[20] current administrator PIN

Returns: command processing error code

◆ NK_fill_SD_card_with_random_data()

NK_C_API int NK_fill_SD_card_with_random_data ( const char * admin_pin )

Fill SD card with random data.

Should be done on first stick initialization after creating keys. Storage only

Parameters

admin_pin 20 characters

Returns: command processing error code

◆ NK_first_authenticate()

NK_C_API int NK_first_authenticate	(	const char *	admin_password,
		const char *	admin_temporary_password )

Authenticates the user on ADMIN privilages with admin_password and sets user's temporary password on device to admin_temporary_password.

Parameters

admin_password	char[25] current administrator PIN
admin_temporary_password	char[25] admin temporary password to be set on device for further communication (authentication command)

Returns: command processing error code

◆ NK_free_config()

NK_C_API void NK_free_config ( uint8_t * config )

Free a value returned by NK_read_config.

May be called with a NULL argument.

◆ NK_free_device_info()

NK_C_API void NK_free_device_info ( struct NK_device_info * device_info )

Free a linked list returned by NK_list_devices.

Parameters

the	linked list to free or null

◆ NK_free_password_safe_slot_status()

NK_C_API void NK_free_password_safe_slot_status ( uint8_t * status )

Free a value returned by NK_get_password_safe_slot_status.

May be called with a NULL argument.

◆ NK_get_admin_retry_count()

NK_C_API uint8_t NK_get_admin_retry_count ( )

Get retry count of admin PIN.

Returns: admin PIN retry count

◆ NK_get_device_model()

NK_C_API enum NK_device_model NK_get_device_model ( )

Query the model of the connected device.

Returns the model of the connected device or NK_DISCONNECTED.

Returns: true if a device is connected and the out argument has been set

◆ NK_get_hotp_code()

NK_C_API char * NK_get_hotp_code ( uint8_t slot_number )

Get HOTP code from the device.

Parameters

slot_number HOTP slot number, slot_number<3

Returns: HOTP code

◆ NK_get_hotp_code_PIN()

NK_C_API char * NK_get_hotp_code_PIN	(	uint8_t	slot_number,
		const char *	user_temporary_password )

Get HOTP code from the device (PIN protected)

Parameters

slot_number	HOTP slot number, slot_number<3
user_temporary_password	char[25] user temporary password if PIN protected OTP codes are enabled, otherwise should be set to empty string - ''

Returns: HOTP code

◆ NK_get_hotp_slot_name()

NK_C_API char * NK_get_hotp_slot_name ( uint8_t slot_number )

Parameters

slot_number HOTP slot number, slot_number<3

Returns: char[20] the name of the slot

◆ NK_get_last_command_status()

NK_C_API uint8_t NK_get_last_command_status ( )

Get last command processing status.

Useful for commands which returns the results of their own and could not return an error code.

Returns: previous command processing error code

◆ NK_get_library_version()

NK_C_API const char * NK_get_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.

Returns: the library version as a string

◆ NK_get_major_firmware_version()

NK_C_API uint8_t NK_get_major_firmware_version ( )

Get device's major firmware version.

Returns: major part of the version number (e.g. 0 from 0.48, 0 from 0.7 etc.)

◆ NK_get_major_library_version()

NK_C_API unsigned int NK_get_major_library_version ( )

Get the major library version, e.

g. the 3 in v3.2.

Returns: the major library version

◆ NK_get_minor_firmware_version()

NK_C_API uint8_t NK_get_minor_firmware_version ( )

Get device's minor firmware version.

Returns: minor part of the version number (e.g. 7 from 0.7, 48 from 0.48 etc.)

◆ NK_get_minor_library_version()

NK_C_API unsigned int NK_get_minor_library_version ( )

Get the minor library version, e.

g. the 2 in v3.2.

Returns: the minor library version

◆ NK_get_password_safe_slot_login()

NK_C_API char * NK_get_password_safe_slot_login ( uint8_t slot_number )

Get password safe slot login.

Parameters

slot_number password safe slot number, slot_number<16

Returns: login from the PWS slot

◆ NK_get_password_safe_slot_name()

NK_C_API char * NK_get_password_safe_slot_name ( uint8_t slot_number )

Get password safe slot name.

Parameters

slot_number password safe slot number, slot_number<16

Returns: slot name

◆ NK_get_password_safe_slot_password()

NK_C_API char * NK_get_password_safe_slot_password ( uint8_t slot_number )

Get the password safe slot password.

Parameters

slot_number password safe slot number, slot_number<16

Returns: password from the PWS slot

◆ NK_get_password_safe_slot_status()

NK_C_API uint8_t * NK_get_password_safe_slot_status ( )

Get password safe slots' status The return value must be freed using NK_free_password_safe_slot_status.

Returns: uint8_t[16] slot statuses - each byte represents one slot with 0 (not programmed) and 1 (programmed)

◆ NK_get_progress_bar_value()

NK_C_API int NK_get_progress_bar_value ( )

Get progress value of current long operation.

Storage only

Returns: int in range 0-100 or -1 if device is not busy or -2 if an error occured

◆ NK_get_SD_usage_data()

NK_C_API int NK_get_SD_usage_data ( struct NK_SD_usage_data * 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

Parameters

out	the output pointer for the usage data

Returns: command processing error code

◆ NK_get_SD_usage_data_as_string()

NK_C_API char * NK_get_SD_usage_data_as_string ( )

Get SD card usage attributes as string.

Usable during hidden volumes creation. Storage only

Returns: string with SD card usage attributes

◆ NK_get_status()

NK_C_API int NK_get_status ( struct NK_status * out )

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.

Parameters

out	the output pointer for the status

Returns: command processing error code

◆ NK_get_status_as_string()

NK_C_API char * NK_get_status_as_string ( )

Return the debug status string.

Debug purposes.

Returns: string representation of the status or an empty string if the command failed

◆ NK_get_status_storage()

NK_C_API int NK_get_status_storage ( struct NK_storage_status * out )

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.

Parameters

out	the output pointer for the storage status

Returns: command processing error code

◆ NK_get_status_storage_as_string()

NK_C_API char * NK_get_status_storage_as_string ( )

Get Storage stick status as string.

Storage only

Returns: string with devices attributes

◆ NK_get_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.

Parameters

slot_number	TOTP slot number, slot_number<15
challenge	TOTP challenge – unused
last_totp_time	last time – unused
last_interval	last interval –unused

Returns: TOTP code

◆ NK_get_totp_code_PIN()

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 )

Get TOTP code from the device (PIN protected)

Parameters

slot_number	TOTP slot number, slot_number<15
challenge	TOTP challenge – unused
last_totp_time	last time – unused
last_interval	last interval – unused
user_temporary_password	char[25] user temporary password if PIN protected OTP codes are enabled, otherwise should be set to empty string - ''

Returns: TOTP code

◆ NK_get_totp_slot_name()

NK_C_API char * NK_get_totp_slot_name ( uint8_t slot_number )

Get name of given TOTP slot.

Parameters

slot_number TOTP slot number, slot_number<15

Returns: char[20] the name of the slot

◆ NK_get_user_retry_count()

NK_C_API uint8_t NK_get_user_retry_count ( )

Get retry count of user PIN.

Returns: user PIN retry count

◆ NK_is_AES_supported()

NK_C_API int NK_is_AES_supported ( const char * user_password )

Check whether AES is supported by the device.

Returns: 0 for no and 1 for yes

◆ NK_list_devices()

NK_C_API struct NK_device_info * NK_list_devices ( )

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.

Returns: a linked list of all connected devices

◆ NK_lock_device()

NK_C_API int NK_lock_device ( )

Lock device - cancel any user device unlocking.

Returns: command processing error code

◆ NK_lock_encrypted_volume()

NK_C_API int NK_lock_encrypted_volume ( )

Locks encrypted volume.

Returns: command processing error code

◆ NK_lock_hidden_volume()

NK_C_API int NK_lock_hidden_volume ( )

Locks hidden volume.

Returns: command processing error code

◆ NK_login()

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.

Parameters

device_model char 'S': Nitrokey Storage, 'P': Nitrokey Pro

Returns: 1 if connected, 0 if wrong model or cannot connect

◆ NK_login_auto()

NK_C_API int NK_login_auto ( )

Connect to first available device, starting checking from Pro 1st to Storage 2nd.

Returns: 1 if connected, 0 if wrong model or cannot connect

◆ NK_login_enum()

NK_C_API int NK_login_enum ( enum NK_device_model device_model )

Connect to device of given model.

Currently library can be connected only to one device at once.

Parameters

device_model NK_device_model: NK_PRO: Nitrokey Pro, NK_STORAGE: Nitrokey Storage, NK_LIBREM: Librem Key

Returns: 1 if connected, 0 if wrong model or cannot connect

◆ NK_logout()

NK_C_API int NK_logout ( )

Disconnect from the device.

Returns: command processing error code

◆ NK_read_config()

NK_C_API uint8_t * NK_read_config ( )

Get currently set config - status of function Numlock/Capslock/Scrollock OTP sending and is enabled PIN protected OTP The return value must be freed using NK_free_config.

See also: NK_write_config

Returns: 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_read_config_struct()

NK_C_API int NK_read_config_struct ( struct NK_config * out )

Get currently set config and write it to the given pointer.

See also: NK_read_config; NK_write_config_struct

Parameters

out	a pointer to the struct that should be written to

Returns: command processing error code

◆ NK_send_startup()

NK_C_API int NK_send_startup ( uint64_t seconds_from_epoch )

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
Parameters

seconds_from_epoch date and time expressed in seconds

◆ NK_set_debug()

NK_C_API void NK_set_debug ( bool state )

Set debug level of messages written on stderr.

Parameters

state state=True - most messages, state=False - only errors level

◆ NK_set_debug_level()

NK_C_API void NK_set_debug_level ( const int level )

Set debug level of messages written on stderr.

Parameters

level (int) 0-lowest verbosity, 5-highest verbosity

◆ NK_set_encrypted_read_only()

NK_C_API int NK_set_encrypted_read_only ( 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

Parameters

admin_pin 20 characters

Returns: command processing error code

◆ NK_set_encrypted_read_write()

NK_C_API int NK_set_encrypted_read_write ( 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

Parameters

admin_pin 20 characters

Returns: command processing error code

◆ NK_set_log_function()

NK_C_API void NK_set_log_function ( NK_log_function fn )

Set a custom log function.

The log function is called for every log message that matches the log level settings (see NK_set_debug and NK_set_debug_level).

◆ NK_set_unencrypted_read_only()

DEPRECATED NK_C_API int NK_set_unencrypted_read_only ( 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.50, v0.48 and below Storage only

Parameters

user_pin 20 characters User PIN

Returns: command processing error code

◆ NK_set_unencrypted_read_only_admin()

NK_C_API int NK_set_unencrypted_read_only_admin ( const char * admin_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

Parameters

admin_pin 20 characters Admin PIN

Returns: command processing error code

◆ NK_set_unencrypted_read_write()

DEPRECATED NK_C_API int NK_set_unencrypted_read_write ( 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

Parameters

user_pin 20 characters User PIN

Returns: command processing error code

◆ NK_set_unencrypted_read_write_admin()

NK_C_API int NK_set_unencrypted_read_write_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

Parameters

admin_pin 20 characters Admin PIN

Returns: command processing error code

◆ NK_set_unencrypted_volume_rorw_pin_type_user()

NK_C_API int NK_set_unencrypted_volume_rorw_pin_type_user ( )

Function to determine unencrypted volume PIN type.

Parameters

minor_firmware_version

Returns: Returns 1, if set unencrypted volume ro/rw pin type is User, 0 otherwise.

◆ NK_status()

DEPRECATED NK_C_API char * NK_status ( )

Return the debug status string.

Debug purposes. This function is deprecated in favor of NK_get_status_as_string.

Returns: string representation of the status or an empty string if the command failed

◆ NK_totp_set_time()

NK_C_API int NK_totp_set_time ( uint64_t time )

Set time on the device (for TOTP requests)

Parameters

time	seconds in unix epoch (from 01.01.1970)

Returns: command processing error code

◆ NK_totp_set_time_soft()

NK_C_API int NK_totp_set_time_soft ( uint64_t time )

Set the device time used for TOTP to the given time.

Contrary to set_time(uint64_t), this command fails if old_time > time or if old_time is zero (where old_time is the current time on the device).

Parameters

time	new device time as Unix timestamp (seconds since 1970-01-01)

Returns: command processing error code

◆ NK_unlock_encrypted_volume()

NK_C_API int NK_unlock_encrypted_volume ( const char * user_pin )

Unlock encrypted volume.

Storage only

Parameters

user_pin user pin 20 characters

Returns: command processing error code

◆ NK_unlock_hidden_volume()

NK_C_API int NK_unlock_hidden_volume ( const char * hidden_volume_password )

Unlock hidden volume and lock encrypted volume.

Requires encrypted volume to be unlocked. Storage only

Parameters

hidden_volume_password 20 characters

Returns: command processing error code

◆ NK_unlock_user_password()

NK_C_API int NK_unlock_user_password	(	const char *	admin_password,
		const char *	new_user_password )

Unlock user PIN locked after 3 incorrect codes tries.

Parameters

admin_password char[20] current administrator PIN

Returns: command processing error code

◆ NK_user_authenticate()

NK_C_API int NK_user_authenticate	(	const char *	user_password,
		const char *	user_temporary_password )

Authenticates the user on USER privilages with user_password and sets user's temporary password on device to user_temporary_password.

Parameters

user_password	char[25] current user password
user_temporary_password	char[25] user temporary password to be set on device for further communication (authentication command)

Returns: command processing error code

◆ NK_wink()

NK_C_API int NK_wink ( )

Blink red and green LED alternatively and infinitely (until device is reconnected).

Returns: command processing error code

◆ NK_write_config()

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 )

Write general config to the device.

Parameters

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
capslock	similar to numlock but with capslock
scrolllock	similar to numlock but with scrolllock
enable_user_password	set True to enable OTP PIN protection (require PIN each OTP code request)
delete_user_password	(unused)
admin_temporary_password	current admin temporary password

Returns: command processing error code

◆ NK_write_config_struct()

NK_C_API int NK_write_config_struct	(	struct NK_config	config,
		const char *	admin_temporary_password )

Write general config to the device.

Parameters

config	the configuration data
admin_temporary_password	current admin temporary password

Returns: command processing error code

◆ NK_write_hotp_slot()

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 HOTP slot data to the device.

Parameters

slot_number	HOTP slot number, slot_number<3, 0-numbered
slot_name	char[15] desired slot name. C string (requires ending '\0'; 16 bytes).
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.
hotp_counter	uint32_t starting value of HOTP counter
use_8_digits	should returned codes be 6 (false) or 8 digits (true)
use_enter	press ENTER key after sending OTP code using double-pressed scroll/num/capslock
use_tokenID

See also: token_ID

Parameters

token_ID

See also: https://openauthentication.org/token-specs/, 'Class A' section

Parameters

temporary_password char[25] admin temporary password

Returns: command processing error code

◆ NK_write_password_safe_slot()

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 )

Write password safe data to the slot.

Parameters

slot_number	password safe slot number, slot_number<16
slot_name	char[11] name of the slot
slot_login	char[32] login string
slot_password	char[20] password string

Returns: command processing error code

◆ NK_write_totp_slot()

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 )

Write TOTP slot data to the device.

Parameters

slot_number	TOTP slot number, slot_number<15, 0-numbered
slot_name	char[15] desired slot name. C string (requires ending '\0'; 16 bytes).
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.
time_window	uint16_t time window for this TOTP
use_8_digits	should returned codes be 6 (false) or 8 digits (true)
use_enter	press ENTER key after sending OTP code using double-pressed scroll/num/capslock
use_tokenID

See also: token_ID

Parameters

token_ID

See also: https://openauthentication.org/token-specs/, 'Class A' section

Parameters

temporary_password char[20] admin temporary password

Returns: command processing error code

Variable Documentation

◆ NK_log_function

NK_C_API typedef void(* NK_log_function) (int, const char *)	(	int	,
		const char *	)

Callback function for NK_set_log_function.

The first argument is the log level (0 = Error, 1 = Warn, 2 = Info, 3 = DebugL1, 4 = Debug, 5 = DebugL2) and the second argument is the log message.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ NK_device_model

Function Documentation

◆ NK_build_aes_key()

◆ NK_change_admin_PIN()

◆ NK_change_firmware_password_pro()

◆ NK_change_update_password()

◆ NK_change_user_PIN()

◆ NK_clear_new_sd_card_warning()

◆ NK_connect_with_ID()

◆ NK_connect_with_path()

◆ NK_create_hidden_volume()

◆ NK_device_serial_number()

◆ NK_device_serial_number_as_u32()

◆ NK_enable_firmware_update()

◆ NK_enable_firmware_update_pro()

◆ NK_enable_password_safe()

◆ NK_erase_hotp_slot()

◆ NK_erase_password_safe_slot()

◆ NK_erase_totp_slot()

◆ NK_export_firmware()

◆ NK_factory_reset()

◆ NK_fill_SD_card_with_random_data()

◆ NK_first_authenticate()

◆ NK_free_config()

◆ NK_free_device_info()

◆ NK_free_password_safe_slot_status()

◆ NK_get_admin_retry_count()

◆ NK_get_device_model()

◆ NK_get_hotp_code()

◆ NK_get_hotp_code_PIN()

◆ NK_get_hotp_slot_name()

◆ NK_get_last_command_status()

◆ NK_get_library_version()

◆ NK_get_major_firmware_version()

◆ NK_get_major_library_version()

◆ NK_get_minor_firmware_version()

◆ NK_get_minor_library_version()

◆ NK_get_password_safe_slot_login()

◆ NK_get_password_safe_slot_name()

◆ NK_get_password_safe_slot_password()

◆ NK_get_password_safe_slot_status()

◆ NK_get_progress_bar_value()

◆ NK_get_SD_usage_data()

◆ NK_get_SD_usage_data_as_string()

◆ NK_get_status()

◆ NK_get_status_as_string()

◆ NK_get_status_storage()

◆ NK_get_status_storage_as_string()

◆ NK_get_totp_code()

◆ NK_get_totp_code_PIN()

◆ NK_get_totp_slot_name()

◆ NK_get_user_retry_count()

◆ NK_is_AES_supported()

◆ NK_list_devices()

◆ NK_lock_device()

◆ NK_lock_encrypted_volume()

◆ NK_lock_hidden_volume()

◆ NK_login()

◆ NK_login_auto()

◆ NK_login_enum()

◆ NK_logout()

◆ NK_read_config()

◆ NK_read_config_struct()

◆ NK_send_startup()

◆ NK_set_debug()

◆ NK_set_debug_level()

◆ NK_set_encrypted_read_only()

◆ NK_set_encrypted_read_write()

◆ NK_set_log_function()

◆ NK_set_unencrypted_read_only()

◆ NK_set_unencrypted_read_only_admin()

◆ NK_set_unencrypted_read_write()

◆ NK_set_unencrypted_read_write_admin()

◆ NK_set_unencrypted_volume_rorw_pin_type_user()