libyubihsm
Data Structures | Macros | Typedefs | Enumerations | Functions
yubihsm.h File Reference

Everything you need for yubihsm. More...

Go to the source code of this file.

Data Structures

struct  yh_capabilities
 Capabilitites representation. More...
 
struct  yh_log_entry
 Logging struct as returned by device. More...
 
struct  yh_object_descriptor
 Object descriptor. More...
 

Macros

#define YH_CONTEXT_LEN   16
 Length of context array for authentication.
 
#define YH_HOST_CHAL_LEN   8
 Length of host challenge for authentication.
 
#define YH_MSG_BUF_SIZE   2048
 Maximum length of message buffer.
 
#define YH_KEY_LEN   16
 Length of authentication keys.
 
#define YH_VID   0x1050
 Device vendor ID.
 
#define YH_PID   0x0030
 Device product ID.
 
#define YH_CMD_RESP_FLAG   0x80
 Response flag for commands.
 
#define YH_MAX_ITEMS_COUNT   256
 Max items the device may hold.
 
#define YH_MAX_SESSIONS   16
 Max sessions the device may hold.
 
#define YH_DEFAULT_ENC_KEY   "\x09\x0b\x47\xdb\xed\x59\x56\x54\x90\x1d\xee\x1c\xc6\x55\xe4\x20"
 Default encryption key.
 
#define YH_DEFAULT_MAC_KEY   "\x59\x2f\xd4\x83\xf7\x59\xe2\x99\x09\xa0\x4c\x45\x05\xd2\xce\x0a"
 Default MAC key.
 
#define YH_DEFAULT_PASSWORD   "password"
 Default authentication key password.
 
#define YH_DEFAULT_SALT   "Yubico"
 Salt to be used for PBKDF2 key derivation.
 
#define YH_DEFAULT_ITERS   10000
 Number of iterations for PBKDF2 key derivation.
 
#define YH_CAPABILITIES_LEN   8
 Length of capabilities array.
 
#define YH_MAX_LOG_ENTRIES   64
 Max log entries the device may hold.
 
#define YH_OBJ_LABEL_LEN   40
 Length of object labels.
 
#define YH_MAX_DOMAINS   16
 Max number of domains.
 
#define YH_VERB_QUIET   0x00
 No messages.
 
#define YH_VERB_INTERMEDIATE   0x01
 Intermediate results.
 
#define YH_VERB_CRYPTO   0x02
 Crypto results.
 
#define YH_VERB_RAW   0x04
 Raw messages.
 
#define YH_VERB_INFO   0x08
 General info.
 
#define YH_VERB_ERR   0x10
 Error messages.
 
#define YH_VERB_ALL   0xff
 All previous options enabled.
 
#define YH_CCM_WRAP_OVERHEAD   (1 + 13 + 16)
 This is the overhead when doing aes-ccm wrapping, 1 byte identifier, 13 bytes nonce and 16 bytes mac.
 
#define ADD_COMMAND(c, v)   c = v, c##_R = v | YH_CMD_RESP_FLAG
 Macro to define command and response command.
 
#define YH_MAX_ALGORITHM_COUNT   0xff
 Max number of algorithms defined here.
 
#define YH_LOG_DIGEST_SIZE   16
 Size that the log digest is truncated to.
 
#define YH_ORIGIN_GENERATED   0x01
 Origin is generated.
 
#define YH_ORIGIN_IMPORTED   0x02
 Origin is imported.
 
#define YH_ORIGIN_IMPORTED_WRAPPED   0x10
 Origin is wrapped (note: this is used in combination with objects original origin)
 

Typedefs

typedef struct yh_connector yh_connector
 Reference to a connector.
 
typedef struct yh_session yh_session
 Reference to a session.
 

Enumerations

enum  yh_rc {
  YHR_SUCCESS = 0, YHR_MEMORY = -1, YHR_INIT_ERROR = -2, YHR_NET_ERROR = -3,
  YHR_CONNECTOR_NOT_FOUND = -4, YHR_INVALID_PARAMS = -5, YHR_WRONG_LENGTH = -6, YHR_BUFFER_TOO_SMALL = -7,
  YHR_CRYPTOGRAM_MISMATCH = -8, YHR_AUTH_SESSION_ERROR = -9, YHR_MAC_MISMATCH = -10, YHR_DEVICE_OK = -11,
  YHR_DEVICE_INV_COMMAND = -12, YHR_DEVICE_INV_DATA = -13, YHR_DEVICE_INV_SESSION = -14, YHR_DEVICE_AUTH_FAIL = -15,
  YHR_DEVICE_SESSIONS_FULL = -16, YHR_DEVICE_SESSION_FAILED = -17, YHR_DEVICE_STORAGE_FAILED = -18, YHR_DEVICE_WRONG_LENGTH = -19,
  YHR_DEVICE_INV_PERMISSION = -20, YHR_DEVICE_LOG_FULL = -21, YHR_DEVICE_OBJ_NOT_FOUND = -22, YHR_DEVICE_ID_ILLEGAL = -23,
  YHR_DEVICE_INVALID_OTP = -24, YHR_DEVICE_DEMO_MODE = -25, YHR_DEVICE_CMD_UNEXECUTED = -26, YHR_GENERIC_ERROR = -27,
  YHR_DEVICE_OBJECT_EXISTS = -28, YHR_CONNECTOR_ERROR = -29
}
 Return codes. More...
 
