Nightmarish Pawnshop Mystic

    @dannymoerkerke/fido2-lib

    2.4.1 • Public • Published

    Build Status Coverage Status Known Vulnerabilities

    Install

    npm install fido2-lib

    Overview

    A library for performing FIDO 2.0 / WebAuthn server functionality

    This library contains all the functionality necessary for implementing a full FIDO2 / WebAuthn server. It intentionally does not implement any kind of networking protocol (e.g. - REST endpoints) so that it can remain independent of any messaging protocols.

    There are four primary functions:

    1. attestationOptions - creates the challenge that will be sent to the client (e.g. - browser) for the credential create call. Note that the library does not keep track of sessions or context, so the caller is expected to associate the resulting challenge with a session so that it can be appropriately matched with a response.
    2. attestationResult - parses and validates the response from the client
    3. assertionOptions - creates the challenge that will be sent to the client for credential assertion.
    4. assertionResult - parses and validates the response from the client

    There is also an extension point for adding new attestation formats.

    Full documentation can be found here.

    For working examples see fido2-server-demo and / or webauthn.org

    Features

    • Works with Windows Hello
    • Attestation formats: packed, tpm, android-safetynet, fido-u2f, none
    • Convenient API for adding more attestation formats
    • Convenient API for adding extensions
    • Metadata service (MDS) support enables authenticator root of trust and authenticator metadata
    • Support for multiple simultaneous metadata services (e.g. FIDO MDS 1 & 2)
    • Crypto families: ECDSA, RSA
    • x509 cert parsing, support for FIDO-related extensions, and NIST Public Key Interoperability Test Suite (PKITS) chain validation (from pki.js)
    • Returns parsed and validated data, along with extra audit data for risk engines

    Example

    Instantiate Library (Simple):

    const { Fido2Lib } = require("fido2-lib");
     
    // create a new instance of the library
    var f2l = new Fido2Lib();

    Instantiate Library (Complex):

    // could also use one or more of the options below,
    // which just makes the options calls easier later on:
    var f2l = new Fido2Lib({
        timeout: 42,
        rpId: "example.com",
        rpName: "ACME",
        rpIcon: "https://example.com/logo.png",
        challengeSize: 128,
        attestation: "none",
        cryptoParams: [-7, -257],
        authenticatorAttachment: "platform",
        authenticatorRequireResidentKey: false,
        authenticatorUserVerification: "required"
    });

    Registration:

    var registrationOptions = await f2l.attestationOptions();
     
    // make sure to add registrationOptions.user.id
    // save the challenge in the session information...
    // send registrationOptions to client and pass them in to `navigator.credentials.create()`...
    // get response back from client (clientAttestationResponse)
     
    var attestationExpectations = {
        challenge: "33EHav-jZ1v9qwH783aU-j0ARx6r5o-YHh-wd7C6jPbd7Wh6ytbIZosIIACehwf9-s6hXhySHO-HHUjEwZS29w",
        origin: "https://localhost:8443",
        factor: "either"
    };
    var regResult = await f2l.attestationResult(clientAttestationResponse, attestationExpectations); // will throw on error
     
    // registration complete!
    // save publicKey and counter from regResult to user's info for future authentication calls

    Authentication:

    var authnOptions = await f2l.assertionOptions();
     
    // save the challenge in the session information...
    // send authnOptions to client and pass them in to `navigator.credentials.get()`...
    // get response back from client (clientAssertionResponse)
     
    var assertionExpectations = {
        challenge: "eaTyUNnyPDDdK8SNEgTEUvz1Q8dylkjjTimYd5X7QAo-F8_Z1lsJi3BilUpFZHkICNDWY8r9ivnTgW7-XZC3qQ",
        origin: "https://localhost:8443",
        factor: "either",
        publicKey: "-----BEGIN PUBLIC KEY-----\n" +
            "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAERez9aO2wBAWO54MuGbEqSdWahSnG\n" +
            "MAg35BCNkaE3j8Q+O/ZhhKqTeIKm7El70EG6ejt4sg1ZaoQ5ELg8k3ywTg==\n" +
            "-----END PUBLIC KEY-----\n",
        prevCounter: 362
    };
    var authnResult = await f2l.attestationResult(clientAssertionResponse, assertionExpectations); // will throw on error
     
    // authentication complete!

    For a real-life example, refer to component-fido2.

    Sponsor

    Note that while I used to be Technical Director for FIDO Alliance (and I am currently the Technical Advisor for FIDO Alliance), THIS PROJECT IS NOT ENDORSED OR SPONSORED BY FIDO ALLIANCE.

    Work for this project is supported by my consulting company: WebAuthn Consulting.

    Install

    npm i @dannymoerkerke/fido2-lib

    DownloadsWeekly Downloads

    9

    Version

    2.4.1

    License

    MIT

    Unpacked Size

    421 kB

    Total Files

    36

    Last publish

    Collaborators

    • dannymoerkerke