{"id":19619697,"url":"https://github.com/fxamacker/webauthn","last_synced_at":"2025-04-28T03:31:32.330Z","repository":{"id":45321563,"uuid":"199052989","full_name":"fxamacker/webauthn","owner":"fxamacker","description":"WebAuthn server library decoupled from http for easy intergration, provides WebAuthn registration and authentication for clients using FIDO2 keys, FIDO U2F keys, TPM, etc.","archived":false,"fork":false,"pushed_at":"2020-08-24T01:26:06.000Z","size":298,"stargazers_count":41,"open_issues_count":8,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-06-18T21:41:23.124Z","etag":null,"topics":["authentication","fido-u2f","fido2","go","golang","passwordless","safetynet","security","u2f","webauthn"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fxamacker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["fxamacker"]}},"created_at":"2019-07-26T17:04:47.000Z","updated_at":"2024-01-27T14:28:10.000Z","dependencies_parsed_at":"2022-07-19T03:02:07.511Z","dependency_job_id":null,"html_url":"https://github.com/fxamacker/webauthn","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxamacker%2Fwebauthn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxamacker%2Fwebauthn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxamacker%2Fwebauthn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxamacker%2Fwebauthn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fxamacker","download_url":"https://codeload.github.com/fxamacker/webauthn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224091907,"owners_count":17254152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","fido-u2f","fido2","go","golang","passwordless","safetynet","security","u2f","webauthn"],"created_at":"2024-11-11T11:14:41.568Z","updated_at":"2024-11-11T11:14:42.848Z","avatar_url":"https://github.com/fxamacker.png","language":"Go","funding_links":["https://github.com/sponsors/fxamacker"],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/fxamacker/webauthn.svg?branch=master)](https://travis-ci.com/fxamacker/webauthn)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fxamacker/webauthn)](https://goreportcard.com/report/github.com/fxamacker/webauthn)\n[![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](http://godoc.org/github.com/fxamacker/webauthn)\n[![GitHub](https://img.shields.io/github/license/fxamacker/webauthn)](https://github.com/fxamacker/webauthn/blob/master/LICENSE)\n\n# WebAuthn server library (Go/Golang)\n\nThis [WebAuthn](https://en.wikipedia.org/wiki/WebAuthn) server library provides registration and authentication for clients using FIDO2 keys, FIDO U2F keys, TPM, and etc.\n\n* It's decoupled from `net/http` and doesn't force you to use a framework.  So it's easy to use in existing projects.\n\n* It's modular so you only import the attestation formats you need.  This helps your software avoid bloat.\n\n* Six attestation formats are provided: fidou2f, androidkeystore, androidsafetynet, packed, tpm, and none.\n\n* It doesn't import unreliable packages. It imports [fxamacker/cbor](https://github.com/fxamacker/cbor) because it doesn't crash and it's the most well-tested CBOR library available (v1.5 has 375+ tests and passed 3+ billion execs in coverage-guided fuzzing).\n\nA [demo webapp (webauthn-demo)](https://www.github.com/fxamacker/webauthn-demo) shows how to use this library with a security token like the YubiKey pictured here.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/57072051/68431219-4e066780-0177-11ea-8a3f-5a137cc76cf1.png\" alt=\"Picture of FIDO U2F key\"\u003e\n\u003c/p\u003e\n\n## What's WebAuthn?\nWebAuthn (Web Authentication) is a [W3C web standard](https://www.w3.org/TR/webauthn/) for authenticating users to web-based apps and services.  It's a core component of [FIDO2](https://en.wikipedia.org/wiki/FIDO2_Project), the successor of FIDO U2F legacy protocol.\n\n## Design Goals\nfxamacker/webauthn is designed to be:\n\n* __small and no unreliable imports__ -- only 1 external dependency [fxamacker/cbor](https://www.github.com/fxamacker/cbor)\n* __simple and lightweight__ -- decoupled from `net/http` and is not a framework\n* __modular__ -- 5 separate attestation packages (packed, tpm, androidkeystore, androidsafetynet, and fidou2f), so you only import what you need.\n\n## Status\nIt's functional enough to demo but unit tests need work.  Expired certs embedded in test data can make unit tests to fail.  A temporary workaround is to fake datetime when running unit tests locally until expired test data are replaced.\n\n* __replace expired certs in unit tests__ -- automate replacement of test certs and/or make expiration dates longer\n* __more tests and fuzzing__ -- add more extensive tests and fuzzing like fxamacker/cbor and fxamacker/cbor-fuzz\n* __standards compliance__ -- publish results of standards conformance tests when ready to announce\n\n## Features\n\n* Easy server-side authentication for clients using FIDO2 keys, legacy FIDO U2F keys, and etc.\n* Register credential algorithm for use\n* Register attestation format for use\n* Create new attestation format by implementing AttestationStatement interface\n* Credential algorithms: RS1, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, and ES512\n* Credential public key types: RSA, RSA-PSS, and ECDSA\n* Credential public key curves: P-256, P-384, and P-521\n* Attestation formats: fido-u2f, android-key, android-safetynet, packed, tpm, and none\n* Attestation types: Basic, Self, and None\n\n## System Requirements\n\n* Go 1.12 (or newer)\n* Tested on x86_64 but it should work on other little-endian systems supported by Go.\n\n## Installation \n\n```\ngo get github.com/fxamacker/webauthn\n```\n\n## High-level API\n\nSee [API docs](https://godoc.org/github.com/fxamacker/webauthn).\n\n__Create assertion or attestation options:__\n\nNewAssertionOptions creates [PublicKeyCredentialRequestOptions](https://w3c.github.io/webauthn/#dictionary-assertion-options).  NewAttestationOptions creates [PublicKeyCredentialCreationOptions](https://w3c.github.io/webauthn/#dictionary-makecredentialoptions).  Config represents Relying Party settings used to create those options.  Config is initialized at startup and used throughout the program.  User contains user data for which the Relying Party requests attestation or assertion.\n\n```\nfunc NewAssertionOptions(config *Config, user *User) (*PublicKeyCredentialRequestOptions, error)\nfunc NewAttestationOptions(config *Config, user *User) (*PublicKeyCredentialCreationOptions, error)\n```\n\n__Parse assertion or attestation:__\n\nParseAssertion returns parsed [PublicKeyCredentialAssertion](https://w3c.github.io/webauthn/#iface-pkcredential).  ParseAttestation returns parsed [PublicKeyCredentialAttestation](https://w3c.github.io/webauthn/#iface-pkcredential).\n\n```\nfunc ParseAssertion(r io.Reader) (*PublicKeyCredentialAssertion, error)\nfunc ParseAttestation(r io.Reader) (*PublicKeyCredentialAttestation, error)\n```\n\n__Verify assertion or attestation:__\n\nVerifyAssertion verifies [PublicKeyCredentialAssertion](https://w3c.github.io/webauthn/#iface-pkcredential), returned by ParseAssertion.  AssertionExpectedData contains data needed to [verify an assertion](https://w3c.github.io/webauthn/#sctn-verifying-assertion).  \n\nVerifyAttestation verifies [PublicKeyCredentialAttestation](https://w3c.github.io/webauthn/#iface-pkcredential), returned by ParseAttestation.  AttestationExpectedData contains data needed to [verify an attestation](https://w3c.github.io/webauthn/#sctn-registering-a-new-credential) before registering a new credential.  VerifyAttestation returns [attestation type](https://w3c.github.io/webauthn/#sctn-attestation-types) and [attestation trust path](https://w3c.github.io/webauthn/#attestation-trust-path).  Library users need to assess the attestation trustworthiness by verifying that attestation type is acceptable and trust path can be trusted.\n\n```\nfunc VerifyAssertion(credentialAssertion *PublicKeyCredentialAssertion, expected *AssertionExpectedData) error\nfunc VerifyAttestation(credentialAttestation *PublicKeyCredentialAttestation, expected *AttestationExpectedData) (attType AttestationType, trustPath interface{}, err error)\n```\n\n## Examples\n\nSee [examples](example_test.go).\n\n__Initialize Relying Party config:__\n\n```\n// cfg is initialized at startup and used throughout the program to create attestation and assertion options.  \ncfg := \u0026webauthn.Config{\n    RPID:                    \"localhost\",\n    RPName:                  \"WebAuthn local host\",\n    Timeout:                 uint64(30000),\n    ChallengeLength:         64,\n    AuthenticatorAttachment: webauthn.AuthenticatorPlatform,\n    ResidentKey:             webauthn.ResidentKeyPreferred,\n    UserVerification:        webauthn.UserVerificationPreferred,\n    Attestation:             webauthn.AttestationDirect,\n    CredentialAlgs:          []int{webauthn.COSEAlgES256, webauthn.COSEAlgES384, webauthn.COSEAlgES512},\n}\nerr := cfg.Valid()\nif err != nil {\n    return err\n}\n```\n\n__Create attestation options:__\n\n```\n// user contains user data for which the Relying Party requests attestation or assertion.\nuser := \u0026webauthn.User{\n    ID:          []byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, \n    Name:        \"Jane Doe\",\n    DisplayName: \"Jane\",\n}\ncreationOptions, err := webauthn.NewAttestationOptions(cfg, user)\nif err != nil {\n    return err\n}\ncreationOptionsJSON, err := json.Marshal(creationOptions)\nif err != nil {\n    return err\n}\n// Save user and creationOptions in session to verify attestation later.\n// Send creationOptionsJSON to web client, which passes it to navigator.credentials.create().\n```\n\n__Parse and verify attestation:__\n\n```\n// Parse PublicKeyCredentialAttestation returned by navigator.credentials.create().\ncredentialAttestation, err := webauthn.ParseAttestation(r)\nif err != nil {\n    return err\n}\n// Create AttestationExpectedData object from session's user and creationOptions.\nexpected := \u0026webauthn.AttestationExpectedData{\n    Origin:           \"https://localhost:8443\",\n    RPID:             \"localhost\",\n    CredentialAlgs:   []int{webauthn.COSEAlgES256, webauthn.COSEAlgES384, webauthn.COSEAlgES512},\n    Challenge:        \"33EHav-jZ1v9qwH783aU-j0ARx6r5o-YHh-wd7C6jPbd7Wh6ytbIZosIIACehwf9-s6hXhySHO-HHUjEwZS29w\",\n    UserVerification: webauthn.UserVerificationPreferred,\n}\nattType, trustPath, err := webauthn.VerifyAttestation(credentialAttestation, expected)\nif err != nil {\n    return err\n}\n// Verify that attType is acceptable and trustPath can be trusted.\n// Save user info, credential id, algorithm, public key, and counter to persistent store.\n// User is registered.\n```\n\n__Create assertion options:__\n\n```\n// user contains user data for which the Relying Party requests attestation or assertion.\nuser := \u0026webauthn.User{\n    ID:          []byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, \n    Name:        \"Jane Doe\",\n    DisplayName: \"Jane\",\n    CredentialIDs: [][]byte{\n        []byte{11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26}, \n    },\n}\nrequestOptions, err := webauthn.NewAssertionOptions(cfg, user)\nif err != nil {\n    return err\n}\nrequestOptionsJSON, err := json.Marshal(requestOptions)\nif err != nil {\n    return err\n}\n// Save user and requestOptions in session to verify assertion later.\n// Send requestOptionsJSON to web client, which passes it to navigator.credentials.get().\n```\n\n__Parse and verify assertion:__\n\n```\n// Parse PublicKeyCredentialAssertion returned by navigator.credentials.get().\ncredentialAssertion, err := webauthn.ParseAssertion(r)\nif err != nil {\n    return err\n}\n// Create AssertionExpectedData object from session's user and requestOptions.\nexpected := \u0026webauthn.AssertionExpectedData{\n    Origin:            \"https://localhost:8443\",\n    RPID:              \"localhost\",\n    Challenge:         \"eaTyUNnyPDDdK8SNEgTEUvz1Q8dylkjjTimYd5X7QAo-F8_Z1lsJi3BilUpFZHkICNDWY8r9ivnTgW7-XZC3qQ\",\n    UserVerification:  webauthn.UserVerificationPreferred,\n    UserID:            []byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, \n    UserCredentialIDs: [][]byte{\n        []byte{11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26}, \n    },\n    PrevCounter:       uint32(362),\n    Credential:        credential,\n}\nerr = webauthn.VerifyAssertion(credentialAssertion, expected)\nif err != nil {\n    return err\n}\n// Update counter in persistent store.\n// User is authenticated.\n```\n\n## Limitations\n\nThis library doesn't support:\n\n* Attestation validation through FIDO Metadata Service\n* Extensions\n* Token Binding\n* CA attestation\n* Elliptic Curve Direct Anonymous Attestation (ECDAA)\n\n## Security Policy\n\nSecurity fixes are provided for the latest released version.\n\nTo report security vulnerabilities, please email faye.github@gmail.com and allow time for the problem to be resolved before reporting it to the public.\n\n## Special Thanks\n\n* Montgomery Edwards⁴⁴⁸ [(x448)](https://github.com/x448) for updating README.md and filing helpful issues.\n\n* Ackermann Yuriy [(herrjemand)](https://github.com/herrjemand) for his extensive [tutorials](https://medium.com/@herrjemand) on WebAuthn/FIDO2.  \n\n* Adam Powers [(apowers313)](https://github.com/apowers313) for [fido2-lib](https://github.com/apowers313/fido2-lib) because that pointed me in the direction of separating WebAuthn functionality from any networking protocol.  \n\nThis library uses attestation and assertion test data from both herrjemand and apowers313.\n\n## License\n\nCopyright 2019-present [Faye Amacker](https://github.com/fxamacker)\n\nfxamacker/webauthn is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxamacker%2Fwebauthn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffxamacker%2Fwebauthn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxamacker%2Fwebauthn/lists"}