enum  yh_cmd {
  YHC_ECHO = 0x01, YHC_ECHO_R = 0x01 | 0x80, YHC_CREATE_SES = 0x03, YHC_CREATE_SES_R = 0x03 | 0x80,
  YHC_AUTH_SES = 0x04, YHC_AUTH_SES_R = 0x04 | 0x80, YHC_SES_MSG = 0x05, YHC_SES_MSG_R = 0x05 | 0x80,
  YHC_GET_DEVICE_INFO = 0x06, YHC_GET_DEVICE_INFO_R = 0x06 | 0x80, YHC_BSL = 0x07, YHC_BSL_R = 0x07 | 0x80,
  YHC_RESET = 0x08, YHC_RESET_R = 0x08 | 0x80, YHC_CLOSE_SES = 0x40, YHC_CLOSE_SES_R = 0x40 | 0x80,
  YHC_STATS = 0x041, YHC_STATS_R = 0x041 | 0x80, YHC_PUT_OPAQUE = 0x42, YHC_PUT_OPAQUE_R = 0x42 | 0x80,
  YHC_GET_OPAQUE = 0x43, YHC_GET_OPAQUE_R = 0x43 | 0x80, YHC_PUT_AUTHKEY = 0x44, YHC_PUT_AUTHKEY_R = 0x44 | 0x80,
  YHC_PUT_ASYMMETRIC_KEY = 0x45, YHC_PUT_ASYMMETRIC_KEY_R = 0x45 | 0x80, YHC_GEN_ASYMMETRIC_KEY = 0x46, YHC_GEN_ASYMMETRIC_KEY_R = 0x46 | 0x80,
  YHC_SIGN_DATA_PKCS1 = 0x47, YHC_SIGN_DATA_PKCS1_R = 0x47 | 0x80, YHC_LIST = 0x48, YHC_LIST_R = 0x48 | 0x80,
  YHC_DECRYPT_PKCS1 = 0x49, YHC_DECRYPT_PKCS1_R = 0x49 | 0x80, YHC_EXPORT_WRAPPED = 0x4a, YHC_EXPORT_WRAPPED_R = 0x4a | 0x80,
  YHC_IMPORT_WRAPPED = 0x4b, YHC_IMPORT_WRAPPED_R = 0x4b | 0x80, YHC_PUT_WRAP_KEY = 0x4c, YHC_PUT_WRAP_KEY_R = 0x4c | 0x80,
  YHC_GET_LOGS = 0x4d, YHC_GET_LOGS_R = 0x4d | 0x80, YHC_GET_OBJECT_INFO = 0x4e, YHC_GET_OBJECT_INFO_R = 0x4e | 0x80,
  YHC_PUT_OPTION = 0x4f, YHC_PUT_OPTION_R = 0x4f | 0x80, YHC_GET_OPTION = 0x50, YHC_GET_OPTION_R = 0x50 | 0x80,
  YHC_GET_PSEUDO_RANDOM = 0x51, YHC_GET_PSEUDO_RANDOM_R = 0x51 | 0x80, YHC_PUT_HMAC_KEY = 0x52, YHC_PUT_HMAC_KEY_R = 0x52 | 0x80,
  YHC_HMAC_DATA = 0x53, YHC_HMAC_DATA_R = 0x53 | 0x80, YHC_GET_PUBKEY = 0x54, YHC_GET_PUBKEY_R = 0x54 | 0x80,
  YHC_SIGN_DATA_PSS = 0x55, YHC_SIGN_DATA_PSS_R = 0x55 | 0x80, YHC_SIGN_DATA_ECDSA = 0x56, YHC_SIGN_DATA_ECDSA_R = 0x56 | 0x80,
  YHC_DECRYPT_ECDH = 0x57, YHC_DECRYPT_ECDH_R = 0x57 | 0x80, YHC_DELETE_OBJECT = 0x58, YHC_DELETE_OBJECT_R = 0x58 | 0x80,
  YHC_DECRYPT_OAEP = 0x59, YHC_DECRYPT_OAEP_R = 0x59 | 0x80, YHC_GENERATE_HMAC_KEY = 0x5a, YHC_GENERATE_HMAC_KEY_R = 0x5a | 0x80,
  YHC_GENERATE_WRAP_KEY = 0x5b, YHC_GENERATE_WRAP_KEY_R = 0x5b | 0x80, YHC_VERIFY_HMAC = 0x5c, YHC_VERIFY_HMAC_R = 0x5c | 0x80,
  YHC_SSH_CERTIFY = 0x5d, YHC_SSH_CERTIFY_R = 0x5d | 0x80, YHC_PUT_TEMPLATE = 0x5e, YHC_PUT_TEMPLATE_R = 0x5e | 0x80,
  YHC_GET_TEMPLATE = 0x5f, YHC_GET_TEMPLATE_R = 0x5f | 0x80, YHC_OTP_DECRYPT = 0x60, YHC_OTP_DECRYPT_R = 0x60 | 0x80,
  YHC_OTP_AEAD_CREATE = 0x61, YHC_OTP_AEAD_CREATE_R = 0x61 | 0x80, YHC_OTP_AEAD_RANDOM = 0x62, YHC_OTP_AEAD_RANDOM_R = 0x62 | 0x80,
  YHC_OTP_AEAD_REWRAP = 0x63, YHC_OTP_AEAD_REWRAP_R = 0x63 | 0x80, YHC_ATTEST_ASYMMETRIC = 0x64, YHC_ATTEST_ASYMMETRIC_R = 0x64 | 0x80,
  YHC_PUT_OTP_AEAD_KEY = 0x65, YHC_PUT_OTP_AEAD_KEY_R = 0x65 | 0x80, YHC_GENERATE_OTP_AEAD_KEY = 0x66, YHC_GENERATE_OTP_AEAD_KEY_R = 0x66 | 0x80,
  YHC_SET_LOG_INDEX = 0x67, YHC_SET_LOG_INDEX_R = 0x67 | 0x80, YHC_WRAP_DATA = 0x68, YHC_WRAP_DATA_R = 0x68 | 0x80,
  YHC_UNWRAP_DATA = 0x69, YHC_UNWRAP_DATA_R = 0x69 | 0x80, YHC_SIGN_DATA_EDDSA = 0x6a, YHC_SIGN_DATA_EDDSA_R = 0x6a | 0x80,
  YHC_BLINK = 0x6b, YHC_BLINK_R = 0x6b | 0x80, YHC_ERROR = 0x7f
}
 Command definitions. More...
 
enum  yh_object_type {
  YH_OPAQUE = 0x01, YH_AUTHKEY = 0x02, YH_ASYMMETRIC = 0x03, YH_WRAPKEY = 0x04,
  YH_HMACKEY = 0x05, YH_TEMPLATE = 0x06, YH_OTP_AEAD_KEY = 0x07, YH_PUBLIC = 0x83
}
 Object types. More...
 
enum  yh_algorithm {
  YH_ALGO_RSA_PKCS1_SHA1 = 1, YH_ALGO_RSA_PKCS1_SHA256 = 2, YH_ALGO_RSA_PKCS1_SHA384 = 3, YH_ALGO_RSA_PKCS1_SHA512 = 4,
  YH_ALGO_RSA_PSS_SHA1 = 5, YH_ALGO_RSA_PSS_SHA256 = 6, YH_ALGO_RSA_PSS_SHA384 = 7, YH_ALGO_RSA_PSS_SHA512 = 8,
  YH_ALGO_RSA_2048 = 9, YH_ALGO_RSA_3072 = 10, YH_ALGO_RSA_4096 = 11, YH_ALGO_EC_P256 = 12,
  YH_ALGO_EC_P384 = 13, YH_ALGO_EC_P521 = 14, YH_ALGO_EC_K256 = 15, YH_ALGO_EC_BP256 = 16,
  YH_ALGO_EC_BP384 = 17, YH_ALGO_EC_BP512 = 18, YH_ALGO_HMAC_SHA1 = 19, YH_ALGO_HMAC_SHA256 = 20,
  YH_ALGO_HMAC_SHA384 = 21, YH_ALGO_HMAC_SHA512 = 22, YH_ALGO_EC_ECDSA_SHA1 = 23, YH_ALGO_EC_ECDH = 24,
  YH_ALGO_RSA_OAEP_SHA1 = 25, YH_ALGO_RSA_OAEP_SHA256 = 26, YH_ALGO_RSA_OAEP_SHA384 = 27, YH_ALGO_RSA_OAEP_SHA512 = 28,
  YH_ALGO_AES128_CCM_WRAP = 29, YH_ALGO_OPAQUE_DATA = 30, YH_ALGO_OPAQUE_X509_CERT = 31, YH_ALGO_MGF1_SHA1 = 32,
  YH_ALGO_MGF1_SHA256 = 33, YH_ALGO_MGF1_SHA384 = 34, YH_ALGO_MGF1_SHA512 = 35, YH_ALGO_TEMPL_SSH = 36,
  YH_ALGO_YUBICO_OTP_AES128 = 37, YH_ALGO_YUBICO_AES_AUTH = 38, YH_ALGO_YUBICO_OTP_AES192 = 39, YH_ALGO_YUBICO_OTP_AES256 = 40,
  YH_ALGO_AES192_CCM_WRAP = 41, YH_ALGO_AES256_CCM_WRAP = 42, YH_ALGO_EC_ECDSA_SHA256 = 43, YH_ALGO_EC_ECDSA_SHA384 = 44,
  YH_ALGO_EC_ECDSA_SHA512 = 45, YH_ALGO_EC_ED25519 = 46, YH_ALGO_EC_P224 = 47
}
 Algorithms.
 
enum  yh_option { YH_OPTION_FORCE_AUDIT = 1, YH_OPTION_COMMAND_AUDIT = 3 }
 Global options. More...
 
enum  yh_connector_option { YH_CONNECTOR_HTTPS_CA = 1, YH_CONNECTOR_PROXY_SERVER = 2 }
 Options for the connector, set with yh_set_connector_option() More...
 

Functions

const char * yh_strerror (yh_rc err)
 Return a string describing an error condition. More...
 
yh_rc yh_set_verbosity (uint8_t verbosity)
 Set verbosity This function may be called prior to global library initialization. More...
 
yh_rc yh_get_verbosity (uint8_t *verbosity)
 Get verbosity. More...
 
void yh_set_debug_output (FILE *output)
 Set file for debug output. More...
 
yh_rc yh_init (void)
 Global library initialization. More...
 
