webauthn

package
v1.2.3-fred.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 18, 2022 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package webauthn implements server-side support for the Web Authentication specification.

Refer to https://www.w3.org/TR/webauthn-2/ for details.

Index

Constants

View Source 
const AppIDExtension = "appid"

AppIDExtension is the key for the appid extension. https://www.w3.org/TR/webauthn-2/#sctn-appid-extension.

Variables

This section is empty.

Functions

func CredentialAssertionResponseToProto 

func CredentialAssertionResponseToProto(car *CredentialAssertionResponse) *wantypes.CredentialAssertionResponse

CredentialAssertionResponseToProto converts a CredentialAssertionResponse to its proto counterpart.

func CredentialAssertionToProto 

func CredentialAssertionToProto(assertion *CredentialAssertion) *wantypes.CredentialAssertion

CredentialAssertionToProto converts a CredentialAssertion to its proto counterpart.

func CredentialCreationResponseToProto 

func CredentialCreationResponseToProto(ccr *CredentialCreationResponse) *wantypes.CredentialCreationResponse

CredentialCreationResponseToProto converts a CredentialCreationResponse to its proto counterpart.

func CredentialCreationToProto 

func CredentialCreationToProto(cc *CredentialCreation) *wantypes.CredentialCreation

CredentialCreationToProto converts a CredentialCreation to its proto counterpart.

func U2FKeyToCBOR 

func U2FKeyToCBOR(pubKey *ecdsa.PublicKey) ([]byte, error)

U2FKeyToCBOR transforms a DER-encoded U2F into its CBOR counterpart.

Types

type AuthenticationExtensionsClientOutputs 

type AuthenticationExtensionsClientOutputs struct {
	AppID bool `json:"appid,omitempty"`
}

type AuthenticatorAssertionResponse 

type AuthenticatorAssertionResponse struct {
	AuthenticatorResponse
	AuthenticatorData protocol.URLEncodedBase64 `json:"authenticatorData"`
	Signature         protocol.URLEncodedBase64 `json:"signature"`
	UserHandle        protocol.URLEncodedBase64 `json:"userHandle,omitempty"`
}

type AuthenticatorAttestationResponse 

type AuthenticatorAttestationResponse struct {
	AuthenticatorResponse
	AttestationObject protocol.URLEncodedBase64 `json:"attestationObject"`
}

type AuthenticatorResponse 

type AuthenticatorResponse protocol.AuthenticatorResponse

type Credential 

type Credential protocol.Credential

type CredentialAssertion 

type CredentialAssertion protocol.CredentialAssertion

CredentialAssertion is the payload sent to authenticators to initiate login.

func CredentialAssertionFromProto 

func CredentialAssertionFromProto(assertion *wantypes.CredentialAssertion) *CredentialAssertion

CredentialAssertionFromProto converts a CredentialAssertion proto to its lib counterpart.

func (*CredentialAssertion) Validate 

func (ca *CredentialAssertion) Validate() error

Validate performs client-side validation of CredentialAssertion. It makes sure that data are valid and can be sent to authenticator. This is general purpose validation and authenticator should add its own on top of it, if necessary.

type CredentialAssertionResponse 

type CredentialAssertionResponse struct {
	PublicKeyCredential
	AssertionResponse AuthenticatorAssertionResponse `json:"response"`
}

CredentialAssertionResponse is the reply from authenticators to complete login.

func CredentialAssertionResponseFromProto 

func CredentialAssertionResponseFromProto(car *wantypes.CredentialAssertionResponse) *CredentialAssertionResponse

CredentialAssertionResponseFromProto converts a CredentialAssertionResponse proto to its lib counterpart.

type CredentialCreation 

type CredentialCreation protocol.CredentialCreation

CredentialCreation is the payload sent to authenticators to initiate registration.

func CredentialCreationFromProto 

func CredentialCreationFromProto(cc *wantypes.CredentialCreation) *CredentialCreation

CredentialCreationFromProto converts a CredentialCreation proto to its lib counterpart.

func (*CredentialCreation) RequireResidentKey 

func (cc *CredentialCreation) RequireResidentKey() (bool, error)

RequireResidentKey returns information whether resident key is required or not. It checks ResidentKey and fallbacks to RequireResidentKey.

