ykneomgr

ykneomgr

Functions

Object Hierarchy


Description

Functions

ykneomgr_global_init ()

ykneomgr_rc
ykneomgr_global_init (ykneomgr_initflags flags);

Initialize the library. This function is not guaranteed to be thread safe and must be invoked on application startup.

Parameters

flags

initialization flags, ORed ykneomgr_initflags.

 

Returns

On success YKNEOMGR_OK (integer 0) is returned, and on errors an ykneomgr_rc error code.


ykneomgr_global_done ()

void
ykneomgr_global_done (void);

Release all resources from the library. Call this function when no further use of the library is needed.


ykneomgr_strerror ()

const char *
ykneomgr_strerror (int err);

Convert return code to human readable string explanation of the reason for the particular error code.

This string can be used to output a diagnostic message to the user.

This function is one of few in the library that can be used without a successful call to ykneomgr_global_init().

Parameters

err

error code

 

Returns

Returns a pointer to a statically allocated string containing an explanation of the error code err .


ykneomgr_strerror_name ()

const char *
ykneomgr_strerror_name (int err);

Convert return code to human readable string representing the error code symbol itself. For example, ykneomgr_strerror_name(YKNEOMGR_OK) returns the string "YKNEOMGR_OK".

This string can be used to output a diagnostic message to the user.

This function is one of few in the library that can be used without a successful call to ykneomgr_global_init().

Parameters

err

error code

 

Returns

Returns a pointer to a statically allocated string containing a string version of the error code err , or NULL if the error code is not known.


ykneomgr_init ()

ykneomgr_rc
ykneomgr_init (ykneomgr_dev **dev);

Create a YubiKey NEO device handle. The handle must be deallocated using ykneomgr_done() when you no longer need it.

Parameters

dev

pointer to newly allocated device handle.

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_done ()

void
ykneomgr_done (ykneomgr_dev *dev);

Release all resources allocated to a YubiKey NEO device handle.

Parameters

dev

device handle to deallocate, created by ykneomgr_init().

 

ykneomgr_list_devices ()

ykneomgr_rc
ykneomgr_list_devices (ykneomgr_dev *dev,
                       char *devicestr,
                       size_t *len);

List devices.

Parameters

dev

a ykneomgr_dev device handle.

 

devicestr

output buffer to hold string, or NULL.

 

len

on input length of devicestr buffer, on output holds output length

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_connect ()

ykneomgr_rc
ykneomgr_connect (ykneomgr_dev *dev,
                  const char *name);

Establish connection to a named PCSC device and verify that it has the YubiKey OTP applet. The name string should be a PCSC device name; you can use ykneomgr_list_devices() to list connected devices.

Parameters

dev

a ykneomgr_dev device handle.

 

name

input string with device name to connect to.

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, when no device could be found YKNEOMGR_NO_DEVICE is returned, or another ykneomgr_rc error code.


ykneomgr_discover ()

ykneomgr_rc
ykneomgr_discover (ykneomgr_dev *dev);

Discover and establish connection to the first found YubiKey NEO. A YubiKey NEO is identified by having the YubiKey OTP applet installed, i.e., a connect followed by attempting to select the YubiKey OTP applet.

Parameters

dev

a ykneomgr_dev device handle.

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, when no device could be found YKNEOMGR_NO_DEVICE is returned, otherwise another ykneomgr_rc error code is returned.


ykneomgr_discover_match ()

ykneomgr_rc
ykneomgr_discover_match (ykneomgr_dev *dev,
                         const char *match);

Discover and establish connection to the first found YubiKey NEO that has a card reader name matching match . A YubiKey NEO is identified by having the YubiKey OTP applet installed, i.e., a connect followed by attempting to select the YubiKey OTP applet. If match is NULL, then the first YubiKey NEO device detected will be used.

Parameters

dev

a ykneomgr_dev device handle.

 

match

substring to match card reader for, or NULL.

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, when no device could be found YKNEOMGR_NO_DEVICE is returned, or another ykneomgr_rc error code.

