Download the PHP package code-lts/u2f-php-server without Composer

U2F-php-server

Server-side handling of FIDO U2F registration and authentication for PHP.

Securing your online accounts and doing your bit to protect your data is extremely important and increasingly more so as hackers get more sophisticated. FIDO's U2F enables you to add a simple unobtrusive method of 2nd factor authentication, allowing users of your service and/or application to link a hardware key to their account.

Story about this library fork

All started in this issue in October 2020. I quickly worked hard on building tests and opening a pull-request. But nothing got merged because the library author vanished.

What does change in this fork ?

For the first released version: nothing changed, only tests where written. And PHP 8.1 support was done. Future versions may change things.

The Family of U2F php Libraries

Base Library

https://github.com/code-lts/U2F-php-server

Contents

1. Installation
2. Requirements
   1. OpenSSL
   2. Clientside Magic
   3. HTTPS and SSL
3. Terminology
4. Recommended Datastore Structure
5. Process Workflow
   1. Registration Process Flow
   2. Authentication Process Flow
6. Example Code
   1. Compatibility Check
   2. Registration Code
   3. Authentication Code
7. Frameworks
   1. Laravel
   2. Yii
   3. CodeIgniter
8. Licence
9. Credits

Installation

composer require code-lts/u2f-php-server

Requirements

A few things you need to know before working with this:

1. OpenSSL You need at least OpenSSL 1.0.0 or higher.
2. Client-side Handling You need to be able to communicate with a some kind of device.
3. A HTTPS URL This is very important, without HTTPS U2F simply will not work.
4. A Datastore You need some kind of datastore for all your U2F registered users (although if you have a system with user authentication I'm presuming you've got this one sorted).

OpenSSL

This repository requires OpenSSL 1.0.0 or higher. For further details on installing OpenSSL please refer to the php manual.

Also see Compatibility Code, to check if you have the correct version of OpenSSL installed, and are unsure how else to check.

Client-side (The magic JavaScript Bit of talking with a USB device)

My presumption is that if you are looking to add U2F authentication to a php system, then you'll probably are also looking for some client-side handling. You've got a U2F enabled USB device and you want to get the USB device speaking with the browser and then with your server running php.

1. Google already have this bit sorted : u2f-api.js
2. Mastahyeti has created a repo dedicated to Google's JavaScript Client-side API : https://github.com/mastahyeti/u2f-api

HTTPS and SSL

For U2F to work your website/service must use a HTTPS URL. Without a HTTPS URL your code won't work, so get one for your localhost, get one for your production. https://letsencrypt.org/ Basically encrypt everything.

Terminology

HID : Human Interface Device, like A USB Device like these things

Recommended Datastore Structure

You don't need to follow this structure exactly, but you will need to associate your Registration data with a user. You'll also need to store the key handle, public key and the certificate, counter isn't 100% essential but it makes your application more secure.

TODO the descriptions

Process Workflow

Registration Process Flow

1. User navigates to a 2nd factor authentication page in your application.

... TODO add the rest of the registration process flow ...

Authentication Process Flow

1. User navigates to their login page as they usually would, submits username and password.
2. Server received POST request authentication data, normal username + password validation occurs
3. On successful authentication, the application checks 2nd factor authentication is required. We're going to presume it is, otherwise the user would just be logged in at this stage.
4. Application gets the user's registered signatures from the application datastore: $registrations.
5. Application gets its ID, usually the domain the application is accessible from: $appId
6. Application makes a U2F::makeAuthentication($registrations, $appId) call, the method returns an array of SignRequest objects: $authenticationRequest.
7. Application JSON encodes the array and passes the data to the view
8. When the browser loads the page the JavaScript fires the u2f.sign(authenticationRequest, function(data){ // Callback logic }) function
9. The view will use JavaScript / Browser to poll the host machine's ports for a FIDO U2F device
10. Once the HID has been found the JavaScript / Browser will send the sign request with data.
11. The HID will prompt the user to authorize the sign request
12. On success the HID returns authentication data
13. The JavaScript receives the HID's returned data and passes it to the server
14. The application takes the returned data passes it to the U2F::authenticate($authenticationRequest, $registrations, $authenticationResponse) method
15. If the method returns a registration and doesn't throw an Exception, authentication is complete.
16. Set the user's session, inform the user of the success, and redirect them.

Example Code

For a full working code example for this repository please see the dedicated example repository

You can also install it with the following:

1. Compatibility Code
2. Registration Code
   1. Step 1: Starting
   2. Step 2: Talking to the HID
   3. Step 3: Validation & Storage
3. Authentication Code
   1. Step 1: Starting
   2. Step 2: Talking to the HID
   3. Step 3: Validation

Compatibility Code

You'll only ever need to use this method call once per installation and only in the context of debugging if the class is giving you unexpected errors. This method call will check your OpenSSL version and ensure it is at least 1.0.0 .

Registration Code

Registration Step 1:

Starting the registration process:

We assume that user has successfully authenticated and wishes to register.

Registration Step 2:

Client-side, Talking To The USB

Non-AJAX client-side registration of U2F key token. AJAX can of course be used in your application, but it is easier to demonstrate a linear process without AJAX and callbacks.

Registration Step 3:

Validation and Key Storage

This is the last stage of registration. Validate the registration response data against the original request data.

Authentication Code

Authentication Step 1:

Starting the authentication process:

We assume that user has successfully authenticated and has previously registered to use FIDO U2F.

Authentication Step 2:

Client-side, Talking To The USB

Non-AJAX client-side authentication of U2F key token. AJAX can of course be used in your application, but it is easier to demonstrate a linear process without AJAX and callbacks.

Authentication Step 3:

Validation

This is the last stage of authentication. Validate the authentication response data against the original request data.

Again, if you want to just download some example code to play with just install the full working code examples written for this repository please see the dedicated example repository

You can also install it with the following:

Licence

The repository is licensed under a BSD license. Read details here

Credits

This repo was originally based on the Yubico php-u2flib-server