.\" Automatically generated by Pod::Man 4.10 (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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::U2F::Server::Simple 3pm"
.TH Crypt::U2F::Server::Simple 3pm "2018-11-02" "perl v5.28.0" "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"
Crypt::U2F::Server::Simple \- Register and Authenticate U2F compatible security devices
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Crypt::U2F::Server:Simple;
\&  
\&  my $crypter = Crypt::U2F::Server::Simple\->new(
\&      appId  => \*(AqPerl\*(Aq,
\&      origin => \*(Aqhttp://search.cpan.org\*(Aq
\&  );
\&  
\&  # Generate a registration request
\&  my $registerRequest = $crypter\->registrationChallenge();
\&  
\&  # Give $registerRequest to client, receive $registrationData from client
\&  # NB: if Crypt::U2F::Server::Simple has been recreated (web process for example), challenge
\&  #     value must be restored (value only, not JSON blob):
\&  #$crypter\->setChallenge($challenge)
\&  my ($keyHandle, $userKey) = $crypter\->registrationVerify($registrationData)
\&  
\&  # Generate an authentication request (using the previously generated key handle and user key)
\&  my $authrequest = $crypter\->authenticationChallenge();
\&  
\&  # Send $authrequest to client, receive $authSignature
\&  # NB: if Crypt::U2F::Server::Simple has been recreated (web process for example), challenge
\&  #     value must be restored (value only, not JSON blob):
\&  #$crypter\->setChallenge($challenge)
\&  my $authok = $crypter\->authenticationVerify($authSignature);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the server side of U2F authentication through Yubico's C library.
.PP
Both registration and authentication are two step processes that each must be run in the same instance
of this perl module. To clarify You can run registration from another instance than authentication, or even
in another program on another server. But, as far as it is currently implemented, you must run both registration
steps in the same instance of this module, the same goes for authentication. Needs more testing, really.
.PP
A successful registration of a key yields to two scalars, a key handle and a public key. It is \fByour\fR
responsibility to keep them safe somewhere and reload them into this module whenever you want to do
authentication.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
This module requires the Yubico u2f\-server shared library installed, please see the official
project page at <https://developers.yubico.com/libu2f\-server/> on how to do that.
.SH "NO MULTITHREADING"
.IX Header "NO MULTITHREADING"
The way this is currently implemented, i doubt very much that multithreadingm will work.
Multi-Forking should be \s-1OK\s0 as long as you only call \fBnew()\fR \fBafter\fR forking, though. Also
using more than one instance of this module in your program. This isn't really tested
at the moment, though...
.SH "ALPHA WARNING"
.IX Header "ALPHA WARNING"
As already stated above, at this time Crypt::U2F::Server and Crypt::U2F::Server::Simple have seen only
very limited testing and the modules are still subject to change.
.PP
That isn't to say that you shouldn't use this at all. Rather, if you are interested, you should test this
a lot and report any bugs you find!
.SH "FUNCTION DESCRIPTION"
.IX Header "FUNCTION DESCRIPTION"
.SS "\fBlastError()\fP"
.IX Subsection "lastError()"
Probably the most important function of all, therefore mention first. If something goes wrong
(but not HorriblyWrong[tm]), you'll get the last error description of whatever happened.
.PP
If something fails during \fBnew()\fR, call it with the full name:
.PP
.Vb 1
\&    my $oooops = Crypt::U2F::Server::Simple::lastError();
.Ve
.PP
If you already got an instance, you can use that as well:
.PP
.Vb 1
\&    my $oooops = $auth\->lastError();
.Ve
.PP
Errors are global over all instances of this module.
.PP
If things go HorriblyWrong[tm], your program might crash. Or get remote-buffer-overflow-exploited
or something. In these case, \fBlastError()\fR might not work reliably. You know, just the usual crypto
stuff...
.SS "\fBnew()\fP"
.IX Subsection "new()"
This comes in two forms, depending if you do authentication in the same instance as the registration steps.
.PP
The simple form (only registration or registration+authentication) only requires the arguments appId and origin:
.PP
.Vb 4
\&    my $auth = Crypt::U2F::Server::Simple\->new(
\&        appId  => \*(AqPerl\*(Aq,
\&        origin => \*(Aqhttp://search.cpan.org\*(Aq
\&    );
.Ve
.PP
If you only do authentication, you have to supply the keyHandle and publicKey data as well:
.PP
.Vb 6
\&    my $auth = Crypt::U2F::Server::Simple\->new(
\&        appId     => \*(AqPerl\*(Aq,
\&        origin    => \*(Aqhttp://search.cpan.org\*(Aq,
\&        keyHandle => $keyHandleData
\&        publicKey => $publicKeyData
\&    );
.Ve
.PP
For security, i would recommend creating a new instance for each and every authentication request.
.PP
If something goes wrong during initialization, \f(CW$auth\fR will be \fIundef\fR.
.PP
To enable Yubico library debug, set debug to 1:
.PP
.Vb 5
\&    my $auth = Crypt::U2F::Server::Simple\->new(
\&        appId  => \*(AqPerl\*(Aq,
\&        origin => \*(Aqhttp://search.cpan.org\*(Aq,
\&        debug  => 1
\&    );
.Ve
.SS "\fBregistrationChallenge()\fP"
.IX Subsection "registrationChallenge()"
.Vb 1
\&    my $challenge = $auth\->registrationChallenge();
.Ve
.PP
Gives you a unique registration challenge on every call. This is a \s-1JSON\s0 string and should be send to the client
(called a \*(L"host\*(R" for whatever reason) as is.
.PP
If something goes wrong, \f(CW$challenge\fR will be \fIundef\fR.
.PP
\&\f(CW$challenge\fR is a \s-1JSON\s0 blob that contains a hash. Here are the main keys
.IP "version: the protocol version" 4
.IX Item "version: the protocol version"
.PD 0
.IP "appId: the appId given in \fBnew()\fR" 4
.IX Item "appId: the appId given in new()"
.IP "challenge: the challenge value" 4
.IX Item "challenge: the challenge value"
.PD
.SS "\fBregistrationVerify()\fP"
.IX Subsection "registrationVerify()"
.Vb 1
\&    my ($keyHandle, $publicKey) = $auth\->registrationVerify($reply);
.Ve
.PP
If the client (the \*(L"host\*(R") accepts the challenge, it will send you another \s-1JSON\s0 blob ($reply).
.PP
If everything goes well and registration succeeds, you will get the key handle and public key of, well
client key. If it fails, you will get \fIundef\fR.
.PP
\&\f(CW$keyHandle\fR and \f(CW$publicKey\fR will get set internally for direct following authentication in the same instance,
you need to store it in some persistent way yourself for future authentication.
.PP
As an added bonus, \f(CW$publicKey\fR will be a binary blob, so you may have to convert it to something like Base64 for
easier handling. See MIME::Base64 on how to do that. Make sure you un-encode before loading it into this
module!
.SS "\fBauthenticationChallenge()\fP"
.IX Subsection "authenticationChallenge()"
This function generates an authentication challenge. To do that, it needs keyHandle and publicKey, since this
is key dependent.
.PP
.Vb 1
\&    my $challenge = $auth\->authenticationChallenge();
.Ve
.PP
Otherwise, this works the same as the registration challenge. You get a \s-1JSON\s0 blob, send that to the client and
get an answer.
.PP
The \s-1JSON\s0 blob structure is described in \fBregistrationChallenge()\fR doc.
.SS "\fBauthenticationVerify()\fP"
.IX Subsection "authenticationVerify()"
After you get the authentication answer, you need to verify it:
.PP
.Vb 1
\&    my $isValid = $auth\->authenticationVerify($reply);
.Ve
.PP
\&\f(CW$isValid\fR is true if authentication succeedsr. If something went wrong (library error, fake user), \f(CW$isValid\fR is false, in which
case you can look into \fBlastError()\fR to see what went wrong.
.SS "\fBsetChallenge()\fP"
.IX Subsection "setChallenge()"
If Crypt::U2F::Server::Simple has been recreated since \fBregistrationChallenge()\fR
or \fBauthenticationChallenge()\fR usage, challenge value must be restored:
.PP
.Vb 1
\&    $auth\->setChallenge($challenge)
.Ve
.PP
Note that \f(CW$challenge\fR must be the string value of challenge, not the \s-1JSON\s0 blob.
See \fBregistrationChallenge()\fR doc to get challenge description.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Crypt::U2F::Server for the low level library if you want better headaches.
.PP
There are two examples in the tarball for registration and authentication.
.SH "BUGS"
.IX Header "BUGS"
Yes, there should be some in there. First of all, this is crypto stuff, so
it's broken by default (it only depends on the time it takes to happen).
.PP
Also, at the moment, this module has seen only very limited testing.
.SH "AUTHOR"
.IX Header "AUTHOR"
.IP "Rene Schickbauer, <rene.schickbauer@magnapowertrain.com>" 4
.IX Item "Rene Schickbauer, <rene.schickbauer@magnapowertrain.com>"
.PD 0
.IP "Xavier Guimard, <x.guimard@free.fr>" 4
.IX Item "Xavier Guimard, <x.guimard@free.fr>"
.PD
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Adapted as a Perl library by Rene 'cavac' Schickbauer
.PP
This roughly based on u2f\-server.c from Yubico's
C library, see <https://developers.yubico.com/libu2f\-server/>
.PP
In order for this to work, you need to install that
library.
.PP
This adaption is (C) 2014\-2018 Rene 'cavac' Schickbauer and 2018 Xavier
Guimard, but as it is based on Yubico's code, the licence below applies!
.PP
\&\fIWe, the community, would hereby thank Yubico for open sourcing their code!\fR
.PP
.Vb 10
\&    /*
\&    * Copyright (c) 2014 Yubico AB
\&    * All rights reserved.
\&    *
\&    * Redistribution and use in source and binary forms, with or without
\&    * modification, are permitted provided that the following conditions are
\&    * met:
\&    *
\&    * * Redistributions of source code must retain the above copyright
\&    * notice, this list of conditions and the following disclaimer.
\&    *
\&    * * Redistributions in binary form must reproduce the above
\&    * copyright notice, this list of conditions and the following
\&    * disclaimer in the documentation and/or other materials provided
\&    * with the distribution.
\&    *
\&    * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
\&    * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
\&    * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
\&    * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
\&    * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
\&    * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
\&    * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
\&    * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
\&    * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
\&    * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
\&    * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\&    */
.Ve