NK_C_API.h

Go to the documentation of this file.

/*
 * 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
 
#ifdef __cplusplus
extern "C" {
#endif
 
  extern const uint8_t NK_PWS_SLOT_COUNT;
 
  static const int MAXIMUM_STR_REPLY_LENGTH = 8192;
 
        enum NK_device_model {
                NK_DISCONNECTED = 0,
            NK_PRO = 1,
            NK_STORAGE = 2,
            NK_LIBREM = 3
        };
 
    struct NK_device_info {
        enum NK_device_model model;
        char* path;
        char* serial_number;
        struct NK_device_info* next;
    };
 
    struct NK_status {
        uint8_t firmware_version_major;
        uint8_t firmware_version_minor;
        uint32_t serial_number_smart_card;
        uint8_t config_numlock;
        uint8_t config_capslock;
        uint8_t config_scrolllock;
        bool otp_user_password;
    };
 
        struct NK_storage_status {
        bool unencrypted_volume_read_only;
        bool unencrypted_volume_active;
        bool encrypted_volume_read_only;
        bool encrypted_volume_active;
        bool hidden_volume_read_only;
        bool hidden_volume_active;
        uint8_t firmware_version_major;
        uint8_t firmware_version_minor;
        bool firmware_locked;
        uint32_t serial_number_sd_card;
        uint32_t serial_number_smart_card;
        uint8_t user_retry_count;
        uint8_t admin_retry_count;
        bool new_sd_card_found;
        bool filled_with_random;
        bool stick_initialized;
        };
 
    struct NK_SD_usage_data {
        uint8_t write_level_min;
        uint8_t write_level_max;
    };
 
        struct NK_config {
            uint8_t numlock;
            uint8_t capslock;
            uint8_t scrolllock;
            bool enable_user_password;
            bool disable_user_password;
        };
 
   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);
 
 
    NK_C_API void NK_set_debug(bool state);
 
    NK_C_API void NK_set_debug_level(const int level);
 
    NK_C_API typedef void (*NK_log_function)(int, const char*);
 
    NK_C_API void NK_set_log_function(NK_log_function fn);
 
    NK_C_API unsigned int NK_get_major_library_version();
 
    NK_C_API unsigned int NK_get_minor_library_version();
 
    NK_C_API const char* NK_get_library_version();
 
    NK_C_API int NK_login(const char *device_model);
 
        NK_C_API int NK_login_enum(enum NK_device_model device_model);
 
    NK_C_API int NK_login_auto();
 
    NK_C_API int NK_logout();
 
    NK_C_API enum NK_device_model NK_get_device_model();
 
    DEPRECATED
    NK_C_API char * NK_status();
 
    NK_C_API char * NK_get_status_as_string();
 
    NK_C_API int NK_get_status(struct NK_status* out);
 
    NK_C_API char * NK_device_serial_number();
 
    NK_C_API uint32_t NK_device_serial_number_as_u32();
 
    NK_C_API uint8_t NK_get_last_command_status();
 
    NK_C_API int NK_lock_device();
 
    NK_C_API int NK_user_authenticate(const char* user_password, const char* user_temporary_password);
 
    NK_C_API int NK_first_authenticate(const char* admin_password, const char* admin_temporary_password);
 
    NK_C_API int NK_factory_reset(const char* admin_password);
 
    NK_C_API int NK_build_aes_key(const char* admin_password);
 
    NK_C_API int NK_unlock_user_password(const char *admin_password, const char *new_user_password);
 
    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);
 
    NK_C_API int NK_write_config_struct(struct NK_config config, const char *admin_temporary_password);
 
    NK_C_API uint8_t* NK_read_config();
 
        NK_C_API void NK_free_config(uint8_t* config);
 
    NK_C_API int NK_read_config_struct(struct NK_config* out);
 
    //OTP
 
    NK_C_API char * NK_get_totp_slot_name(uint8_t slot_number);
 
    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);
 
    NK_C_API int NK_erase_totp_slot(uint8_t slot_number, const char *temporary_password);
 
    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);
 
    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);
 
    NK_C_API char * NK_get_hotp_code(uint8_t slot_number);
 
    NK_C_API char * NK_get_hotp_code_PIN(uint8_t slot_number, const char *user_temporary_password);
 
    NK_C_API char * NK_get_totp_code(uint8_t slot_number, uint64_t challenge, uint64_t last_totp_time,
        uint8_t last_interval);
 
    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);
 
    NK_C_API int NK_totp_set_time(uint64_t time);
 
    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
    NK_C_API int NK_change_admin_PIN(const char *current_PIN, const char *new_PIN);
 
    NK_C_API int NK_change_user_PIN(const char *current_PIN, const char *new_PIN);
 
 
    NK_C_API uint8_t NK_get_user_retry_count();
 
    NK_C_API uint8_t NK_get_admin_retry_count();
    //password safe
 
    NK_C_API int NK_enable_password_safe(const char *user_pin);
 
    NK_C_API uint8_t * NK_get_password_safe_slot_status();
 
        NK_C_API void NK_free_password_safe_slot_status(uint8_t* status);
 
    NK_C_API char *NK_get_password_safe_slot_name(uint8_t slot_number);
 
    NK_C_API char *NK_get_password_safe_slot_login(uint8_t slot_number);
 
    NK_C_API char *NK_get_password_safe_slot_password(uint8_t slot_number);
 
    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);
 
    NK_C_API int NK_erase_password_safe_slot(uint8_t slot_number);
 
    NK_C_API int NK_is_AES_supported(const char *user_password);
 
    NK_C_API uint8_t NK_get_major_firmware_version();
 
    NK_C_API uint8_t NK_get_minor_firmware_version();
 
    NK_C_API int NK_set_unencrypted_volume_rorw_pin_type_user();
 
 
    NK_C_API int NK_send_startup(uint64_t seconds_from_epoch);
 
    NK_C_API int NK_unlock_encrypted_volume(const char* user_pin);
 
    NK_C_API int NK_lock_encrypted_volume();
 
    NK_C_API int NK_unlock_hidden_volume(const char* hidden_volume_password);
 
    NK_C_API int NK_lock_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);
 
  //[[deprecated("Use NK_set_unencrypted_read_only_admin instead")]]
  DEPRECATED
  NK_C_API int NK_set_unencrypted_read_only(const char *user_pin);
 
  //[[deprecated("Use NK_set_unencrypted_read_write_admin instead")]]
  DEPRECATED
  NK_C_API int NK_set_unencrypted_read_write(const char *user_pin);
 
    NK_C_API int NK_set_unencrypted_read_only_admin(const char* admin_pin);
 
    NK_C_API int NK_set_unencrypted_read_write_admin(const char* admin_pin);
 
    NK_C_API int NK_set_encrypted_read_only(const char* admin_pin);
 
    NK_C_API int NK_set_encrypted_read_write(const char* admin_pin);
 
    NK_C_API int NK_export_firmware(const char* admin_pin);
 
    NK_C_API int NK_clear_new_sd_card_warning(const char* admin_pin);
 
    NK_C_API int NK_fill_SD_card_with_random_data(const char* admin_pin);
 
    NK_C_API int NK_change_update_password(const char* current_update_password,
        const char* new_update_password);
 
    NK_C_API int NK_enable_firmware_update(const char* update_password);
 
    NK_C_API char* NK_get_status_storage_as_string();
 
    NK_C_API int NK_get_status_storage(struct NK_storage_status* out);
 
    NK_C_API int NK_get_SD_usage_data(struct NK_SD_usage_data* out);
 
    NK_C_API char* NK_get_SD_usage_data_as_string();
 
    NK_C_API int NK_get_progress_bar_value();
 
    NK_C_API char* NK_list_devices_by_cpuID();
 
    NK_C_API struct NK_device_info* NK_list_devices();
 
    NK_C_API void NK_free_device_info(struct NK_device_info* device_info);
 
    NK_C_API int NK_connect_with_ID(const char* id);
 
        NK_C_API int NK_connect_with_path(const char* path);
 
    NK_C_API int NK_wink();
 
 
    NK_C_API int NK_enable_firmware_update_pro(const char* update_password);
 
  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;
};
 
struct GetRandom_t {
    uint8_t op_success;
    uint8_t size_effective;
    uint8_t data[51];
};
 
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);
 
#ifdef __cplusplus
}
#endif
 
#endif //LIBNITROKEY_NK_C_API_H