Yubico YubiKey NEO CCID Manager C Library: ykneomgr

## ykneomgr ykneomgr |

## Functions

ykneomgr_rc | ykneomgr_global_init ()
void | ykneomgr_global_done ()
const char * | ykneomgr_strerror ()
const char * | ykneomgr_strerror_name ()
ykneomgr_rc | ykneomgr_init ()
void | ykneomgr_done ()
ykneomgr_rc | ykneomgr_list_devices ()
ykneomgr_rc | ykneomgr_connect ()
ykneomgr_rc | ykneomgr_discover ()
ykneomgr_rc | ykneomgr_discover_match ()
uint8_t | ykneomgr_get_version_major ()
uint8_t | ykneomgr_get_version_minor ()
uint8_t | ykneomgr_get_version_build ()
uint8_t | ykneomgr_get_mode ()
uint32_t | ykneomgr_get_serialno ()
ykneomgr_rc | ykneomgr_modeswitch ()
ykneomgr_rc | ykneomgr_authenticate ()
ykneomgr_rc | ykneomgr_applet_list ()
ykneomgr_rc | ykneomgr_applet_delete ()
ykneomgr_rc | ykneomgr_applet_install ()
ykneomgr_rc | ykneomgr_send_apdu ()

## 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