@hexagon/webauthn
new Webauthn(opts)
Creates a FIDO2 server class
Parameters:
opts
(
Object
)
Options for the server
Properties
timeout
(
Number
)
<optional>The amount of time to wait, in milliseconds, before a call has timed out
rpId
(
String
)
<optional>The name of the server
rpName
(
String
)
<optional>The name of the server
challengeSize
(
Number
)
<optional>The number of bytes to use for the challenge
authenticatorSelectionCriteria
(
Object
)
<optional>An object describing what types of authenticators are allowed to register with the service. See AuthenticatorSelectionCriteria 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>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
(static) .addAttestationFormat(fmt, parseFn, validateFn)
Adds a new attestation format that will automatically be recognized and parsed for any future Fido2CreateRequest messages
Parameters:
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)
Adds a new global extension that will be available to all instantiations of Webauthn. Note that the extension must still be enabled by calling enableExtension for each instantiation of a Fido2Lib.
Parameters:
extName
(
String
)
The name of the extension to add. (e.g. - "appid")
optionGeneratorFn
(
function
)
Extensions are included in
resultParserFn
(
function
)
[description]
resultValidatorFn
(
function
)
[description]
(static) .deleteAllAttestationFormats()
Deletes all currently registered attestation formats.
(static) .deleteAllExtensions()
Removes all extensions from the global extension registry. Mostly used for testing.
(async) .assertionOptions(optsopt, extraDataopt) → {Promise.<PublicKeyCredentialRequestOptions>}
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.
Parameters:
opts
(
Object
)
<optional>An object containing various options for the option creation
Properties
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.
(async) .assertionResult(res, expected) → {Promise.<Fido2AssertionResult>}
Parses and validates an assertion response from the client
Parameters:
res
(
Object
)
The assertion result that was generated by the client. See AuthenticatorAssertionResponse in the WebAuthn spec.
Properties
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
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
(async) .attestationOptions(optsopt, extraDataopt) → {Promise.<PublicKeyCredentialCreationOptions>}
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.
Parameters:
opts
(
Object
)
<optional>An object containing various options for the option creation
Properties
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.
(async) .attestationResult(res, expected) → {Promise.<Fido2AttestationResult>}
Parses and validates an attestation response from the client
Parameters:
res
(
Object
)
The assertion result that was generated by the client. See AuthenticatorAttestationResponse in the WebAuthn spec.
Properties
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
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
.disableExtension(extName)
Disables the specified extension.
Parameters:
extName
(
String
)
The name of the extension to enable. Must be a valid extension that has been registered through Fido2Lib#addExtension
.enableExtension(extName)
Enables the specified extension.
Parameters:
extName
(
String
)
The name of the extension to enable. Must be a valid extension that has been registered through Fido2Lib#addExtension
.setExtensionOptions(extName, options)
Specifies the options to be used for the extension
Parameters:
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")