WARNING:
This project is still in its pre-alpha stage.
Serious refactoring and documentations are needed.



lightu2f.py is a zero-dependency FIDO U2F relying party library
---------------------------------------------------------------

There are two different types of U2F transactions between a U2F Relying Party
and a U2F Client: authenticator enrollment transactions and identity assertion
transactions.

Each transaction consists of a request and a response.  At the perspective of a
U2F Relying Party, a U2F Client, despite its name, works like a "server" since
it provides access to U2F authenticators through a high-level API so that a U2F
Relying Party does not need to worry about low-level device drivers for all
kinds of authenticators in the wild.

This Python module provides 4 functions, which are the core U2F transaction
logic for a U2F Relying Party:

    generate_enrollment_request()
    generate_idassertion_request()
    process_enrollment_response()
    process_idassertion_response()

Below are two diagrams that show how you can use these functions to do your U2F
transactions.



         An Authenticator Enrollment Transaction

   U2F Client                          U2F Relying Party
        |                                      |
        |              enr_request             |
        |<-------------------------------------| generate_enrollment_request()
        |                                      |
        |                                      |
        |------------------------------------->| process_enrollment_response()
        |             enr_response             |
        v                                      v



           An Identity Assertion Transaction

   U2F Client                          U2F Relying Party
        |                                      |
        |              ida_request             |
        |<-------------------------------------| generate_idassertion_request()
        |                                      |
        |                                      |
        |------------------------------------->| process_idassertion_response()
        |             ida_response             |
        v                                      v



Arguments for generate_enrollment_request() and generate_idassertion_request()

    app_id (str)

        This is a unicode string like "https://example.com" that identifies
        yourself.  For the simplest case, this is just the web origin of your
        website.  Check U2F spec for more information on application identity
        if you need to support multiple domains at once.

    transaction_nonce (bytes)

        This is an octet string that is only used once for a transaction.  It
        must be unpredictable.  32 bytes from /dev/urandom should be good for
        example.

    khs (iterable<bytes>)

        This is an enumerable collection that _MUST_ contain zero or more octet
        strings.  Each octet string is a registered key handle of the user you
        are dealing with, and its length _MUST_NOT_ exceed 255.

        A key handle is used to uniquely identify a key pair generated by some
        U2F authenticator.

    kh_pk_cnts (iterable<sequence<bytes, bytes, union<int, NoneType>>>)

        This is an enumerable collection that _MUST_ contain one or more
        unpackable sequences.  Each unpackable sequence _MUST_ unpack to three
        values: (1) a key handle, (2) a public key, and (3) a counter.

            (1) the key handle _MUST_ be an octet string of length 0-255.
            (2) the public key _MUST_ be an octet string of length 65.
            (3) the counter _MUST_ be an integer in range [0, 2**32-1] or None.

        A (kh, pk, cnt) tuple describes all necessary information about a U2F
        authenticator registered by a user.