yh_rc yh_exit (void)
 Global library cleanup. More...
 
yh_rc yh_init_connector (const char *url, yh_connector **connector)
 Instantiate a new connector. More...
 
yh_rc yh_set_connector_option (yh_connector *connector, yh_connector_option opt, const void *val)
 Set connector options. More...
 
yh_rc yh_connect_all (yh_connector **connectors, size_t *n_connectors, int timeout)
 Connect to all specified connectors. More...
 
yh_rc yh_connect_best (yh_connector **connectors, size_t n_connectors, int *idx)
 Connect to one connector in array. More...
 
yh_rc yh_disconnect (yh_connector *connector)
 Disconnect from connector. More...
 
yh_rc yh_send_plain_msg (yh_connector *connector, yh_cmd cmd, const uint8_t *data, size_t data_len, yh_cmd *response_cmd, uint8_t *response, size_t *response_len)
 Send a plain message to a connector. More...
 
yh_rc yh_send_secure_msg (yh_session *session, yh_cmd cmd, const uint8_t *data, size_t data_len, yh_cmd *response_cmd, uint8_t *response, size_t *response_len)
 Send an encrypted message over a session. More...
 
yh_rc yh_create_session_derived (yh_connector *connector, uint16_t auth_keyset_id, const uint8_t *password, size_t password_len, bool recreate_session, uint8_t *context, size_t context_len, yh_session **session)
 Create a session with keys derived frm password. More...
 
yh_rc yh_create_session (yh_connector *connector, uint16_t auth_keyset_id, const uint8_t *key_enc, size_t key_enc_len, const uint8_t *key_mac, size_t key_mac_len, bool recreate_session, uint8_t *context, size_t context_len, yh_session **session)
 Create a session. More...
 
yh_rc yh_begin_create_session_ext (yh_connector *connector, uint16_t auth_keyset_id, uint8_t *context, size_t context_len, uint8_t *card_cryptogram, size_t card_cryptogram_len, yh_session **session)
 Begin create extenal session. More...
 
yh_rc yh_finish_create_session_ext (yh_connector *connector, yh_session *session, const uint8_t *key_senc, size_t key_senc_len, const uint8_t *key_smac, size_t key_smac_len, const uint8_t *key_srmac, size_t key_srmac_len, uint8_t *context, size_t context_len, uint8_t *card_cryptogram, size_t card_cryptogram_len)
 Finish creating external session. More...
 
yh_rc yh_destroy_session (yh_session **session)
 Free data associated with session. More...
 
yh_rc yh_authenticate_session (yh_session *session, uint8_t *context, size_t context_len)
 Authenticate session. More...
 
yh_rc yh_util_get_device_info (yh_connector *connector, uint8_t *major, uint8_t *minor, uint8_t *patch, uint32_t *serial, uint8_t *log_total, uint8_t *log_used, yh_algorithm *algorithms, size_t *n_algorithms)
 Get device info. More...
 
yh_rc yh_util_list_objects (yh_session *session, uint16_t id, yh_object_type type, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const char *label, yh_object_descriptor *objects, size_t *n_objects)
 List objects. More...
 
yh_rc yh_util_get_object_info (yh_session *session, uint16_t id, yh_object_type type, yh_object_descriptor *object)
 Get object info. More...
 
yh_rc yh_util_get_pubkey (yh_session *session, uint16_t id, uint8_t *data, size_t *datalen, yh_algorithm *algorithm)
 Get Public key. More...
 
yh_rc yh_util_close_session (yh_session *session)
 Close session. More...
 
