Documentation
¶
Overview ¶
Package webauthn implements the server-side (relying party) parts of WebAuthn used for passkey registration and authentication: ceremony option types, credential wire-format parsing (see the transport subpackage), CBOR attestation-object and authenticator-data parsing with COSE credential-key extraction, and ceremony validation.
Attestation statements are not verified; the package is intended for relying parties that request attestation "none".
Index ¶
- Constants
- Variables
- func NewVerifier(algorithm cose.Algorithm, publicKey crypto.PublicKey) (motmedelCryptoInterfaces.Verifier, error)
- func ValidateAssertionPublicKeyCredential(credential *AssertionPublicKeyCredential, rawClientDataJson []byte, ...) error
- func ValidateAttestationPublicKeyCredential(credential *AttestationPublicKeyCredential, ...) error
- func ValidateAuthenticatorData(authenticatorData *AuthenticatorData, expectedRpId string, ...) error
- func ValidateCollectedClientData(clientData *CollectedClientData, expectedType string, expectedChallenge []byte, ...) error
- type AssertionPublicKeyCredential
- type AttestationObject
- type AttestationPublicKeyCredential
- type AttestedCredentialData
- type AuthenticatorAssertionResponse
- type AuthenticatorAttestationResponse
- type AuthenticatorData
- type AuthenticatorResponse
- type AuthenticatorSelection
- type CollectedClientData
- type PublicKeyCredential
- type PublicKeyCredentialCreationOptions
- type PublicKeyCredentialDescriptor
- type PublicKeyCredentialParam
- type PublicKeyCredentialRequestOptions
- type PublicKeyCredentialUserEntity
- type RelyingParty
Constants ¶
const ( FlagUserPresent byte = 0x01 FlagUserVerified byte = 0x04 FlagBackupEligible byte = 0x08 FlagBackedUp byte = 0x10 FlagAttestedCredentialData byte = 0x40 FlagExtensionData byte = 0x80 )
Authenticator data flag bits (WebAuthn §6.1).
const ( WebauthnCreateType = "webauthn.create" WebauthnGetType = "webauthn.get" ExpectedCredentialType = "public-key" )
Variables ¶
var ( CommonBadRequestErrors = []error{ webauthnErrors.ErrCredentialTypeMismatch, webauthnErrors.ErrCollectedClientDataTypeMismatch, webauthnErrors.ErrChallengeMismatch, webauthnErrors.ErrOriginMismatch, webauthnErrors.ErrRpIdHashMismatch, webauthnErrors.ErrUserNotPresent, webauthnErrors.ErrUserNotVerified, webauthnErrors.ErrUnexpectedSignatureCount, } AttestationBadRequestErrors = []error{ webauthnErrors.ErrPublicKeyAlgorithmMismatch, } AssertionBadRequestErrors = []error{ webauthnErrors.ErrSignatureVerifyFailure, } )
The classification lists group validation errors that are caused by bad client input, for mapping to Bad Request responses.
Functions ¶
func NewVerifier ¶
func NewVerifier( algorithm cose.Algorithm, publicKey crypto.PublicKey, ) (motmedelCryptoInterfaces.Verifier, error)
NewVerifier returns a verifier for WebAuthn assertion signatures produced with the given COSE algorithm and credential public key. ECDSA signatures are expected in the ASN.1 DER encoding WebAuthn uses (not the raw encoding of COSE signatures).
func ValidateAssertionPublicKeyCredential ¶
func ValidateAssertionPublicKeyCredential( credential *AssertionPublicKeyCredential, rawClientDataJson []byte, rawAuthenticatorData []byte, expectedCollectedClientDataChallenge []byte, expectedCollectedClientDataOrigin string, expectedRpId string, previousSignatureCount uint32, verifier motmedelCryptoInterfaces.Verifier, ) error
ValidateAssertionPublicKeyCredential validates an authentication ceremony's credential, including its signature over the raw authenticator data and client data hash.
func ValidateAttestationPublicKeyCredential ¶
func ValidateAttestationPublicKeyCredential( credential *AttestationPublicKeyCredential, expectedCollectedClientDataChallenge []byte, expectedCollectedClientDataOrigin string, expectedRpId string, allowedPublicKeyAlgorithms []cose.Algorithm, ) error
ValidateAttestationPublicKeyCredential validates a registration ceremony's credential. The allowed algorithms are checked against the alg parameter of the COSE credential public key in the attestation object's authenticator data.
func ValidateAuthenticatorData ¶
func ValidateAuthenticatorData( authenticatorData *AuthenticatorData, expectedRpId string, previousSignatureCount uint32, validateAttestedCredential bool, verifyUser bool, ) error
ValidateAuthenticatorData validates authenticator data against the expected relying party id, signature count, and flag requirements.
func ValidateCollectedClientData ¶
func ValidateCollectedClientData( clientData *CollectedClientData, expectedType string, expectedChallenge []byte, expectedOrigin string, ) error
ValidateCollectedClientData validates the client data of a ceremony against the expected type, challenge, and origin.
Types ¶
type AssertionPublicKeyCredential ¶
type AssertionPublicKeyCredential = PublicKeyCredential[AuthenticatorAssertionResponse]
type AttestationObject ¶
type AttestationObject struct {
Format string
AttestationStatement map[any]any
AuthenticatorData *AuthenticatorData
RawAuthenticatorData []byte
}
AttestationObject is a parsed attestation object (WebAuthn §6.5.4). The attestation statement is kept as decoded CBOR without being verified.
func ParseAttestationObject ¶
func ParseAttestationObject(data []byte) (*AttestationObject, error)
ParseAttestationObject parses a CBOR-encoded attestation object and the authenticator data within it.
type AttestationPublicKeyCredential ¶
type AttestationPublicKeyCredential = PublicKeyCredential[AuthenticatorAttestationResponse]
type AttestedCredentialData ¶
type AttestedCredentialData struct {
Aaguid []byte
CredentialId []byte
// PublicKey is the parsed COSE credential public key.
PublicKey crypto.PublicKey
// PublicKeyAlgorithm is the alg parameter of the COSE credential public key, or 0 when the
// key carries none.
PublicKeyAlgorithm cose.Algorithm
// RawPublicKey is the CBOR-encoded COSE_Key exactly as carried in the authenticator data.
RawPublicKey []byte
}
AttestedCredentialData is the attested credential data of a registration ceremony's authenticator data (WebAuthn §6.5.1).
type AuthenticatorAssertionResponse ¶
type AuthenticatorAssertionResponse struct {
ClientDataJson CollectedClientData
AuthenticatorData AuthenticatorData
Signature []byte
UserHandle []byte
}
AuthenticatorAssertionResponse is an authenticator's response to an authentication ceremony (WebAuthn §5.2.2).
func (AuthenticatorAssertionResponse) GetAuthenticatorData ¶
func (a AuthenticatorAssertionResponse) GetAuthenticatorData() *AuthenticatorData
func (AuthenticatorAssertionResponse) GetClientDataJson ¶
func (a AuthenticatorAssertionResponse) GetClientDataJson() *CollectedClientData
type AuthenticatorAttestationResponse ¶
type AuthenticatorAttestationResponse struct {
ClientDataJson CollectedClientData
AttestationObject *AttestationObject
Transports []string
}
AuthenticatorAttestationResponse is an authenticator's response to a registration ceremony (WebAuthn §5.2.1). The authenticator data is the one embedded in the attestation object.
func (AuthenticatorAttestationResponse) GetAuthenticatorData ¶
func (a AuthenticatorAttestationResponse) GetAuthenticatorData() *AuthenticatorData
func (AuthenticatorAttestationResponse) GetClientDataJson ¶
func (a AuthenticatorAttestationResponse) GetClientDataJson() *CollectedClientData
type AuthenticatorData ¶
type AuthenticatorData struct {
RpIdHash []byte
Flags byte
SignCount uint32
AttestedCredential *AttestedCredentialData
Extensions map[any]any
}
AuthenticatorData is parsed authenticator data (WebAuthn §6.1).
func ParseAuthenticatorData ¶
func ParseAuthenticatorData(data []byte) (*AuthenticatorData, error)
ParseAuthenticatorData parses the binary authenticator data format. The embedded COSE credential public key is delimited by CBOR decoding, separating it from any extension data that follows it.
func (*AuthenticatorData) UserPresent ¶
func (a *AuthenticatorData) UserPresent() bool
func (*AuthenticatorData) UserVerified ¶
func (a *AuthenticatorData) UserVerified() bool
type AuthenticatorResponse ¶
type AuthenticatorResponse interface {
GetClientDataJson() *CollectedClientData
GetAuthenticatorData() *AuthenticatorData
}
AuthenticatorResponse is implemented by both authenticator response types.
type AuthenticatorSelection ¶
type AuthenticatorSelection struct {
AuthenticatorAttachment string `json:"authenticatorAttachment,omitzero"`
ResidentKey string `json:"residentKey,omitzero"`
RequireResidentKey bool `json:"requireResidentKey,omitzero"`
}
AuthenticatorSelection restricts which authenticators may take part in a registration ceremony (WebAuthn §5.4.4).
func (*AuthenticatorSelection) MarshalJSON ¶
func (a *AuthenticatorSelection) MarshalJSON() ([]byte, error)
type CollectedClientData ¶
type CollectedClientData struct {
Type string
Challenge []byte
Origin string
CrossOrigin bool
// TopOrigin is not part of the specification, but is sent by clients.
TopOrigin string
}
CollectedClientData is the parsed client data of a ceremony (WebAuthn §5.8.1).
type PublicKeyCredential ¶
type PublicKeyCredential[T AuthenticatorAttestationResponse | AuthenticatorAssertionResponse] struct { Id []byte Type string RawId []byte Response T ClientExtension map[string]any }
PublicKeyCredential is a parsed credential from a navigator.credentials call (WebAuthn §5.1).
type PublicKeyCredentialCreationOptions ¶
type PublicKeyCredentialCreationOptions struct {
RelyingParty *RelyingParty `json:"rp"`
User *PublicKeyCredentialUserEntity `json:"user"`
Challenge []byte `json:"challenge"`
PubKeyCredParams []*PublicKeyCredentialParam `json:"pubKeyCredParams"`
Timeout uint64 `json:"timeout,omitzero"`
ExcludeCredentials []*PublicKeyCredentialDescriptor `json:"excludeCredentials,omitzero"`
AuthenticatorSelection *AuthenticatorSelection `json:"authenticatorSelection,omitzero"`
Attestation string `json:"attestation,omitzero"`
Extensions map[string]any `json:"extensions,omitzero"`
}
PublicKeyCredentialCreationOptions are the options of a registration ceremony (WebAuthn §5.4).
type PublicKeyCredentialDescriptor ¶
type PublicKeyCredentialDescriptor struct {
Id string `json:"id"`
Type string `json:"type"`
Transports []string `json:"transports,omitzero"`
}
PublicKeyCredentialDescriptor identifies an existing credential (WebAuthn §5.8.3).
type PublicKeyCredentialParam ¶
PublicKeyCredentialParam expresses an accepted credential type and COSE algorithm (WebAuthn §5.3).
type PublicKeyCredentialRequestOptions ¶
type PublicKeyCredentialRequestOptions struct {
Challenge []byte `json:"challenge"`
Timeout uint64 `json:"timeout,omitzero"`
RpId string `json:"rpId,omitzero"`
AllowedCredentials []*PublicKeyCredentialDescriptor `json:"allowedCredentials,omitzero"`
UserVerification string `json:"userVerification,omitzero"`
Extensions map[string]any `json:"extensions,omitzero"`
}
PublicKeyCredentialRequestOptions are the options of an authentication ceremony (WebAuthn §5.5).
type PublicKeyCredentialUserEntity ¶
type PublicKeyCredentialUserEntity struct {
Name string `json:"name"`
Id []byte `json:"id"`
DisplayName string `json:"displayName"`
}
PublicKeyCredentialUserEntity identifies the user account a credential is registered to (WebAuthn §5.4.3).
type RelyingParty ¶
RelyingParty identifies the relying party in creation options (WebAuthn §5.4.2).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package transport contains the JSON wire-format counterparts of the webauthn package's domain types, with base64url-encoded binary fields, and the conversions from wire format to parsed domain values.
|
Package transport contains the JSON wire-format counterparts of the webauthn package's domain types, with base64url-encoded binary fields, and the conversions from wire format to parsed domain values. |