.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Authen::U2F::Tester 3pm"
.TH Authen::U2F::Tester 3pm "2018-04-12" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::U2F::Tester \- FIDO/U2F Authentication Test Client
.SH "VERSION"
.IX Header "VERSION"
version 0.03
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& my $tester = Authen::U2F::Tester\->new(
\&     cert_file => $certfile,
\&     key_file  => $keyfile);
\&
\& #
\& # Test a U2F registration
\& #
\& my $app_id = \*(Aqhttps://www.example.com\*(Aq;
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a \s-1FIDO/U2F\s0 tester that can be used for testing web
applications that support \s-1FIDO/U2F.\s0  Think of this module as a \*(L"virtual\*(R" U2F
security key.
.SH "METHODS"
.IX Header "METHODS"
.SS "new(%args)"
.IX Subsection "new(%args)"
Constructor.
.PP
The following arguments are required:
.IP "\(bu" 4
key_file
.Sp
The location of the private key file.
.IP "\(bu" 4
cert_file
.Sp
The location of the \f(CW\*(C`X.509\*(C'\fR certificate file.
.PP
Alternatively, the key and certificate can be passed in directly as objects:
.IP "\(bu" 4
key
.Sp
An Crypt::PK::ECC object.
.IP "\(bu" 4
certificate
.Sp
An Crypt::OpenSSL::X509 object.
.PP
In order to create and use the tester, you will need both an Elliptic Curve
key, and a \s-1SSL X.509\s0 certificate.  The key can be generated using OpenSSL:
.PP
.Vb 1
\& % openssl ecparam \-name secp256r1 \-genkey \-noout \-out key.pem
.Ve
.PP
Then this key can be used to generate a self signed X.509 certificate:
.PP
.Vb 3
\& % openssl req \-key key.pem \-x509 \-days 3560 \-sha256 \e
\&     \-subj \*(Aq/C=US/ST=Texas/O=Untrusted U2F Org/CN=virtual\-u2f\*(Aq \e
\&     \-out cert.pem
.Ve
.PP
Note that this key is also used to encrypt key handles that the tester
generates for registration requests.
.SS "\fIkey()\fP: Crypt::PK::ECC"
.IX Subsection "key(): Crypt::PK::ECC"
Get the key for this tester.
.SS "\fIkeystore()\fP: Authen::U2F::Tester::Role::Keystore"
.IX Subsection "keystore(): Authen::U2F::Tester::Role::Keystore"
This returns the key store instance that the tester uses.  The default key
store is a \*(L"wrapped\*(R" key store as described in the \s-1FIDO/U2F\s0 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.
.SS "\fIcertificate()\fP: Crypt::OpenSSL::X509"
.IX Subsection "certificate(): Crypt::OpenSSL::X509"
Get the \s-1SSL\s0 certificate that this tester uses.
.ie n .SS "register($app_id, $challenge, @keyhandles): Authen::U2F::Tester::RegisterResponse"
.el .SS "register($app_id, \f(CW$challenge\fP, \f(CW@keyhandles\fP): Authen::U2F::Tester::RegisterResponse"
.IX Subsection "register($app_id, $challenge, @keyhandles): Authen::U2F::Tester::RegisterResponse"
Complete a registration request.
.PP
Returns a Authen::U2F::Tester::RegisterResponse on success, or an
Authen::U2F::Error object on failure.
.PP
Arguments are:
.IP "\(bu" 4
app_id: string
.Sp
The application id
.IP "\(bu" 4
challenge: string
.Sp
The challenge parameter, in Base64 \s-1URL\s0 encoded format
.IP "\(bu" 4
keyhandles: list (optional)
.Sp
List of already registered keyhandles for the current user, in Base64 \s-1URL\s0 format.
.PP
Example:
.PP
.Vb 2
\& my $app_id = \*(Aqhttps://www.example.com\*(Aq;
\& my $challenge = Authen::U2F\->challenge;
\&
\& my $res = $tester\->register($app_id, $challenge);
\&
\& unless ($res\->is_success) {
\&     die $res\->error_message;
\& }
.Ve
.ie n .SS "sign($app_id, $challenge, @keyhandles)"
.el .SS "sign($app_id, \f(CW$challenge\fP, \f(CW@keyhandles\fP)"
.IX Subsection "sign($app_id, $challenge, @keyhandles)"
Complete a U2F signing request.  Returns a Authen::U2F::Tester::SignResponse
object on success, Authen::U2F::Error object otherwise.
.PP
Arguments are:
.IP "\(bu" 4
app_id
.Sp
The appId value
.IP "\(bu" 4
challenge
.Sp
The challenge parameter, in Base64 \s-1URL\s0 encoded format
.IP "\(bu" 4
keyhandles
.Sp
List of possible keyhandles, in Base64 \s-1URL\s0 encoded format
.PP
Example:
.PP
.Vb 2
\& my $app_id = \*(Aqhttps://www.example.com\*(Aq;
\& 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;
.Ve
.SH "SOURCE"
.IX Header "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>
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests on the bugtracker website
<https://github.com/mschout/perl\-authen\-u2f\-tester/issues>
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Schout <mschout@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Michael Schout.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.