Crypt:...Simple(3pm)

📦
version 0.47 · 8 versions
, in ubuntu stonking

🎀 Crypt::...Simple 🎀

okay bestie, buckle up 💖 this lil page lives in the perl man pages (User Contributed Perl Documentation section, Crypt:...Simple(3pm)), and it's here to tell you how to register and authenticate U2F-compatible security devices with Crypt::U2F::Server::Simple. yes, the actual little USB key thing you boop with your finger. iconic behavior honestly 🔥

✨ NAME ✨

Crypt::U2F::Server::Simple — register and authenticate U2F compatible security devices 🔑

like. it does the server side of the boop-your-key ritual. that's the whole vibe.

🌸 SYNOPSIS 🌸

here's the whole flow in one go, no cap:

  use Crypt::U2F::Server:Simple;

  my $crypter = Crypt::U2F::Server::Simple->new(
      appId  => 'Perl',
      origin => 'http://search.cpan.org'
  );

  # 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);
🫶 pspsps — those two setChallenge lines are commented out on purpose. they're your little emergency escape hatch when your web process got recreated mid-flow, iykyk.

💫 DESCRIPTION 💫

this module implements the server side of U2F authentication, riding on top of Yubico's C library. it's giving "backend bestie doing the hard work" 💅

so, registration and authentication are each two step processes, and each pair of steps has to run in the same instance of this perl module. the way that works: you can totally run registration from a different instance than authentication — or even in a whole other program on a whole other server, go off. but as far as it's currently implemented, both registration steps must run in the same instance of this module, and same for both authentication steps. needs more testing, really. 😭

a successful key registration hands you two scalars: a key handle and a public key. it is your responsibility to keep them safe somewhere and reload them into this module whenever you wanna do authentication. nobody else is gonna do it for you, bestie. 👑

🧚 INSTALLATION 🧚

this module needs the Yubico u2f-server shared library installed first. pls go see the official project page at https://developers.yubico.com/libu2f-server/ for how to do that. no library, no vibes. ✨

💀 NO MULTITHREADING 💀

the way this is currently implemented, i doubt very much that multithreading will work. 😬

Multi-Forking should be OK as long as you only call new() after forking, though. also: using more than one instance of this module in your program. this isn't really tested at the moment, though... 🙈

not me warning you about concurrency before you even write a line. test it, bestie.

⚠️ 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. 😭

that isn't to say you shouldn't use this at all. rather — if you're interested, you should test this a lot and report any bugs you find! 🫶

🔮 FUNCTION DESCRIPTION 🔮

💖 lastError()

probably the most important function of all, therefore mentioned first. 💅 if something goes wrong (but not HorriblyWrong[tm]), you'll get the last error description of whatever happened.

if something fails during new(), call it with the full name:

    my $oooops = Crypt::U2F::Server::Simple::lastError();

if you already got an instance, you can use that as well:

    my $oooops = $auth->lastError();

Errors are global over all instances of this module. 🌍

if things go HorriblyWrong[tm], your program might crash. or get remote-buffer-overflow-exploited or something. 😳 in these cases, lastError() might not work reliably. you know, just the usual crypto stuff...

💖 new()

this comes in two forms, depending on whether you do authentication in the same instance as the registration steps.

The simple form (only registration, or registration+authentication) only requires the arguments appId and origin:

    my $auth = Crypt::U2F::Server::Simple->new(
        appId  => 'Perl',
        origin => 'http://search.cpan.org'
    );

If you only do authentication, you have to supply the keyHandle and publicKey data as well:

    my $auth = Crypt::U2F::Server::Simple->new(
        appId     => 'Perl',
        origin    => 'http://search.cpan.org',
        keyHandle => $keyHandleData
        publicKey => $publicKeyData
    );

for security, i would recommend creating a new instance for each and every authentication request. 🔒

if something goes wrong during initialization, $auth will be undef.

to enable Yubico library debug, set debug to 1:

    my $auth = Crypt::U2F::Server::Simple->new(
        appId  => 'Perl',
        origin => 'http://search.cpan.org',
        debug  => 1
    );

💖 registrationChallenge()

    my $challenge = $auth->registrationChallenge();

gives you a unique registration challenge on every call. 🌈 this is a JSON string and should be sent to the client (called a "host" for whatever reason) as is. no edits, no filters, no glow-up.

if something goes wrong, $challenge will be undef. 😭

$challenge is a JSON blob that contains a hash. here are the main keys:

  • version: the protocol version
  • appId: the appId given in new()
  • challenge: the challenge value

💖 registrationVerify()

    my ($keyHandle, $publicKey) = $auth->registrationVerify($reply);

if the client (the "host") accepts the challenge, it will send you another JSON blob ($reply). 🦋

if everything goes well and registration succeeds, you will get the key handle and public key of, well, the client key. if it fails, you will get undef.

$keyHandle and $publicKey will get set internally for direct following authentication in the same instance — you need to store them in some persistent way yourself for future authentication. 📝

as an added bonus, $publicKey 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! 🚨

💖 authenticationChallenge()

this function generates an authentication challenge. to do that, it needs keyHandle and publicKey, since this is key dependent. 🔑

    my $challenge = $auth->authenticationChallenge();

otherwise, this works the same as the registration challenge. you get a JSON blob, send that to the client and get an answer. ✨

the JSON blob structure is described in registrationChallenge() doc. go read it, bestie.

💖 authenticationVerify()

after you get the authentication answer, you need to verify it:

    my $isValid = $auth->authenticationVerify($reply);

$isValid is true if authentication succeeds. if something went wrong (library error, fake user), $isValid is false — in which case you can look into lastError() to see what went wrong. 👀

💖 setChallenge()

if Crypt::U2F::Server::Simple has been recreated since registrationChallenge() or authenticationChallenge() usage, the challenge value must be restored:

    $auth->setChallenge($challenge)

note that $challenge must be the string value of challenge, not the JSON blob. 😤 see registrationChallenge() doc to get the challenge description.

🌟 SEE ALSO 🌟

  • see Crypt::U2F::Server for the low level library if you want better headaches. 💀
  • there are two examples in the tarball for registration and authentication. 🎀

🐛 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). 🙃

also, at the moment, this module has seen only very limited testing. 💅

👑 AUTHOR 👑

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

adapted as a Perl library by Rene 'cavac' Schickbauer.

this is roughly based on u2f-server.c from Yubico's C library, see https://developers.yubico.com/libu2f-server/

in order for this to work, you need to install that library. 🛠️

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!

we, the community, would hereby thank Yubico for open sourcing their code! 🫶💖

    /*
    * 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.
    */

and that's a wrap, bestie 💅 this whole thing came to you from the perl v5.42.3 era, dated 2026-08-21 — the Crypt:...Simple(3pm) page, closing out exactly the way it opened. go boop a security key for me. 🔑✨

📦 where this page comes from