NAME

       Authen::U2F::Tester - FIDO/U2F Authentication Test Client

VERSION

       version 0.03

SYNOPSIS

        my $tester = Authen::U2F::Tester->new(
            cert_file => $certfile,
            key_file  => $keyfile);

        #
        # Test a U2F registration
        #
        my $app_id = 'https://www.example.com';
        my $challenge = Authen::U2F->challenge;

        my $r = $tester->register($app_id, $challenge);

        unless ($r->is_success) {
            die $r->error_message;
        }

        print $res->client_data;
        print $res->registration_data;

        # the fields in $res can be used to verify the registration using
        # Authen::U2F
        my ($handle, $key) = Authen::U2F->registration_verify(
            challenge         => $challenge,
            app_id            => $app_id,
            origin            => $origin,
            registration_data => $res->registration_data,
            client_data       => $res->client_data);

        #
        # Test a U2F Signing request
        #
        $r = $tester->sign($app_id, $challenge, $handle);

        unless ($r->is_success) {
            die $r->error_message;
        }

        print $res->client_data;
        print $res->signature_data;

        # verify the signing request with Authen::U2F
        Authen::U2F->signature_verify(
            challenge      => $challenge,
            app_id         => $app_id,
            origin         => $app_id,
            key_handle     => $handle,
            key            => $key,
            signature_data => $r->signature_data,
            client_data    => $r->client_data);

DESCRIPTION

       This module implements a FIDO/U2F tester that can be used for testing web applications
       that support FIDO/U2F.  Think of this module as a "virtual" U2F security key.

METHODS

   new(%args)
       Constructor.

       The following arguments are required:

       •   key_file

           The location of the private key file.

       •   cert_file

           The location of the "X.509" certificate file.

       Alternatively, the key and certificate can be passed in directly as objects:

       •   key

           An Crypt::PK::ECC object.

       •   certificate

           An Crypt::OpenSSL::X509 object.

       In order to create and use the tester, you will need both an Elliptic Curve key, and a SSL
       X.509 certificate.  The key can be generated using OpenSSL:

        % openssl ecparam -name secp256r1 -genkey -noout -out key.pem

       Then this key can be used to generate a self signed X.509 certificate:

        % openssl req -key key.pem -x509 -days 3560 -sha256 \
            -subj '/C=US/ST=Texas/O=Untrusted U2F Org/CN=virtual-u2f' \
            -out cert.pem

       Note that this key is also used to encrypt key handles that the tester generates for
       registration requests.

   key(): Crypt::PK::ECC
       Get the key for this tester.

   keystore(): Authen::U2F::Tester::Role::Keystore
       This returns the key store instance that the tester uses.  The default key store is a
       "wrapped" key store as described in the FIDO/U2F specs.  What this means is it does not
       actually store anything, but instead encrypts the private key using the tester's private
       key, and returns that as the key handle. This key store will accept any encrypted private
       key as a valid key handle so long as it can be decrypted by the tester's private key.
       This is similar to how many physical U2F devices work in the real world.  See
       Authen::U2F::Tester::Keystore::Wrapped for more information.

   certificate(): Crypt::OpenSSL::X509
       Get the SSL certificate that this tester uses.

   register($app_id, $challenge, @keyhandles): Authen::U2F::Tester::RegisterResponse
       Complete a registration request.

       Returns a Authen::U2F::Tester::RegisterResponse on success, or an Authen::U2F::Error
       object on failure.

       Arguments are:

       •   app_id: string

           The application id

       •   challenge: string

           The challenge parameter, in Base64 URL encoded format

       •   keyhandles: list (optional)

           List of already registered keyhandles for the current user, in Base64 URL format.

       Example:

        my $app_id = 'https://www.example.com';
        my $challenge = Authen::U2F->challenge;

        my $res = $tester->register($app_id, $challenge);

        unless ($res->is_success) {
            die $res->error_message;
        }

   sign($app_id, $challenge, @keyhandles)
       Complete a U2F signing request.  Returns a Authen::U2F::Tester::SignResponse object on
       success, Authen::U2F::Error object otherwise.

       Arguments are:

       •   app_id

           The appId value

       •   challenge

           The challenge parameter, in Base64 URL encoded format

       •   keyhandles

           List of possible keyhandles, in Base64 URL encoded format

       Example:

        my $app_id = 'https://www.example.com';
        my $challenge = Authen::U2F->challenge;

        my $res = $tester->sign($app_id, $challenge, $keyhandle);

        unless ($res->is_success) {
            die $res->error_message;
        }

        # signature and client data, which should be sent to relaying party for
        # verification.
        print $res->signature_data;
        print $res->client_data;

SOURCE

       The development version is on github at
       <http://https://github.com/mschout/perl-authen-u2f-tester> and may be cloned from
       <git://https://github.com/mschout/perl-authen-u2f-tester.git>

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/mschout/perl-authen-u2f-tester/issues>

       When submitting a bug or request, please include a test-file or a patch to an existing
       test-file that illustrates the bug or desired feature.

AUTHOR

       Michael Schout <mschout@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2017 by Michael Schout.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.