Provided by: libauthen-webauthn-perl_0.002-1_all 
NAME
Authen::WebAuthn - A library to add Web Authentication support to server applications
VERSION
version 0.002
SYNOPSIS
This module lets you validate Web Authentication <https://www.w3.org/TR/webauthn/>
registration and authentication responses.
Currently, it does not handle the generation of registration and authentication requests.
The transmission of requests and responses from the application server to the user's
browser, and interaction with the WebAuthn browser API is also out of scope and could be
handled by a dedicated JS library.
To register a new device:
# Obtain registration response from web browser
# Then,
my $webauthn_rp = Authen::WebAuthn->new(
rp_id => "app.example.com",
origin => "https://app.example.com"
);
my $registration_result = eval {
$webauthn_rp->validate_registration(
challenge_b64 => ... ,
requested_uv => ... ,
client_data_json_b64 => ... ,
attestation_object_b64 => ... ,
token_binding_id_b64 => ... ,
)
};
if ($@) {
die "Error validating registration: $@";
}
To authenticate a user:
# Obtain authentication response from web browser
# Then,
my $webauthn_rp = Authen::WebAuthn->new(
rp_id => "app.example.com",
origin => "https://app.example.com"
);
my $validation_result = eval {
$webauthn_rp->validate_assertion(
challenge_b64 => ...,
credential_pubkey_b64 => ...,
stored_sign_count => ...,
requested_uv => ...,
client_data_json_b64 => ...,
authenticator_data_b64 => ...,
signature_b64 => ...,
extension_results => ...,
token_binding_id_b64 => ...,
trust_anchors => ...,
)
};
if ($@) {
die "Error validating authentication: $@";
}
ATTRIBUTES
rp_id
The identifier of your Relying Party. Usually, this is set to the domain name over which
your application is accessed (app.example.com).
origin
The origin, as defined by the HTML standard, that your Relying Party is expecting to find
in registration or authentication responses. This must contain the scheme and port of your
application, but no path (http://app.example.com:8080 or https://app.example.com)
METHODS
validate_registration
This method validates the registration response emitted by the authenticator.
It takes the following named arguments
challenge_b64
The base64url-encoded challenge that was submitted to the authenticator
requested_uv
Whether or not the Relying Party required user verification for this operation.
Possible values are "required", "preferred", "discouraged".
client_data_json_b64
The base64url-encoded client data received from the authenticator
attestation_object_b64
The base64url-encoded attestation object received from the authenticator
token_binding_id_b64
The base64url-encoded Token Binding ID for the current connection. Usually this comes
from a "Sec-Provided-Token-Binding-ID" HTTP header. If you are not using Token
Binding, you can omit this parameter.
trust_anchors
If the authenticator response contains an attestation, "validate_registration" will
attempt to chain it to a trusted root certificate. You need to explicitly specify
which certificates to trust if your authenticator provides an attestation.
If you requested "none" as an attestation format while initiating the registration
flow, there is no need to provide any trust anchors.
This optional parameter can either be an arrayref of strings representing PEM-encoded
certificates, or a subref which returns a arrayref of PEM-encoded certificates:
sub {
my (%params) = @_;
my $aaguid = $params{'aaguid'};
my $attestation_type = $params{'attestation_type'};
my $attestation_format = $params{'attestation_format'};
...
return [ $pem1, $pem2, ...];
}
allowed_attestation_types
If you want to restrict the allowed attestation types, you can pass an arrayref of
strings as the "allowed_attestation_types" parameter.
Currently supported values are "None","Self","Basic"
By default, all attestation types are allowed
This method croaks on errors. If the registration was successful, it returns a hashref
with the following subkeys:
credential_id
The base64url-encoded credential ID for this authenticator
credential_pubkey
The base64url-encoded public key for this authenticator, in COSE format
signature_count
The initial signature count of this authenticator
This information is supposed to be persisted in the Relying Party, usually in some sort of
database
The following keys are also returned:
attestation_result
Contains information about the result of the attestation validation
type
The type of attestation used by the authenticator: "None", "Self", "Basic", ...
trust_path
An arrayref of DER-encoded certificates provided by the authenticator
aaguid
The verified AAGUID of the authenticator, this is only provided if the attestation
was verified successfully
validate_assertion
This method validates the registration response emitted by the authenticator.
It takes the following named arguments
challenge_b64
The base64url-encoded challenge that was submitted to the authenticator
credential_pubkey_b64
The base64url-encoded credential public key corresponding to the received Credential
ID
stored_sign_count
The current signature count in the Relying Party's database. Set it to 0 to disable
verification of the signature count
requested_uv
Whether or not the Relying Party required user verification for this operation.
Possible values are "required", "preferred", "discouraged".
client_data_json_b64
The base64url-encoded client data received from the authenticator
authenticator_data_b64
The base64url-encoded authenticator data received from the authenticator
signature_b64
The base64url-encoded signature received from the authenticator
extension_results
A hashref containing extension results received from the authenticator
token_binding_id_b64
The base64url-encoded Token Binding ID for the current connection. Usually this comes
from a "Sec-Provided-Token-Binding-ID" HTTP header. If you are not using Token
Binding, you can omit this parameter.
This method croaks on errors. If the registration was successful, it returns a hashref
with the following subkeys:
signature_count
The new signature count, to be updated in the Relying Party's database
convert_raw_ecc_to_cose
my $cose_b64 = Authen::WebAuthn::convert_raw_ecc_to_cose($u2f_b64);
This method takes the base64url-encoded raw ECC key (U2F format) and converts it to a
base64url-encoded COSE representation. It can be useful for converting existing U2F device
registration to WebAuthen device registrations in your Relying Party.
CAVEAT
This module only supports the "None" attestation type at the moment, which means Relying
Parties cannot have a strong guarantee of the authenticator's security properties. This
makes it possible for users to register weak authenticators.
Because of that, is it not recommended to use this module in passwordless authentication
scenarios. However, it should be good enough for using security keys as a second factor.
This limitation may be addressed in a future version.
SEE ALSO
W3C Web Authentication specification <https://www.w3.org/TR/webauthn/>
FIDO::Raw
A library with a similar purpose, based on Yubico's libfido2
Authen::U2F
A library for adding U2F support to server applications
Crypt::U2F::Server
A library for adding U2F support to server applications, based on Yubico's
libu2f-server
AUTHOR
Maxime Besson <mbesson@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2022 by Maxime Besson.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.