yh_rc yh_util_sign_pkcs1v1_5 (yh_session *session, uint16_t key_id, bool hashed, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Sign data using PKCS1 v1.5. More...
 
yh_rc yh_util_sign_pss (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len, size_t salt_len, yh_algorithm mgf1Algo)
 Sign data using RSS. More...
 
yh_rc yh_util_sign_ecdsa (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Sign data using ECDSA. More...
 
yh_rc yh_util_sign_eddsa (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Sign data using EDDSA. More...
 
yh_rc yh_util_hmac (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 HMAC data. More...
 
yh_rc yh_util_get_random (yh_session *session, size_t len, uint8_t *out, size_t *out_len)
 Get pseudo random data. More...
 
yh_rc yh_util_import_key_rsa (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const uint8_t *p, const uint8_t *q)
 Import RSA key. More...
 
yh_rc yh_util_import_key_ec (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const uint8_t *s)
 Import EC key. More...
 
yh_rc yh_util_import_key_ed (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const uint8_t *k)
 Import ED key. More...
 
yh_rc yh_util_import_key_hmac (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const uint8_t *key, size_t key_len)
 Import HMAC key. More...
 
yh_rc yh_util_generate_key_rsa (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm)
 Generate RSA key. More...
 
yh_rc yh_util_generate_key_ec (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm)
 Generate EC key. More...
 
yh_rc yh_util_generate_key_ed (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm)
 Generate ED key. More...
 
yh_rc yh_util_hmac_verify (yh_session *session, uint16_t key_id, const uint8_t *signature, size_t signature_len, const uint8_t *data, size_t data_len, bool *verified)
 Verify HMAC data. More...
 
yh_rc yh_util_generate_key_hmac (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm)
 Generate HMAC key. More...
 
yh_rc yh_util_decrypt_pkcs1v1_5 (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Decrypt PKCS1 v1.5 data. More...
 
yh_rc yh_util_decrypt_oaep (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len, const uint8_t *label, size_t label_len, yh_algorithm mgf1Algo)
 Decrypt OAEP data. More...
 
yh_rc yh_util_decrypt_ecdh (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Perform ECDH key exchange. More...
 
yh_rc yh_util_delete_object (yh_session *session, uint16_t id, yh_object_type type)
 Delete an object. More...
 
yh_rc yh_util_export_wrapped (yh_session *session, uint16_t wrapping_key_id, yh_object_type target_type, uint16_t target_id, uint8_t *out, size_t *out_len)
 Export an object under wrap. More...
 
yh_rc yh_util_import_wrapped (yh_session *session, uint16_t wrapping_key_id, const uint8_t *in, size_t in_len, yh_object_type *target_type, uint16_t *target_id)
 Import a wrapped object. More...
 
yh_rc yh_util_import_key_wrap (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const yh_capabilities *delegated_capabilities, const uint8_t *in, size_t in_len)
 Import a wrap key. More...
 
yh_rc yh_util_generate_key_wrap (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const yh_capabilities *delegated_capabilities)
 Generate a wrap key. More...
 
yh_rc yh_util_get_logs (yh_session *session, uint16_t *unlogged_boot, uint16_t *unlogged_auth, yh_log_entry *out, size_t *n_items)
 Get logs. More...
 
yh_rc yh_util_set_log_index (yh_session *session, uint16_t index)
 Set the log index. More...
 
yh_rc yh_util_get_opaque (yh_session *session, uint16_t object_id, uint8_t *out, size_t *out_len)
 Get opaque object. More...
 
yh_rc yh_util_import_opaque (yh_session *session, uint16_t *object_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const uint8_t *in, size_t in_len)
 Import opaque object. More...
 
yh_rc yh_util_ssh_certify (yh_session *session, uint16_t key_id, uint16_t template_id, yh_algorithm sig_algo, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 SSH certify. More...
 
yh_rc yh_util_import_authkey (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, const yh_capabilities *delegated_capabilities, const uint8_t *password, size_t password_len)
 Import authentication key. More...
 
yh_rc yh_util_get_template (yh_session *session, uint16_t object_id, uint8_t *out, size_t *out_len)
 Get template. More...
 
yh_rc yh_util_import_template (yh_session *session, uint16_t *object_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, const uint8_t *in, size_t in_len)
 Import template. More...
 
yh_rc yh_util_otp_aead_create (yh_session *session, uint16_t key_id, const uint8_t *key, const uint8_t *private_id, uint8_t *out, size_t *out_len)
 Create OTP AEAD. More...
 
yh_rc yh_util_otp_aead_random (yh_session *session, uint16_t key_id, uint8_t *out, size_t *out_len)
 Create OTP AEAD from random. More...
 
yh_rc yh_util_otp_decrypt (yh_session *session, uint16_t key_id, const uint8_t *aead, size_t aead_len, const uint8_t *otp, uint16_t *useCtr, uint8_t *sessionCtr, uint8_t *tstph, uint16_t *tstpl)
 Decrypt OTP. More...
 
yh_rc yh_util_put_otp_aead_key (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, uint32_t nonce_id, const uint8_t *in, size_t in_len)
 Import OTP AEAD Key. More...
 
yh_rc yh_util_generate_otp_aead_key (yh_session *session, uint16_t *key_id, const char *label, uint16_t domains, const yh_capabilities *capabilities, yh_algorithm algorithm, uint32_t nonce_id)
 Generate OTP AEAD Key. More...
 
yh_rc yh_util_attest_asymmetric (yh_session *session, uint16_t key_id, uint16_t attest_id, uint8_t *out, size_t *out_len)
 Attest asymmetric key. More...
 
yh_rc yh_util_put_option (yh_session *session, yh_option option, size_t len, uint8_t *val)
 Put global option. More...
 
yh_rc yh_util_get_option (yh_session *session, yh_option option, uint8_t *out, size_t *out_len)
 Get global option. More...
 
yh_rc yh_util_get_storage_stats (yh_session *session, uint16_t *total_records, uint16_t *free_records, uint16_t *total_pages, uint16_t *free_pages, uint16_t *page_size)
 Get storage statistics. More...
 
yh_rc yh_util_wrap_data (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Wrap data. More...
 
yh_rc yh_util_unwrap_data (yh_session *session, uint16_t key_id, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len)
 Unwrap data. More...
 
yh_rc yh_util_blink (yh_session *session, uint8_t seconds)
 Blink the device. More...
 
yh_rc yh_util_reset (yh_session *session)
 Reset the device. More...
 
yh_rc yh_get_session_id (yh_session *session, uint8_t *sid)
 Get session ID. More...
 
bool yh_connector_has_device (yh_connector *connector)
 Check if the connector has a device connected. More...
 
yh_rc yh_get_connector_version (yh_connector *connector, uint8_t *major, uint8_t *minor, uint8_t *patch)
 Get the connector version. More...
 
yh_rc yh_get_connector_address (yh_connector *connector, char **const address)
 Get connector address. More...
 
yh_rc yh_capabilities_to_num (const char *capability, yh_capabilities *result)
 Convert capability string to byte array. More...
 
yh_rc yh_num_to_capabilities (const yh_capabilities *num, const char *result[], size_t *n_result)
 Convert capability byte array to strings. More...
 
bool yh_check_capability (const yh_capabilities *capabilities, const char *capability)
 Check if capability is set. More...
 
yh_rc yh_merge_capabilities (const yh_capabilities *a, const yh_capabilities *b, yh_capabilities *result)
 Merge two sets of capabilities. More...
 
yh_rc yh_filter_capabilities (const yh_capabilities *capabilities, const yh_capabilities *filter, yh_capabilities *result)
 Filter one set of capabilities with another. More...
 
bool yh_is_rsa (yh_algorithm algorithm)
 Check if algorithm is an RSA algorithm. More...
 
bool yh_is_ec (yh_algorithm algorithm)
 Check if algorithm is an EC algorithm. More...
 
bool yh_is_ed (yh_algorithm algorithm)
 Check if algorithm is an ED algorithm. More...
 
bool yh_is_hmac (yh_algorithm algorithm)
 Check if algorithm is a HMAC algorithm. More...
 
yh_rc yh_get_key_bitlength (yh_algorithm algorithm, size_t *result)
 Get algorithm bitlength. More...
 
yh_rc yh_algo_to_string (yh_algorithm algo, char const **result)
 Convert algorithm to string. More...
 
yh_rc yh_string_to_algo (const char *string, yh_algorithm *algo)
 Convert string to algorithm. More...
 
yh_rc yh_type_to_string (yh_object_type type, char const **result)
 Convert type to string. More...
 
yh_rc yh_string_to_type (const char *string, yh_object_type *type)
 Convert string to type. More...
 
yh_rc yh_string_to_option (const char *string, yh_option *option)
 Convert string to option. More...
 
bool yh_verify_logs (yh_log_entry *logs, size_t n_items, yh_log_entry *last_previous_log)
 Verify an array of log entries. More...
 
yh_rc yh_parse_domains (const char *domains, uint16_t *result)
 Parse a string to a domains parameter. More...
 
yh_rc yh_domains_to_string (uint16_t domains, char *string, size_t max_len)
 Write out domains to a string. More...
 

Detailed Description

Everything you need for yubihsm.

Enumeration Type Documentation

◆ yh_cmd

enum yh_cmd

Command definitions.

Enumerator
YHC_ECHO 

Echo.

YHC_CREATE_SES 

Create session.

YHC_AUTH_SES 

Authenticate session.

YHC_SES_MSG 

Session message.

YHC_GET_DEVICE_INFO 

Get device info.

YHC_BSL 

BSL.

YHC_RESET 

Reset.

YHC_CLOSE_SES 

Close session.

YHC_STATS 

Storage statistics.

YHC_PUT_OPAQUE 

Put opaque.

YHC_GET_OPAQUE 

Get opaque.

YHC_PUT_AUTHKEY 

Put authentication key.

YHC_PUT_ASYMMETRIC_KEY 

Put asymmetric key.

YHC_GEN_ASYMMETRIC_KEY 

Generate asymmetric key.

YHC_SIGN_DATA_PKCS1 

Sign data with PKCS1.

YHC_LIST 

List objects.

YHC_DECRYPT_PKCS1 

Decrypt data with PKCS1.

YHC_EXPORT_WRAPPED 

Export an object wrapped.

YHC_IMPORT_WRAPPED 

Import a wrapped object.

YHC_PUT_WRAP_KEY 

Put wrap key.

YHC_GET_LOGS 

Get audit logs.

YHC_GET_OBJECT_INFO 

Get object information.

YHC_PUT_OPTION 

Put a global option.

YHC_GET_OPTION 

Get a global option.

YHC_GET_PSEUDO_RANDOM 

Get pseudo random data.

YHC_PUT_HMAC_KEY 

Put HMAC key.

YHC_HMAC_DATA 

HMAC data.

YHC_GET_PUBKEY 

Get a public key.

YHC_SIGN_DATA_PSS 

Sign data with PSS.

YHC_SIGN_DATA_ECDSA 

Sign data with ECDSA.

YHC_DECRYPT_ECDH 

Perform a ECDH exchange.

YHC_DELETE_OBJECT 

Delete an object.

YHC_DECRYPT_OAEP 

Decrypt data with OAEP.

YHC_GENERATE_HMAC_KEY 

Generate HMAC key.

YHC_GENERATE_WRAP_KEY 

Generate wrap key.

YHC_VERIFY_HMAC 

Verify HMAC data.

YHC_SSH_CERTIFY 

SSH Certify.

YHC_PUT_TEMPLATE 

Put template.

YHC_GET_TEMPLATE 

Get template.

YHC_OTP_DECRYPT 

Decrypt OTP.

YHC_OTP_AEAD_CREATE 

Create OTP AEAD.

YHC_OTP_AEAD_RANDOM 

Create OTP AEAD from random.

YHC_OTP_AEAD_REWRAP 

Rewrap OTP AEAD.

YHC_ATTEST_ASYMMETRIC 

Attest an asymmetric key.

YHC_PUT_OTP_AEAD_KEY 

Put OTP AEAD key.

YHC_GENERATE_OTP_AEAD_KEY 

Generate OTP AEAD key.

YHC_SET_LOG_INDEX 

Set log index.

YHC_WRAP_DATA 

Wrap data.

YHC_UNWRAP_DATA 

Unwrap data.

YHC_SIGN_DATA_EDDSA 

Sign data with EDDSA.

YHC_BLINK 

Blink the device.

YHC_ERROR 

Error.

◆ yh_connector_option

Options for the connector, set with yh_set_connector_option()

Enumerator
YH_CONNECTOR_HTTPS_CA 

File with CA certificate to validate the connector with (const char *) not implemented on windows.

YH_CONNECTOR_PROXY_SERVER 

Proxy server to use for connecting to the connector (const char *) not implemented on windows.

◆ yh_object_type

Object types.

Enumerator
YH_OPAQUE 

Opaque object.

YH_AUTHKEY 

Authentication key.

YH_ASYMMETRIC 

Asymmetric key.

YH_WRAPKEY 

Wrap key.

YH_HMACKEY 

HMAC key.

YH_TEMPLATE 

Template.

YH_OTP_AEAD_KEY 

OTP AEAD key.

YH_PUBLIC 

Public key (virtual..)

◆ yh_option

enum yh_option

Global options.

Enumerator
YH_OPTION_FORCE_AUDIT 

Forced audit mode.

YH_OPTION_COMMAND_AUDIT 

Audit logging per command.

◆ yh_rc

enum yh_rc

Return codes.

Enumerator
YHR_SUCCESS 

Success.

YHR_MEMORY 

Memory error.

YHR_INIT_ERROR 

Init error.

YHR_NET_ERROR 

Net error.

YHR_CONNECTOR_NOT_FOUND 

Connector not found.

YHR_INVALID_PARAMS 

Invalid parameters.

YHR_WRONG_LENGTH 

Wrong length.

YHR_BUFFER_TOO_SMALL 

Buffer too small.

YHR_CRYPTOGRAM_MISMATCH 

Cryptogram error.

YHR_AUTH_SESSION_ERROR 

Authenticate session error.

YHR_MAC_MISMATCH 

MAC not matching.

YHR_DEVICE_OK 

Device success.

YHR_DEVICE_INV_COMMAND 

Invalid command.

YHR_DEVICE_INV_DATA 

Malformed command / invalid data.

YHR_DEVICE_INV_SESSION 

Invalid session.

YHR_DEVICE_AUTH_FAIL 

Message encryption / verification failed.

YHR_DEVICE_SESSIONS_FULL 

All sessions are allocated.

YHR_DEVICE_SESSION_FAILED 

Session creation failed.

YHR_DEVICE_STORAGE_FAILED 

Storage failure.

YHR_DEVICE_WRONG_LENGTH 

Wrong length.

YHR_DEVICE_INV_PERMISSION 

Wrong permissions for operation.

YHR_DEVICE_LOG_FULL 

Log buffer is full and forced audit is set.

YHR_DEVICE_OBJ_NOT_FOUND 

Object not found.

YHR_DEVICE_ID_ILLEGAL 

Id use is illegal.

YHR_DEVICE_INVALID_OTP 

OTP submitted is invalid.

YHR_DEVICE_DEMO_MODE 

Device is in demo mode and has to be power cycled.

YHR_DEVICE_CMD_UNEXECUTED 

The command execution has not terminated.

YHR_GENERIC_ERROR 

Unknown error.

YHR_DEVICE_OBJECT_EXISTS 

Object with that ID already exists.

YHR_CONNECTOR_ERROR 

Connector operation failed.

Function Documentation

◆ yh_algo_to_string()

yh_rc yh_algo_to_string ( yh_algorithm  algo,
char const **  result 
)

Convert algorithm to string.

Parameters
algoalgorithm
resultstring
Returns
yh_rc error code

◆ yh_authenticate_session()

yh_rc yh_authenticate_session ( yh_session session,
uint8_t *  context,
size_t  context_len 
)

Authenticate session.

Parameters
sessionsession to authenticate
contextcontext data
context_lencontext length
Returns
yh_rc error code

◆ yh_begin_create_session_ext()

yh_rc yh_begin_create_session_ext ( yh_connector connector,
uint16_t  auth_keyset_id,
uint8_t *  context,
size_t  context_len,
uint8_t *  card_cryptogram,
size_t  card_cryptogram_len,
yh_session **  session 
)

Begin create extenal session.

Parameters
connectorconnector to create the session with
auth_keyset_idID of the authentication key
contextcontext data for the authentication
context_lenlength of context data
card_cryptogramcard cryptogram
card_cryptogram_lencatd cryptogram length
sessioncreated session
Returns
yh_rc error code

◆ yh_capabilities_to_num()

yh_rc yh_capabilities_to_num ( const char *  capability,
yh_capabilities result 
)

Convert capability string to byte array.

Parameters
capabilitystring of capabilities
resultcapabilities
Returns
yh_rc error code

◆ yh_check_capability()

bool yh_check_capability ( const yh_capabilities capabilities,
const char *  capability 
)

Check if capability is set.

Parameters
capabilitiescapabilities
capabilitycapability string
Returns
true or false

◆ yh_connect_all()

yh_rc yh_connect_all ( yh_connector **  connectors,
size_t *  n_connectors,
int  timeout 
)

Connect to all specified connectors.

Parameters
connectorspointer of connector array
n_connectorsnumber of connectors in array (will be set to successful connectors on return)
timeouttimeout in seconds
Returns
yh_rc error code

◆ yh_connect_best()

yh_rc yh_connect_best ( yh_connector **  connectors,
size_t  n_connectors,
int *  idx 
)

Connect to one connector in array.

Parameters
connectorspointer of connector array
n_connectorsnumber of connectors in array
idxindex of connected connector, may be NULL
Returns
yh_rc error code

◆ yh_connector_has_device()

bool yh_connector_has_device ( yh_connector connector)

Check if the connector has a device connected.

Parameters
connectorconnector
Returns
true or false

◆ yh_create_session()

yh_rc yh_create_session ( yh_connector connector,
uint16_t  auth_keyset_id,
const uint8_t *  key_enc,
size_t  key_enc_len,
const uint8_t *  key_mac,
size_t  key_mac_len,
bool  recreate_session,
uint8_t *  context,
size_t  context_len,
yh_session **  session 
)

Create a session.

Parameters
connectorconnector to create the session with
auth_keyset_idID of the authentication key
key_encencryption key
key_enc_lenlength of encryption key
key_macMAC key
key_mac_lenlength of MAC key
recreate_sessionsession will be recreated if expired, this caches the password in memory
contextcontext data for the authentication
context_lencontext length
sessioncreated session
Returns
yh_rc error code

◆ yh_create_session_derived()

yh_rc yh_create_session_derived ( yh_connector connector,
uint16_t  auth_keyset_id,
const uint8_t *  password,
size_t  password_len,
bool  recreate_session,
uint8_t *  context,
size_t  context_len,
yh_session **  session 
)

Create a session with keys derived frm password.

Parameters
connectorconnector to create the session with
auth_keyset_idID of the authentication key to be used
passwordpassword to derive keys from
password_lenlength of the password in bytes
recreate_sessionsession will be recreated if expired, this caches the password in memory
contextcontext data for the authentication
context_lencontext length
sessioncreated session
Returns
yh_rc error code

◆ yh_destroy_session()

yh_rc yh_destroy_session ( yh_session **  session)

Free data associated with session.

Parameters
sessionsession to destroy
Returns
yh_rc error code

◆ yh_disconnect()

yh_rc yh_disconnect ( yh_connector connector)

Disconnect from connector.

Parameters
connectorconnector to disconnect from
Returns
yh_rc error code

◆ yh_domains_to_string()

yh_rc yh_domains_to_string ( uint16_t  domains,
char *  string,
size_t  max_len 
)

Write out domains to a string.

Parameters
domainsencoded domains
stringstring to hold the result
max_lenmaximum length of string
Returns
yh_rc error code

◆ yh_exit()

yh_rc yh_exit ( void  )

Global library cleanup.

Returns
yh_rc error code

◆ yh_filter_capabilities()

yh_rc yh_filter_capabilities ( const yh_capabilities capabilities,
const yh_capabilities filter,
yh_capabilities result 
)

Filter one set of capabilities with another.

Parameters
capabilitiesset of capabilities
filtercapabilities to filter with
resultresulting set of capabilities
Returns
yh_rc error code

◆ yh_finish_create_session_ext()

yh_rc yh_finish_create_session_ext ( yh_connector connector,
yh_session session,
const uint8_t *  key_senc,
size_t  key_senc_len,
const uint8_t *  key_smac,
size_t  key_smac_len,
const uint8_t *  key_srmac,
size_t  key_srmac_len,
uint8_t *  context,
size_t  context_len,
uint8_t *  card_cryptogram,
size_t  card_cryptogram_len 
)

Finish creating external session.

Parameters
connectorconnector to create the session with
sessionsession
key_sencsession encryption key
key_senc_lensession encrypt key length
key_smacsession MAC key
key_smac_lensession MAC key length
key_srmacsession return MAC key
key_srmac_lensession return MAC key length
contextcontext data
context_lencontext length
card_cryptogramcard cryptogram
card_cryptogram_lencard cryptogram length
Returns
yh_rc error code

◆ yh_get_connector_address()

yh_rc yh_get_connector_address ( yh_connector connector,
char **const  address 
)

Get connector address.

Parameters
connectorconnector
addresspointer to string address
Returns
yh_rc error code

◆ yh_get_connector_version()

yh_rc yh_get_connector_version ( yh_connector connector,
uint8_t *  major,
uint8_t *  minor,
uint8_t *  patch 
)

Get the connector version.

Parameters
connectorconnector
majormajor version
minorminor version
patchpatch version
Returns
yh_rc error code

◆ yh_get_key_bitlength()

yh_rc yh_get_key_bitlength ( yh_algorithm  algorithm,
size_t *  result 
)

Get algorithm bitlength.

Parameters
algorithmalgorithm
resultbitlength
Returns
yh_rc error code

◆ yh_get_session_id()

yh_rc yh_get_session_id ( yh_session session,
uint8_t *  sid 
)

Get session ID.

Parameters
sessionsession to use
sidsession ID
Returns
yh_rc error code

◆ yh_get_verbosity()

yh_rc yh_get_verbosity ( uint8_t *  verbosity)

Get verbosity.

Parameters
verbosity
Returns
yh_rc error code

◆ yh_init()

yh_rc yh_init ( void  )

Global library initialization.

Returns
yh_rc error code

◆ yh_init_connector()

yh_rc yh_init_connector ( const char *  url,
yh_connector **  connector 
)

Instantiate a new connector.

Parameters
urlURL to associate with this connector
connectorreference to connector
Returns
yh_rc error code

◆ yh_is_ec()

bool yh_is_ec ( yh_algorithm  algorithm)

Check if algorithm is an EC algorithm.

Parameters
algorithmalgorithm
Returns
true or false

◆ yh_is_ed()

bool yh_is_ed ( yh_algorithm  algorithm)

Check if algorithm is an ED algorithm.

Parameters
algorithmalgorithm
Returns
true or false

◆ yh_is_hmac()

bool yh_is_hmac ( yh_algorithm  algorithm)

Check if algorithm is a HMAC algorithm.

Parameters
algorithmalgorithm
Returns
true or false

◆ yh_is_rsa()

bool yh_is_rsa ( yh_algorithm  algorithm)

Check if algorithm is an RSA algorithm.

Parameters
algorithmalgorithm
Returns
true or false

◆ yh_merge_capabilities()

yh_rc yh_merge_capabilities ( const yh_capabilities a,
const yh_capabilities b,
yh_capabilities result 
)

Merge two sets of capabilities.

Parameters
aa set of capabilities
ba set of capabilities
resultresulting set of capabilities
Returns
yh_rc error code

◆ yh_num_to_capabilities()

yh_rc yh_num_to_capabilities ( const yh_capabilities num,
const char *  result[],
size_t *  n_result 
)

Convert capability byte array to strings.

Parameters
numcapabilities
resultarray of string pointers
n_resultnumber of elements of result
Returns
yh_rc error code

◆ yh_parse_domains()

yh_rc yh_parse_domains ( const char *  domains,
uint16_t *  result 
)

Parse a string to a domains parameter.

Parameters
domainsstring of the format 1,2,3
resultresulting parsed domain parameter
Returns
yh_rc error code

◆ yh_send_plain_msg()

yh_rc yh_send_plain_msg ( yh_connector connector,
yh_cmd  cmd,
const uint8_t *  data,
size_t  data_len,
yh_cmd response_cmd,
uint8_t *  response,
size_t *  response_len 
)

Send a plain message to a connector.

Parameters
connectorconnector to send to
cmdcommand to send
datadata to send
data_lendata length
response_cmdresponse command
responseresponse data
response_lenresponse length
Returns
yh_rc error code

◆ yh_send_secure_msg()

yh_rc yh_send_secure_msg ( yh_session session,
yh_cmd  cmd,
const uint8_t *  data,
size_t  data_len,
yh_cmd response_cmd,
uint8_t *  response,
size_t *  response_len 
)

Send an encrypted message over a session.

Parameters
sessionsession to send over
cmdcommand to send
datadata to send
data_lendata length
response_cmdresponse command
responseresponse data
response_lenresponse length
Returns
yh_rc error code

◆ yh_set_connector_option()

yh_rc yh_set_connector_option ( yh_connector connector,
yh_connector_option  opt,
const void *  val 
)

Set connector options.

Parameters
connectorconnector to set an option on
optoption to set
See also
yh_connector_option
Parameters
valvalue to set, type is specific for the given option
Returns
yh_rc error code

◆ yh_set_debug_output()

void yh_set_debug_output ( FILE *  output)

Set file for debug output.

Parameters
output
Returns
void

◆ yh_set_verbosity()

yh_rc yh_set_verbosity ( uint8_t  verbosity)

Set verbosity This function may be called prior to global library initialization.

Parameters
verbosity
Returns
yh_rc error code

◆ yh_strerror()

const char* yh_strerror ( yh_rc  err)

Return a string describing an error condition.

Parameters
erryh_rc error code
Returns
String with descriptive error

◆ yh_string_to_algo()

yh_rc yh_string_to_algo ( const char *  string,
yh_algorithm algo 
)

Convert string to algorithm.

Parameters
stringalgorithm as string
algoalgorithm
Returns
yh_rc error code

◆ yh_string_to_option()

yh_rc yh_string_to_option ( const char *  string,
yh_option option 
)

Convert string to option.

Parameters
stringoption as string
optionoption
Returns
yh_rc error code

◆ yh_string_to_type()

yh_rc yh_string_to_type ( const char *  string,
yh_object_type type 
)

Convert string to type.

Parameters
stringtype as string
typetype
Returns
yh_rc error code

◆ yh_type_to_string()

yh_rc yh_type_to_string ( yh_object_type  type,
char const **  result 
)

Convert type to string.

Parameters
typetype
resultstring
Returns
yh_rc error code

◆ yh_util_attest_asymmetric()

yh_rc yh_util_attest_asymmetric ( yh_session session,
uint16_t  key_id,
uint16_t  attest_id,
uint8_t *  out,
size_t *  out_len 
)

Attest asymmetric key.

Parameters
sessionsession to use
key_idObject ID
attest_idAttestation key ID
outCertificate
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_blink()

yh_rc yh_util_blink ( yh_session session,
uint8_t  seconds 
)

Blink the device.

Parameters
sessionsession to use
secondsseconds to blink
Returns
yh_rc error code

◆ yh_util_close_session()

yh_rc yh_util_close_session ( yh_session session)

Close session.

Parameters
sessionsession to close
Returns
yh_rc error code

◆ yh_util_decrypt_ecdh()

yh_rc yh_util_decrypt_ecdh ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Perform ECDH key exchange.

Parameters
sessionsession to use
key_idObject ID
inpublic key
in_lenlength of public key
outAgreed key
out_lenlength of agreed key
Returns
yh_rc error code

◆ yh_util_decrypt_oaep()

yh_rc yh_util_decrypt_oaep ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len,
const uint8_t *  label,
size_t  label_len,
yh_algorithm  mgf1Algo 
)

Decrypt OAEP data.

Parameters
sessionsession to use
key_idObject ID
inEncrypted data
in_lenlength of encrypted data
outDecrypted data
out_lenlength of decrypted data
labelOAEP label
label_lenlabel length
mgf1AlgoMGF1 algorithm
Returns
yh_rc error code

◆ yh_util_decrypt_pkcs1v1_5()

yh_rc yh_util_decrypt_pkcs1v1_5 ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Decrypt PKCS1 v1.5 data.

Parameters
sessionsession to use
key_idObject ID
inEncrypted data
in_lenlength of encrypted data
outDecrypted data
out_lenlength of decrypted data
Returns
yh_rc error code

◆ yh_util_delete_object()

yh_rc yh_util_delete_object ( yh_session session,
uint16_t  id,
yh_object_type  type 
)

Delete an object.

Parameters
sessionsession to use
idObject ID
typeObject type
Returns
yh_rc error code

◆ yh_util_export_wrapped()

yh_rc yh_util_export_wrapped ( yh_session session,
uint16_t  wrapping_key_id,
yh_object_type  target_type,
uint16_t  target_id,
uint8_t *  out,
size_t *  out_len 
)

Export an object under wrap.

Parameters
sessionsession to use
wrapping_key_idID of wrapping key
target_typeType of object
target_idID of object
outwrapped data
out_lenlength of wrapped data
Returns
yh_rc error code

◆ yh_util_generate_key_ec()

yh_rc yh_util_generate_key_ec ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm 
)

Generate EC key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
Returns
yh_rc error code

◆ yh_util_generate_key_ed()

yh_rc yh_util_generate_key_ed ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm 
)

Generate ED key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
Returns
yh_rc error code

◆ yh_util_generate_key_hmac()

yh_rc yh_util_generate_key_hmac ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm 
)

Generate HMAC key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
Returns
yh_rc error code

◆ yh_util_generate_key_rsa()

yh_rc yh_util_generate_key_rsa ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm 
)

Generate RSA key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
Returns
yh_rc error code

◆ yh_util_generate_key_wrap()

yh_rc yh_util_generate_key_wrap ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const yh_capabilities delegated_capabilities 
)

Generate a wrap key.

Parameters
sessionsession to use
key_idObject ID
labellabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
delegated_capabilitiesdelegated capabilitites
Returns
yh_rc error code

◆ yh_util_generate_otp_aead_key()

yh_rc yh_util_generate_otp_aead_key ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
uint32_t  nonce_id 
)

Generate OTP AEAD Key.

Parameters
sessionsession to use
key_idObject ID
labellabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
nonce_idnonce ID
Returns
yh_rc error code

◆ yh_util_get_device_info()

yh_rc yh_util_get_device_info ( yh_connector connector,
uint8_t *  major,
uint8_t *  minor,
uint8_t *  patch,
uint32_t *  serial,
uint8_t *  log_total,
uint8_t *  log_used,
yh_algorithm algorithms,
size_t *  n_algorithms 
)

Get device info.

Parameters
connectorconnector to send over
majorversion major
minorversion minor
patchversion path
serialserial number
log_totaltotal number of log entries
log_usedlog entries used
algorithmsalgorithms array
n_algorithmsnumber of algorithms
Returns
yh_rc error code

◆ yh_util_get_logs()

yh_rc yh_util_get_logs ( yh_session session,
uint16_t *  unlogged_boot,
uint16_t *  unlogged_auth,
yh_log_entry out,
size_t *  n_items 
)

Get logs.

Parameters
sessionsession to use
unlogged_bootnumber of unlogged boots
unlogged_authnumber of unlogged authentications
outarray of log entries
n_itemsnumber of items in out
Returns
yh_rc error code

◆ yh_util_get_object_info()

yh_rc yh_util_get_object_info ( yh_session session,
uint16_t  id,
yh_object_type  type,
yh_object_descriptor object 
)

Get object info.

Parameters
sessionsession to use
idObject ID
typeObject type
objectobject information
Returns
yh_rc error code

◆ yh_util_get_opaque()

yh_rc yh_util_get_opaque ( yh_session session,
uint16_t  object_id,
uint8_t *  out,
size_t *  out_len 
)

Get opaque object.

Parameters
sessionsession to use
object_idObject ID
outdata
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_get_option()

yh_rc yh_util_get_option ( yh_session session,
yh_option  option,
uint8_t *  out,
size_t *  out_len 
)

Get global option.

Parameters
sessionsession to use
optionoption
outoption data
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_get_pubkey()

yh_rc yh_util_get_pubkey ( yh_session session,
uint16_t  id,
uint8_t *  data,
size_t *  datalen,
yh_algorithm algorithm 
)

Get Public key.

Parameters
sessionsession to use
idObject ID
dataData out
datalenData length
algorithmAlgorithm of object
Returns
yh_rc error code

◆ yh_util_get_random()

yh_rc yh_util_get_random ( yh_session session,
size_t  len,
uint8_t *  out,
size_t *  out_len 
)

Get pseudo random data.

Parameters
sessionsession to use
lenlength of data to get
outrandom data out
out_lenlength of random data
Returns
yh_rc error code

◆ yh_util_get_storage_stats()

yh_rc yh_util_get_storage_stats ( yh_session session,
uint16_t *  total_records,
uint16_t *  free_records,
uint16_t *  total_pages,
uint16_t *  free_pages,
uint16_t *  page_size 
)

Get storage statistics.

Parameters
sessionsession to use
total_recordstotal records available
free_recordsnumber of free records
total_pagestotal pages available
free_pagesnumber of free pages
page_sizepage size in bytes
Returns
yh_rc error code

◆ yh_util_get_template()

yh_rc yh_util_get_template ( yh_session session,
uint16_t  object_id,
uint8_t *  out,
size_t *  out_len 
)

Get template.

Parameters
sessionsession to use
object_idObject ID
outdata
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_hmac()

yh_rc yh_util_hmac ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

HMAC data.

Parameters
sessionsession to use
key_idObject ID
indata to hmac
in_lenlength of in
outHMAC
out_lenlength of HMAC
Returns
yh_rc error code

◆ yh_util_hmac_verify()

yh_rc yh_util_hmac_verify ( yh_session session,
uint16_t  key_id,
const uint8_t *  signature,
size_t  signature_len,
const uint8_t *  data,
size_t  data_len,
bool *  verified 
)

Verify HMAC data.

Parameters
sessionsession to use
key_idObject ID
signatureHMAC
signature_lenHMAC length
datadata to verify
data_lendata length
verifiedif verification succeeded
Returns
yh_rc error code

◆ yh_util_import_authkey()

yh_rc yh_util_import_authkey ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
const yh_capabilities delegated_capabilities,
const uint8_t *  password,
size_t  password_len 
)

