1Authen::U2F::Tester(3)User Contributed Perl DocumentationAuthen::U2F::Tester(3)
2
3
4

NAME

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

VERSION

9       version 0.03
10

SYNOPSIS

12        my $tester = Authen::U2F::Tester->new(
13            cert_file => $certfile,
14            key_file  => $keyfile);
15
16        #
17        # Test a U2F registration
18        #
19        my $app_id = 'https://www.example.com';
20        my $challenge = Authen::U2F->challenge;
21
22        my $r = $tester->register($app_id, $challenge);
23
24        unless ($r->is_success) {
25            die $r->error_message;
26        }
27
28        print $res->client_data;
29        print $res->registration_data;
30
31        # the fields in $res can be used to verify the registration using
32        # Authen::U2F
33        my ($handle, $key) = Authen::U2F->registration_verify(
34            challenge         => $challenge,
35            app_id            => $app_id,
36            origin            => $origin,
37            registration_data => $res->registration_data,
38            client_data       => $res->client_data);
39
40        #
41        # Test a U2F Signing request
42        #
43        $r = $tester->sign($app_id, $challenge, $handle);
44
45        unless ($r->is_success) {
46            die $r->error_message;
47        }
48
49        print $res->client_data;
50        print $res->signature_data;
51
52        # verify the signing request with Authen::U2F
53        Authen::U2F->signature_verify(
54            challenge      => $challenge,
55            app_id         => $app_id,
56            origin         => $app_id,
57            key_handle     => $handle,
58            key            => $key,
59            signature_data => $r->signature_data,
60            client_data    => $r->client_data);
61

DESCRIPTION

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

METHODS

68   new(%args)
69       Constructor.
70
71       The following arguments are required:
72
73       •   key_file
74
75           The location of the private key file.
76
77       •   cert_file
78
79           The location of the "X.509" certificate file.
80
81       Alternatively, the key and certificate can be passed in directly as
82       objects:
83
84       •   key
85
86           An Crypt::PK::ECC object.
87
88       •   certificate
89
90           An Crypt::OpenSSL::X509 object.
91
92       In order to create and use the tester, you will need both an Elliptic
93       Curve key, and a SSL X.509 certificate.  The key can be generated using
94       OpenSSL:
95
96        % openssl ecparam -name secp256r1 -genkey -noout -out key.pem
97
98       Then this key can be used to generate a self signed X.509 certificate:
99
100        % openssl req -key key.pem -x509 -days 3560 -sha256 \
101            -subj '/C=US/ST=Texas/O=Untrusted U2F Org/CN=virtual-u2f' \
102            -out cert.pem
103
104       Note that this key is also used to encrypt key handles that the tester
105       generates for registration requests.
106
107   key(): Crypt::PK::ECC
108       Get the key for this tester.
109
110   keystore(): Authen::U2F::Tester::Role::Keystore
111       This returns the key store instance that the tester uses.  The default
112       key store is a "wrapped" key store as described in the FIDO/U2F specs.
113       What this means is it does not actually store anything, but instead
114       encrypts the private key using the tester's private key, and returns
115       that as the key handle. This key store will accept any encrypted
116       private key as a valid key handle so long as it can be decrypted by the
117       tester's private key.  This is similar to how many physical U2F devices
118       work in the real world.  See Authen::U2F::Tester::Keystore::Wrapped for
119       more information.
120
121   certificate(): Crypt::OpenSSL::X509
122       Get the SSL certificate that this tester uses.
123
124   register($app_id, $challenge, @keyhandles):
125       Authen::U2F::Tester::RegisterResponse
126       Complete a registration request.
127
128       Returns a Authen::U2F::Tester::RegisterResponse on success, or an
129       Authen::U2F::Error object on failure.
130
131       Arguments are:
132
133       •   app_id: string
134
135           The application id
136
137       •   challenge: string
138
139           The challenge parameter, in Base64 URL encoded format
140
141       •   keyhandles: list (optional)
142
143           List of already registered keyhandles for the current user, in
144           Base64 URL format.
145
146       Example:
147
148        my $app_id = 'https://www.example.com';
149        my $challenge = Authen::U2F->challenge;
150
151        my $res = $tester->register($app_id, $challenge);
152
153        unless ($res->is_success) {
154            die $res->error_message;
155        }
156
157   sign($app_id, $challenge, @keyhandles)
158       Complete a U2F signing request.  Returns a
159       Authen::U2F::Tester::SignResponse object on success, Authen::U2F::Error
160       object otherwise.
161
162       Arguments are:
163
164       •   app_id
165
166           The appId value
167
168       •   challenge
169
170           The challenge parameter, in Base64 URL encoded format
171
172       •   keyhandles
173
174           List of possible keyhandles, in Base64 URL encoded format
175
176       Example:
177
178        my $app_id = 'https://www.example.com';
179        my $challenge = Authen::U2F->challenge;
180
181        my $res = $tester->sign($app_id, $challenge, $keyhandle);
182
183        unless ($res->is_success) {
184            die $res->error_message;
185        }
186
187        # signature and client data, which should be sent to relaying party for
188        # verification.
189        print $res->signature_data;
190        print $res->client_data;
191

SOURCE

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

BUGS

199       Please report any bugs or feature requests on the bugtracker website
200       <https://github.com/mschout/perl-authen-u2f-tester/issues>
201
202       When submitting a bug or request, please include a test-file or a patch
203       to an existing test-file that illustrates the bug or desired feature.
204

AUTHOR

206       Michael Schout <mschout@cpan.org>
207

209       This software is copyright (c) 2017 by Michael Schout.
210
211       This is free software; you can redistribute it and/or modify it under
212       the same terms as the Perl 5 programming language system itself.
213
214
215
216perl v5.38.0                      2023-10-25            Authen::U2F::Tester(3)
Impressum