== Yubico Authenticator
The Yubico Authenticator is a graphical desktop tool for generating Open
AuTHentication (OATH) event-based HOTP and time-based TOTP one-time password
codes, with the help of a YubiKey that protects the shared secrets.

image::usage.gif[]

=== Installation
The recommended way to install this software including dependencies is by using
the provided precompiled binaries for your platform. For Windows and OS X (10.7 and above),
there are installers available for download
https://developers.yubico.com/yubioath-desktop/Releases/[here]. For Ubuntu we
have a custom PPA with a package for it
https://launchpad.net/~yubico/+archive/ubuntu/stable[here].

=== Supported devices
Usage of this software requires a compatible YubiKey device. Yubico
Authenticator is capable of provisioning and using both slot-based credentials
(compatible with any YubiKey that supports OTP) as well as the more powerful
standalone OATH functionality of the YubiKey NEO. To use the standalone OATH
functionality your YubiKey must have the CCID mode enabled, which can be done
by using the https://developers.yubico.com/yubikey-neo-manager/[YubiKey NEO
Manager].

==== Detecting the device when using CCID
Under Linux and OS X this application uses libccid to communicate with the
YubiKey. This library requires that each card reader used is listed in its
configuration file, else the device will not be detected ("Insert a YubiKey..."
will be displayed even though a YubiKey is present). To ensure that your
libccid configuration contains all necessary entries you can run one of the two
files locates in the resources directory of this repository, linux-patch-ccid
or osx-patch-ccid, depending on your OS. You will need to run these scripts as
root. If installing the OS X version from the binary installer, this script
will be run automatically for you.

NOTE: You may have to reboot your computer for the change to the libccid
configuration to take effect!

=== Dependencies
Yubico Authenticator requires PySide, yubikey-personalization, pyscard, and
PyCrypto.

=== Building binaries
Binaries for Windows and OSX are built using PyInstaller.

Get the source release file, yubioath-desktop-<version>.tar.gz, and extract it.
It should contain a single directory, henceforth refered to as the release
directory.

When building binaries for Windows or OS X, you will need to include
.dll/.dylib files from the yubikey-personalization project. Create a
subdirectory called "lib" in the release directory. Download the correct binary
release for your architecture from
https://developers.yubico.com/yubikey-personalization/Releases/[here] and
extract the contained .dll/.dylib files to the "lib" directory you created
previously.

==== Windows
For Windows you will need python, PySide, pyscard, PyCrypto, PyInstaller and
Pywin32 installed (32 or 64-bit versions depending on the architecture of the
binary your are building).

To sign the executable you will need signtool.exe (from the Windows SDK) either
copied into the root as well or in a location in your PATH, as well as a
certificate in the Windows certificate store that you wish to sign with.

Run "python setup.py executable" from the main release directory.

With NSIS installed, a Windows installer will be built as well.

==== OSX
For OSX you need python, pyside, pyscard, pycrypto, and pyinstaller installed.
One way to install these dependencies is by using Homebrew and pip:

  brew install python
  brew install pyside
  pip install PyInstaller
  pip install pycrypto
  pip install pyscard

NOTE: Homebrew will build backwards-incompatible binaries, so the resulting
build will not run on an older version of OSX.

Run "python setup.py executable" from the main release directory. This
will create an .app in the dist directory.

Sign the code using codesign:

  codesign -s 'Developer ID Application' dist/Yubico\ Authenticator.app --deep

There is also a project file for use with
http://s.sudre.free.fr/Packaging.html[Packages] located at
`resources/yubioath.pkgproj`. This can be used to create an installer for
distribution, which you should sign prior to distribution:

  packagesbuild resources/osx-installer.pkgproj
  productsign --sign 'Developer ID Installer' dist/Yubico\ Authenticator.pkg \
      dist/yubioath-desktop-mac.pkg

=== Working with the source code repository
To work with the source code repository, if you wish to build your own release
or contribute pull requests, follow these steps to set up your environment. If
you just wish to install the application use the pre-build binaries or the
source release packages. This project is developed on a Debian based system,
other OSes may not be supported for development.

==== Installing the dependencies
Make sure to install the needed dependencies:

  sudo apt-get install python-setuptools python-crypto python-pyscard \
      python-pyside pyside-tools libykpers-1-1 pcscd

==== Check out the code
Run these commands to check out the source code:

  git clone https://github.com/Yubico/yubioath-desktop.git
  cd yubioath-desktop
  git submodule init
  git submodule update

==== Build a source release
To build a source release tar ball, run this command:

  python setup.py sdist

The resulting build will be created in the dist/ subdirectory.

=== License
Yubico Authenticator is licensed under GPLv3+, see COPYING for details.

Entypo pictograms by Daniel Bruce - www.entypo.com