Download the PHP package firehed/u2f without Composer
On this page you can find all versions of the php package firehed/u2f. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package u2f
Short Description A library providing U2F authentication
License MIT
Homepage https://github.com/Firehed/u2f-php
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package u2f
Important: This repository is archived
This repository has been replaced by firehed/webauthn-php, and is no longer being maintained. The replacement no longer supports the long-deprecated U2F protocol, which allows for a more modern and flexible API. It DOES support U2F hardware keys, but only through the WebAuthn protocols.
U2F
A PHP implementation of the FIDO U2F authentication standard. Now also for Web Authentication!
Introduction
Web Authenication (commonly called WebAuthn) is a set of technologies to securely authenticate users in web applications. It is most commonly used as a second factor - either biometrics or a hardware device - to supplement password logins. It allows websites to replace the need for a companion app (such as Google Authenticator) or communication protocols (e.g. SMS) with a hardware-based second factor.
This library has its roots in the U2F (universal second factor) protocol that WebAuthn evolved from, and supports both standards. Note that browsers are starting to drop support for the original U2F protocols in favor of WebAuthn; consequently, this library will do the same in the next major version.
This library is designed to allow easy integration of the U2F protocol to an existing user authentication scheme. It handles the parsing and validating all of the raw message formats, and translates them into standard PHP objects.
Note that use of the word "key" throughout this document should be interpreted to mean "FIDO U2F Token". These are often USB "keys" but can also be NFC or Bluetooth devices.
There are two main operations that you will need to understand for a successful integration: registration and authentication. Registration is the act of associating a key that the end-user is physically in posession of with their existing account; authentication is where that key is used to cryptographically sign a message from your application to verify posession of said key.
Additional resources:
Demo
You may try all of this at https://u2f.ericstern.com, and see the corresponding code at https://github.com/Firehed/u2f-php-examples
The example code is only designed to show how the APIs interact with each other, and intentionally leaves out best practices such as use of routers and dependency inversion containers to keep the examples as simple as possible. See its README for more information.
Installation
composer require firehed/u2f
Note: you must not be using the deprecated mbstring.func_overload functionality, which can completely break working on binary data.
The library will immediately throw an exception if you have it enabled.
Usage
Usage will be described in three parts: setup, registration, and authentication. The code in setup should be used before both registration and authentication.
The API is designed to "fail loudly"; that is, failures will throw an exception, ensuring that return values are always the result of a successful operation.
This reduces the need for complex error checking and handling during use, since the whole thing can be simply wrapped in a try/catch block and assume that everything went well if no exceptions are caught.
This guide covers the modern Web Authentication ("WebAuthn") usage and data formats. More information on the legacy U2F protocols are available in versions of this README from v1.1.0 and earlier.
Setup
All operations are performed by the U2F Server class, so it needs to be instanciated and configured:
The trusted CAs are whitelisted vendors, and must be an array of absolute paths to PEM-formatted CA certs (as strings).
Some provider certificates are provided in the CACerts/ directory in the repository root; in a deployed project, these should be available via $PROJECT_ROOT/vendor/firehed/u2f/CACerts/*.pem.
You may also choose to disable CA verification, by calling ->disableCAVerification() instead of setTrustedCAs().
This removes trust in the hardware vendors, but ensures that as new vendors issue tokens, they will be forward-compatible with your website.
The URI provided to the constructor must be the HTTPS domain component of your website. See FIDO U2F AppID and Facet Specification for additional information.
Registration
Registering a token to a user's account is a two-step process: generating a challenge, and verifying the response to that challenge.
Generating the challenge
Start by generating a challenge. You will need to store this temporarily (e.g. in a session), then send it to the user:
Client-side registration
Create a PublicKeyCredentialCreationOptions data structure, and provide it to the WebAuthn API:
Parse and verify the response
Using the previously-generated registration request, ask the server to verify the POSTed data. If verification succeeds, you will have a Registration object to associate with the user:
Persist the $registration
Registrations SHOULD be persisted as a one-to-many relationship with the user, since a user may own multiple keys and may want to associate all of them with their account (e.g. a backup key is kept on a spouse's keychain).
It is RECOMMENDED to use (user_id, key_handle) as a unique composite identifier.
After doing this, you should add a flag of some kind on the user to indicate that 2FA is enabled, and ensure that they have authenticated with their second factor. Since this is entirely application-specific, it won't be covered here.
Authentication
Authentication is a similar process as registration: generate challenges to sign for each of the user's registrations, and validate the response when received.
Generating the challenge
Start by generating sign requests. Like with registration, you will need to store them temporarily for verification. After doing so, send them to the user:
Client-side authentication
Create a PublicKeyCredentialRequestOptions data structure, and provide it to the WebAuthn API:
Parse and verify the response
Parse the POSTed data into a LoginResponseInterface:
Persist the updated $registration
If no exception is thrown, $registration will be a Registration object with an updated counter; you MUST persist this updated counter to wherever the registrations are stored.
Failure to do so is insecure and exposes your application to token cloning attacks.
If you reach this point, the user has succcessfully authenticated with their second factor. Update their session to indicate this, and allow them to proceeed.
Tests
All tests are in the tests/ directory and can be run with vendor/bin/phpunit.
License
MIT