Since 0.1.4


ykneomgr_get_version_major ()

uint8_t
ykneomgr_get_version_major (ykneomgr_dev *dev);

Get major version of a YubiKey NEO. Versions are in the form of MAJOR.MINOR.BUILD, for example 3.0.4, in which case this function would return 3.

Parameters

dev

a ykneomgr_dev device handle.

 

Returns

the YubiKey NEO major version number.


ykneomgr_get_version_minor ()

uint8_t
ykneomgr_get_version_minor (ykneomgr_dev *dev);

Get minor version of a YubiKey NEO. Versions are in the form of MINOR.MINOR.BUILD, for example 3.0.4, in which case this function would return 0.

Parameters

dev

a ykneomgr_dev device handle.

 

Returns

the YubiKey NEO minor version number.


ykneomgr_get_version_build ()

uint8_t
ykneomgr_get_version_build (ykneomgr_dev *dev);

Get build version of a YubiKey NEO. Versions are in the form of BUILD.MINOR.BUILD, for example 3.0.4, in which case this function would return 4.

Parameters

dev

a ykneomgr_dev device handle.

 

Returns

the YubiKey NEO build version number.


ykneomgr_get_mode ()

uint8_t
ykneomgr_get_mode (ykneomgr_dev *dev);

Get mode of a YubiKey NEO.

Parameters

dev

a ykneomgr_dev device handle.

 

Returns

the YubiKey NEO device mode.


ykneomgr_get_serialno ()

uint32_t
ykneomgr_get_serialno (ykneomgr_dev *dev);

Get serial number of a YubiKey NEO, if visible.

Parameters

dev

a ykneomgr_dev device handle.

 

Returns

the YubiKey NEO serial number, or 0 if not visible.


ykneomgr_modeswitch ()

ykneomgr_rc
ykneomgr_modeswitch (ykneomgr_dev *dev,
                     uint8_t mode);

Mode switch a YubiKey NEO.

Parameters

dev

a ykneomgr_dev device handle.

 

mode

new mode to switch the device into

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_authenticate ()

ykneomgr_rc
ykneomgr_authenticate (ykneomgr_dev *dev,
                       const uint8_t *key);

Authenticate to the device, to prepare for privileged function access.

Parameters

dev

a ykneomgr_dev device handle.

 

key

Double-DES key in binary, 16 bytes

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_applet_list ()

ykneomgr_rc
ykneomgr_applet_list (ykneomgr_dev *dev,
                      char *appletstr,
                      size_t *len);

List installed applets.

Parameters

dev

a ykneomgr_dev device handle.

 

appletstr

output buffer to hold string, or NULL.

 

len

on input length of appletstr buffer, on output holds output length

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_applet_delete ()

ykneomgr_rc
ykneomgr_applet_delete (ykneomgr_dev *dev,
                        const uint8_t *aid,
                        size_t aidlen);

Delete specified applet.

Parameters

dev

a ykneomgr_dev device handle.

 

aid

aid to delete.

 

aidlen

length of aid buffer.

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_applet_install ()

ykneomgr_rc
ykneomgr_applet_install (ykneomgr_dev *dev,
                         const char *capfile);

Install specified applet.

Parameters

dev

a ykneomgr_dev device handle.

 

capfile

string with path filename to CAP file

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code.


ykneomgr_send_apdu ()

ykneomgr_rc
ykneomgr_send_apdu (ykneomgr_dev *dev,
                    const uint8_t *send,
                    size_t sendlen,
                    uint8_t *recv,
                    size_t *recvlen);

Send an arbitrary apdu to the device.

Parameters

dev

a ykneomgr_dev device handle.

 

send

apdu to send

 

sendlen

length of send buffer

 

recv

response apdu

 

recvlen

length of recv buffer

 

Returns

On success, YKNEOMGR_OK (integer 0) is returned, or another ykneomgr_rc error code. recvlen will be set to the length of the data in recv .

Types and Values