func (*CredentialCreation) Validate 

func (cc *CredentialCreation) Validate() error

Validate performs client-side validation of CredentialCreation. It makes sure that data are valid and can be sent to authenticator. This is general purpose validation and authenticator should add its own on top of it, if necessary.

type CredentialCreationResponse 

type CredentialCreationResponse struct {
	PublicKeyCredential
	AttestationResponse AuthenticatorAttestationResponse `json:"response"`
}

CredentialCreationResponse is the reply from authenticators to complete registration.

func CredentialCreationResponseFromProto 

func CredentialCreationResponseFromProto(ccr *wantypes.CredentialCreationResponse) *CredentialCreationResponse

CredentialCreationResponseFromProto converts a CredentialCreationResponse proto to its lib counterpart.

type LoginFlow 

type LoginFlow struct {
	U2F      *types.U2F
	Webauthn *types.Webauthn
	// Identity is typically an implementation of the Identity service, ie, an
	// object with access to user, device and MFA storage.
	Identity LoginIdentity
}

LoginFlow represents the WebAuthn login procedure (aka authentication).

The login flow consists of:

  1. Client requests a CredentialAssertion (containing, among other info, a challenge to be signed)
  2. Server runs Begin(), generates a credential assertion.
  3. Client validates the assertion, performs a user presence test (usually by asking the user to touch a secure token), and replies with CredentialAssertionResponse (containing the signed challenge)
  4. Server runs Finish()
  5. If all server-side checks are successful, then login/authentication is complete.

func (*LoginFlow) Begin 

func (f *LoginFlow) Begin(ctx context.Context, user string) (*CredentialAssertion, error)

Begin is the first step of the LoginFlow. The CredentialAssertion created is relayed back to the client, who in turn performs a user presence check and signs the challenge contained within the assertion. As a side effect Begin may assign (and record in storage) a WebAuthn ID for the user.

func (*LoginFlow) Finish 

func (f *LoginFlow) Finish(ctx context.Context, user string, resp *CredentialAssertionResponse) (*types.MFADevice, error)

Finish is the second and last step of the LoginFlow. It returns the MFADevice used to solve the challenge. If login is successful, Finish has the side effect of updating the counter and last used timestamp of the returned device.

type LoginIdentity 

type LoginIdentity interface {
	GetWebauthnLocalAuth(ctx context.Context, user string) (*types.WebauthnLocalAuth, error)

	GetMFADevices(ctx context.Context, user string, withSecrets bool) ([]*types.MFADevice, error)
	UpsertMFADevice(ctx context.Context, user string, d *types.MFADevice) error
	UpsertWebauthnSessionData(ctx context.Context, user, sessionID string, sd *wantypes.SessionData) error
	GetWebauthnSessionData(ctx context.Context, user, sessionID string) (*wantypes.SessionData, error)
	DeleteWebauthnSessionData(ctx context.Context, user, sessionID string) error
}

LoginIdentity represents the subset of Identity methods used by LoginFlow. It exists to better scope LoginFlow's use of Identity and to facilitate testing.

func WithDevices 

func WithDevices(identity LoginIdentity, devs []*types.MFADevice) LoginIdentity

WithDevices returns a LoginIdentity backed by a fixed set of devices. The supplied devices are returned in all GetMFADevices calls.

type PasswordlessFlow 

type PasswordlessFlow struct {
	Webauthn *types.Webauthn
	Identity PasswordlessIdentity
}

PasswordlessFlow provides passwordless authentication.

func (*PasswordlessFlow) Begin 

func (f *PasswordlessFlow) Begin(ctx context.Context) (*CredentialAssertion, error)

Begin is the first step of the passwordless login flow. It works similarly to LoginFlow.Begin, but it doesn't require a Teleport username nor implies a previous password-validation step.

func (*PasswordlessFlow) Finish 

func (f *PasswordlessFlow) Finish(ctx context.Context, resp *CredentialAssertionResponse) (*types.MFADevice, string, error)

Finish is the last step of the passwordless login flow. It works similarly to LoginFlow.Finish, but the user identity is established via the response UserHandle, instead of an explicit Teleport username.

type PasswordlessIdentity 

