# PODNAME: Authen::WebAuthn
# ABSTRACT: A library to add Web Authentication support to server applications

__END__

=pod

=encoding UTF-8

=head1 NAME

Authen::WebAuthn - A library to add Web Authentication support to server applications

=head1 VERSION

version 0.005

=head1 SYNOPSIS

This module lets you validate L<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: $@";
    }

=head1 ATTRIBUTES

=head2 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).

=head2 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)

=head1 METHODS

=head2 validate_registration

This method validates the registration response emitted by the authenticator.

It takes the following named arguments

=over 4

=item challenge_b64

The base64url-encoded challenge that was submitted to the authenticator

=item requested_uv

Whether or not the Relying Party required user verification for this operation.
Possible values are C<required>, C<preferred>, C<discouraged>.

=item client_data_json_b64

The base64url-encoded client data received from the authenticator

=item attestation_object_b64

The base64url-encoded attestation object received from the authenticator

=item token_binding_id_b64

The base64url-encoded Token Binding ID for the current connection. Usually this
comes from a C<Sec-Provided-Token-Binding-ID> HTTP header. If you are not using
Token Binding, you can omit this parameter.

=item trust_anchors

If the authenticator response contains an attestation, C<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, ...];
    }

=item allowed_attestation_types

If you want to restrict the allowed attestation types, you can pass an arrayref of strings as the C<allowed_attestation_types> parameter.

Currently supported values are C<None>,C<Self>,C<Basic>

By default, all attestation types are allowed

=item allow_untrusted_attestation

By default, if an attestation type such as C<Basic> is used by the
authenticator and a correct trust_anchor could not be found, the validation
will fail as mandated by the WebAuthn specification. However, in some cases it
is permitted to allow the registration to proceed, but treat it as C<Self>
attestation.

This setting allows you to successfully validate registration, but change the
type to C<Self> if a trusted certificate was not provided in the
C<trust_anchors> parameter.

=item allow_unknown_attestation_format

By default, if an unimplemented attestation format is encountered, registration
validation will fail.

This setting allows you to successfully validate registration, but change the
attestation type to C<None> if an unimplemented attestation format is
encountered.

=back

This method croaks on errors. If the registration was successful, it returns a hashref with the following subkeys:

=over 4

=item credential_id

The base64url-encoded credential ID for this authenticator

=item credential_pubkey

The base64url-encoded public key for this authenticator, in COSE format

=item signature_count

The initial signature count of this authenticator

=back

This information is supposed to be persisted in the Relying Party, usually in some sort of database

The following keys are also returned:

=over 4

=item attestation_result

Contains information about the result of the attestation validation

=over 4

=item type

The type of attestation used by the authenticator: C<None>, C<Self>, C<Basic>, ...

=item trust_path

An arrayref of DER-encoded certificates provided by the authenticator

=item aaguid

The verified AAGUID of the authenticator, this is only provided if the
attestation was verified successfully and chained up to a trusted root
certificate.

=back

=back

=head2 validate_assertion

This method validates the registration response emitted by the authenticator.

It takes the following named arguments

=over 4

=item challenge_b64

The base64url-encoded challenge that was submitted to the authenticator

=item credential_pubkey_b64

The base64url-encoded credential public key corresponding to the received Credential ID

=item stored_sign_count

The current signature count in the Relying Party's database. Set it to 0 to
disable verification of the signature count

=item requested_uv

Whether or not the Relying Party required user verification for this operation.
Possible values are C<required>, C<preferred>, C<discouraged>.

=item client_data_json_b64

The base64url-encoded client data received from the authenticator

=item authenticator_data_b64

The base64url-encoded authenticator data received from the authenticator

=item signature_b64

The base64url-encoded signature received from the authenticator

=item extension_results

A hashref containing extension results received from the authenticator

=item token_binding_id_b64

The base64url-encoded Token Binding ID for the current connection. Usually this
comes from a C<Sec-Provided-Token-Binding-ID> HTTP header. If you are not using
Token Binding, you can omit this parameter.

=back

This method croaks on errors. If the registration was successful, it returns a
hashref with the following subkeys:

=over 4

=item signature_count

The new signature count, to be updated in the Relying Party's database

=back

=head2 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.

=head1 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.

=head1 SEE ALSO

=over 4

=item L<W3C Web Authentication specification|https://www.w3.org/TR/webauthn/>

=item L<FIDO::Raw>

A library with a similar purpose, based on Yubico's libfido2

=item L<Authen::U2F>

A library for adding U2F support to server applications

=item L<Crypt::U2F::Server>

A library for adding U2F support to server applications, based on Yubico's libu2f-server

=back

=head1 AUTHOR

Maxime Besson <mbesson@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2024 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.

=cut