Everything you need to establish a connection to the YubiHSM 2 and use its functions. More...

Data Structures
struct	yh_capabilities
	Capabilities 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
	Max length of object labels.

#define	YH_MAX_DOMAINS 16
	Max number of domains.

#define	YH_LOG_DIGEST_SIZE 16
	Size that the log digest is truncated to.

#define	YH_USB_URL_SCHEME "yhusb://"
	URL scheme used for direct USB access.

#define	YH_VERB_QUIET 0x00
	Debug level quiet. No messages printed out.

#define	YH_VERB_INTERMEDIATE 0x01
	Debug level intermediate. Intermediate results printed out.

#define	YH_VERB_CRYPTO 0x02
	Debug level crypto. Crypto results printed out.

#define	YH_VERB_RAW 0x04
	Debug level raw. Raw messages printed out.

#define	YH_VERB_INFO 0x08
	Debug level info. General information messages printed out.

#define	YH_VERB_ERR 0x10
	Debug level error. Error messages printed out.

#define	YH_VERB_ALL 0xff
	Debug level all. 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_ORIGIN_GENERATED 0x01
	The object was generated on the device.

#define	YH_ORIGIN_IMPORTED 0x02
	The object was imported into the device.

#define	YH_ORIGIN_IMPORTED_WRAPPED 0x10
	The object was imported into the device under wrap. More...

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_ERROR = -1, YHR_INIT_ERROR = -2, YHR_CONNECTION_ERROR = -3, YHR_CONNECTOR_NOT_FOUND = -4, YHR_INVALID_PARAMETERS = -5, YHR_WRONG_LENGTH = -6, YHR_BUFFER_TOO_SMALL = -7, YHR_CRYPTOGRAM_MISMATCH = -8, YHR_SESSION_AUTHENTICATION_FAILED = -9, YHR_MAC_MISMATCH = -10, YHR_DEVICE_OK = -11, YHR_DEVICE_INVALID_COMMAND = -12, YHR_DEVICE_INVALID_DATA = -13, YHR_DEVICE_INVALID_SESSION = -14, YHR_DEVICE_AUTHENTICATION_FAILED = -15, YHR_DEVICE_SESSIONS_FULL = -16, YHR_DEVICE_SESSION_FAILED = -17, YHR_DEVICE_STORAGE_FAILED = -18, YHR_DEVICE_WRONG_LENGTH = -19, YHR_DEVICE_INSUFFICIENT_PERMISSIONS = -20, YHR_DEVICE_LOG_FULL = -21, YHR_DEVICE_OBJECT_NOT_FOUND = -22, YHR_DEVICE_INVALID_ID = -23, YHR_DEVICE_INVALID_OTP = -24, YHR_DEVICE_DEMO_MODE = -25, YHR_DEVICE_COMMAND_UNEXECUTED = -26, YHR_GENERIC_ERROR = -27, YHR_DEVICE_OBJECT_EXISTS = -28, YHR_CONNECTOR_ERROR = -29, YHR_DEVICE_SSH_CA_CONSTRAINT_VIOLATION = -30 }
	Return codes. More...

enum	yh_cmd { YHC_ECHO = 0x01, YHC_ECHO_R = 0x01 \| 0x80, YHC_CREATE_SESSION = 0x03, YHC_CREATE_SESSION_R = 0x03 \| 0x80, YHC_AUTHENTICATE_SESSION = 0x04, YHC_AUTHENTICATE_SESSION_R = 0x04 \| 0x80, YHC_SESSION_MESSAGE = 0x05, YHC_SESSION_MESSAGE_R = 0x05 \| 0x80, YHC_GET_DEVICE_INFO = 0x06, YHC_GET_DEVICE_INFO_R = 0x06 \| 0x80, YHC_RESET_DEVICE = 0x08, YHC_RESET_DEVICE_R = 0x08 \| 0x80, YHC_CLOSE_SESSION = 0x40, YHC_CLOSE_SESSION_R = 0x40 \| 0x80, YHC_GET_STORAGE_INFO = 0x041, YHC_GET_STORAGE_INFO_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_AUTHENTICATION_KEY = 0x44, YHC_PUT_AUTHENTICATION_KEY_R = 0x44 \| 0x80, YHC_PUT_ASYMMETRIC_KEY = 0x45, YHC_PUT_ASYMMETRIC_KEY_R = 0x45 \| 0x80, YHC_GENERATE_ASYMMETRIC_KEY = 0x46, YHC_GENERATE_ASYMMETRIC_KEY_R = 0x46 \| 0x80, YHC_SIGN_PKCS1 = 0x47, YHC_SIGN_PKCS1_R = 0x47 \| 0x80, YHC_LIST_OBJECTS = 0x48, YHC_LIST_OBJECTS_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_LOG_ENTRIES = 0x4d, YHC_GET_LOG_ENTRIES_R = 0x4d \| 0x80, YHC_GET_OBJECT_INFO = 0x4e, YHC_GET_OBJECT_INFO_R = 0x4e \| 0x80, YHC_SET_OPTION = 0x4f, YHC_SET_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_SIGN_HMAC = 0x53, YHC_SIGN_HMAC_R = 0x53 \| 0x80, YHC_GET_PUBLIC_KEY = 0x54, YHC_GET_PUBLIC_KEY_R = 0x54 \| 0x80, YHC_SIGN_PSS = 0x55, YHC_SIGN_PSS_R = 0x55 \| 0x80, YHC_SIGN_ECDSA = 0x56, YHC_SIGN_ECDSA_R = 0x56 \| 0x80, YHC_DERIVE_ECDH = 0x57, YHC_DERIVE_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_SIGN_SSH_CERTIFICATE = 0x5d, YHC_SIGN_SSH_CERTIFICATE_R = 0x5d \| 0x80, YHC_PUT_TEMPLATE = 0x5e, YHC_PUT_TEMPLATE_R = 0x5e \| 0x80, YHC_GET_TEMPLATE = 0x5f, YHC_GET_TEMPLATE_R = 0x5f \| 0x80, YHC_DECRYPT_OTP = 0x60, YHC_DECRYPT_OTP_R = 0x60 \| 0x80, YHC_CREATE_OTP_AEAD = 0x61, YHC_CREATE_OTP_AEAD_R = 0x61 \| 0x80, YHC_RANDOMIZE_OTP_AEAD = 0x62, YHC_RANDOMIZE_OTP_AEAD_R = 0x62 \| 0x80, YHC_REWRAP_OTP_AEAD = 0x63, YHC_REWRAP_OTP_AEAD_R = 0x63 \| 0x80, YHC_SIGN_ATTESTATION_CERTIFICATE = 0x64, YHC_SIGN_ATTESTATION_CERTIFICATE_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_EDDSA = 0x6a, YHC_SIGN_EDDSA_R = 0x6a \| 0x80, YHC_BLINK_DEVICE = 0x6b, YHC_BLINK_DEVICE_R = 0x6b \| 0x80, YHC_CHANGE_AUTHENTICATION_KEY = 0x6c, YHC_CHANGE_AUTHENTICATION_KEY_R = 0x6c \| 0x80, YHC_ERROR = 0x7f }
	Command definitions. More...

enum	yh_object_type { YH_OPAQUE = 0x01, YH_AUTHENTICATION_KEY = 0x02, YH_ASYMMETRIC_KEY = 0x03, YH_WRAP_KEY = 0x04, YH_HMAC_KEY = 0x05, YH_TEMPLATE = 0x06, YH_OTP_AEAD_KEY = 0x07, YH_PUBLIC_KEY = 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_CERTIFICATE = 31, YH_ALGO_MGF1_SHA1 = 32, YH_ALGO_MGF1_SHA256 = 33, YH_ALGO_MGF1_SHA384 = 34, YH_ALGO_MGF1_SHA512 = 35, YH_ALGO_TEMPLATE_SSH = 36, YH_ALGO_AES128_YUBICO_OTP = 37, YH_ALGO_AES128_YUBICO_AUTHENTICATION = 38, YH_ALGO_AES192_YUBICO_OTP = 39, YH_ALGO_AES256_YUBICO_OTP = 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. More...

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 (yh_connector *connector, uint8_t verbosity)
	Set verbosity level when executing commands. More...

yh_rc	yh_get_verbosity (uint8_t *verbosity)
	Get verbosity level when executing commands. More...

void	yh_set_debug_output (yh_connector connector, FILE output)
	Set file for debug output. More...

yh_rc	yh_init (void)
	Global library initialization. More...

yh_rc	yh_exit (void)
	Global library clean up. 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 (yh_connector *connector, int timeout)
	Connect to the device through the specified connector. More...

yh_rc	yh_disconnect (yh_connector *connector)
	Disconnect from a 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 (unencrypted) message to the device through 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 to the device over a session. More...

yh_rc	yh_create_session_derived (yh_connector connector, uint16_t authkey_id, const uint8_t password, size_t password_len, bool recreate_session, yh_session **session)
	Create a session that uses an encryption key and a MAC key derived from a password. More...

yh_rc	yh_create_session (yh_connector connector, uint16_t authkey_id, const uint8_t key_enc, size_t key_enc_len, const uint8_t key_mac, size_t key_mac_len, bool recreate_session, yh_session *session)
	Create a session that uses the specified encryption key and MAC key to derive session-specific keys. More...

yh_rc	yh_begin_create_session_ext (yh_connector connector, uint16_t authkey_id, uint8_t context, uint8_t card_cryptogram, size_t card_cryptogram_len, yh_session **session)
	Begin creating an external 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 card_cryptogram, size_t card_cryptogram_len)
	Finish creating external session. More...

