1 /* 2 * Copyright (c) 2015-2018 Nitrokey UG 3 * 4 * This file is part of libnitrokey. 5 * 6 * libnitrokey is free software: you can redistribute it and/or modify 7 * it under the terms of the GNU Lesser General Public License as published by 8 * the Free Software Foundation, either version 3 of the License, or 9 * any later version. 10 * 11 * libnitrokey is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public License 17 * along with libnitrokey. If not, see <http://www.gnu.org/licenses/>. 18 * 19 * SPDX-License-Identifier: LGPL-3.0 20 */ 21 22 #ifndef LIBNITROKEY_NK_C_API_H 23 #define LIBNITROKEY_NK_C_API_H 24 25 #include <stdbool.h> 26 #include <stdint.h> 27 28 #include "deprecated.h" 29 30 #ifdef _MSC_VER 31 #define NK_C_API __declspec(dllexport) 32 #else 33 #define NK_C_API 34 #endif 35 36 /** 37 * \file 38 * 39 * C API for libnitrokey 40 * 41 * \mainpage 42 * 43 * **libnitrokey** provides access to Nitrokey Pro and Nitrokey Storage devices. 44 * This documentation describes libnitrokey’s C API. For a list of the 45 * available functions, see the NK_C_API.h file. 46 * 47 * \section getting_started Example 48 * 49 * \code{.c} 50 * #include <stdio.h> 51 * #include <stdlib.h> 52 * #include <libnitrokey/NK_C_API.h> 53 * 54 * int main(void) 55 * { 56 * if (NK_login_auto() != 1) { 57 * fprintf(stderr, "No Nitrokey found.\n"); 58 * return 1; 59 * } 60 * 61 * NK_device_model model = NK_get_device_model(); 62 * printf("Connected to "); 63 * switch (model) { 64 * case NK_PRO: 65 * printf("a Nitrokey Pro"); 66 * break; 67 * case NK_STORAGE: 68 * printf("a Nitrokey Storage"); 69 * break; 70 * case NK_LIBREM: 71 * printf("a Librem Key"); 72 * break; 73 * default: 74 * printf("an unsupported Nitrokey"); 75 * break; 76 * } 77 * 78 * char* serial_number = NK_device_serial_number(); 79 * if (serial_number) 80 * printf(" with serial number %s\n", serial_number); 81 * else 82 * printf(" -- could not query serial number!\n"); 83 * free(serial_number); 84 * 85 * NK_logout(); 86 * return 0; 87 * } 88 * \endcode 89 */ 90 91 #ifdef __cplusplus 92 extern "C" { 93 #endif 94 95 /** 96 * The number of slots in the password safe. 97 */ 98 extern const uint8_t NK_PWS_SLOT_COUNT; 99 100 static const int MAXIMUM_STR_REPLY_LENGTH = 8192; 101 102 /** 103 * The Nitrokey device models supported by the API. 104 */ 105 enum NK_device_model { 106 /** 107 * Use, if no supported device is connected 108 */ 109 NK_DISCONNECTED = 0, 110 /** 111 * Nitrokey Pro. 112 */ 113 NK_PRO = 1, 114 /** 115 * Nitrokey Storage. 116 */ 117 NK_STORAGE = 2, 118 /** 119 * Librem Key. 120 */ 121 NK_LIBREM = 3 122 }; 123 124 /** 125 * The connection info for a Nitrokey device as a linked list. 126 */ 127 struct NK_device_info { 128 /** 129 * The model of the Nitrokey device. 130 */ 131 enum NK_device_model model; 132 /** 133 * The USB device path for NK_connect_with_path. 134 */ 135 char* path; 136 /** 137 * The serial number. 138 */ 139 char* serial_number; 140 /** 141 * The pointer to the next element of the linked list or null 142 * if this is the last element in the list. 143 */ 144 struct NK_device_info* next; 145 }; 146 147 /** 148 * Stores the common device status for all Nitrokey devices. 149 */ 150 struct NK_status { 151 /** 152 * The major firmware version, e. g. 0 in v0.40. 153 */ 154 uint8_t firmware_version_major; 155 /** 156 * The minor firmware version, e. g. 40 in v0.40. 157 */ 158 uint8_t firmware_version_minor; 159 /** 160 * The serial number of the smart card. 161 */ 162 uint32_t serial_number_smart_card; 163 /** 164 * The HOTP slot to generate a password from if the numlock 165 * key is pressed twice (slot 0-1, or any other value to 166 * disable the function). 167 */ 168 uint8_t config_numlock; 169 /** 170 * The HOTP slot to generate a password from if the capslock 171 * key is pressed twice (slot 0-1, or any other value to 172 * disable the function). 173 */ 174 uint8_t config_capslock; 175 /** 176 * The HOTP slot to generate a password from if the scrolllock 177 * key is pressed twice (slot 0-1, or any other value to 178 * disable the function). 179 */ 180 uint8_t config_scrolllock; 181 /** 182 * Indicates whether the user password is required to generate 183 * an OTP value. 184 */ 185 bool otp_user_password; 186 }; 187 188 /** 189 * Stores the status of a Storage device. 190 */ 191 struct NK_storage_status { 192 /** 193 * Indicates whether the unencrypted volume is read-only. 194 */ 195 bool unencrypted_volume_read_only; 196 /** 197 * Indicates whether the unencrypted volume is active. 198 */ 199 bool unencrypted_volume_active; 200 /** 201 * Indicates whether the encrypted volume is read-only. 202 */ 203 bool encrypted_volume_read_only; 204 /** 205 * Indicates whether the encrypted volume is active. 206 */ 207 bool encrypted_volume_active; 208 /** 209 * Indicates whether the hidden volume is read-only. 210 */ 211 bool hidden_volume_read_only; 212 /** 213 * Indicates whether the hidden volume is active. 214 */ 215 bool hidden_volume_active; 216 /** 217 * The major firmware version, e. g. 0 in v0.40. 218 */ 219 uint8_t firmware_version_major; 220 /** 221 * The minor firmware version, e. g. 40 in v0.40. 222 */ 223 uint8_t firmware_version_minor; 224 /** 225 * Indicates whether the firmware is locked. 226 */ 227 bool firmware_locked; 228 /** 229 * The serial number of the SD card in the Storage stick. 230 */ 231 uint32_t serial_number_sd_card; 232 /** 233 * The serial number of the smart card in the Storage stick. 234 */ 235 uint32_t serial_number_smart_card; 236 /** 237 * The number of remaining login attempts for the user PIN. 238 */ 239 uint8_t user_retry_count; 240 /** 241 * The number of remaining login attempts for the admin PIN. 242 */ 243 uint8_t admin_retry_count; 244 /** 245 * Indicates whether a new SD card was found. 246 */ 247 bool new_sd_card_found; 248 /** 249 * Indicates whether the SD card is filled with random characters. 250 */ 251 bool filled_with_random; 252 /** 253 * Indicates whether the stick has been initialized by generating 254 * the AES keys. 255 */ 256 bool stick_initialized; 257 }; 258 259 /** 260 * Data about the usage of the SD card. 261 */ 262 struct NK_SD_usage_data { 263 /** 264 * The minimum write level, as a percentage of the total card 265 * size. 266 */ 267 uint8_t write_level_min; 268 /** 269 * The maximum write level, as a percentage of the total card 270 * size. 271 */ 272 uint8_t write_level_max; 273 }; 274 275 /** 276 * The general configuration of a Nitrokey device. 277 */ 278 struct NK_config { 279 /** 280 * value in range [0-1] to send HOTP code from slot 'numlock' after double pressing numlock 281 * or outside the range to disable this function 282 */ 283 uint8_t numlock; 284 /** 285 * similar to numlock but with capslock 286 */ 287 uint8_t capslock; 288 /** 289 * similar to numlock but with scrolllock 290 */ 291 uint8_t scrolllock; 292 /** 293 * True to enable OTP PIN protection (require PIN each OTP code request) 294 */ 295 bool enable_user_password; 296 /** 297 * Unused. 298 */ 299 bool disable_user_password; 300 }; 301 302 struct NK_storage_ProductionTest{ 303 uint8_t FirmwareVersion_au8[2]; 304 uint8_t FirmwareVersionInternal_u8; 305 uint8_t SD_Card_Size_u8; 306 uint32_t CPU_CardID_u32; 307 uint32_t SmartCardID_u32; 308 uint32_t SD_CardID_u32; 309 uint8_t SC_UserPwRetryCount; 310 uint8_t SC_AdminPwRetryCount; 311 uint8_t SD_Card_ManufacturingYear_u8; 312 uint8_t SD_Card_ManufacturingMonth_u8; 313 uint16_t SD_Card_OEM_u16; 314 uint16_t SD_WriteSpeed_u16; 315 uint8_t SD_Card_Manufacturer_u8; 316 }; 317 318 NK_C_API int NK_get_storage_production_info(struct NK_storage_ProductionTest * out); 319 320 321 /** 322 * Set debug level of messages written on stderr 323 * @param state state=True - most messages, state=False - only errors level 324 */ 325 NK_C_API void NK_set_debug(bool state); 326 327 /** 328 * Set debug level of messages written on stderr 329 * @param level (int) 0-lowest verbosity, 5-highest verbosity 330 */ 331 NK_C_API void NK_set_debug_level(const int level); 332 333 /** 334 * Get the major library version, e. g. the 3 in v3.2. 335 * @return the major library version 336 */ 337 NK_C_API unsigned int NK_get_major_library_version(); 338 339 /** 340 * Get the minor library version, e. g. the 2 in v3.2. 341 * @return the minor library version 342 */ 343 NK_C_API unsigned int NK_get_minor_library_version(); 344 345 /** 346 * Get the library version as a string. This is the output of 347 * `git describe --always` at compile time, for example "v3.3" or 348 * "v3.3-19-gaee920b". 349 * The return value is a string literal and must not be freed. 350 * @return the library version as a string 351 */ 352 NK_C_API const char* NK_get_library_version(); 353 354 /** 355 * Connect to device of given model. Currently library can be connected only to one device at once. 356 * @param device_model char 'S': Nitrokey Storage, 'P': Nitrokey Pro 357 * @return 1 if connected, 0 if wrong model or cannot connect 358 */ 359 NK_C_API int NK_login(const char *device_model); 360 361 /** 362 * Connect to device of given model. Currently library can be connected only to one device at once. 363 * @param device_model NK_device_model: NK_PRO: Nitrokey Pro, NK_STORAGE: Nitrokey Storage, NK_LIBREM: Librem Key 364 * @return 1 if connected, 0 if wrong model or cannot connect 365 */ 366 NK_C_API int NK_login_enum(enum NK_device_model device_model); 367 368 /** 369 * Connect to first available device, starting checking from Pro 1st to Storage 2nd. 370 * @return 1 if connected, 0 if wrong model or cannot connect 371 */ 372 NK_C_API int NK_login_auto(); 373 374 /** 375 * Disconnect from the device. 376 * @return command processing error code 377 */ 378 NK_C_API int NK_logout(); 379 380 /** 381 * Query the model of the connected device. 382 * Returns the model of the connected device or NK_DISCONNECTED. 383 * 384 * @return true if a device is connected and the out argument has been set 385 */ 386 NK_C_API enum NK_device_model NK_get_device_model(); 387 388 /** 389 * Return the debug status string. Debug purposes. This function is 390 * deprecated in favor of NK_get_status_as_string. 391 * @return string representation of the status or an empty string 392 * if the command failed 393 */ 394 DEPRECATED 395 NK_C_API char * NK_status(); 396 397 /** 398 * Return the debug status string. Debug purposes. 399 * @return string representation of the status or an empty string 400 * if the command failed 401 */ 402 NK_C_API char * NK_get_status_as_string(); 403 404 /** 405 * Get the stick status common to all Nitrokey devices and return the 406 * command processing error code. If the code is zero, i. e. the 407 * command was successful, the storage status is written to the output 408 * pointer's target. The output pointer must not be null. 409 * 410 * @param out the output pointer for the status 411 * @return command processing error code 412 */ 413 NK_C_API int NK_get_status(struct NK_status* out); 414 415 /** 416 * Return the device's serial number string in hex. 417 * @return string device's serial number in hex 418 */ 419 NK_C_API char * NK_device_serial_number(); 420 421 /** 422 * Return the device's serial number string as an integer. Use 423 * NK_last_command_status to check for an error if this function 424 * returns zero. 425 * @return device's serial number as an integer 426 */ 427 NK_C_API uint32_t NK_device_serial_number_as_u32(); 428 429 /** 430 * Get last command processing status. Useful for commands which returns the results of their own and could not return 431 * an error code. 432 * @return previous command processing error code 433 */ 434 NK_C_API uint8_t NK_get_last_command_status(); 435 436 /** 437 * Lock device - cancel any user device unlocking. 438 * @return command processing error code 439 */ 440 NK_C_API int NK_lock_device(); 441 442 /** 443 * Authenticates the user on USER privilages with user_password and sets user's temporary password on device to user_temporary_password. 444 * @param user_password char[25] current user password 445 * @param user_temporary_password char[25] user temporary password to be set on device for further communication (authentication command) 446 * @return command processing error code 447 */ 448 NK_C_API int NK_user_authenticate(const char* user_password, const char* user_temporary_password); 449 450 /** 451 * Authenticates the user on ADMIN privilages with admin_password and sets user's temporary password on device to admin_temporary_password. 452 * @param admin_password char[25] current administrator PIN 453 * @param admin_temporary_password char[25] admin temporary password to be set on device for further communication (authentication command) 454 * @return command processing error code 455 */ 456 NK_C_API int NK_first_authenticate(const char* admin_password, const char* admin_temporary_password); 457 458 /** 459 * Execute a factory reset. 460 * @param admin_password char[20] current administrator PIN 461 * @return command processing error code 462 */ 463 NK_C_API int NK_factory_reset(const char* admin_password); 464 465 /** 466 * Generates AES key on the device 467 * @param admin_password char[20] current administrator PIN 468 * @return command processing error code 469 */ 470 NK_C_API int NK_build_aes_key(const char* admin_password); 471 472 /** 473 * Unlock user PIN locked after 3 incorrect codes tries. 474 * @param admin_password char[20] current administrator PIN 475 * @return command processing error code 476 */ 477 NK_C_API int NK_unlock_user_password(const char *admin_password, const char *new_user_password); 478 479 /** 480 * Write general config to the device 481 * @param numlock set value in range [0-1] to send HOTP code from slot 'numlock' after double pressing numlock 482 * or outside the range to disable this function 483 * @param capslock similar to numlock but with capslock 484 * @param scrolllock similar to numlock but with scrolllock 485 * @param enable_user_password set True to enable OTP PIN protection (require PIN each OTP code request) 486 * @param delete_user_password (unused) 487 * @param admin_temporary_password current admin temporary password 488 * @return command processing error code 489 */ 490 NK_C_API int NK_write_config(uint8_t numlock, uint8_t capslock, uint8_t scrolllock, 491 bool enable_user_password, bool delete_user_password, const char *admin_temporary_password); 492 493 /** 494 * Write general config to the device 495 * @param config the configuration data 496 * @param admin_temporary_password current admin temporary password 497 * @return command processing error code 498 */ 499 NK_C_API int NK_write_config_struct(struct NK_config config, const char *admin_temporary_password); 500 501 /** 502 * Get currently set config - status of function Numlock/Capslock/Scrollock OTP sending and is enabled PIN protected OTP 503 * The return value must be freed using NK_free_config. 504 * @see NK_write_config 505 * @return uint8_t general_config[5]: 506 * uint8_t numlock; 507 uint8_t capslock; 508 uint8_t scrolllock; 509 uint8_t enable_user_password; 510 uint8_t delete_user_password; 511 512 */ 513 NK_C_API uint8_t* NK_read_config(); 514 515 /** 516 * Free a value returned by NK_read_config. May be called with a NULL 517 * argument. 518 */ 519 NK_C_API void NK_free_config(uint8_t* config); 520 521 /** 522 * Get currently set config and write it to the given pointer. 523 * @see NK_read_config 524 * @see NK_write_config_struct 525 * @param out a pointer to the struct that should be written to 526 * @return command processing error code 527 */ 528 NK_C_API int NK_read_config_struct(struct NK_config* out); 529 530 //OTP 531 532 /** 533 * Get name of given TOTP slot 534 * @param slot_number TOTP slot number, slot_number<15 535 * @return char[20] the name of the slot 536 */ 537 NK_C_API char * NK_get_totp_slot_name(uint8_t slot_number); 538 539 /** 540 * 541 * @param slot_number HOTP slot number, slot_number<3 542 * @return char[20] the name of the slot 543 */ 544 NK_C_API char * NK_get_hotp_slot_name(uint8_t slot_number); 545 546 /** 547 * Erase HOTP slot data from the device 548 * @param slot_number HOTP slot number, slot_number<3 549 * @param temporary_password admin temporary password 550 * @return command processing error code 551 */ 552 NK_C_API int NK_erase_hotp_slot(uint8_t slot_number, const char *temporary_password); 553 554 /** 555 * Erase TOTP slot data from the device 556 * @param slot_number TOTP slot number, slot_number<15 557 * @param temporary_password admin temporary password 558 * @return command processing error code 559 */ 560 NK_C_API int NK_erase_totp_slot(uint8_t slot_number, const char *temporary_password); 561 562 /** 563 * Write HOTP slot data to the device 564 * @param slot_number HOTP slot number, slot_number<3, 0-numbered 565 * @param slot_name char[15] desired slot name. C string (requires ending '\0'; 16 bytes). 566 * @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). 567 * See NitrokeyManager::is_320_OTP_secret_supported. 568 * @param hotp_counter uint32_t starting value of HOTP counter 569 * @param use_8_digits should returned codes be 6 (false) or 8 digits (true) 570 * @param use_enter press ENTER key after sending OTP code using double-pressed scroll/num/capslock 571 * @param use_tokenID @see token_ID 572 * @param token_ID @see https://openauthentication.org/token-specs/, 'Class A' section 573 * @param temporary_password char[25] admin temporary password 574 * @return command processing error code 575 */ 576 NK_C_API int NK_write_hotp_slot(uint8_t slot_number, const char *slot_name, const char *secret, uint64_t hotp_counter, 577 bool use_8_digits, bool use_enter, bool use_tokenID, const char *token_ID, 578 const char *temporary_password); 579 580 /** 581 * Write TOTP slot data to the device 582 * @param slot_number TOTP slot number, slot_number<15, 0-numbered 583 * @param slot_name char[15] desired slot name. C string (requires ending '\0'; 16 bytes). 584 * @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). 585 * See NitrokeyManager::is_320_OTP_secret_supported. 586 * @param time_window uint16_t time window for this TOTP 587 * @param use_8_digits should returned codes be 6 (false) or 8 digits (true) 588 * @param use_enter press ENTER key after sending OTP code using double-pressed scroll/num/capslock 589 * @param use_tokenID @see token_ID 590 * @param token_ID @see https://openauthentication.org/token-specs/, 'Class A' section 591 * @param temporary_password char[20] admin temporary password 592 * @return command processing error code 593 */ 594 NK_C_API int NK_write_totp_slot(uint8_t slot_number, const char *slot_name, const char *secret, uint16_t time_window, 595 bool use_8_digits, bool use_enter, bool use_tokenID, const char *token_ID, 596 const char *temporary_password); 597 598 /** 599 * Get HOTP code from the device 600 * @param slot_number HOTP slot number, slot_number<3 601 * @return HOTP code 602 */ 603 NK_C_API char * NK_get_hotp_code(uint8_t slot_number); 604 605 /** 606 * Get HOTP code from the device (PIN protected) 607 * @param slot_number HOTP slot number, slot_number<3 608 * @param user_temporary_password char[25] user temporary password if PIN protected OTP codes are enabled, 609 * otherwise should be set to empty string - '' 610 * @return HOTP code 611 */ 612 NK_C_API char * NK_get_hotp_code_PIN(uint8_t slot_number, const char *user_temporary_password); 613 614 /** 615 * Get TOTP code from the device 616 * @param slot_number TOTP slot number, slot_number<15 617 * @param challenge TOTP challenge -- unused 618 * @param last_totp_time last time -- unused 619 * @param last_interval last interval --unused 620 * @return TOTP code 621 */ 622 NK_C_API char * NK_get_totp_code(uint8_t slot_number, uint64_t challenge, uint64_t last_totp_time, 623 uint8_t last_interval); 624 625 /** 626 * Get TOTP code from the device (PIN protected) 627 * @param slot_number TOTP slot number, slot_number<15 628 * @param challenge TOTP challenge -- unused 629 * @param last_totp_time last time -- unused 630 * @param last_interval last interval -- unused 631 * @param user_temporary_password char[25] user temporary password if PIN protected OTP codes are enabled, 632 * otherwise should be set to empty string - '' 633 * @return TOTP code 634 */ 635 NK_C_API char * NK_get_totp_code_PIN(uint8_t slot_number, uint64_t challenge, 636 uint64_t last_totp_time, uint8_t last_interval, 637 const char *user_temporary_password); 638 639 /** 640 * Set time on the device (for TOTP requests) 641 * @param time seconds in unix epoch (from 01.01.1970) 642 * @return command processing error code 643 */ 644 NK_C_API int NK_totp_set_time(uint64_t time); 645 646 /** 647 * Set the device time used for TOTP to the given time. Contrary to 648 * {@code set_time(uint64_t)}, this command fails if {@code old_time} 649 * > {@code time} or if {@code old_time} is zero (where {@code 650 * old_time} is the current time on the device). 651 * 652 * @param time new device time as Unix timestamp (seconds since 653 * 1970-01-01) 654 * @return command processing error code 655 */ 656 NK_C_API int NK_totp_set_time_soft(uint64_t time); 657 658 // NK_totp_get_time is deprecated -- use NK_totp_set_time_soft instead 659 DEPRECATED 660 NK_C_API int NK_totp_get_time(); 661 662 //passwords 663 /** 664 * Change administrator PIN 665 * @param current_PIN char[25] current PIN 666 * @param new_PIN char[25] new PIN 667 * @return command processing error code 668 */ 669 NK_C_API int NK_change_admin_PIN(const char *current_PIN, const char *new_PIN); 670 671 /** 672 * Change user PIN 673 * @param current_PIN char[25] current PIN 674 * @param new_PIN char[25] new PIN 675 * @return command processing error code 676 */ 677 NK_C_API int NK_change_user_PIN(const char *current_PIN, const char *new_PIN); 678 679 680 /** 681 * Get retry count of user PIN 682 * @return user PIN retry count 683 */ 684 NK_C_API uint8_t NK_get_user_retry_count(); 685 686 /** 687 * Get retry count of admin PIN 688 * @return admin PIN retry count 689 */ 690 NK_C_API uint8_t NK_get_admin_retry_count(); 691 //password safe 692 693 /** 694 * Enable password safe access 695 * @param user_pin char[30] current user PIN 696 * @return command processing error code 697 */ 698 NK_C_API int NK_enable_password_safe(const char *user_pin); 699 700 /** 701 * Get password safe slots' status 702 * The return value must be freed using NK_free_password_safe_slot_status. 703 * @return uint8_t[16] slot statuses - each byte represents one slot with 0 (not programmed) and 1 (programmed) 704 */ 705 NK_C_API uint8_t * NK_get_password_safe_slot_status(); 706 707 /** 708 * Free a value returned by NK_get_password_safe_slot_status. May be 709 * called with a NULL argument. 710 */ 711 NK_C_API void NK_free_password_safe_slot_status(uint8_t* status); 712 713 /** 714 * Get password safe slot name 715 * @param slot_number password safe slot number, slot_number<16 716 * @return slot name 717 */ 718 NK_C_API char *NK_get_password_safe_slot_name(uint8_t slot_number); 719 720 /** 721 * Get password safe slot login 722 * @param slot_number password safe slot number, slot_number<16 723 * @return login from the PWS slot 724 */ 725 NK_C_API char *NK_get_password_safe_slot_login(uint8_t slot_number); 726 727 /** 728 * Get the password safe slot password 729 * @param slot_number password safe slot number, slot_number<16 730 * @return password from the PWS slot 731 */ 732 NK_C_API char *NK_get_password_safe_slot_password(uint8_t slot_number); 733 734 /** 735 * Write password safe data to the slot 736 * @param slot_number password safe slot number, slot_number<16 737 * @param slot_name char[11] name of the slot 738 * @param slot_login char[32] login string 739 * @param slot_password char[20] password string 740 * @return command processing error code 741 */ 742 NK_C_API int NK_write_password_safe_slot(uint8_t slot_number, const char *slot_name, 743 const char *slot_login, const char *slot_password); 744 745 /** 746 * Erase the password safe slot from the device 747 * @param slot_number password safe slot number, slot_number<16 748 * @return command processing error code 749 */ 750 NK_C_API int NK_erase_password_safe_slot(uint8_t slot_number); 751 752 /** 753 * Check whether AES is supported by the device 754 * @return 0 for no and 1 for yes 755 */ 756 NK_C_API int NK_is_AES_supported(const char *user_password); 757 758 /** 759 * Get device's major firmware version 760 * @return major part of the version number (e.g. 0 from 0.48, 0 from 0.7 etc.) 761 */ 762 NK_C_API uint8_t NK_get_major_firmware_version(); 763 764 /** 765 * Get device's minor firmware version 766 * @return minor part of the version number (e.g. 7 from 0.7, 48 from 0.48 etc.) 767 */ 768 NK_C_API uint8_t NK_get_minor_firmware_version(); 769 770 /** 771 * Function to determine unencrypted volume PIN type 772 * @param minor_firmware_version 773 * @return Returns 1, if set unencrypted volume ro/rw pin type is User, 0 otherwise. 774 */ 775 NK_C_API int NK_set_unencrypted_volume_rorw_pin_type_user(); 776 777 778 /** 779 * This command is typically run to initiate 780 * communication with the device (altough not required). 781 * It sets time on device and returns its current status 782 * - a combination of set_time and get_status_storage commands 783 * Storage only 784 * @param seconds_from_epoch date and time expressed in seconds 785 */ 786 NK_C_API int NK_send_startup(uint64_t seconds_from_epoch); 787 788 /** 789 * Unlock encrypted volume. 790 * Storage only 791 * @param user_pin user pin 20 characters 792 * @return command processing error code 793 */ 794 NK_C_API int NK_unlock_encrypted_volume(const char* user_pin); 795 796 /** 797 * Locks encrypted volume 798 * @return command processing error code 799 */ 800 NK_C_API int NK_lock_encrypted_volume(); 801 802 /** 803 * Unlock hidden volume and lock encrypted volume. 804 * Requires encrypted volume to be unlocked. 805 * Storage only 806 * @param hidden_volume_password 20 characters 807 * @return command processing error code 808 */ 809 NK_C_API int NK_unlock_hidden_volume(const char* hidden_volume_password); 810 811 /** 812 * Locks hidden volume 813 * @return command processing error code 814 */ 815 NK_C_API int NK_lock_hidden_volume(); 816 817 /** 818 * Create hidden volume. 819 * Requires encrypted volume to be unlocked. 820 * Storage only 821 * @param slot_nr slot number in range 0-3 822 * @param start_percent volume begin expressed in percent of total available storage, int in range 0-99 823 * @param end_percent volume end expressed in percent of total available storage, int in range 1-100 824 * @param hidden_volume_password 20 characters 825 * @return command processing error code 826 */ 827 NK_C_API int NK_create_hidden_volume(uint8_t slot_nr, uint8_t start_percent, uint8_t end_percent, 828 const char *hidden_volume_password); 829 830 /** 831 * Make unencrypted volume read-only. 832 * Device hides unencrypted volume for a second therefore make sure 833 * buffers are flushed before running. 834 * Does nothing if firmware version is not matched 835 * Firmware range: Storage v0.50, v0.48 and below 836 * Storage only 837 * @param user_pin 20 characters User PIN 838 * @return command processing error code 839 */ 840 //[[deprecated("Use NK_set_unencrypted_read_only_admin instead")]] 841 DEPRECATED 842 NK_C_API int NK_set_unencrypted_read_only(const char *user_pin); 843 844 /** 845 * Make unencrypted volume read-write. 846 * Device hides unencrypted volume for a second therefore make sure 847 * buffers are flushed before running. 848 * Does nothing if firmware version is not matched 849 * Firmware range: Storage v0.50, v0.48 and below 850 * Storage only 851 * @param user_pin 20 characters User PIN 852 * @return command processing error code 853 */ 854 //[[deprecated("Use NK_set_unencrypted_read_write_admin instead")]] 855 DEPRECATED 856 NK_C_API int NK_set_unencrypted_read_write(const char *user_pin); 857 858 /** 859 * Make unencrypted volume read-only. 860 * Device hides unencrypted volume for a second therefore make sure 861 * buffers are flushed before running. 862 * Does nothing if firmware version is not matched 863 * Firmware range: Storage v0.49, v0.51+ 864 * Storage only 865 * @param admin_pin 20 characters Admin PIN 866 * @return command processing error code 867 */ 868 NK_C_API int NK_set_unencrypted_read_only_admin(const char* admin_pin); 869 870 /** 871 * Make unencrypted volume read-write. 872 * Device hides unencrypted volume for a second therefore make sure 873 * buffers are flushed before running. 874 * Does nothing if firmware version is not matched 875 * Firmware range: Storage v0.49, v0.51+ 876 * Storage only 877 * @param admin_pin 20 characters Admin PIN 878 * @return command processing error code 879 */ 880 NK_C_API int NK_set_unencrypted_read_write_admin(const char* admin_pin); 881 882 /** 883 * Make encrypted volume read-only. 884 * Device hides encrypted volume for a second therefore make sure 885 * buffers are flushed before running. 886 * Firmware range: v0.49 only, future (see firmware release notes) 887 * Storage only 888 * @param admin_pin 20 characters 889 * @return command processing error code 890 */ 891 NK_C_API int NK_set_encrypted_read_only(const char* admin_pin); 892 893 /** 894 * Make encrypted volume read-write. 895 * Device hides encrypted volume for a second therefore make sure 896 * buffers are flushed before running. 897 * Firmware range: v0.49 only, future (see firmware release notes) 898 * Storage only 899 * @param admin_pin 20 characters 900 * @return command processing error code 901 */ 902 NK_C_API int NK_set_encrypted_read_write(const char* admin_pin); 903 904 /** 905 * Exports device's firmware to unencrypted volume. 906 * Storage only 907 * @param admin_pin 20 characters 908 * @return command processing error code 909 */ 910 NK_C_API int NK_export_firmware(const char* admin_pin); 911 912 /** 913 * Clear new SD card notification. It is set after factory reset. 914 * Storage only 915 * @param admin_pin 20 characters 916 * @return command processing error code 917 */ 918 NK_C_API int NK_clear_new_sd_card_warning(const char* admin_pin); 919 920 /** 921 * Fill SD card with random data. 922 * Should be done on first stick initialization after creating keys. 923 * Storage only 924 * @param admin_pin 20 characters 925 * @return command processing error code 926 */ 927 NK_C_API int NK_fill_SD_card_with_random_data(const char* admin_pin); 928 929 /** 930 * Change update password. 931 * Update password is used for entering update mode, where firmware 932 * could be uploaded using dfu-programmer or other means. 933 * Storage only 934 * @param current_update_password 20 characters 935 * @param new_update_password 20 characters 936 * @return command processing error code 937 */ 938 NK_C_API int NK_change_update_password(const char* current_update_password, 939 const char* new_update_password); 940 941 /** 942 * Enter update mode. Needs update password. 943 * When device is in update mode it no longer accepts any HID commands until 944 * firmware is launched (regardless of being updated or not). 945 * Smartcard (through CCID interface) and its all volumes are not visible as well. 946 * Its VID and PID are changed to factory-default (03eb:2ff1 Atmel Corp.) 947 * to be detected by flashing software. Result of this command can be reversed 948 * by using 'launch' command. 949 * For dfu-programmer it would be: 'dfu-programmer at32uc3a3256s launch'. 950 * Storage only 951 * @param update_password 20 characters 952 * @return command processing error code 953 */ 954 NK_C_API int NK_enable_firmware_update(const char* update_password); 955 956 /** 957 * Get Storage stick status as string. 958 * Storage only 959 * @return string with devices attributes 960 */ 961 NK_C_API char* NK_get_status_storage_as_string(); 962 963 /** 964 * Get the Storage stick status and return the command processing 965 * error code. If the code is zero, i. e. the command was successful, 966 * the storage status is written to the output pointer's target. 967 * The output pointer must not be null. 968 * 969 * @param out the output pointer for the storage status 970 * @return command processing error code 971 */ 972 NK_C_API int NK_get_status_storage(struct NK_storage_status* out); 973 974 /** 975 * Get SD card usage attributes. Usable during hidden volumes creation. 976 * If the command was successful (return value 0), the usage data is 977 * written to the output pointer’s target. The output pointer must 978 * not be null. 979 * Storage only 980 * @param out the output pointer for the usage data 981 * @return command processing error code 982 */ 983 NK_C_API int NK_get_SD_usage_data(struct NK_SD_usage_data* out); 984 985 /** 986 * Get SD card usage attributes as string. 987 * Usable during hidden volumes creation. 988 * Storage only 989 * @return string with SD card usage attributes 990 */ 991 NK_C_API char* NK_get_SD_usage_data_as_string(); 992 993 /** 994 * Get progress value of current long operation. 995 * Storage only 996 * @return int in range 0-100 or -1 if device is not busy or -2 if an 997 * error occured 998 */ 999 NK_C_API int NK_get_progress_bar_value(); 1000 1001 /** 1002 * Returns a list of connected devices' id's, delimited by ';' character. Empty string is returned on no device found. 1003 * Each ID could consist of: 1004 * 1. SC_id:SD_id_p_path (about 40 bytes) 1005 * 2. path (about 10 bytes) 1006 * where 'path' is USB path (bus:num), 'SC_id' is smartcard ID, 'SD_id' is storage card ID and 1007 * '_p_' and ':' are field delimiters. 1008 * Case 2 (USB path only) is used, when the device cannot be asked about its status data (e.g. during a long operation, 1009 * like clearing SD card. 1010 * Internally connects to all available devices and creates a map between ids and connection objects. 1011 * Side effects: changes active device to last detected Storage device. 1012 * Storage only 1013 * @example Example of returned data: '00005d19:dacc2cb4_p_0001:0010:02;000037c7:4cf12445_p_0001:000f:02;0001:000c:02' 1014 * @return string delimited id's of connected devices 1015 */ 1016 NK_C_API char* NK_list_devices_by_cpuID(); 1017 1018 /** 1019 * Returns a linked list of all connected devices, or null if no devices 1020 * are connected or an error occured. The linked list must be freed by 1021 * calling NK_free_device_info. 1022 * @return a linked list of all connected devices 1023 */ 1024 NK_C_API struct NK_device_info* NK_list_devices(); 1025 1026 /** 1027 * Free a linked list returned by NK_list_devices. 1028 * @param the linked list to free or null 1029 */ 1030 NK_C_API void NK_free_device_info(struct NK_device_info* device_info); 1031 1032 /** 1033 * Connects to the device with given ID. ID's list could be created with NK_list_devices_by_cpuID. 1034 * Requires calling to NK_list_devices_by_cpuID first. Connecting to arbitrary ID/USB path is not handled. 1035 * On connection requests status from device and disconnects it / removes from map on connection failure. 1036 * Storage only 1037 * @param id Target device ID (example: '00005d19:dacc2cb4_p_0001:0010:02') 1038 * @return 1 on successful connection, 0 otherwise 1039 */ 1040 NK_C_API int NK_connect_with_ID(const char* id); 1041 1042 /** 1043 * Connects to a device with the given path. The path is a USB device 1044 * path as returned by hidapi. 1045 * @param path the device path 1046 * @return 1 on successful connection, 0 otherwise 1047 */ 1048 NK_C_API int NK_connect_with_path(const char* path); 1049 1050 /** 1051 * Blink red and green LED alternatively and infinitely (until device is reconnected). 1052 * @return command processing error code 1053 */ 1054 NK_C_API int NK_wink(); 1055 1056 1057 /** 1058 * Enable update mode on Nitrokey Pro. 1059 * Supported from v0.11. 1060 * @param update_password 20 bytes update password 1061 * @return command processing error code 1062 */ 1063 NK_C_API int NK_enable_firmware_update_pro(const char* update_password); 1064 1065 /** 1066 * Change update-mode password on Nitrokey Pro. 1067 * Supported from v0.11. 1068 * @param current_firmware_password 20 bytes update password 1069 * @param new_firmware_password 20 bytes update password 1070 * @return command processing error code 1071 */ 1072 NK_C_API int NK_change_firmware_password_pro(const char *current_firmware_password, const char *new_firmware_password); 1073 1074 1075 // as in ReadSlot::ResponsePayload 1076 struct ReadSlot_t { 1077 uint8_t slot_name[15]; 1078 uint8_t _slot_config; 1079 uint8_t slot_token_id[13]; 1080 uint64_t slot_counter; 1081 }; 1082 1083 1084 NK_C_API int NK_read_HOTP_slot(const uint8_t slot_num, struct ReadSlot_t* out); 1085 1086 #ifdef __cplusplus 1087 } 1088 #endif 1089 1090 #endif //LIBNITROKEY_NK_C_API_H 1091