Awesome
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.