yh_rc	yh_destroy_session (yh_session **session)
	Free data associated with the session. More...

yh_rc	yh_authenticate_session (yh_session *session)
	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 version, device serial number, supported algorithms and available log entries. 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 accessible from the session. More...

yh_rc	yh_util_get_object_info (yh_session session, uint16_t id, yh_object_type type, yh_object_descriptor object)
	Get metadata of the object with the specified Object ID and Type. More...

yh_rc	yh_util_get_public_key (yh_session session, uint16_t id, uint8_t data, size_t data_len, yh_algorithm algorithm)
	Get the value of the public key with the specified Object ID. More...

yh_rc	yh_util_close_session (yh_session *session)
	Close a 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 RSA-PKCS#1v1.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 RSA-PSS. 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_sign_hmac (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 HMAC. More...

yh_rc	yh_util_get_pseudo_random (yh_session session, size_t len, uint8_t out, size_t *out_len)
	Get a fixed number of pseudo-random bytes from the device. More...

yh_rc	yh_util_import_rsa_key (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 an RSA key into the device. More...

yh_rc	yh_util_import_ec_key (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 an Elliptic Curve key into the device. More...

yh_rc	yh_util_import_ed_key (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 an ED key into the device. More...

yh_rc	yh_util_import_hmac_key (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 an HMAC key into the device. More...

yh_rc	yh_util_generate_rsa_key (yh_session session, uint16_t key_id, const char label, uint16_t domains, const yh_capabilities capabilities, yh_algorithm algorithm)
	Generate an RSA key in the device. More...

yh_rc	yh_util_generate_ec_key (yh_session session, uint16_t key_id, const char label, uint16_t domains, const yh_capabilities capabilities, yh_algorithm algorithm)
	Generate an Elliptic Curve key in the device. More...

yh_rc	yh_util_generate_ed_key (yh_session session, uint16_t key_id, const char label, uint16_t domains, const yh_capabilities capabilities, yh_algorithm algorithm)
	Generate an ED key in the device. More...

yh_rc	yh_util_verify_hmac (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 a generated HMAC. More...

yh_rc	yh_util_generate_hmac_key (yh_session session, uint16_t key_id, const char label, uint16_t domains, const yh_capabilities capabilities, yh_algorithm algorithm)
	Generate an HMAC key in the device. 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 data that was encrypted using RSA-PKCS#1v1.5. 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 data using RSA-OAEP. More...

yh_rc	yh_util_derive_ecdh (yh_session session, uint16_t key_id, const uint8_t in, size_t in_len, uint8_t out, size_t out_len)
	Derive an ECDH key from a private EC key on the device and a provided public EC key. More...

yh_rc	yh_util_delete_object (yh_session *session, uint16_t id, yh_object_type type)
	Delete an object in the device. 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 from the device. 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 into the device. More...

yh_rc	yh_util_import_wrap_key (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 into the device. More...

yh_rc	yh_util_generate_wrap_key (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 that can be used for export, import, wrap data and unwrap data in the device. More...

yh_rc	yh_util_get_log_entries (yh_session session, uint16_t unlogged_boot, uint16_t unlogged_auth, yh_log_entry out, size_t *n_items)
	Get audit logs from the device. More...

yh_rc	yh_util_set_log_index (yh_session *session, uint16_t index)
	Set the index of the last extracted log entry. More...

yh_rc	yh_util_get_opaque (yh_session session, uint16_t object_id, uint8_t out, size_t *out_len)
	Get an YH_OPAQUE object (like an X.509 certificate) from the device. 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 an YH_OPAQUE object into the device. More...

yh_rc	yh_util_sign_ssh_certificate (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)
	Sign an SSH Certificate request. More...

yh_rc	yh_util_import_authentication_key (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 key_enc, size_t key_enc_len, const uint8_t *key_mac, size_t key_mac_len)
	Import an YH_AUTHENTICATION_KEY into the device. More...

yh_rc	yh_util_import_authentication_key_derived (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 an YH_AUTHENTICATION_KEY with long lived keys derived from a password. More...

yh_rc	yh_util_change_authentication_key (yh_session session, uint16_t key_id, const uint8_t key_enc, size_t key_enc_len, const uint8_t key_mac, size_t key_mac_len)
	Replace the long lived encryption key and MAC key associated with an YH_AUTHENTICATION_KEY in the device. More...

yh_rc	yh_util_change_authentication_key_derived (yh_session session, uint16_t key_id, const uint8_t *password, size_t password_len)
	Replace the long lived encryption key and MAC key associated with an YH_AUTHENTICATION_KEY in the device with keys derived from a password. More...

yh_rc	yh_util_get_template (yh_session session, uint16_t object_id, uint8_t out, size_t *out_len)
	Get a YH_TEMPLATE object from the device. 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 a YH_TEMPLATE object into the device. More...

yh_rc	yh_util_create_otp_aead (yh_session session, uint16_t key_id, const uint8_t key, const uint8_t private_id, uint8_t out, size_t *out_len)
	Create a Yubico OTP AEAD using the provided data. More...

yh_rc	yh_util_randomize_otp_aead (yh_session session, uint16_t key_id, uint8_t out, size_t *out_len)
	Create OTP AEAD from random data. More...

yh_rc	yh_util_decrypt_otp (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 a Yubico OTP and return counters and time information. More...

yh_rc	yh_util_import_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 an YH_OTP_AEAD_KEY used for Yubico OTP Decryption. 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 an YH_OTP_AEAD_KEY for Yubico OTP decryption in the device. More...

yh_rc	yh_util_sign_attestation_certificate (yh_session session, uint16_t key_id, uint16_t attest_id, uint8_t out, size_t *out_len)
	Get attestation of an Asymmetric Key in the form of an X.509 certificate. More...

yh_rc	yh_util_set_option (yh_session session, yh_option option, size_t len, uint8_t val)
	Set a device-global option. More...

yh_rc	yh_util_get_option (yh_session session, yh_option option, uint8_t out, size_t *out_len)
	Get a device-global option. More...

yh_rc	yh_util_get_storage_info (yh_session session, uint16_t total_records, uint16_t free_records, uint16_t total_pages, uint16_t free_pages, uint16_t page_size)
	Report currently free storage. 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)
	Encrypt (wrap) data using a YH_WRAP_KEY. 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)
	Decrypt (unwrap) data using a YH_WRAP_KEY. More...

yh_rc	yh_util_blink_device (yh_session *session, uint8_t seconds)
	Blink the LED of the device to identify it. More...

yh_rc	yh_util_reset_device (yh_session *session)
	Factory reset the device. More...

yh_rc	yh_get_session_id (yh_session session, uint8_t sid)
	Get the 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_string_to_capabilities (const char capability, yh_capabilities result)
	Convert capability string to byte array. More...

yh_rc	yh_capabilities_to_strings (const yh_capabilities num, const char result[], size_t *n_result)
	Convert an array of yh_capabilities into strings separated by ','. More...

bool	yh_check_capability (const yh_capabilities capabilities, const char capability)
	Check if a 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 an algorithm is a supported RSA algorithm. More...

bool	yh_is_ec (yh_algorithm algorithm)
	Check if an algorithm is a supported Elliptic Curve algorithm. More...

bool	yh_is_ed (yh_algorithm algorithm)
	Check if an algorithm is a supported ED algorithm. More...

bool	yh_is_hmac (yh_algorithm algorithm)
	Check if algorithm is a supported HMAC algorithm. More...

yh_rc	yh_get_key_bitlength (yh_algorithm algorithm, size_t *result)
	Get the expected key length of a key generated by the given algorithm. More...

yh_rc	yh_algo_to_string (yh_algorithm algo, char const **result)
	Convert an algorithm to its string representation. More...

yh_rc	yh_string_to_algo (const char string, yh_algorithm algo)
	Convert a string to an algorithm's numeric value. More...

yh_rc	yh_type_to_string (yh_object_type type, char const **result)
	Convert a yh_object_type to its string representation. More...

yh_rc	yh_string_to_type (const char string, yh_object_type type)
	Convert a string to a type's numeric value. More...

yh_rc	yh_string_to_option (const char string, yh_option option)
	Convert a string to an option's numeric value. 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_string_to_domains (const char domains, uint16_t result)
	Convert a string to a domain's numeric value. More...

yh_rc	yh_domains_to_string (uint16_t domains, char *string, size_t max_len)
	Convert domains parameter to its String representation. More...

Detailed Description

Everything you need to establish a connection to the YubiHSM 2 and use its functions.

Macro Definition Documentation

◆ YH_ORIGIN_IMPORTED_WRAPPED

#define YH_ORIGIN_IMPORTED_WRAPPED 0x10

The object was imported into the device under wrap.

This is used in combination with objects original 'origin'

Enumeration Type Documentation

◆ yh_algorithm

enum yh_algorithm

Algorithms.

See also: Objects

Enumerator
YH_ALGO_RSA_PKCS1_SHA1	rsa-pkcs1-sha1
YH_ALGO_RSA_PKCS1_SHA256	rsa-pkcs1-sha256
YH_ALGO_RSA_PKCS1_SHA384	rsa-pkcs1-sha384
YH_ALGO_RSA_PKCS1_SHA512	rsa-pkcs1-sha512
YH_ALGO_RSA_PSS_SHA1	rsa-pss-sha1
YH_ALGO_RSA_PSS_SHA256	rsa-pss-sha256
YH_ALGO_RSA_PSS_SHA384	rsa-pss-sha384
YH_ALGO_RSA_PSS_SHA512	rsa-pss-sha512
YH_ALGO_RSA_2048	rsa2048
YH_ALGO_RSA_3072	rsa3072
YH_ALGO_RSA_4096	rsa4096
YH_ALGO_EC_P256	ecp256
YH_ALGO_EC_P384	ecp384
YH_ALGO_EC_P521	ecp521
YH_ALGO_EC_K256	eck256
YH_ALGO_EC_BP256	ecbp256
YH_ALGO_EC_BP384	ecbp384
YH_ALGO_EC_BP512	ecbp512
YH_ALGO_HMAC_SHA1	hmac-sha1
YH_ALGO_HMAC_SHA256	hmac-sha256
YH_ALGO_HMAC_SHA384	hmac-sha384
YH_ALGO_HMAC_SHA512	hmac-sha512
YH_ALGO_EC_ECDSA_SHA1	ecdsa-sha1
YH_ALGO_EC_ECDH	ecdh
YH_ALGO_RSA_OAEP_SHA1	rsa-oaep-sha1
YH_ALGO_RSA_OAEP_SHA256	rsa-oaep-sha256
YH_ALGO_RSA_OAEP_SHA384	rsa-oaep-sha384
YH_ALGO_RSA_OAEP_SHA512	rsa-oaep-sha512
YH_ALGO_AES128_CCM_WRAP	aes128-ccm-wrap
YH_ALGO_OPAQUE_DATA	opaque-data
YH_ALGO_OPAQUE_X509_CERTIFICATE	opaque-x509-certificate
YH_ALGO_MGF1_SHA1	mgf1-sha1
YH_ALGO_MGF1_SHA256	mgf1-sha256
YH_ALGO_MGF1_SHA384	mgf1-sha384
YH_ALGO_MGF1_SHA512	mgf1-sha512
YH_ALGO_TEMPLATE_SSH	template-ssh
YH_ALGO_AES128_YUBICO_OTP	aes128-yubico-otp
YH_ALGO_AES128_YUBICO_AUTHENTICATION	aes128-yubico-authentication
YH_ALGO_AES192_YUBICO_OTP	aes192-yubico-otp
YH_ALGO_AES256_YUBICO_OTP	aes256-yubico-otp
YH_ALGO_AES192_CCM_WRAP	aes192-ccm-wrap
YH_ALGO_AES256_CCM_WRAP	aes256-ccm-wrap
YH_ALGO_EC_ECDSA_SHA256	ecdsa-sha256
YH_ALGO_EC_ECDSA_SHA384	ecdsa-sha384
YH_ALGO_EC_ECDSA_SHA512	ecdsa-sha512
YH_ALGO_EC_ED25519	ed25519
YH_ALGO_EC_P224	ecp224

◆ yh_cmd

enum yh_cmd

Command definitions.

Enumerator
YHC_ECHO	Echo data back from the device.
YHC_CREATE_SESSION	Create a session with the device.
YHC_AUTHENTICATE_SESSION	Authenticate the session to the device.
YHC_SESSION_MESSAGE	Send a command over an established session.
YHC_GET_DEVICE_INFO	Get device metadata.
YHC_RESET_DEVICE	Factory reset a device.
YHC_CLOSE_SESSION	Close session.
YHC_GET_STORAGE_INFO	Get storage information.
YHC_PUT_OPAQUE	Import an Opaque Object into the device.
YHC_GET_OPAQUE	Get an Opaque Object from device.
YHC_PUT_AUTHENTICATION_KEY	Import an Authentication Key into the device.
YHC_PUT_ASYMMETRIC_KEY	Import an Asymmetric Key into the device.
YHC_GENERATE_ASYMMETRIC_KEY	Generate an Asymmetric Key in the device.
YHC_SIGN_PKCS1	Sign data using RSA-PKCS#1v1.5.
YHC_LIST_OBJECTS	List objects in the device.
YHC_DECRYPT_PKCS1	Decrypt data that was encrypted using RSA-PKCS#1v1.5.
YHC_EXPORT_WRAPPED	Get an Object under wrap from the device.
YHC_IMPORT_WRAPPED	Import a wrapped Object into the device.
YHC_PUT_WRAP_KEY	Import a Wrap Key into the device.
YHC_GET_LOG_ENTRIES	Get all current audit log entries from the device Log Store.
YHC_GET_OBJECT_INFO	Get all metadata about an Object.
YHC_SET_OPTION	Set a device-global options that affect general behavior.
YHC_GET_OPTION	Get a device-global option.
YHC_GET_PSEUDO_RANDOM	Get a fixed number of pseudo-random bytes from the device.
YHC_PUT_HMAC_KEY	Import a HMAC key into the device.
YHC_SIGN_HMAC	Perform an HMAC operation in the device.
YHC_GET_PUBLIC_KEY	Get the public key of an Asymmetric Key in the device.
YHC_SIGN_PSS	Sign data using RSA-PSS.
YHC_SIGN_ECDSA	Sign data using ECDSA.
YHC_DERIVE_ECDH	Perform an ECDH key exchange operation with a private key in the device.
YHC_DELETE_OBJECT	Delete object in the device.
YHC_DECRYPT_OAEP	Decrypt data using RSA-OAEP.
YHC_GENERATE_HMAC_KEY	Generate an HMAC Key in the device.
YHC_GENERATE_WRAP_KEY	Generate a Wrap Key in the device.
YHC_VERIFY_HMAC	Verify a generated HMAC.
YHC_SIGN_SSH_CERTIFICATE	Sign SSH certificate request.
YHC_PUT_TEMPLATE	Import a template into the device.
YHC_GET_TEMPLATE	Get a template from the device.
YHC_DECRYPT_OTP	Decrypt a Yubico OTP.
YHC_CREATE_OTP_AEAD	Create a Yubico OTP AEAD.
YHC_RANDOMIZE_OTP_AEAD	Generate an OTP AEAD from random data.
YHC_REWRAP_OTP_AEAD	Re-encrypt a Yubico OTP AEAD from one OTP AEAD Key to another OTP AEAD Key.
YHC_SIGN_ATTESTATION_CERTIFICATE	Get attestation of an Asymmetric Key.
YHC_PUT_OTP_AEAD_KEY	Import an OTP AEAD Key into the device.
YHC_GENERATE_OTP_AEAD_KEY	Generate an OTP AEAD Key in the device.
YHC_SET_LOG_INDEX	Set the last extracted audit log entry.
YHC_WRAP_DATA	Encrypt (wrap) data using a Wrap Key.
YHC_UNWRAP_DATA	Decrypt (unwrap) data using a Wrap Key.
YHC_SIGN_EDDSA	Sign data using EdDSA.
YHC_BLINK_DEVICE	Blink the LED of the device.
YHC_CHANGE_AUTHENTICATION_KEY	Replace the Authentication Key used to establish the current Session.
YHC_ERROR	The response byte returned from the device if the command resulted in an error.

◆ yh_connector_option

enum 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

enum yh_object_type

Object types.

See also: Objects

Enumerator
YH_OPAQUE	Opaque Object is an unchecked kind of Object, normally used to store raw data in the device.
YH_AUTHENTICATION_KEY	Authentication Key is used to establish Sessions with a device.
YH_ASYMMETRIC_KEY	Asymmetric Key is the private key of an asymmetric key-pair.
YH_WRAP_KEY	Wrap Key is a secret key used to wrap and unwrap Objects during the export and import process.
YH_HMAC_KEY	HMAC Key is a secret key used when computing and verifying HMAC signatures.
YH_TEMPLATE	Template is a binary object used for example to validate SSH certificate requests.
YH_OTP_AEAD_KEY	OTP AEAD Key is a secret key used to decrypt Yubico OTP values.
YH_PUBLIC_KEY	Public Key is the public key of an asymmetric key-pair. The public key never exists in device and is mostly here for PKCS#11.

◆ yh_option

enum yh_option

Global options.

Enumerator
YH_OPTION_FORCE_AUDIT	Enable/Disable Forced Audit mode.
YH_OPTION_COMMAND_AUDIT	Enable/Disable logging of specific commands.

◆ yh_rc

enum yh_rc

Return codes.

Enumerator
YHR_SUCCESS	Returned value when function was successful.
YHR_MEMORY_ERROR	Returned value when unable to allocate memory.
YHR_INIT_ERROR	Returned value when failing to initialize libyubihsm.
YHR_CONNECTION_ERROR	Returned value when a connection error was encountered.
YHR_CONNECTOR_NOT_FOUND	Returned value when failing to find a suitable connector.
YHR_INVALID_PARAMETERS	Returned value when an argument to a function is invalid.
YHR_WRONG_LENGTH	Returned value when there is a mismatch between expected and received length of an argument to a function.
YHR_BUFFER_TOO_SMALL	Returned value when there is not enough space to store data.
YHR_CRYPTOGRAM_MISMATCH	Returned value when failing to verify cryptogram.
YHR_SESSION_AUTHENTICATION_FAILED	Returned value when failing to authenticate the session.
YHR_MAC_MISMATCH	Returned value when failing to verify MAC.
YHR_DEVICE_OK	Returned value when the device returned no error.
YHR_DEVICE_INVALID_COMMAND	Returned value when the device receives and invalid command.
YHR_DEVICE_INVALID_DATA	Returned value when the device receives a malformed command invalid data.
YHR_DEVICE_INVALID_SESSION	Returned value when the device session is invalid.
YHR_DEVICE_AUTHENTICATION_FAILED	Return value when the device fails to encrypt or verify the message.
YHR_DEVICE_SESSIONS_FULL	Return value when no more sessions can be opened on the device.
YHR_DEVICE_SESSION_FAILED	Return value when failing to create a device session.
YHR_DEVICE_STORAGE_FAILED	Return value when encountering a storage failure on the device.
YHR_DEVICE_WRONG_LENGTH	Return value when there is a mismatch between expected and received length of an argument to a function on the device.
YHR_DEVICE_INSUFFICIENT_PERMISSIONS	Return value when the permissions to perform the operation are wrong.
YHR_DEVICE_LOG_FULL	Return value when the log buffer is full and forced audit is set.
YHR_DEVICE_OBJECT_NOT_FOUND	Return value when the object not found on the device.
YHR_DEVICE_INVALID_ID	Return value when an invalid Object ID is used.
YHR_DEVICE_INVALID_OTP	Return value when an invalid OTP is submitted.
YHR_DEVICE_DEMO_MODE	Return value when the device is in demo mode and has to be power cycled.
YHR_DEVICE_COMMAND_UNEXECUTED	Return value when the command execution has not terminated.
YHR_GENERIC_ERROR	Return value when encountering an unknown error.
YHR_DEVICE_OBJECT_EXISTS	Return value when trying to add an object with an ID that already exists.
YHR_CONNECTOR_ERROR	Return value when connector operation failed.
YHR_DEVICE_SSH_CA_CONSTRAINT_VIOLATION	Return value when encountering SSH CA constraint violation.

Function Documentation

◆ yh_algo_to_string()

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

Convert an algorithm to its string representation.

Parameters

algo	Algorithm to convert. See yh_algorithm
result	The algorithm as a String. "Unknown" if the algorithm is not supported by YubiHSM 2.

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if result is NULL.

See also: Algorithms

◆ yh_authenticate_session()

yh_rc yh_authenticate_session ( yh_session * session )

Authenticate session.

Parameters

session Session to authenticate

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. YHR_SESSION_AUTHENTICATION_FAILED if the session fails to authenticate. See yh_rc for other possible errors

See also: Session

◆ yh_begin_create_session_ext()

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

Begin creating an external session.

The session's encryption key and MAC key are not stored in the device.

This function must be followed by yh_finish_create_session_ext() to set the session keys.

Parameters

connector	Connector to the device
authkey_id	Object ID of the Authentication Key used to authenticate the session
context	pointer to where context data is saved
card_cryptogram	Card cryptogram
card_cryptogram_len	Length of card cryptogram
session	created session

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_MEMORY_ERROR if failed to allocate memory for the session. See yh_rc for other possible errors

See also: Session

◆ yh_capabilities_to_strings()

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

Convert an array of yh_capabilities into strings separated by ','.

Parameters

num	Array of yh_capabilities
result	Array of the capabilies as strings
n_result	Number of elements in result

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_BUFFER_TOO_SMALL if n_result is too small

See also: Capability

◆ yh_check_capability()

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

Check if a capability is set.

Parameters

capabilities	Array of yh_capabilities
capability	Capability to check as a string.

Returns: True if the capability is in capabilities. False otherwise

Code sample

char *capabilities_str = "sign-pkcs,decrypt-pkcs,set-option";
yh_capabilities capabilities = {{0}};
yh_string_to_capabilities(capabilities_str, &capabilities);
//yh_check_capability(&capabilities, "something") => false
//yh_check_capability(&capabilities, "sign-pss") => false
//yh_check_capability(&capabilities, "decrypt-pkcs") => true

See also: Capability

◆ yh_connect()

yh_rc yh_connect	(	yh_connector *	connector,
		int	timeout
	)

Connect to the device through the specified connector.

Parameters

connector	Connector to the device
timeout	Connection timeout in seconds

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the connector does not exist. See yh_rc for other possible errors

◆ yh_connector_has_device()

bool yh_connector_has_device ( yh_connector * connector )

Check if the connector has a device connected.

Parameters

connector Connector currently in use

Returns: True if the connector is not NULL and there is a device connected to it. False otherwise

◆ yh_create_session()

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

Create a session that uses the specified encryption key and MAC key to derive session-specific keys.

Parameters

connector	Connector to the device
authkey_id	Object ID of the Authentication Key used to authenticate the session
key_enc	Encryption key used to derive the session encryption key
key_enc_len	Length of the encryption key.
key_mac	MAC key used to derive the session MAC key
key_mac_len	Length of the MAC key.
recreate_session	If true, the session will be recreated if expired. This caches the password in memory
session	created session

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or incorrect. See yh_rc for other possible errors

See also: Session, Authentication Key

◆ yh_create_session_derived()

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

Create a session that uses an encryption key and a MAC key derived from a password.

Parameters

connector	Connector to the device
authkey_id	Object ID of the Authentication Key used to authenticate the session
password	Password used to derive the session encryption key and MAC key
password_len	Length of the password in bytes
recreate_session	If true, the session will be recreated if expired. This caches the password in memory
session	The created session

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the connector, the password or the session are NULL. YHR_GENERIC_ERROR if failed to derive the session encryption key and/or the MAC key or if PRNG related errors occur. YHR_MEMORY_ERROR if failed to allocate memory for the session. See yh_rc for other possible errors

See also: Session

◆ yh_destroy_session()

yh_rc yh_destroy_session ( yh_session ** session )

Free data associated with the session.

Parameters

session Pointer to the session to destroy

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL.

See also: Session

◆ yh_disconnect()

yh_rc yh_disconnect ( yh_connector * connector )

Disconnect from a connector.

Parameters

connector Connector from which to disconnect

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the connector is NULL

◆ yh_domains_to_string()

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

Convert domains parameter to its String representation.

Parameters

domains	Encoded domains
string	Domains as a string
max_len	Maximum length of the string

Returns: YHR_SUCCESS if successful. YHR_BUFFER_TOO_SMALL if max_len is too small

Examples

1 => "1"
0x8001 => "1:16"
0, ""
0xffff => "1:2:3:4:5:6:7:8:9:10:11:12:13:14:15:16"

See also: Domains

◆ yh_exit()

yh_rc yh_exit ( void )

Global library clean up.

Returns: YHR_SUCCESS

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

The resulting set of capabilities contains only the capabilities that exist in both sets of input capabilities

Parameters

capabilities	Array of yh_capabilities
filter	Array of yh_capabilities
result	Resulting array of yh_capabilities

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL.

See also: Capability

◆ 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 *	card_cryptogram,
		size_t	card_cryptogram_len
	)

Finish creating external session.

The session's encryption key and MAC key are not stored in the device.

This function must be called after yh_begin_create_session_ext().

Parameters

connector	Connector to the device
session	The session created with yh_begin_create_session_ext()
key_senc	Session encryption key used to encrypt the messages exchanged with the device
key_senc_len	Lenght of the encryption key. Must be YH_KEY_LEN
key_smac	Session MAC key used for creating the authentication tag for each message
key_smac_len	Length of the MAC key. Must be YH_KEY_LEN
key_srmac	Session return MAC key used for creating the authentication tag for each response message
key_srmac_len	Length of the return MAC key. Must be YH_KEY_LEN
card_cryptogram	Card cryptogram
card_cryptogram_len	Length of card cryptogram

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or any of the key lengths are not YH_KEY_LEN. See yh_rc for other possible errors

See also: Session

◆ yh_get_connector_address()

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

Get connector address.

Parameters

connector	Connector currently in use
address	Pointer to the connector address as string

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL.

◆ 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

connector	Connector currently in use
major	Connector major version
minor	Connector minor version
patch	Connector patch version

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL.

◆ yh_get_key_bitlength()

yh_rc yh_get_key_bitlength	(	yh_algorithm	algorithm,
		size_t *	result
	)

Get the expected key length of a key generated by the given algorithm.

Parameters

algorithm	Algorithm to check. See yh_algorithm
result	Expected bitlength of a key generated by the algorithm

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if result is NULL or if the algorithm is no supported by YubiHSM 2. For a list of supported algorithms, see yh_algorithm

◆ yh_get_session_id()

yh_rc yh_get_session_id	(	yh_session *	session,
		uint8_t *	sid
	)

Get the session ID.

Parameters

session	Authenticated session to use
sid	Session ID

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL.

◆ yh_get_verbosity()

yh_rc yh_get_verbosity ( uint8_t * verbosity )

Get verbosity level when executing commands.

Parameters

verbosity The verbosity level

Returns: YHR_SUCCESS if seccessful. YHR_INVALID_PARAMETERS if verbosity is NULL

See also: YH_VERB_QUIET, YH_VERB_INTERMEDIATE, YH_VERB_CRYPTO, YH_VERB_RAW, YH_VERB_INFO, YH_VERB_ERR, YH_VERB_ALL

◆ yh_init()

yh_rc yh_init ( void )

Global library initialization.

Returns: YHR_SUCCESS

◆ yh_init_connector()

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

Instantiate a new connector.

Parameters

url	URL associated with this connector
connector	Connector to the device

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if either the URL or the connector are NULL. YHR_GENERIC_ERROR if failed to load the backend. YHR_MEMORY_ERROR if failed to allocate memory for the connector. YHR_CONNECTION_ERROR if failed to create the connector

◆ yh_is_ec()

bool yh_is_ec ( yh_algorithm algorithm )

Check if an algorithm is a supported Elliptic Curve algorithm.

Supported EC algorithms: YH_ALGO_EC_P224, YH_ALGO_EC_P256, YH_ALGO_EC_P384, YH_ALGO_EC_P521, YH_ALGO_EC_K256, YH_ALGO_EC_BP256, YH_ALGO_EC_BP384 and YH_ALGO_EC_BP512

Parameters

algorithm Algorithm to check. See yh_algorithm

Returns: True if the algorithm is one of the supported EC algorithms. False otherwise

◆ yh_is_ed()

bool yh_is_ed ( yh_algorithm algorithm )

Check if an algorithm is a supported ED algorithm.

Supported ED algorithms: YH_ALGO_EC_ED25519

Parameters

algorithm algorithm. See yh_algorithm

Returns: True if the algorithm is YH_ALGO_EC_ED25519. False otherwise

◆ yh_is_hmac()

bool yh_is_hmac ( yh_algorithm algorithm )

Check if algorithm is a supported HMAC algorithm.

Supported HMAC algorithms: YH_ALGO_HMAC_SHA1, YH_ALGO_HMAC_SHA256, YH_ALGO_HMAC_SHA384 and YH_ALGO_HMAC_SHA512

Parameters

algorithm Algorithm to check. See yh_algorithm

Returns: True if the algorithm is one of the supported HMAC algorithms. False otherwise

◆ yh_is_rsa()

bool yh_is_rsa ( yh_algorithm algorithm )

Check if an algorithm is a supported RSA algorithm.

Supported RSA algorithms: YH_ALGO_RSA_2048, YH_ALGO_RSA_3072 and YH_ALGO_RSA_4096

Parameters

algorithm Algorithm to check. See yh_algorithm

Returns: True if the algorithm is one of the supported RSA algorithms . False otherwise

◆ yh_merge_capabilities()

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

Merge two sets of capabilities.

The resulting set of capabilities contain all capabilities from both arrays

Parameters

a	Array of yh_capabilities
b	Array of yh_capabilities
result	Resulting array of yh_capabilities

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL.

See also: Capability

◆ 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 (unencrypted) message to the device through a connector.

Parameters

connector	Connector to the device
cmd	Command to send. See yh_cmd
data	Data to send
data_len	length of data to send
response_cmd	Response command
response	Response data
response_len	Length of response data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_BUFFER_TOO_SMALL if the actual response was longer than response_len. See yh_rc for other possible errors

◆ 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 to the device over a session.

The session has to be authenticated

Parameters

session	Session to send the message over
cmd	Command to send
data	Data to send
data_len	Length of data to send
response_cmd	Response command
response	Response data
response_len	Length of response data

Returns: YHR_SUCCESS if successful. See yh_rc for possible errors

◆ yh_set_connector_option()

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

Set connector options.

Note that backend options are not supported with winhttp or USB connectors

Parameters

connector	Connector to set an option on
opt	Option to set. See yh_connector_option
val	Value of the option. Type of value is specific to the given option

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the connector or the value are NULL or if the option is unknown. YHR_CONNECTOR_ERROR if failed to set the option

◆ yh_set_debug_output()

void yh_set_debug_output	(	yh_connector *	connector,
		FILE *	output
	)

Set file for debug output.

Parameters

connector	If not NULL, the debug messages will be written to the specified output file
output	The destination of the debug messages

Returns: void

◆ yh_set_verbosity()

yh_rc yh_set_verbosity	(	yh_connector *	connector,
		uint8_t	verbosity
	)

Set verbosity level when executing commands.

Default verbosity is YH_VERB_QUIET

This function may be called prior to global library initialization to set the debug level

Parameters

connector	If not NULL, the verbosity of the specific connector will be set
verbosity	The desired level of debug output

Returns: YHR_SUCCESS

See also: YH_VERB_QUIET, YH_VERB_INTERMEDIATE, YH_VERB_CRYPTO, YH_VERB_RAW, YH_VERB_INFO, YH_VERB_ERR, YH_VERB_ALL

◆ yh_strerror()

const char* yh_strerror ( yh_rc err )

Return a string describing an error condition.

Parameters

err	yh_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 a string to an algorithm's numeric value.

Parameters

string	Algorithm as string. See yh_algorithm
algo	Algorithm numeric value

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if the algorithm is not supported by YubiHSM 2.

Code sample

yh_algorithm algorithm;
//yh_string_to_algo(NULL, &algorithm) => YHR_INVALID_PARAMETERS
//yh_string_to_algo("something", NULL) => YHR_INVALID_PARAMETERS
//yh_string_to_algo("something", &algorithm) => YHR_INVALID_PARAMETERS
//yh_string_to_algo("rsa-pkcs1-sha1", &algorithm) =>

YH_ALGO_RSA_PKCS1_SHA1 //yh_string_to_algo("rsa2048", &algorithm) => YH_ALGO_RSA_2048

See also: Algorithms

◆ yh_string_to_capabilities()

yh_rc yh_string_to_capabilities	(	const char *	capability,
		yh_capabilities *	result
	)

Convert capability string to byte array.

Parameters

capability	String of capabilities separated by ',', ':' or '\|'
result	Array of yh_capabilities

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_BUFFER_TOO_SMALL if capability is too big

Examples:

"get-opaque" => {"\x00\x00\x00\x00\x00\x00\x00\x01"}
"sign-hmac:verify-hmac|exportable-under-wrap," => {"\x00\x00\x00\x00\x00\xc1\x00\x00"}
",,unwrap-data|:wrap-data,,," => {"\x00\x00\x00\x60\x00\x00\x00\x00"}
"0x7fffffffffffffff" => {"\x7f\xff\xff\xff\xff\xff\xff\xff"}
"0xffffffffffffffff" => {"\xff\xff\xff\xff\xff\xff\xff\xff"}

See also: Capability

◆ yh_string_to_domains()

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

Convert a string to a domain's numeric value.

The domains string can contain one or several domains separated by ',', ':' or '|'. Each domain can be written in decimal or hex format

Parameters

domains	String of domains
result	Resulting parsed domains as an unsigned int

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL, if the domains string is does not contains the expected values

Examples

"1" => 1
"1,2:3,4|5,6;7,8,9,10,11,12,13,14,15,16" => 0xffff
"1,16" => 0x8001
"16" => 0x8000
"16,15" => 0xc000
"1,0xf" => 0x4001
"0x1,0x2" => 3
"0x8888" => 0x8888
"0" => 0
"all" => 0xffff
"2" => 2
"2:4" => 10

See also: Domains

◆ yh_string_to_option()

yh_rc yh_string_to_option	(	const char *	string,
		yh_option *	option
	)

Convert a string to an option's numeric value.

Parameters

string	Option as string. See yh_option
option	Option numeric value

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if the option was not recognized.

Code sample

yh_option option;
//yh_string_to_option(NULL, &option) => YHR_INVALID_PARAMETERS
//yh_string_to_option("something", NULL) => YHR_INVALID_PARAMETERS
//yh_string_to_option("something", &option) => YHR_INVALID_PARAMETERS
//yh_string_to_option("force-audit", &option) =>

option=YH_OPTION_FORCE_AUDIT

See also: Options

◆ yh_string_to_type()

yh_rc yh_string_to_type	(	const char *	string,
		yh_object_type *	type
	)

Convert a string to a type's numeric value.

Parameters

string	Type as a String. See yh_object_type
type	Type numeric value

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if the type was not recognized.

Code sample

yh_object_type type;
//yh_string_to_type(NULL, &type) => YHR_INVALID_PARAMETERS
//yh_string_to_type("something", NULL) => YHR_INVALID_PARAMETERS
//yh_string_to_type("something", &type) => YHR_INVALID_PARAMETERS
//yh_string_to_type("opaque", &type) => type=YH_OPAQUE
//yh_string_to_type("authentication-key", &type) =>

type=YH_AUTHENTICATION_KEY

See also: Object

◆ yh_type_to_string()

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

Convert a yh_object_type to its string representation.

Parameters

type	Type to convert. See yh_object_type
result	The type as a String. "Unknown" if the type was not recognized

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if result is NULL.

Code sample

const char *string;
//yh_type_to_string(0, NULL) => YHR_INVALID_PARAMETERS
//yh_type_to_string(99, &string) => string="Unknown"
//yh_type_to_string(YH_OPAQUE, &string) => string="opaque"
//yh_type_to_string(YH_AUTHENTICATION_KEY, &string) =>

string="authentication-key"

See also: Object

◆ yh_util_blink_device()

yh_rc yh_util_blink_device	(	yh_session *	session,
		uint8_t	seconds
	)

Blink the LED of the device to identify it.

Parameters

session	Authenticated session to use
seconds	Number of seconds to blink

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. See yh_rc for other possible errors

◆ yh_util_change_authentication_key()

yh_rc yh_util_change_authentication_key	(	yh_session *	session,
		uint16_t *	key_id,
		const uint8_t *	key_enc,
		size_t	key_enc_len,
		const uint8_t *	key_mac,
		size_t	key_mac_len
	)

Replace the long lived encryption key and MAC key associated with an YH_AUTHENTICATION_KEY in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key to replace
key_enc	New long lived encryption key
key_enc_len	Length of the new encryption key. Must be YH_KEY_LEN
key_mac	New long lived MAC key
key_mac_len	Length of the new MAC key. Must be YH_KEY_LEN

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if key_enc_len or key_mac_len are not the expected values. See yh_rc for other possible errors

See also: Authentication Key

◆ yh_util_change_authentication_key_derived()

yh_rc yh_util_change_authentication_key_derived	(	yh_session *	session,
		uint16_t *	key_id,
		const uint8_t *	password,
		size_t	password_len
	)

Replace the long lived encryption key and MAC key associated with an YH_AUTHENTICATION_KEY in the device with keys derived from a password.

Parameters

session	Authenticated session to use
key_id	Object ID of the key to replace
password	Password to derive the new encryption key and MAC key
password_len	Length of password

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

See also: Authentication Key

◆ yh_util_close_session()

yh_rc yh_util_close_session ( yh_session * session )

Close a session.

Parameters

session Session to close

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. See yh_rc for other possible errors

◆ yh_util_create_otp_aead()

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

Create a Yubico OTP AEAD using the provided data.

Parameters

session	Authenticated session to use
key_id	Object ID of the Otp-aead Key to use
key	OTP key
private_id	OTP private id
out	The created AEAD
out_len	Length of the created AEAD

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ 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 data using RSA-OAEP.

Parameters

session	Authenticated session to use
key_id	Object ID of the RSA key to use for decryption
in	Encrypted data
in_len	Length of encrypted data. Must be 256, 384 or 512
out	Decrypted data
out_len	Length of decrypted data
label	OAEP label
label_len	Length of OAEP label. Must be 20, 32, 48 or 64
mgf1Algo	MGF1 algorithm

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL. YHR_WRONG_LENGTH if in_len or label_len are not what expected. See yh_rc for other possible errors

◆ yh_util_decrypt_otp()

yh_rc yh_util_decrypt_otp	(	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 a Yubico OTP and return counters and time information.

Parameters

session	Authenticated session to use
key_id	Object ID of the key used for decryption
aead	AEAD as created by yh_util_create_otp_aead() or yh_util_randomize_otp_aead()
aead_len	Length of AEAD
otp	OTP
useCtr	OTP use counter
sessionCtr	OTP session counter
tstph	OTP timestamp high
tstpl	OTP timestamp low

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ 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 data that was encrypted using RSA-PKCS#1v1.5.

Parameters

session	Authenticated session to use
key_id	Object ID of the RSA key to use for decryption
in	Encrypted data
in_len	Length of encrypted data
out	Decrypted data
out_len	Length of decrypted data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is bigger than YH_MSG_BUF_SIZE-2. See yh_rc for other possible errors

◆ yh_util_delete_object()

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

Delete an object in the device.

Parameters

session	Authenticated session to use
id	Object ID of the object to delete
type	Type of object to delete. See yh_object_type

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if session is NULL. See yh_rc for other possible errors

◆ yh_util_derive_ecdh()

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

Derive an ECDH key from a private EC key on the device and a provided public EC key.

Parameters

session	Authenticated session to use
key_id	Object ID of the EC private key to use for ECDH derivation
in	Public key of another EC key-pair
in_len	Length of public key
out	Shared secret ECDH key
out_len	Length of the shared ECDH key

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is bigger than YH_MSG_BUF_SIZE-2. See yh_rc for other possible errors

◆ 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 from the device.

Parameters

session	Authenticated session to use
wrapping_key_id	Object ID of the Wrap Key to use to wrap the object
target_type	Type of the object to be exported. See yh_object_type
target_id	Object ID of the object to be exported
out	Wrapped data
out_len	Length of wrapped data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_generate_ec_key()

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

Generate an Elliptic Curve key in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm to use to generate the EC key. Supported algorithm: YH_ALGO_EC_P224, YH_ALGO_EC_P256, YH_ALGO_EC_K256, YH_ALGO_EC_BP256, YH_ALGO_EC_P384, YH_ALGO_EC_BP384, YH_ALGO_EC_BP512 and YH_ALGO_EC_P521.

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or the algorithm is not one of YH_ALGO_EC_P224, YH_ALGO_EC_P256, YH_ALGO_EC_K256, YH_ALGO_EC_BP256, YH_ALGO_EC_P384, YH_ALGO_EC_BP384, YH_ALGO_EC_BP512 or YH_ALGO_EC_P521. See yh_rc for other possible errors

◆ yh_util_generate_ed_key()

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

Generate an ED key in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label for the key. Maximum length YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the ED key. See yh_string_to_capabilities()
algorithm	Algorithm to use to generate the ED key. Supported algorithm: YH_ALGO_EC_ED25519

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or the algorithm is not YH_ALGO_EC_ED25519. See yh_rc for other possible errors

◆ yh_util_generate_hmac_key()

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

Generate an HMAC key in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm to use to generate the HMAC key. Supported algorithims: YH_ALGO_HMAC_SHA1, YH_ALGO_HMAC_SHA256, YH_ALGO_HMAC_SHA384 and YH_ALGO_HMAC_SHA512

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL. See yh_rc for other possible errors

◆ 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 an YH_OTP_AEAD_KEY for Yubico OTP decryption in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the AEAD Key. 0 if the Object ID should be generated by the device
label	Label of the AEAD Key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains the AEAD Key will be operating within. See yh_string_to_domains()
capabilities	Capabilities of the AEAD Key. See yh_string_to_capabilities()
algorithm	Algorithm used to generate the AEAD Key. Supported algorithms: YH_ALGO_AES128_YUBICO_OTP, YH_ALGO_AES192_YUBICO_OTP and YH_ALGO_AES256_YUBICO_OTP
nonce_id	Nonce ID

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_generate_rsa_key()

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

Generate an RSA key in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm to use to generate the RSA key. Supported algorithms: YH_ALGO_RSA_2048, YH_ALGO_RSA_3072 and YH_ALGO_RSA_4096

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or the algorithm is not one of YH_ALGO_RSA_2048, YH_ALGO_RSA_3072 or YH_ALGO_RSA_4096. See yh_rc for other possible errors

◆ yh_util_generate_wrap_key()

yh_rc yh_util_generate_wrap_key	(	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 that can be used for export, import, wrap data and unwrap data in the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the Wrap Key. 0 if the Object ID should be generated by the device
label	Label of the Wrap Key. Maximum length YH_OBJ_LABEL_LEN
domains	Domains where the Wrap Key will be operating within. See yh_string_to_domains()
capabilities	Capabilities of the Wrap Key. See yh_string_to_capabilities()
algorithm	Algorithm used to generate the Wrap Key
delegated_capabilities	Delegated capabilitites of the Wrap Key. See yh_string_to_capabilities()

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

See also: yh_object_type

◆ 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 version, device serial number, supported algorithms and available log entries.

Parameters

connector	Connector to the device
major	Device major version number
minor	Device minor version number
patch	Device build version number
serial	Device serial number
log_total	Total number of log entries
log_used	Number of written log entries
algorithms	List of supported algorithms
n_algorithms	Number of supported algorithms

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the connector is NULL. YHR_BUFFER_TOO_SMALL if n_algorithms is smaller than the number of actually supported algorithms. See yh_rc for other possible errors.

See also: Algorithms

◆ yh_util_get_log_entries()

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

Get audit logs from the device.

When audit enforce is set, if the log buffer is full, no new operations (other than authentication operations) can be performed unless the log entries are read by this command and then the log index is set by calling yh_util_set_log_index().

Parameters

session	Authenticated session to use
unlogged_boot	Number of unlogged boot events. Used if the log buffer is full and audit enforce is set
unlogged_auth	Number of unlogged authentication events. Used if the log buffer is full and audit enforce is set
out	Log entries on the device
n_items	Number of log entries

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_BUFFER_TOO_SMALL if n_items is smaller than the actual number of retrieved log entries. See yh_rc for other possible errors

◆ 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 metadata of the object with the specified Object ID and Type.

Parameters

session	Authenticated session to use
id	Object ID of the object to get
type	Object type. See yh_object_type
object	Object information

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. See yh_rc for other possible errors.

See also: Objects

◆ 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 an YH_OPAQUE object (like an X.509 certificate) from the device.

Parameters

session	Authenticated session to use
object_id	Object ID of the Opaque object
out	the retrieved Opaque object
out_len	Length of the retrieved Opaque object

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_get_option()

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

Get a device-global option.

Parameters

session	Authenticated session to use
option	Option to get. See yh_option
out	Option value
out_len	Length of option value

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_get_pseudo_random()

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

Get a fixed number of pseudo-random bytes from the device.

Parameters

session	Authenticated session to use
len	Length of pseudo-random data to get
out	Pseudo-random data out
out_len	Length of pseudo-random data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_get_public_key()

yh_rc yh_util_get_public_key	(	yh_session *	session,
		uint16_t	id,
		uint8_t *	data,
		size_t *	data_len,
		yh_algorithm *	algorithm
	)

Get the value of the public key with the specified Object ID.

Parameters

session	Authenticated session to use
id	Object ID of the public key
data	Value of the public key
data_len	Length of the public key in bytes
algorithm	Algorithm of the key

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_BUFFER_TOO_SMALL if the actual key length was bigger than data_len. See yh_rc for other possible errors

◆ yh_util_get_storage_info()

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

Report currently free storage.

This is reported as free records, free pages and page size.

Parameters

session	Authenticated session to use
total_records	Total number of records
free_records	Number of free records
total_pages	Total number of pages
free_pages	Number of free pages
page_size	Page size in bytes

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. See yh_rc for other possible errors

◆ 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 a YH_TEMPLATE object from the device.

Parameters

session	Authenticated session to use
object_id	Object ID of the Template to get
out	The retrieved Template
out_len	Length of the retrieved Template

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_import_authentication_key()

yh_rc yh_util_import_authentication_key	(	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 *	key_enc,
		size_t	key_enc_len,
		const uint8_t *	key_mac,
		size_t	key_mac_len
	)

Import an YH_AUTHENTICATION_KEY into the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the imported key. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
delegated_capabilities	Delegated capabilities of the key. See yh_string_to_capabilities()
key_enc	Long lived encryption key of the Authentication Key to import
key_enc_len	Length of the encryption key. Must be YH_KEY_LEN
key_mac	Long lived MAC key of the Authentication Key to import
key_mac_len	Length of the MAC key. Must be YH_KEY_LEN

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if key_enc_len or key_mac_len are not the expected values. See yh_rc for other possible errors

See also: Authentication Key

◆ yh_util_import_authentication_key_derived()

yh_rc yh_util_import_authentication_key_derived	(	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 an YH_AUTHENTICATION_KEY with long lived keys derived from a password.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
delegated_capabilities	Delegated capabilities of the key. See yh_string_to_capabilities()
password	Password used to derive the long lived encryption key and MAC key of the Athentication Key
password_len	Length of password

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

See also: Authentication Key

◆ yh_util_import_ec_key()

yh_rc yh_util_import_ec_key	(	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 an Elliptic Curve key into the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs specified as an unsigned int. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm of the key to import. Must be one of: YH_ALGO_EC_P224, YH_ALGO_EC_P256, YH_ALGO_EC_K256, YH_ALGO_EC_BP256, YH_ALGO_EC_P384, YH_ALGO_EC_BP384, YH_ALGO_EC_BP512 or YH_ALGO_EC_P521
s	the EC key to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or the algorithm is not one of YH_ALGO_EC_P224, YH_ALGO_EC_P256, YH_ALGO_EC_K256, YH_ALGO_EC_BP256, YH_ALGO_EC_P384, YH_ALGO_EC_BP384, YH_ALGO_EC_BP512 or YH_ALGO_EC_P521. See yh_rc for other possible errors

◆ yh_util_import_ed_key()

yh_rc yh_util_import_ed_key	(	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 an ED key into the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key will have. 0 if the Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm of the key to import. Must be YH_ALGO_EC_ED25519
k	the ED key to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or the algorithm is not YH_ALGO_EC_ED25519. See yh_rc for other possible errors

◆ yh_util_import_hmac_key()

yh_rc yh_util_import_hmac_key	(	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 an HMAC key into the device.

Parameters

session	Authenticated session to use
key_id	Object ID of the key. 0 if the Object ID should be generated by the device
label	Label of the key. Maxium length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm of the key to import. Must be one of: YH_ALGO_HMAC_SHA1, YH_ALGO_HMAC_SHA256, YH_ALGO_HMAC_SHA384 or YH_ALGO_HMAC_SHA512
key	The HMAC key to import
key_len	Length of the HMAC key to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL. See yh_rc for other possible errors

◆ 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 an YH_OPAQUE object into the device.

Parameters

session	Authenticated session to use
object_id	Object ID of the Opaque object. 0 if the Object ID should be generated by the device
label	Label of the Opaque object. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains the Opaque object will be operating within. See yh_string_to_domains()
capabilities	Capabilities of the Opaque object. See yh_string_to_capabilities()
algorithm	Algorithm of the Opaque object
in	the Opaque object to import
in_len	Length of the Opaque object to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or in_len is too big. See yh_rc for other possible errors

◆ yh_util_import_otp_aead_key()

yh_rc yh_util_import_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 an YH_OTP_AEAD_KEY used for Yubico OTP Decryption.

Parameters

session	Authenticated session to use
key_id	Object ID of the AEAD Key. 0 if the Object ID should be generated by the device
label	Label of the AEAD Key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains the AEAD Key will be operating within. See yh_string_to_domains()
capabilities	Capabilities of the AEAD Key. See yh_string_to_capabilities()
nonce_id	Nonce ID
in	AEAD Key to import
in_len	Length of AEAD Key to import. Must be 16, 24 or 32

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if in_len is not one of 16, 24 or 32. See yh_rc for other possible errors

◆ yh_util_import_rsa_key()

yh_rc yh_util_import_rsa_key	(	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 an RSA key into the device.

Parameters

session	Authenticated session to use
key_id	Object ID the key. 0 if Object ID should be generated by the device
label	Label of the key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains to which the key belongs specified as an unsigned int. See yh_string_to_domains()
capabilities	Capabilities of the key. See yh_string_to_capabilities()
algorithm	Algorithm of the key to import. Must be one of: YH_ALGO_RSA_2048, YH_ALGO_RSA_3072 or YH_ALGO_RSA_4096
p	P component of the RSA key to import
q	Q component of the RSA key to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or the algorithm is not one of YH_ALGO_RSA_2048, YH_ALGO_RSA_3072 or YH_ALGO_RSA_4096. See yh_rc for other possible errors

◆ 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 a YH_TEMPLATE object into the device.

Parameters

session	Authenticated session to use
object_id	Object ID of the Template. 0 if the Object ID should be generated by the device
label	Label of the Template. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains the Template will be operating within. See yh_string_to_domains()
capabilities	Capabilities of the Template. See yh_string_to_capabilities
algorithm	Algorithm of the Template
in	Template to import
in_len	Length of the Template to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if in_len is too big. See yh_rc for other possible errors

◆ yh_util_import_wrap_key()

yh_rc yh_util_import_wrap_key	(	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 into the device.

Parameters

session	Authenticated session to use
key_id	Object ID the Wrap Key. 0 if the Object ID should be generated by the device
label	Label of the Wrap Key. Maximum length is YH_OBJ_LABEL_LEN
domains	Domains where the Wrap Key will be operating within. See yh_string_to_domains()
capabilities	Capabilities of the Wrap Key. See yh_string_to_capabilities()
algorithm	Algorithm of the Wrap Key. Supported algorithms: YH_ALGO_AES128_CCM_WRAP, YH_ALGO_AES192_CCM_WRAP and YH_ALGO_AES256_CCM_WRAP
delegated_capabilities	Delegated capabilities of the Wrap Key. See yh_string_to_capabilities()
in	the Wrap Key to import
in_len	Length of the Wrap Key to import

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL, in_len is not what expected based on the algorithm and if the algorithms is not one of YH_ALGO_AES128_CCM_WRAP, YH_ALGO_AES192_CCM_WRAP or YH_ALGO_AES256_CCM_WRAP. See yh_rc for other possible errors

◆ 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 into the device.

The object should have been previously exported by yh_util_export_wrapped()

Parameters

session	Authenticated session to use
wrapping_key_id	Object ID of the Wrap Key to use to unwrap the object
in	Wrapped data
in_len	Length of wrapped data
target_type	Type of the imported object
target_id	Object ID of the imported object

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ 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 accessible from the session.

Parameters

session	Authenticated session to use
id	Object ID to filter by (0 to not filter by ID)
type	Object type to filter by (0 to not filter by type). See yh_object_type
domains	Domains to filter by (0 to not filter by domain)
capabilities	Capabilities to filter by (0 to not filter by capabilities). See yh_capabilities
algorithm	Algorithm to filter by (0 to not filter by algorithm)
label	Label to filter by
objects	Array of objects returned
n_objects	Max number of objects (will be set to number found on return)

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. YHR_BUFFER_TOO_SMALL if n_objects is smaller than the number of objects found. See yh_rc for other possible errors.

See also: Objects, Domains, Capabilities, Algorithms, Labels

◆ yh_util_randomize_otp_aead()

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

Create OTP AEAD from random data.

Parameters

session	Authenticated session to use
key_id	Object ID of the Otp-aead Key to use
out	The created AEAD
out_len	Length of the created AEAD

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

◆ yh_util_reset_device()

yh_rc yh_util_reset_device ( yh_session * session )

Factory reset the device.

Resets and reboots the device, deletes all Objects and restores the default YH_AUTHENTICATION_KEY.

Parameters

session Authenticated session to use

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. See yh_rc for other possible errors

◆ yh_util_set_log_index()

yh_rc yh_util_set_log_index	(	yh_session *	session,
		uint16_t	index
	)

Set the index of the last extracted log entry.

This function should be called after yh_util_get_log_entries() to inform the device what the last extracted log entry is so new logs can be written. This is used when forced auditing is enabled.

Parameters

session	Authenticated session to use
index	index to set. Should be the same index as the last entry extracted using yh_util_get_log_entries()

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if the session is NULL. See yh_rc for other possible errors

◆ yh_util_set_option()

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

Set a device-global option.

Parameters

session	Authenticated session to use
option	Option to set. See yh_option
len	Length of option value
val	Option value

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if session or val are NULL or if len is too long. See yh_rc for other possible errors

◆ yh_util_sign_attestation_certificate()

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

Get attestation of an Asymmetric Key in the form of an X.509 certificate.

Parameters

session	Authenticated session to use
key_id	Object ID of the Asymmetric Key to attest
attest_id	Object ID for the key used to sign the attestation certificate
out	The attestation certificate
out_len	Length of the attestation certificate

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL. See yh_rc for other possible errors

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

in is a raw hashed message, a truncated hash to the curve length or a padded hash to the curve length

Parameters

session	Authenticated session to use
key_id	Object ID of the signing key
in	Data to sign
in_len	Length of data to sign
out	Signed data
out_len	Length of signed data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is not 20, 28, 34, 48, 64 or 66. See yh_rc for other possible errors

◆ 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

session	Authenticated session to use
key_id	Object ID of the signing key
in	Data to sign
in_len	Length of data to sign
out	Signed data
out_len	Length of signed data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is bigger than YH_MSG_BUF_SIZE-2. See yh_rc for other possible errors

◆ yh_util_sign_hmac()

yh_rc yh_util_sign_hmac	(	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 HMAC.

Parameters

session	Authenticated session to use
key_id	Object ID of the signing key
in	Data to HMAC
in_len	Length of data to hmac
out	HMAC
out_len	Length of HMAC

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is bigger than YH_MSG_BUF_SIZE-2. See yh_rc for other possible errors

◆ 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 RSA-PKCS#1v1.5.

in is either a raw hashed message (sha1, sha256, sha384 or sha512) or that with correct digestinfo pre-pended

Parameters

session	Authenticated session to use
key_id	Object ID of the signing key
hashed	true if data is only hashed
in	data to sign
in_len	length of data to sign
out	signed data
out_len	length of signed data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is not 20, 34, 48 or 64. See yh_rc for other possible errors

◆ 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 RSA-PSS.

in is a raw hashed message (sha1, sha256, sha384 or sha512)

Parameters

session	Authenticated session to use
key_id	Object ID of the signing key
in	Data to sign
in_len	Length of data to sign
out	Signed data
out_len	Length of signed data
salt_len	Length of salt
mgf1Algo	Algorithm for mgf1 (mask generation function for PSS)

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if in_len is not 20, 34, 48 or 64. See yh_rc for other possible errors

See also: PSS specifications

◆ yh_util_sign_ssh_certificate()

yh_rc yh_util_sign_ssh_certificate	(	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
	)

Sign an SSH Certificate request.

The function produces a signature that can then be used to produce the SSH Certificate

Parameters

session	Authenticated session to use
key_id	Object ID of the key used to sign the request
template_id	Object ID of the template to use as a certificate template
sig_algo	Signature algorithm to use to sign the certificate request
in	Certificate request
in_len	Length of the certificate request
out	Signature
out_len	Length of the signature

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or in_len is too big. See yh_rc for other possible errors

◆ 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
	)

Decrypt (unwrap) data using a YH_WRAP_KEY.

Parameters

session	Authenticated session to use
key_id	Object ID of the Wrap Key to use
in	Wrapped data
in_len	Length of wrapped data
out	Unwrapped data
out_len	Length of unwrapped data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if in_len is too big. See yh_rc for other possible errors

◆ yh_util_verify_hmac()

yh_rc yh_util_verify_hmac	(	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 a generated HMAC.

Parameters

session	Authenticated session to use
key_id	Object ID of the HMAC key
signature	HMAC signature (20, 32, 48 or 64 bytes)
signature_len	length of HMAC signature
data	data to verify
data_len	length of data to verify
verified	true if verification succeeded

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS input parameters are NULL or if signature_len + data_len is too long. See yh_rc for other possible errors

◆ 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
	)

Encrypt (wrap) data using a YH_WRAP_KEY.

Parameters

session	Authenticated session to use
key_id	Object ID of the Wrap Key to use
in	Data to wrap
in_len	Length of data to wrap
out	Wrapped data
out_len	Length of the wrapped data

Returns: YHR_SUCCESS if successful. YHR_INVALID_PARAMETERS if input parameters are NULL or if in_len is too big. See yh_rc for other possible errors

◆ 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

logs	Array of log entries
n_items	number of log entries
last_previous_log	Optional pointer to the entry before the first entry in logs

Returns: True if verification succeeds. False otherwise

See also: Logs

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ YH_ORIGIN_IMPORTED_WRAPPED

Enumeration Type Documentation

◆ yh_algorithm

◆ yh_cmd

◆ yh_connector_option

◆ yh_object_type

◆ yh_option

◆ yh_rc

Function Documentation

◆ yh_algo_to_string()

◆ yh_authenticate_session()

◆ yh_begin_create_session_ext()

◆ yh_capabilities_to_strings()

◆ yh_check_capability()

◆ yh_connect()

◆ yh_connector_has_device()

◆ yh_create_session()

◆ yh_create_session_derived()

◆ yh_destroy_session()

◆ yh_disconnect()

◆ yh_domains_to_string()

◆ yh_exit()

◆ yh_filter_capabilities()

◆ yh_finish_create_session_ext()

◆ yh_get_connector_address()

◆ yh_get_connector_version()

◆ yh_get_key_bitlength()

◆ yh_get_session_id()

◆ yh_get_verbosity()

◆ yh_init()

◆ yh_init_connector()

◆ yh_is_ec()

◆ yh_is_ed()

◆ yh_is_hmac()

◆ yh_is_rsa()

◆ yh_merge_capabilities()

◆ yh_send_plain_msg()

◆ yh_send_secure_msg()

◆ yh_set_connector_option()

◆ yh_set_debug_output()

◆ yh_set_verbosity()

◆ yh_strerror()

◆ yh_string_to_algo()

◆ yh_string_to_capabilities()

◆ yh_string_to_domains()

◆ yh_string_to_option()

◆ yh_string_to_type()

◆ yh_type_to_string()

◆ yh_util_blink_device()

◆ yh_util_change_authentication_key()

◆ yh_util_change_authentication_key_derived()

◆ yh_util_close_session()

◆ yh_util_create_otp_aead()

◆ yh_util_decrypt_oaep()

◆ yh_util_decrypt_otp()

◆ yh_util_decrypt_pkcs1v1_5()

◆ yh_util_delete_object()

◆ yh_util_derive_ecdh()

◆ yh_util_export_wrapped()

◆ yh_util_generate_ec_key()

◆ yh_util_generate_ed_key()

◆ yh_util_generate_hmac_key()

◆ yh_util_generate_otp_aead_key()

◆ yh_util_generate_rsa_key()

◆ yh_util_generate_wrap_key()

◆ yh_util_get_device_info()

◆ yh_util_get_log_entries()

◆ yh_util_get_object_info()

◆ yh_util_get_opaque()

◆ yh_util_get_option()

◆ yh_util_get_pseudo_random()

◆ yh_util_get_public_key()

◆ yh_util_get_storage_info()