Introduction

This is a C library to interact with the CCID-part of the YubiKey NEO. There is a command line tool "ykneomgr" for interactive use. It supports querying the YubiKey NEO for firmware version, operation mode (OTP/CCID) and serial number. You may also mode switch the device and manage applets (list, delete and install).

For more information about Yubico and the YubiKey, see: https://www.yubico.com/

Important

Yubico has learned of a security issue with the OpenPGP Card applet project that is used in the YubiKey NEO. This vulnerability applies to you only if you are using OpenPGP, and you have the OpenPGP applet version 1.0.9 or earlier. SecurityAdvisory 2015-04-14

License

The project is licensed under the LGPLv3+ license. See the file COPYING for exact wording. For any copyright year range specified as YYYY-ZZZZ in this package note that the range specifies every single year in that closed interval.

Building

After downloading and unpacking the package tarball, you build it as follows.

./configure
make check
sudo make install

The backend to use is decided at compile time, see the summary at the end of the ./configure output. Use --with-backend=foo to chose backend, replacing foo with the backend you want to use. The default and recommended backend is "pcsc" which will be selected if present. The backends "pcsc", "macscard", and "winscard" uses the PCSC interface, with slightly different shared library linkage and header file names: "pcsc" is used under GNU-like systems, "macscard" under Mac OS X, and "winscard" is used under Windows. In most situations, running ./configure should automatically find the proper backend to use. There is also a backend "globalplatform" available that will use libglobalplatform to perform operations. To force building using the globalplatform interface, you would use:

./configure --with-backend=globalplatform

LibZIP is a required dependency. On GNU/Linux systems LibZIP and the PCSC dependency may be installed as follows.

Debian/Ubuntu:   apt-get install libpcsclite-dev libzip-dev

Usage

The library usage is documented in the API manual, see gtk-doc/html/ after you built with ./configure --enable-gtk-doc.

There is a command line utility "ykneomgr" for command line use. Use "man ykneomgr" to read the documentation for it.

Building from version controlled sources

Warning! This is only for developers and if you don’t understand what you are doing, you should download the release files instead.

You may check out the sources using Git with the following command:

git clone https://github.com/Yubico/libykneomgr.git

This will create a directory libykneomgr. Enter the directory:

cd libykneomgr

Recent versions of autoconf, automake and libtool must be installed. Libzip is required by the library. Help2man is used to generate the manpages. GTK-DOC is used to generated API documentation. Gengetopt is needed for command line parameter handling.

Debian/Ubuntu:   apt-get install build-essential autoconf automake libtool
Debian/Ubuntu:   apt-get install gtk-doc-tools gengetopt help2man
Debian/Ubuntu:   apt-get install libpcsclite-dev libzip-dev

Build the project using:

make

See cfg.mk for some settings.

Portability

The main development platform is Debian GNU/Linux. The project is cross-compiled to Windows using MinGW (see windows.mk) using the PCSC backend. It may also be built for Mac OS X (see macosx.mk), also using the PCSC backend.

Troubleshooting

If you get a generic error from the library (like YKNEOMGR_BACKEND_ERROR) or "Backend error" from the command line tool, it indicates a problem in the lower-level PCSC backend. On GNU and Mac, check that pcscd is indeed running, and that the command line tool "pcsc_scan" finds your smartcard.

Namespaces

Project short name: libykneomgr
Header files: $prefix/include/ykneomgr/*
Library files: $prefix/lib/libykneomgr*
Library symbol prefix: ykneomgr_
Command line tool: ykneomgr
Pkg-config: ykneomgr