Fido2Lib

Fido2Lib

new Fido2Lib(opts)

Description:

  • Creates a FIDO2 server class

Source:
Parameters:
Name Type Description
opts Object

Options for the server

Properties
Name Type Attributes Default Description
timeout Number <optional>
 60000

The amount of time to wait, in milliseconds, before a call has timed out
rpId String <optional>
 "localhost"

The name of the server
rpName String <optional>
 "Anonymous Service"

The name of the server
rpIcon String <optional>

A URL for the service's icon. Can be a RFC 2397 data URL.
challengeSize Number <optional>
 64

The number of bytes to use for the challenge
authenticatorSelection Object <optional>

An object describing what types of authenticators are allowed to register with the service. See [AuthenticatorSelectionCriteria] https://w3.org/TR/webauthn/#authenticatorSelection in the WebAuthn spec for details.
authenticatorAttachment String <optional>

Indicates whether authenticators should be part of the OS ("platform"), or can be roaming authenticators ("cross-platform")
authenticatorRequireResidentKey Boolean <optional>

Indicates whether authenticators must store the key internally (true) or if they can use a KDF to generate keys
authenticatorUserVerification String <optional>

Indicates whether user verification should be performed. Options are "required", "preferred", or "discouraged".
attestation String <optional>
 "direct"

