.\" 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 3pm"
.TH Authen::U2F 3pm "2018-03-30" "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 \- FIDO U2F library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Authen::U2F qw(
\&      u2f_challenge
\&      u2f_registration_verify
\&      u2f_signature_verify);
\&
\&    # Create a challenge to send to the U2F host
\&    my $challenge = u2f_challenge;
\&
\&    # Process a registration response from the U2F host
\&    my ($key_handle, $key) = u2f_registration_verify(
\&      challenge         => $challenge,
\&      app_id            => $app_id,
\&      origin            => $origin,
\&      registration_data => $registration_data,
\&      client_data       => $client_data,
\&    );
\&
\&    # Process a signing (authentication) response from the U2F host
\&    u2f_signature_verify(
\&      challenge      => $challenge,
\&      app_id         => $app_id,
\&      origin         => $origin,
\&      key_handle     => $key_handle,
\&      key            => $key,
\&      signature_data => $signature_data,
\&      client_data    => $client_data,
\&    );
\&
\&    # Or, if you don\*(Aqt like to clutter up your namespace
\&    my $challenge = Authen::U2F\->challenge;
\&    my ($key_handle, $key) = Authen::U2F\->registration_verify(...);
\&    Authen::U2F\->signature_verify(...);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the tools you need to add support for U2F in your
application.
.PP
It's expected that you know the basics of U2F. More information about this can
be found at Yubico <https://www.yubico.com/about/background/fido/> and
\&\s-1FIDO\s0 <https://fidoalliance.org/specifications/overview/>.
.PP
This module does not handle the wire encoding of U2F challenges and response,
as these are different depending on the U2F host you're using and the style of
your application. In the \f(CW\*(C`examples\*(C'\fR dir there are scripts that implement the
1.0 wire format, used by Yubico's libu2f\-host <https://developers.yubico.com/libu2f-host/>,
and a Plack application that works with
Google's JavaScript module <https://github.com/google/u2f-ref-code/blob/master/u2f-gae-demo/war/js/u2f-api.js>.
.PP
Sadly, the documentation around U2F is rather more confusing than it should be,
and this short description is probably not making things better. Please improve
this or write something about U2F so we can improve application security
everywhere.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
There are three functions: One for generating challenges for the host to sign,
and one for processing the responses from the two types of signing requests U2F
supports.
.PP
There's straight function interface and a class method interface. Both do
exactly the same thing; which you use depends onhow much verbosity you like vs
how much namespace clutter you like. Only the functional interface is mentioned
in this section; see the \s-1SYNOPSIS\s0 for the details.
.SS "u2f_challenge"
.IX Subsection "u2f_challenge"
.Vb 1
\&    my $challenge = u2f_challenge;
.Ve
.PP
Creates a challenge. A challenge is 256 cryptographically-secure random bits.
.SS "u2f_registration_verify"
.IX Subsection "u2f_registration_verify"
Verify a registration response from the host against the challenge. If the
verification is successful, returns the key handle and public key of the device
that signed the challenge. If it fails, this function croaks with an error.
.PP
Takes the following options, all required:
.IP "challenge" 4
.IX Item "challenge"
The challenge originally given to the host.
.IP "app_id" 4
.IX Item "app_id"
The application \s-1ID.\s0
.IP "origin" 4
.IX Item "origin"
The browser location origin. This is typically the same as the application \s-1ID.\s0
.IP "registration_data" 4
.IX Item "registration_data"
The registration data blob from the host.
.IP "client_data" 4
.IX Item "client_data"
The client data blob from the host.
.SS "u2f_signature_verify"
.IX Subsection "u2f_signature_verify"
Verify a signature (authentication) response from the host against the
challenge. If the verification is successful, the user has presented a valid
device and is now authenticated. If the verification fails, this function
croaks with an error.
.PP
Takes the following options, all required.
.IP "challenge" 4
.IX Item "challenge"
The challenge originally given to the host.
.IP "app_id" 4
.IX Item "app_id"
The application \s-1ID.\s0
.IP "origin" 4
.IX Item "origin"
The browser location origin. This is typically the same as the application \s-1ID.\s0
.IP "key_handle" 4
.IX Item "key_handle"
The handle of the key that was used to sign the challenge.
.IP "key" 4
.IX Item "key"
The stored public key associated with the handle.
.IP "signature_data" 4
.IX Item "signature_data"
The signature data blob from the host.
.IP "client_data" 4
.IX Item "client_data"
The client data blob from the host.
.SH "SUPPORT"
.IX Header "SUPPORT"
.SS "Bugs / Feature Requests"
.IX Subsection "Bugs / Feature Requests"
Please report any bugs or feature requests through the issue tracker
at <https://github.com/robn/Authen\-U2F/issues>.
You will be notified automatically of any progress on your issue.
.SS "Source Code"
.IX Subsection "Source Code"
This is open source software. The code repository is available for
public review and contribution under the terms of the license.
.PP
<https://github.com/robn/Authen\-U2F>
.PP
.Vb 1
\&  git clone https://github.com/robn/Authen\-U2F.git
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Robert Norris <rob@eatenbyagrue.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Robert Norris.
.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.