Introduction

Libyubihsm is a library for communicating with a YubiHSM 2 device.

Usage

To use the library, include <yubihsm.h> in the C code and pass the -lyubihsm flag to the linker. Debug output is controlled with the function yh_set_verbosity().

First step of using a YubiHSM 2 is to initialize the library with yh_init(), initialize a connector with yh_init_connector() and then connect it to the YubiHSM 2 with yh_connect(). After this, a session must be established with yh_create_session_derived(), yh_create_session() or yh_begin_create_session_ext(). The session must then be authenticated using yh_authenticate_session().

When a session is authenticated, commands can be exchanged over it. The functions in the namespace yh_util are high-level convenience functions that do specific tasks with the device.

API Reference

All public functions and definitions can be found in yubihsm.h

Code example

Here is a small example of establishing a session with a YubiHSM 2 and fetching some pseudo random bytes before closing the session.

int main(void) {
  yh_connector *connector = NULL;
  yh_session *session = NULL;
  uint8_t data[128] = {0};
  size_t data_len = sizeof(data);
  assert(yh_init() == YHR_SUCCESS);
  assert(yh_init_connector("http://localhost:12345", &connector)==YHR_SUCCESS);
  assert(yh_connect(connector, 0) == YHR_SUCCESS);
  assert(yh_create_session_derived(connector, 1, YH_DEFAULT_PASSWORD,
  strlen(YH_DEFAULT_PASSWORD), false, &session) == YHR_SUCCESS);
  assert(yh_authenticate_session(session) == YHR_SUCCESS);
  assert(yh_util_get_pseudo_random(session, sizeof(data), data,
&data_len)==YHR_SUCCESS);
  assert(data_len == sizeof(data));
  assert(yh_util_close_session(session) == YHR_SUCCESS);
  assert(yh_destroy_session(&session) == YHR_SUCCESS);
  assert(yh_disconnect(connector) == YHR_SUCCESS);
}