madwizard-org / webauthn-server

WebAuthn Relying Party server library for PHP

WebAuthn Relying Party server library for PHP

Current state

Pretty stable but the API may still change slightly until the 1.0 release.

Goal

This library aims to implement the relying party server of the WebAuthn specification in PHP. Important goals are:

• Implement the level 1 WebAuthn specification
• Good quality, secure and maintainable code
• Easy to use for the end-user

Installation

Installation via composer:

composer require madwizard/webauthn

Supported features

• PHP 7.2

• FIDO conformant library
• Attestation types:
  • FIDO U2F
  • Packed
  • TPM
  • Android SafetyNet
  • Android Key
  • Apple
  • None
  • Optional 'unsupported' type to handle future types
• Metadata service support
• Validating metadata
• Extensions:
  • appid

Usage

The library is still in development so documentation is limited. The general pattern to follow is:

1. Implement CredentialStoreInterface (you will need UserCredential or your own implementation of UserCredentialInterface)
2. Create an instance of RelyingParty and use the ServerBuilder class to build a server object:

$server = (new ServerBuilder())
    ->setRelyingParty($rp)
    ->setCredentialStore($store)
    ->build();

3. Use startRegistration/finishRegistration to register credentials. Be sure to store the temporary AttestationContext server side!
4. and startAuthentication/finishAuthentication to authenticate. Be sure to store the temporary AssertionContext server side!

Resources

WebAuthn specification

webauthn-server's Issues

7.2. Verifying an authentication assertion

Hi, I have been having a look at your project and it looks great.

I have also been trying to code the server side of webauthn and bumped into a problem with point '7.2. Verifying an authentication assertion' ( https://www.w3.org/TR/webauthn/#verifying-assertion ), and I think you might want to know about it.

Verification step 16 says: "Using the credential public key looked up in step 3, verify that sig is a valid signature over the binary concatenation of aData and hash." Doing just that I always got a signature that did not match with 'sig'. I spent a lot of hours checking my code without finding anything wrong. I inspected several source codes, including yours, and I found out that this repository, https://github.com/fido-alliance/webauthn-demo, did the verification differently. I tried it and it worked.
The correct concatenation that produces a valid signature is:
rpIdHash + flags (1 byte) + signature counter (4 bytes) + clientDataHash

I hope it helps. I suppose the W3C specification will be updated. By the way, I am using a 'FIDO2 Security Key' by Yubico.

Regards.

Add experimental CRL validating

Convert enumerations to DOMstring where applicable

Level 2 of the spec changes the type of some fields from strict (exhaustive) enumerations to more flexible DOM strings. Make sure the library does not strictly validate these fields if not necessary.

Allow unknown transports

See w3c/webauthn#1275

Add support for client extensions

Add support for Apple's attestation format

See w3c/webauthn#1453. The format is not standardized yet.
This post contains useful links.

Support and test ECC TPM statements

Currently there is no test data for ECC TPM statements so this is not implemented yet.

Exclude conformance tests from composer package

Planning for first stable release?

Hi there,
I am curious if you have a planning for releasing the first stable version.
Maybe you need some help?

Support generating fake credentials to prevent username enumeration

Chrome empty userHandle instead of null

https://bugs.chromium.org/p/chromium/issues/detail?id=847878
Chrome violates the spec here. Wait for fix in Chrome or add check for emtpy ArrayBuffer userHandle and treat as null.

Add useful logging to services

Use LoggerAwareInterface to add logging to services.

Check level 2 webauthn spec for possible future arhcitecture problems before 1.0 release

Add support for Android SafetyNet attestation

See https://www.w3.org/TR/webauthn/#android-safetynet-attestation

Use symfony http client and cachingclient instead of guzzle

TPM attestation parser does not correctly handle ECC keys in pubArea

When parsing the unique field from pubArea during an attestation verification, unique is a TPM2B_PUBLIC_KEY_RSA only if the TPMI_ALG_PUBLIC is TPM_ALG_RSA. If TPMI_ALG_PUBLIC is TPM_ALG_ECC, unique is a TPMS_ECC_POINT. See TPM Rev 2.0 part 2, structures, section 12.2.3.2.

Relevant code is at:

webauthn-server/src/Attestation/Tpm/TpmPublic.php

Line 82 in 3a2451a

$this->unique = $this->readLengthPrefixed($data, $offset);

Validate EC public key coordinates

The x and y coordinates of the public key should be on the elliptic curve to prevent certain attacks.

Feature Request: Make RegistrationOptions function chainable

Would it be possible to change the setter functions in the RegistrationOptions to return self instead of void? This would make it possible to be able to chain those and write something like this:

$opts = RegistrationOptions::createForUser($userIdentity)
            ->setExcludeExistingCredentials(true);
            ->setTimeout(20);
            ->setResidentKey(ResidentKeyRequirement::REQUIRED);
            ->setUserVerification(\MadWizard\WebAuthn\Dom\UserVerificationRequirement::REQUIRED);

instead of this

$opts = RegistrationOptions::createForUser($userIdentity);
$opts->setExcludeExistingCredentials(true);
$opts->setTimeout(20);
$opts->setResidentKey(ResidentKeyRequirement::REQUIRED);
$opts->setUserVerification(\MadWizard\WebAuthn\Dom\UserVerificationRequirement::REQUIRED);

kinda like the ServerBuilder works, this could be done without breaking existing code i think