Import authentication key.

Parameters
sessionsession to use
key_idObject ID
labellabel
domainsdomains
capabilitiescapabilities
delegated_capabilitiesdelegated capabilities
passwordpassword to derive key from
password_lenpassword length in bytes
Returns
yh_rc error code

◆ yh_util_import_key_ec()

yh_rc yh_util_import_key_ec ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const uint8_t *  s 
)

Import EC key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
sS
Returns
yh_rc error code

◆ yh_util_import_key_ed()

yh_rc yh_util_import_key_ed ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const uint8_t *  k 
)

Import ED key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
kk
Returns
yh_rc error code

◆ yh_util_import_key_hmac()

yh_rc yh_util_import_key_hmac ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const uint8_t *  key,
size_t  key_len 
)

Import HMAC key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
keykey data
key_lenlength of key
Returns
yh_rc error code

◆ yh_util_import_key_rsa()

yh_rc yh_util_import_key_rsa ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const uint8_t *  p,
const uint8_t *  q 
)

Import RSA key.

Parameters
sessionsession to use
key_idObject ID
labelLabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
pP
qQ
Returns
yh_rc error code

◆ yh_util_import_key_wrap()

yh_rc yh_util_import_key_wrap ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const yh_capabilities delegated_capabilities,
const uint8_t *  in,
size_t  in_len 
)

