Crypt::U2F::Server::Simple(3pm)

1Crypt::U2F::Server::SimUpsleer(3C)ontributed Perl DocumeCnrtyaptti:o:nU2F::Server::Simple(3)
2
3
4

NAME

6       Crypt::U2F::Server::Simple - Register and Authenticate U2F compatible
7       security devices
8

SYNOPSIS

10         use Crypt::U2F::Server:Simple;
11
12         my $crypter = Crypt::U2F::Server::Simple->new(
13             appId  => 'Perl',
14             origin => 'http://search.cpan.org'
15         );
16
17         # Generate a registration request
18         my $registerRequest = $crypter->registrationChallenge();
19
20         # Give $registerRequest to client, receive $registrationData from client
21         # NB: if Crypt::U2F::Server::Simple has been recreated (web process for example), challenge
22         #     value must be restored (value only, not JSON blob):
23         #$crypter->setChallenge($challenge)
24         my ($keyHandle, $userKey) = $crypter->registrationVerify($registrationData)
25
26         # Generate an authentication request (using the previously generated key handle and user key)
27         my $authrequest = $crypter->authenticationChallenge();
28
29         # Send $authrequest to client, receive $authSignature
30         # NB: if Crypt::U2F::Server::Simple has been recreated (web process for example), challenge
31         #     value must be restored (value only, not JSON blob):
32         #$crypter->setChallenge($challenge)
33         my $authok = $crypter->authenticationVerify($authSignature);
34

DESCRIPTION

36       This module implements the server side of U2F authentication through
37       Yubico's C library.
38
39       Both registration and authentication are two step processes that each
40       must be run in the same instance of this perl module. To clarify You
41       can run registration from another instance than authentication, or even
42       in another program on another server. But, as far as it is currently
43       implemented, you must run both registration steps in the same instance
44       of this module, the same goes for authentication. Needs more testing,
45       really.
46
47       A successful registration of a key yields to two scalars, a key handle
48       and a public key. It is your responsibility to keep them safe somewhere
49       and reload them into this module whenever you want to do
50       authentication.
51

INSTALLATION

53       This module requires the Yubico u2f-server shared library installed,
54       please see the official project page at
55       <https://developers.yubico.com/libu2f-server/> on how to do that.
56

NO MULTITHREADING

58       The way this is currently implemented, i doubt very much that
59       multithreadingm will work.  Multi-Forking should be OK as long as you
60       only call new() after forking, though. Also using more than one
61       instance of this module in your program. This isn't really tested at
62       the moment, though...
63

ALPHA WARNING

65       As already stated above, at this time Crypt::U2F::Server and
66       Crypt::U2F::Server::Simple have seen only very limited testing and the
67       modules are still subject to change.
68
69       That isn't to say that you shouldn't use this at all. Rather, if you
70       are interested, you should test this a lot and report any bugs you
71       find!
72

FUNCTION DESCRIPTION

