Yubico YubiKey NEO CCID Manager C Library
=========================================

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.
link:https://developers.yubico.com/ykneo-openpgp/SecurityAdvisory%202015-04-14.html[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
...