The preferred attestation type to be used. See [AttestationConveyancePreference]{https://w3.org/TR/webauthn/#enumdef-attestationconveyancepreference} in the WebAuthn spec
cryptoParams Array.<Number> <optional>

A list of COSE algorithm identifiers (e.g. -7) ordered by the preference in which the authenticator should use them.

Methods

(async) assertionOptions(optsopt, extraDataopt) → {Promise.<PublicKeyCredentialRequestOptions>}

Description:

  • Creates an assertion challenge and any other parameters for the navigator.credentials.get() call. The challenge property is an ArrayBuffer and will need to be encoded to be transmitted to the client.

Source:
Parameters:
Name Type Attributes Description
opts Object <optional>

An object containing various options for the option creation

Properties
Name Type Attributes Description
extensionOptions Object <optional>

An object that contains the extensions to enable, and the options to use for each of them. The keys of this object are the names of the extensions (e.g. - "appid"), and the value of each key is the option that will be passed to that extension when it is generating the value to send to the client. This object overrides the extensions that have been set with enableExtension and the options that have been set with setExtensionOptions. If an extension was enabled with enableExtension but it isn't included in this object, the extension won't be sent to the client. Likewise, if an extension was disabled with disableExtension but it is included in this object, it will be sent to the client.
extraData String <optional>

Extra data to be signed by the authenticator during attestation. The challenge will be a hash: SHA256(rawChallenge + extraData) and the rawChallenge will be returned as part of PublicKeyCredentialCreationOptions.
Returns:

The options to be passed to navigator.credentials.get()

Type
Promise.<PublicKeyCredentialRequestOptions>

(async) assertionResult(res, expected) → {Promise.<Fido2AssertionResult>}

Description:

  • Parses and validates an assertion response from the client

Source:
Parameters:
Name Type Description
res Object

The assertion result that was generated by the client. See AuthenticatorAssertionResponse in the WebAuthn spec.

Properties
Name Type Attributes Description
id String <optional>

The base64url encoded id returned by the client
rawId String <optional>

The base64url encoded rawId returned by the client. If res.rawId is missing, res.id will be used instead. If both are missing an error will be thrown.
response.clientDataJSON String

The base64url encoded clientDataJSON returned by the client
response.attestationObject String

The base64url encoded authenticatorData returned by the client
response.signature String

The base64url encoded signature returned by the client
response.userHandle String | null <optional>

The base64url encoded userHandle returned by the client. May be null or an empty string.
expected Object

The expected parameters for the assertion response. If these parameters don't match the recieved values, validation will fail and an error will be thrown.

Properties
Name Type Description
challenge String

The base64url encoded challenge that was sent to the client, as generated by assertionOptions
origin String

The expected origin that the authenticator has signed over. For example, "https://localhost:8443" or "https://webauthn.org"
factor String

Which factor is expected for the assertion. Valid values are "first", "second", or "either". If "first", this requires that the authenticator performed user verification (e.g. - biometric authentication, PIN authentication, etc.). If "second", this requires that the authenticator performed user presence (e.g. - user pressed a button). If "either", then either "first" or "second" is acceptable
publicKey String

A PEM encoded public key that will be used to validate the assertion response signature. This is the public key that was returned for this user during attestationResult
prevCounter Number

The previous value of the signature counter for this authenticator.
userHandle String | null

The expected userHandle, which was the user.id during registration
Throws:

If parsing or validation fails

Type
Error
Returns:

Returns a Promise that resolves to a Fido2AssertionResult

Type
Promise.<Fido2AssertionResult>

(async) attestationOptions(optsopt, extraDataopt) → {Promise.<PublicKeyCredentialCreationOptions>}

Description:

  • Gets a challenge and any other parameters for the navigator.credentials.create() call The challenge property is an ArrayBuffer and will need to be encoded to be transmitted to the client.

Source:
Parameters:
Name Type Attributes Description
opts Object <optional>

An object containing various options for the option creation

Properties
Name Type Attributes Description
extensionOptions Object <optional>

An object that contains the extensions to enable, and the options to use for each of them. The keys of this object are the names of the extensions (e.g. - "appid"), and the value of each key is the option that will be passed to that extension when it is generating the value to send to the client. This object overrides the extensions that have been set with enableExtension and the options that have been set with setExtensionOptions. If an extension was enabled with enableExtension but it isn't included in this object, the extension won't be sent to the client. Likewise, if an extension was disabled with disableExtension but it is included in this object, it will be sent to the client.
extraData String <optional>

Extra data to be signed by the authenticator during attestation. The challenge will be a hash: SHA256(rawChallenge + extraData) and the rawChallenge will be returned as part of PublicKeyCredentialCreationOptions.
Returns:

The options for creating calling navigator.credentials.create()

Type
Promise.<PublicKeyCredentialCreationOptions>

(async) attestationResult(res, expected) → {Promise.<Fido2AttestationResult>}

Description:

  • Parses and validates an attestation response from the client

Source:
Parameters:
Name Type Description
res Object

The assertion result that was generated by the client. See AuthenticatorAttestationResponse in the WebAuthn spec.

Properties
Name Type Attributes Description
id String <optional>

The base64url encoded id returned by the client
rawId String <optional>

The base64url encoded rawId returned by the client. If res.rawId is missing, res.id will be used instead. If both are missing an error will be thrown.
response.clientDataJSON String

The base64url encoded clientDataJSON returned by the client
response.authenticatorData String

The base64url encoded authenticatorData returned by the client
expected Object

The expected parameters for the assertion response. If these parameters don't match the recieved values, validation will fail and an error will be thrown.

Properties
Name Type Description
challenge String

The base64url encoded challenge that was sent to the client, as generated by assertionOptions
origin String

The expected origin that the authenticator has signed over. For example, "https://localhost:8443" or "https://webauthn.org"
factor String

Which factor is expected for the assertion. Valid values are "first", "second", or "either". If "first", this requires that the authenticator performed user verification (e.g. - biometric authentication, PIN authentication, etc.). If "second", this requires that the authenticator performed user presence (e.g. - user pressed a button). If "either", then either "first" or "second" is acceptable
Throws:

If parsing or validation fails

Type
Error
Returns:

Returns a Promise that resolves to a Fido2AttestationResult

Type
Promise.<Fido2AttestationResult>

disableExtension(extName)

Description:

  • Disables the specified extension.

Source:
Parameters:
Name Type Description
extName String

The name of the extension to enable. Must be a valid extension that has been registered through Fido2Lib#addExtension

enableExtension(extName)

Description:

  • Enables the specified extension.

Source:
Parameters:
Name Type Description
extName String

The name of the extension to enable. Must be a valid extension that has been registered through Fido2Lib#addExtension

setExtensionOptions(extName, options)

Description:

  • Specifies the options to be used for the extension

Source:
Parameters:
Name Type Description
extName String

The name of the extension to set the options for (e.g. - "appid". Must be a valid extension that has been registered through Fido2Lib#addExtension
options Any

The parameter that will be passed to the option generator function (e.g. - "https://webauthn.org")

(static) addAttestationFormat(fmt, parseFn, validateFn)

Description:

  • Adds a new attestation format that will automatically be recognized and parsed for any future Fido2CreateRequest messages

Source:
Parameters:
Name Type Description
fmt String

The name of the attestation format, as it appears in the ARIN registry and / or as it will appear in the Fido2CreateRequest message that is received
parseFn function

The function that will be called to parse the attestation format. It will receive the attStmt as a parameter and will be called from the context (this) of the Fido2CreateRequest
validateFn function

The function that will be called to validate the attestation format. It will receive no arguments, as all the necessary information for validating the attestation statement will be contained in the calling context (this).

(static) addExtension(extName, optionGeneratorFn, resultParserFn, resultValidatorFn)

Description:

  • Adds a new global extension that will be available to all instantiations of Fido2Lib. Note that the extension must still be enabled by calling enableExtension for each instantiation of a Fido2Lib.

Source:
Parameters:
Name Type Description
extName String

The name of the extension to add. (e.g. - "appid")
optionGeneratorFn function

Extensions are included in
resultParserFn function

[description]
resultValidatorFn function

[description]

(async, static) addMdsCollection(mdsCollection)

Description:

  • Adds a new MdsCollection to the global MDS collection list that will be used for findMdsEntry

Source:
See:
Parameters:
Name Type Description
mdsCollection MdsCollection

The MDS collection that will be used

(static) clearMdsCollections()

Description:

  • Removes all entries from the global MDS collections list. Mostly used for testing.

Source:

(static) createMdsCollection(collectionName) → {MdsCollection}

Description:
Source:
See:
Parameters:
Name Type Description
collectionName String

The name of the collection to create. Used to identify the source of a MdsEntry when Fido2Lib#findMdsEntry finds multiple matching entries from different sources (e.g. FIDO MDS 1 & FIDO MDS 2)
Returns:

The MdsCollection that was created

Type
MdsCollection

(static) deleteAllAttestationFormats()

Description:

  • Deletes all currently registered attestation formats.

Source:

(static) deleteAllExtensions()

Description:

  • Removes all extensions from the global extension registry. Mostly used for testing.

Source:

(static) findMdsEntry(id) → {Array.<MdsEntry>}

Description:

  • Returns MdsEntry objects that match the requested id. The lookup is done by calling MdsCollection#findEntry on the current global MDS collection. If no global MDS collection has been specified using setMdsCollection, an Error will be thrown.

Source:
See:
Parameters:
Name Type Description
id String | ArrayBuffer

The authenticator id to look up metadata for
Returns:

Returns an Array of MdsEntry for the specified id. If no entry was found, the Array will be empty.

Type
Array.<MdsEntry>