Import a wrap key.

Parameters
sessionsession to use
key_idObject ID
labellabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
delegated_capabilitiesdelegated capabilities
inkey
in_lenkey length
Returns
yh_rc error code

◆ yh_util_import_opaque()

yh_rc yh_util_import_opaque ( yh_session session,
uint16_t *  object_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const uint8_t *  in,
size_t  in_len 
)

Import opaque object.

Parameters
sessionsession to use
object_idObject ID
labellabel
domainsdomains
capabilities
algorithmalgorithm
inobject data
in_lenlength of in
Returns

◆ yh_util_import_template()

yh_rc yh_util_import_template ( yh_session session,
uint16_t *  object_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const uint8_t *  in,
size_t  in_len 
)

Import template.

Parameters
sessionsession to use
object_idObject ID
labellabel
domainsdomains
capabilitiescapabilities
algorithmalgorithm
indata
in_lenlength of in
Returns
yh_rc error code

◆ yh_util_import_wrapped()

yh_rc yh_util_import_wrapped ( yh_session session,
uint16_t  wrapping_key_id,
const uint8_t *  in,
size_t  in_len,
yh_object_type target_type,
uint16_t *  target_id 
)

Import a wrapped object.

Parameters
sessionsession to use
wrapping_key_idID of wrapping key
inwrapped data
in_lenlength of wrapped data
target_typewhat type the imported object has
target_idID of imported object
Returns
yh_rc error code