74   lastError()
75       Probably the most important function of all, therefore mention first.
76       If something goes wrong (but not HorriblyWrong[tm]), you'll get the
77       last error description of whatever happened.
78
79       If something fails during new(), call it with the full name:
80
81           my $oooops = Crypt::U2F::Server::Simple::lastError();
82
83       If you already got an instance, you can use that as well:
84
85           my $oooops = $auth->lastError();
86
87       Errors are global over all instances of this module.
88
89       If things go HorriblyWrong[tm], your program might crash. Or get
90       remote-buffer-overflow-exploited or something. In these case,
91       lastError() might not work reliably. You know, just the usual crypto
92       stuff...
93
94   new()
95       This comes in two forms, depending if you do authentication in the same
96       instance as the registration steps.
97
98       The simple form (only registration or registration+authentication) only
99       requires the arguments appId and origin:
100
101           my $auth = Crypt::U2F::Server::Simple->new(
102               appId  => 'Perl',
103               origin => 'http://search.cpan.org'
104           );
105
106       If you only do authentication, you have to supply the keyHandle and
107       publicKey data as well:
108
109           my $auth = Crypt::U2F::Server::Simple->new(
110               appId     => 'Perl',
111               origin    => 'http://search.cpan.org',
112               keyHandle => $keyHandleData
113               publicKey => $publicKeyData
114           );
115
116       For security, i would recommend creating a new instance for each and
117       every authentication request.
118
119       If something goes wrong during initialization, $auth will be undef.
120
121       To enable Yubico library debug, set debug to 1:
122
123           my $auth = Crypt::U2F::Server::Simple->new(
124               appId  => 'Perl',
125               origin => 'http://search.cpan.org',
126               debug  => 1
127           );
128
129   registrationChallenge()
130           my $challenge = $auth->registrationChallenge();
131
132       Gives you a unique registration challenge on every call. This is a JSON
133       string and should be send to the client (called a "host" for whatever
134       reason) as is.
135
136       If something goes wrong, $challenge will be undef.
137
138       $challenge is a JSON blob that contains a hash. Here are the main keys
139
140       version: the protocol version
141       appId: the appId given in new()
142       challenge: the challenge value
143
144   registrationVerify()
145           my ($keyHandle, $publicKey) = $auth->registrationVerify($reply);
146
147       If the client (the "host") accepts the challenge, it will send you
148       another JSON blob ($reply).
149
150       If everything goes well and registration succeeds, you will get the key
151       handle and public key of, well client key. If it fails, you will get
152       undef.
153
154       $keyHandle and $publicKey will get set internally for direct following
155       authentication in the same instance, you need to store it in some
156       persistent way yourself for future authentication.
157
158       As an added bonus, $publicKey will be a binary blob, so you may have to
159       convert it to something like Base64 for easier handling. See
160       MIME::Base64 on how to do that. Make sure you un-encode before loading
161       it into this module!
162
163   authenticationChallenge()
164       This function generates an authentication challenge. To do that, it
165       needs keyHandle and publicKey, since this is key dependent.
166
167           my $challenge = $auth->authenticationChallenge();
168
169       Otherwise, this works the same as the registration challenge. You get a
170       JSON blob, send that to the client and get an answer.
171
172       The JSON blob structure is described in registrationChallenge() doc.
173
174   authenticationVerify()
175       After you get the authentication answer, you need to verify it:
176
177           my $isValid = $auth->authenticationVerify($reply);
178
179       $isValid is true if authentication succeedsr. If something went wrong
180       (library error, fake user), $isValid is false, in which case you can
181       look into lastError() to see what went wrong.
182
183   setChallenge()
184       If Crypt::U2F::Server::Simple has been recreated since
185       registrationChallenge() or authenticationChallenge() usage, challenge
186       value must be restored:
187
188           $auth->setChallenge($challenge)
189
190       Note that $challenge must be the string value of challenge, not the
191       JSON blob.  See registrationChallenge() doc to get challenge
192       description.
193

BUGS

202       Yes, there should be some in there. First of all, this is crypto stuff,
203       so it's broken by default (it only depends on the time it takes to
204       happen).
205
206       Also, at the moment, this module has seen only very limited testing.
207

AUTHOR

209       Rene Schickbauer, <rene.schickbauer@magnapowertrain.com>
210       Xavier Guimard, <x.guimard@free.fr>
211

COPYRIGHT AND LICENSE

213       Adapted as a Perl library by Rene 'cavac' Schickbauer
214
215       This roughly based on u2f-server.c from Yubico's C library, see
216       <https://developers.yubico.com/libu2f-server/>
217
218       In order for this to work, you need to install that library.
219
220       This adaption is (C) 2014-2018 Rene 'cavac' Schickbauer and 2018 Xavier
221       Guimard, but as it is based on Yubico's code, the licence below
222       applies!
223
224       We, the community, would hereby thank Yubico for open sourcing their
225       code!
226
227           /*
228           * Copyright (c) 2014 Yubico AB
229           * All rights reserved.
230           *
231           * Redistribution and use in source and binary forms, with or without
232           * modification, are permitted provided that the following conditions are
233           * met:
234           *
235           * * Redistributions of source code must retain the above copyright
236           * notice, this list of conditions and the following disclaimer.
237           *
238           * * Redistributions in binary form must reproduce the above
239           * copyright notice, this list of conditions and the following
240           * disclaimer in the documentation and/or other materials provided
241           * with the distribution.
242           *
243           * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
244           * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
245           * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
246           * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
247           * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
248           * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
249           * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
250           * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
251           * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
252           * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
253           * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
254           */
255
256
257
258perl v5.38.0                      2023-10-04     Crypt::U2F::Server::Simple(3)