Haskell WebAuthn Library

This library implements the server-side Web Authentication Relying Party specification Level 2. The goal of Web Authentication (WebAuthn) is to bring passwordless login/second factor authentication to the web, logging in using a FIDO U2F Security Key, finger print scanner and some other authenticator.

This project was originally developed in 2020 as a Zurihac project by @arianvp and @duijf. Starting September 2021 a team at Tweag was sponsored by Mercury to create a production-ready open-source implementation of this standard, which was done by @infinisil and @ErinvanderVeen.

Setting up the environment

We assume Nix is used for the development of this library. If not using Nix, take a look at default.nix for the dependencies and GHC version. All instructions below assume the use of Nix.

Nix Caches

Tweag provides a Cachix cache for the library itself and all non-Haskell dependencies, setting up the tweag-webauthn cache can be done using the instructions provided by Cachix.

Nix Shell

The Nix shell provides all libraries and tools required to build the library, tests, and example server. Simply call nix-shell to enter a shell. If the binary caches have been configured properly, this should take little time. If they have not been properly configured, entering the Nix shell will take multiple hours.

All further instructions in this README assume that you are in a Nix shell.

Getting Started

To get started with the library it is best to read the documentation of the Crypto.WebAuthn module. An example of how to use this library to implement a relying party can be found in the server directory, particularly the server/src/Main.hs module. Additionally, we highly recommend reading the relying party section of the WebAuthn security considerations chapter before implementing a relying party.

Developing the Library

The Haskell Language Server (hls) and Ormolu are highly recommended for the development of this library. The hls documentation describes how to configure your editor to use it. We also recommend enabling auto-format using Ormolu for your editor. We do, however, also provide a bash script in bin/autoformat.sh that uses Ormolu to format all Haskell source files in the repository.

Code not formatted using Ormolu will be rejected in CI.

Running the tests

Tests are provided in the tests directory. Running these tests is done via cabal:

cabal run test-suite:tests

Running the demo

The library comes with an example implementation for a server that makes use of it, which can be found in the server directory. All dependencies required to build the example server are included in the Nix shell.

cd server
./run.sh

Changes to the server's source files automatically trigger a rebuild of the server.

Testing with an Authenticator

The easiest way to test the server, or your own application, is to use the Chrome WebAuthn development tool. Simply open the Chrome DevTools, click on the three dots in the top right, select "More tools -> WebAuthn", and then enable the virtual environment.

Testing with a physical authenticator is easiest using an Android or iOS phone supporting it, or a dedicated token like a YubiKey or the open-source SoloKey. Testing with a phone requires setting up a certificate for the domain of the relying party as WebAuthn only works via https, with an exception being made for localhost.

Acknowledgements

The test files in tests/responses/ were not created by Tweag, but were instead copied from existing WebAuthn libraries. Notably the .NET and python libraries by the .NET foundation and Duo Labs respectively.

LICENSES

Copyright
  2020 - 2021 Arian van Putten
  2021 -      Tweag I/O

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.