◆ yh_util_list_objects()

yh_rc yh_util_list_objects ( yh_session session,
uint16_t  id,
yh_object_type  type,
uint16_t  domains,
const yh_capabilities capabilities,
yh_algorithm  algorithm,
const char *  label,
yh_object_descriptor objects,
size_t *  n_objects 
)

List objects.

Parameters
sessionsession to use
idID to filter by (0 to not filter by ID)
typeType to filter by (0 to not filter by type)
See also
yh_object_type
Parameters
domainsDomains to filter by (0 to not filter by domain)
capabilitiesCapabilities to filter by (0 to not filter by capabilities)
See also
yh_capabilities
Parameters
algorithmAlgorithm to filter by (0 to not filter by algorithm)
labelLabel to filter by
objectsArray of objects returned
n_objectsMax length of objects (will be set to number found on return)
Returns
yh_rc error code

◆ yh_util_otp_aead_create()

yh_rc yh_util_otp_aead_create ( yh_session session,
uint16_t  key_id,
const uint8_t *  key,
const uint8_t *  private_id,
uint8_t *  out,
size_t *  out_len 
)

Create OTP AEAD.

Parameters
sessionsession to use
key_idObject ID
keyOTP key
private_idOTP private id
outAEAD
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_otp_aead_random()

yh_rc yh_util_otp_aead_random ( yh_session session,
uint16_t  key_id,
uint8_t *  out,
size_t *  out_len 
)