type PasswordlessIdentity interface {
	GetMFADevices(ctx context.Context, user string, withSecrets bool) ([]*types.MFADevice, error)
	UpsertMFADevice(ctx context.Context, user string, d *types.MFADevice) error

	UpsertGlobalWebauthnSessionData(ctx context.Context, scope, id string, sd *wantypes.SessionData) error
	GetGlobalWebauthnSessionData(ctx context.Context, scope, id string) (*wantypes.SessionData, error)
	DeleteGlobalWebauthnSessionData(ctx context.Context, scope, id string) error
	GetTeleportUserByWebauthnID(ctx context.Context, webID []byte) (string, error)
}

PasswordlessIdentity represents the subset of Identity methods used by PasswordlessFlow.

type PublicKeyCredential 

type PublicKeyCredential struct {
	Credential
	RawID      protocol.URLEncodedBase64              `json:"rawId"`
	Extensions *AuthenticationExtensionsClientOutputs `json:"extensions,omitempty"`
}

type RegisterResponse 

type RegisterResponse struct {
	// User is the device owner.
	User string
	// DeviceName is the name for the new device.
	DeviceName string
	// CreationResponse is the response from the new device.
	CreationResponse *CredentialCreationResponse
	// Passwordless is true if this is expected to be a passwordless registration.
	// Callers may make certain concessions when processing passwordless
	// registration (such as skipping password validation), this flag reflects that.
	// The data stored in the Begin SessionData must match the passwordless flag,
	// otherwise the registration is denied.
	Passwordless bool
}

RegisterResponse represents fields needed to finish registering a new webautn device.

type RegistrationFlow 

type RegistrationFlow struct {
	Webauthn *types.Webauthn
	Identity RegistrationIdentity
}

RegistrationFlow represents the WebAuthn registration ceremony.

Registration consists of:

  1. Client requests a CredentialCreation (containing a challenge and various settings that may constrain allowed authenticators).
  2. Server runs Begin(), generates a credential creation.
  3. Client validates the credential creation, performs a user presence test (usually by asking the user to touch a secure token), and replies with a CredentialCreationResponse (containing the signed challenge and information about the credential and authenticator)
  4. Server runs Finish()
  5. If all server-side checks are successful, then registration is complete and the authenticator may now be used to login.

func (*RegistrationFlow) Begin 

func (f *RegistrationFlow) Begin(ctx context.Context, user string, passwordless bool) (*CredentialCreation, error)

Begin is the first step of the registration ceremony. The CredentialCreation created is relayed back to the client, who in turn performs a user presence check and signs the challenge contained within it. If passwordless is set, then registration asks the authenticator for a resident key. As a side effect Begin may assign (and record in storage) a WebAuthn ID for the user.

func (*RegistrationFlow) Finish 

func (f *RegistrationFlow) Finish(ctx context.Context, req RegisterResponse) (*types.MFADevice, error)

Finish is the second and last step of the registration ceremony. If successful, it returns the created MFADevice. Finish has the side effect or writing the device to storage (using its Identity interface).

type RegistrationIdentity 

type RegistrationIdentity interface {
	UpsertWebauthnLocalAuth(ctx context.Context, user string, wla *types.WebauthnLocalAuth) error
	GetWebauthnLocalAuth(ctx context.Context, user string) (*types.WebauthnLocalAuth, error)
	GetTeleportUserByWebauthnID(ctx context.Context, webID []byte) (string, error)

	GetMFADevices(ctx context.Context, user string, withSecrets bool) ([]*types.MFADevice, error)
	UpsertMFADevice(ctx context.Context, user string, d *types.MFADevice) error
	UpsertWebauthnSessionData(ctx context.Context, user, sessionID string, sd *wantypes.SessionData) error
	GetWebauthnSessionData(ctx context.Context, user, sessionID string) (*wantypes.SessionData, error)
	DeleteWebauthnSessionData(ctx context.Context, user, sessionID string) error
}

RegistrationIdentity represents the subset of Identity methods used by RegistrationFlow.

func WithInMemorySessionData 

func WithInMemorySessionData(identity RegistrationIdentity) RegistrationIdentity

WithInMemorySessionData returns a RegistrationIdentity implementation that keeps SessionData in memory.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.