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/

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

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.

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