Create OTP AEAD from random.

Parameters
sessionsession to use
key_idObject ID
outAEAD
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_otp_decrypt()

yh_rc yh_util_otp_decrypt ( yh_session session,
uint16_t  key_id,
const uint8_t *  aead,
size_t  aead_len,
const uint8_t *  otp,
uint16_t *  useCtr,
uint8_t *  sessionCtr,
uint8_t *  tstph,
uint16_t *  tstpl 
)

Decrypt OTP.

Parameters
sessionsession to use
key_idObject ID
aeadAEAD
aead_lenlength of AEAD
otpOTP
useCtrOTP use counter
sessionCtrOTP session counter
tstphOTP timestamp high
tstplOTP timestamp low
Returns
yh_rc error code

◆ yh_util_put_option()

yh_rc yh_util_put_option ( yh_session session,
yh_option  option,
size_t  len,
uint8_t *  val 
)

Put global option.

Parameters
sessionsession to use
optionoption
lenlength of option data
valoption data
Returns
yh_rc error code

◆ yh_util_put_otp_aead_key()

yh_rc yh_util_put_otp_aead_key ( yh_session session,
uint16_t *  key_id,
const char *  label,
uint16_t  domains,
const yh_capabilities capabilities,
uint32_t  nonce_id,
const uint8_t *  in,
size_t  in_len 
)

Import OTP AEAD Key.

Parameters
sessionsession to use
key_idObject ID
labellabel
domainsdomains
capabilitiescapabilities
nonce_idnonce ID
inkey
in_lenlength of in
Returns

◆ yh_util_reset()

yh_rc yh_util_reset ( yh_session session)

Reset the device.

Parameters
sessionsession to use
Returns
yh_rc error code. This function will normally return a network error

◆ yh_util_set_log_index()

yh_rc yh_util_set_log_index ( yh_session session,
uint16_t  index 
)

Set the log index.

Parameters
sessionsession to use
indexindex to set
Returns
yh_rc error code

◆ yh_util_sign_ecdsa()

yh_rc yh_util_sign_ecdsa ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Sign data using ECDSA.

Parameters
sessionsession to use
key_idObject ID
indata to sign
in_lenlength of in
outsigned data
out_lenlength of signed data
Returns
yh_rc error code

◆ yh_util_sign_eddsa()

yh_rc yh_util_sign_eddsa ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Sign data using EDDSA.

Parameters
sessionsession to use
key_idObject ID
indata to sign
in_lenlength of in
outsigned data
out_lenlength of signed data
Returns
yh_rc error code

◆ yh_util_sign_pkcs1v1_5()

yh_rc yh_util_sign_pkcs1v1_5 ( yh_session session,
uint16_t  key_id,
bool  hashed,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Sign data using PKCS1 v1.5.

Parameters
sessionsession to use
key_idObject ID
hashedif data is already hashed
inin data to sign
in_lenlength of in
outsigned data
out_lenlength of signed data
Returns
yh_rc error code

◆ yh_util_sign_pss()

yh_rc yh_util_sign_pss ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len,
size_t  salt_len,
yh_algorithm  mgf1Algo 
)

Sign data using RSS.

Parameters
sessionsession to use
key_idObject ID
indata to sign
in_lenlength of in
outsigned data
out_lenlength of signed data
salt_lenlength of salt
mgf1Algoalgorithm for mgf1
Returns
yh_rc error code

◆ yh_util_ssh_certify()

yh_rc yh_util_ssh_certify ( yh_session session,
uint16_t  key_id,
uint16_t  template_id,
yh_algorithm  sig_algo,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

SSH certify.

Parameters
sessionsession to use
key_idKey ID
template_idTemplate ID
sig_algosignature algorithm
inCertificate request
in_lenlength of in
outSignature
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_unwrap_data()

yh_rc yh_util_unwrap_data ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Unwrap data.

Parameters
sessionsession to use
key_idObject ID
inwrapped data
in_lenlength of in
outunwrapped data
out_lenlength of out
Returns
yh_rc error code

◆ yh_util_wrap_data()

yh_rc yh_util_wrap_data ( yh_session session,
uint16_t  key_id,
const uint8_t *  in,
size_t  in_len,
uint8_t *  out,
size_t *  out_len 
)

Wrap data.

Parameters
sessionsession to use
key_idObject ID
indata to wrap
in_lenlength of in
outwrapped data
out_lenlength of out
Returns
yh_rc error code

◆ yh_verify_logs()

bool yh_verify_logs ( yh_log_entry logs,
size_t  n_items,
yh_log_entry last_previous_log 
)

Verify an array of log entries.

Parameters
logspointer to an array of log entries
n_itemsnumber of items logs
last_previous_logoptional pointer to the entry before the first entry in logs
Returns
true or false