Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tweag/webauthn

A library for parsing and validating webauthn/fido2 credentials
https://github.com/tweag/webauthn

Last synced: about 2 months ago
JSON representation

A library for parsing and validating webauthn/fido2 credentials

Awesome Lists containing this project

README 

        
# Haskell WebAuthn Library



[![Hackage](https://img.shields.io/hackage/v/webauthn.svg)](https://hackage.haskell.org/package/webauthn)



This library implements the server-side

[Web Authentication Relying Party specification Level 2][spec]. 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](https://wire.engineering/haskell/events/2020/06/18/wire-goes-zurihac.html) by

[@arianvp](https://github.com/arianvp/) and [@duijf](https://github.com/duijf).

Starting September 2021 a team at [Tweag](https://www.tweag.io/) was sponsored

by [Mercury](https://mercury.com/) to create a production-ready open-source

implementation of this standard, which was done by

[@infinisil](https://github.com/infinisil/) and

[@ErinvanderVeen](https://github.com/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][cachix] 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](https://www.w3.org/TR/webauthn-2/#sctn-security-considerations-rp)

of the

[WebAuthn security considerations chapter](https://www.w3.org/TR/webauthn-2/#sctn-security-considerations)

before implementing a relying party.



## Developing the Library

The [Haskell Language Server (hls)][hls] and [Ormolu][ormolu] are highly

recommended for the development of this library. The hls

[documentation][hls-editor] 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:

```bash

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.

```bash

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][yubikey] or the

open-source [SoloKey][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][dotnet] and [python][python] libraries by the .NET foundation and Duo

Labs respectively.



## LICENSES

```text

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.

```



[cache]: https://input-output-hk.github.io/haskell.nix/tutorials/getting-started.html#setting-up-the-binary-cache

[cachix]: https://app.cachix.org/cache/tweag-webauthn

[dotnet]: https://github.com/passwordless-lib/fido2-net-lib

[hls-editor]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor

[hls]: https://github.com/haskell/haskell-language-server

[ormolu]: https://github.com/tweag/ormolu

[python]: https://github.com/duo-labs/py_webauthn

[solokey]: https://solokeys.com/

[spec]: https://www.w3.org/TR/webauthn-2/

[yubikey]: https://www.yubico.com/