README

== u2flib-server
Provides functionality for working with the server side aspects of the U2F
protocol as defined in the link:http://fidoalliance.org/specifications/download[FIDO specifications].
It supports Python 2.6-2.7, Python 3.3+ and PyPy 2.6+.

To read more about U2F and how to use a U2F library, visit
link:http://developers.yubico.com/U2F[developers.yubico.com/U2F].

=== Dependencies
u2flib-server depends on link:https://pypi.python.org/pypi/cryptography[cryptography],
which requires libffi, OpenSSL, and a C compiler to build.
On a Debian or Ubuntu system, the build dependencies can be installed with
the following command: 

  $ sudo apt-get install build-essential libssl-dev libffi-dev python-dev

For Windows the cryptography project provides prebuilt wheels.
For other platforms refer to link:https://cryptography.io/en/stable/installation/[cryptography installation].

=== Installation
u2flib-server is installable by running the following command:

  $ pip install python-u2flib-server

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

  git clone https://github.com/Yubico/python-u2flib-server.git
  cd python-u2flib-server
  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.

=== Example
See examples/u2f_server.py for a working example of a HTTP server for
U2F enrollment and authentication. u2f_server.py can be run as a stand-alone
server, and can be used to test a U2F client implementation, such as
python-u2flib-host, using for example cURL.

The examples below show cURL command to register a U2F device, and to
authenticate it.

==== Registration
Registration is initiated by sending a request to the server:

----
$ curl http://localhost:8081/enroll
{"authenticateRequests": [], "registerRequests": [{"challenge": "9s80ruHc6q9shJM5WLfOmz-ejb_Rm8dmWCnOvgZ2ovw", "version": "U2F_V2", "appId": "http://localhost:8081"}]}
----
The RegisterRequest data is then fed to the U2F client, resulting in the
RegisterResponse data, which is passed back to the server:
----
$ curl http://localhost:8081/bind -d'data={"clientData": "eyJvcmlnaW4iOiAiaHR0cDovL2xvY2FsaG9zdDo4MDgxIiwgImNoYWxsZW5nZSI6ICJEMnB6VFBaYTdicTY5QUJ1aUdRSUxvOXpjc1RVUlAyNlJMaWZUeUNraWxjIiwgInR5cCI6ICJuYXZpZ2F0b3IuaWQuZmluaXNoRW5yb2xsbWVudCJ9", "registrationData": "BQSivQtJ6-lAgZ2qQ0aUGLEiJSRoLWUSGcmMO8C-GuibA0-xTvmuQfTqKyFJZWOUjGzEIgF4xV6gJ6itcagsyuUWQEQh9noDSu-WtzTOMhK_lKHxwHtQgJHCkzs4mukfpf310K5Dq9k6zBNtZ2RMBWgJhI7hJo4JiFn3k2GUNLwKZpwwggGHMIIBLqADAgECAgkAmb7osQyi7BwwCQYHKoZIzj0EATAhMR8wHQYDVQQDDBZZdWJpY28gVTJGIFNvZnQgRGV2aWNlMB4XDTEzMDcxNzE0MjEwM1oXDTE2MDcxNjE0MjEwM1owITEfMB0GA1UEAwwWWXViaWNvIFUyRiBTb2Z0IERldmljZTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABDvhl91zfpg9n7DeCedcQ8gGXUnemiXoi-JEAxz-EIhkVsMPAyzhtJZ4V3CqMZ-MOUgICt2aMxacMX9cIa8dgS2jUDBOMB0GA1UdDgQWBBQNqL-TV04iaO6mS5tjGE6ShfexnjAfBgNVHSMEGDAWgBQNqL-TV04iaO6mS5tjGE6ShfexnjAMBgNVHRMEBTADAQH_MAkGByqGSM49BAEDSAAwRQIgXJWZdbvOWdhVaG7IJtn44o21Kmi8EHsDk4cAfnZ0r38CIQD6ZPi3Pl4lXxbY7BXFyrpkiOvCpdyNdLLYbSTbvIBQOTBFAiEA1uwJKNez6_BHdA2d-DPmRFJj19biYNkhN86SFH5Z_lYCICld2L3ZAVsm_uNFRt13_N9dlhGu50pb1ql8-_3_p5v1"}'
true
----
The result, "true", indicates that registration was successful.

==== Authentication
Authentication for a previously registered U2F device is done by sending a
request to the server:

----
$ curl http://localhost:8081/sign
{"authenticateRequests": [{"challenge": "EHuxwx0Ayh5F8g7sFmSUFdfY945EWWK4hyhOKivjv7g", "version": "U2F_V2", "keyHandle": "bxXoPvBA6WPHbqGMjrGBDclMXh8O_qqPXGBPlAkmuIh8CO3ttWWLDzX27xGzemMBxpI6kQXKgURztp9sqEBrCA", "appId": "http://localhost:8081"}]}
----
The AuthenticateRequest data is then fed to the U2F client, resulting in an
AuthenticateResponse object which is passed back to the server:
----
$ curl http://localhost:8081/verify -d'data={"clientData": "eyJvcmlHR0cDovL2xvY2FsaG9zdDo4MDgxIiwgImNoYWxsZW5nZSI6ICJlNGtScWk3eTdmUHdtZGZ1RnJ5WkxyVUhYby1BdF91YUFwWHdxdkV2UmxzIiwgInR5cCI6ICJuYXZpZ2F0b3IuaWQuZ2V0QXNzZXJ0aW9uIn0", "challenge": "e4kRqi7y7fPwmdfuFryZLrUHXo-At_uaApXwqvEvRls", "keyHandle": "RCH2egNK75a3NM4yEr-UofHAe1CAkcKTOzia6R-l_fXQrkOr2TrME21nZEwFaAmEjuEmjgmIWfeTYZQ0vApmnA", "signatureData": "AQAAAAIwRQIhAIyr0y4xg-pI8NhAUHJmaluGXwZ7yd5i0e7FQE4l9OaEAiB68JP-df7ro8ohxCcgyxfRiKrsY1J67kLcEuYb0MCrDg"}'
{"touch": "\u0001", "counter": 2}
----
The response indicates success, giving the U2F devices internal counter value,
as well as the value of the user presence parameter.