Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Overview of the framework
Webauthn defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users.
The complete specification can be found on the W3C dedicated page.
This framework contains PHP libraries and Symfony bundle to allow developers to integrate that authentication mechanism into their web applications.
Naming things may be complicated. That’s why the following rule applies on the whole framework: the name of classes, constants and properties are identical to the ones you will find in the specification.
As an example, the section 5.2.2 “Web Authentication Assertion” shows an object named AuthenticatorAssertionResponse
that extends AuthenticatorResponse
with the following properties:
authenticatorData
signature
userHandle
You will find EXACTLY the same structure in the PHP class provided by the library.
Attestation Types
Empty
Basic
Self
Private CA
Anonymization CA
Note that Elliptic Curve Direct Anonymous Attestation (ECDAA) is deprecated and not supported
Attestation Formats
FIDO U2F
Packed
TPM
Android Key
Android Safetynet
Apple
Cose Algorithms
RS1, RS256, RS384, RS512
PS256, PS384, PS512
ES256, ES256K, ES384, ES512
ED25519
Extensions
Supported (not fully tested)
appid extension (compatibility with FIDO U2F authenticator
The Token Binding support feature is now deprecated as not part of the latest specification version
The framework is already compatible with all authenticators.
The compliance of the framework is ensured by running unit and functional tests during its development.
It is also tested using the official FIDO Alliance testing tools. The status of the compliance tests are reported in this issue. At the time of writing (January 2023, all features and algorithms are supported and 100% of the tests pass.
I bring solutions to your problems and answer your questions.
If you really love that project, and the work I have done or if you want I prioritize your issues, then you can help me out for a couple of🍻 or more!
Requests for new features, bug fixed and all other ideas to make this framework useful are welcome.
If you feel comfortable writing code, you could try to fix opened issues where help is wanted or those that are easy to fix.
Do not forget to follow these best practices.
If you think you have found a security issue, DO NOT open an issue. You MUST submit your issue here.
Disclaimer: you should not ask for the Attestation Statement unless you are working on an application that requires a high level of trust (e.g. Banking/Financial Company, Government Agency...).
During the Attestation Ceremony (i.e. the registration of the authenticator), you can ask for the Attestation Statement of the authenticator. The Attestation Statements have one of the following types:
None (none
): no Attestation Statement is provided
Basic Attestation (basic
): Authenticator’s attestation key pair is specific to an authenticator model.
Surrogate Basic Attestation (or Self Attestation - self
): Authenticators that have no specific attestation key use the credential private key to create the attestation signature
Attestation CA (AttCA
): Authenticators are based on a Trusted Platform Module (TPM). They can generate multiple attestation identity key pairs (AIK) and requests an Attestation CA to issue an AIK certificate for each.
Anonymization CA (AnonCA
): Authenticators use an Anonymization CA, which dynamically generates per-credential attestation certificates such that the attestation statements presented to Relying Parties do not provide uniquely identifiable information.
The Metadata Statements are issued by the manufacturers of the authenticators. These statements contain details about the authenticators (supported algorithms, biometric capabilities...) and all the necessary information to verify the Attestation Statements generated during the attestation ceremony.
There are several possible sources to get these Metadata Statements. The main source is the FIDO Alliance Metadata Service that allows fetching statements on-demand, but some of them may be provided by other means.
The FIDO Alliance Metadata Service provides a limited number of Metadata Statements. It is mandatory to get the statement from the manufacturer of your authenticators otherwise the Attestation Statement won't be verified and the Attestation Ceremony will fail.
Authenticator details and how to manage them
After the registration of an authenticator, you will get a Public Key Credential Source object. It contains all the credential data needed to perform user authentication and much more.
Each Credential Source is managed using the Public Key Credential Source Repository.
The library does not provide any concrete implementation. It is up to you to create it depending on your application constraints. This only constraint is that your repository class must implement the interface Webauthn\PublicKeyCredentialSourceRepository
.
The PublicKeyCredentialSourceRepository
interface requires the following methods to be implemented:
public function findOneByCredentialId(string $publicKeyCredentialId): ?PublicKeyCredentialSource;
: thie method retreive a key source object from the credential ID.
public function findAllForUserEntity(PublicKeyCredentialUserEntity $publicKeyCredentialUserEntity): array;
: this method lists all key sources associated to the user entity
public function saveCredentialSource(PublicKeyCredentialSource $publicKeyCredentialSource): void;
: this method saves the key source in your storage (files, database...)
How to install the library or the Symfony bundle?
This framework contains several sub-packages that you don’t necessarily need. It is highly recommended to install what you need and not the whole framework.
The preferred way to install the library you need is to use composer:
Hereafter the dependency tree:
web-auth/webauthn-lib
: this is the core library. This package can be used in any PHP project or within any popular framework (Laravel, CakePHP…)
web-auth/webauthn-symfony-bundle
: this is a Symfony bundle that ease the integration of this authentication mechanism in your Symfony project.
The core library also depends on web-auth/cose-lib
and web-auth/metadata-service
. What are these dependencies?
web-auth/cose-lib
contains several cipher algorithms and COSE key support to verify the digital signatures sent by the authenticators during the creation and authentication ceremonies. These algorithms are compliant with the . This library can be used by any other PHP projects. At the moment only signature algorithms are available, but it is planned to add encryption algorithms.
web-auth/metadata-service
provides classes to support the . If you plan to use Attestation Statements during the creation ceremony, this service is mandatory. Please note that Attestation Statements decreases the user privacy as they may leak data that allow to identify a specific user. The use of Attestation Statements and this service are generally not recommended unless you REALLY need this information. This library can also be used by any other PHP projects.
The total size of the core package is approximately 760ko. Hereafter the detail for each component:
web-auth/cose-lib
: 85ko
web-auth/metadata-service
: 81ko
web-auth/webauthn-lib
: 207ko
web-auth/webauthn-symfony-bundle
: 385ko
The total size of the core package + the direct dependencies is approximately 1.7Mo.
Registration and Authentication process overview
In the Webauthn context, there are two ceremonies:
The attestation ceremony
The assertion ceremony: it is used for the authentication of a user.
For both ceremonies, there are two steps to perform:
The creation of options: these options are sent to the authenticator and indicate what to do and how.
The response of the authenticator: after the user interacted with the authenticator, the authenticator computes a response that has to be verified.
Depending on the options and the capabilities of the authenticator, the user interaction may differ. It can be a simple touch on a button or a complete authentication using biometric means (PIN code, fingerprint, facial recognition…).
This ceremony aims at registering an authenticator. It can be used during the creation of a new user account or when an existing user wants to add an additional authenticator.
This ceremony aims at authenticating a user. The user will be asked to interact with one of its authenticators. Additional authentication means, such as PIN code or fingerprint, may be required.
It's all about users
A User Entity object represents a user in the Webauthn context. It has the following constraints:
The user ID must be unique and must be a string,
The username must be unique,
Hereafter a minimalist example of user entity:
The username can be composed of any displayable characters, including emojis. Username "😝🥰😔" is perfectly valid.
Developers should not add rules that prevent users from choosing the username they want.
For privacy reasons, it is not recommended using the e-mail as username.
As for the rp
Entity, the User Entity may have an icon. This icon must also be secured.
The Webauthn specification does not set any limit for the length of the icon.
The icon may be ignored by browsers, especially if its length is greater than 128 bytes.
The User Entity Repository manages all Webauthn users of your application.
There is no interface to implement or abstract class to extend so that it should be easy to integrate it in your application. You may already have a user repository.
Whatever database you use (MySQL, pgSQL…), it is not necessary to create relationships between your users and the Credential Sources.
It shall be noted that the Symfony bundle will need a user entity repository. This service shall implement Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepository
.
The methods required by the interface are as follow:
public function findOneByUsername(string $username): ?PublicKeyCredentialUserEntity;
This method tries to find out a user entity from the username.
public function findOneByUserHandle(string $userHandle): ?PublicKeyCredentialUserEntity;
This method tries to find out a user entity from the user handle i.e. the user ID.
public function generateNextUserEntityId(): string;
This method creates a user entity ID. Note that this method SHALL NOT save that ID. Its main purpose generate a unique ID that could be used for a user entity object at a later stage.
public function saveUserEntity(PublicKeyCredentialUserEntity $userEntity): void;
This method saves the user entity. If the user entity already exists, it should throw an exception.