lib/webauthn/README.md

   1 [![Licensed under the MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/lbuchs/WebAuthn/blob/master/LICENSE)
   2 [![Requires PHP 7.1.0](https://img.shields.io/badge/PHP-7.1.0-green.svg)](https://php.net)
   3 [![Last Commit](https://img.shields.io/github/last-commit/lbuchs/WebAuthn.svg)](https://github.com/lbuchs/WebAuthn/commits/master)
   4
   5 # WebAuthn
   6 *A simple PHP WebAuthn (FIDO2) server library*
   7
   8 Goal of this project is to provide a small, lightweight, understandable library to protect logins with passkeys, security keys like Yubico or Solo, fingerprint on Android or Windows Hello.
   9
  10 ## Manual
  11 See /_test for a simple usage of this library. Check [webauthn.lubu.ch](https://webauthn.lubu.ch) for a working example.
  12
  13 ### Supported attestation statement formats
  14 * android-key &#x2705;
  15 * android-safetynet &#x2705;
  16 * apple &#x2705;
  17 * fido-u2f &#x2705;
  18 * none &#x2705;
  19 * packed &#x2705;
  20 * tpm &#x2705;
  21
  22 This library supports authenticators which are signed with a X.509 certificate or which are self attested. ECDAA is not supported.
  23
  24 ## Workflow
  25
  26              JAVASCRIPT            |          SERVER
  27     ------------------------------------------------------------
  28                              REGISTRATION
  29
  30
  31        window.fetch  ----------------->     getCreateArgs
  32                                                  |
  33     navigator.credentials.create   <-------------'
  34             |
  35             '------------------------->     processCreate
  36                                                  |
  37           alert ok or fail      <----------------'
  38
  39
  40     ------------------------------------------------------------
  41                           VALIDATION
  42
  43
  44        window.fetch ------------------>      getGetArgs
  45                                                  |
  46     navigator.credentials.get   <----------------'
  47             |
  48             '------------------------->      processGet
  49                                                  |
  50           alert ok or fail      <----------------'
  51
  52 ## Attestation
  53 Typically, when someone logs in, you only need to confirm that they are using the same device they used during
  54 registration. In this scenario, you do not require any form of attestation.
  55 However, if you need additional security, such as when your company mandates the use of a Solokey for login,
  56 you can verify its authenticity through direct attestation. Companies may also purchase authenticators that
  57 are signed with their own root certificate, enabling them to validate that an authenticator is affiliated with
  58 their organization.
  59
  60 ### no attestation
  61 just verify that the device is the same device used on registration.
  62 You can use 'none' attestation with this library if you only check 'none' as format.
  63 * this is propably what you want to use if you want simple 2FA login protection like github, facebook, google, etc.
  64
  65 ### indirect attestation
  66 the browser may replace the AAGUID and attestation statement with a more privacy-friendly and/or more easily
  67 verifiable version of the same data (for example, by employing an anonymization CA).
  68 You can not validate against any root ca, if the browser uses a anonymization certificate.
  69 this library sets attestation to indirect, if you select multiple formats but don't provide any root ca.
  70 * hybrid soultion, clients may be discouraged by browser warnings but then you know what device they're using (statistics rulez!)
  71
  72 ### direct attestation
  73 the browser proviedes data about the identificator device, the device can be identified uniquely. User could be tracked over multiple sites, because of that the browser may show a warning message about providing this data when register.
  74 this library sets attestation to direct, if you select multiple formats and provide root ca's.
  75 * this is probably what you want if you know what devices your clients are using and make sure that only this devices are used.
  76
  77 ## Client-side discoverable Credentials
  78 A Client-side discoverable Credential Source is a public key credential source whose credential private key is stored in the authenticator,
  79 client or client device. Such client-side storage requires a resident credential capable authenticator.
  80 This is only supported by FIDO2 hardware, not by older U2F hardware.
  81
  82 ### How does it work?
  83 In a typical **server-side key** process, the user provides their username (and sometimes password)
  84 and the server responds with a list of all the public key credential identifiers that the user has registered.
  85 The authenticator then selects the first credential identifier it issued and responds with a signature
  86 that can be verified using the public key registered during the registration process.
  87
  88 In a client-side key process, the user does not need to provide a username or password.
  89 Instead, the authenticator searches its own memory to see if it has saved a key for the relying party.
  90 If a key is found, the authentication process proceeds in the same way as it would if the server had sent a list
  91 of identifiers. There is no difference in the verification process.
  92
  93 Both Apple and Windows 10/11 (with Firefox and Chromium) support Resident Credential.
  94 However, older operating systems such as Windows 7 do not support it and instead fall back to using FIDO U2F.
  95
  96 ### How can I use it with this library?
  97 #### on registration
  98 When calling `WebAuthn\WebAuthn->getCreateArgs`, set `$requireResidentKey` to true,
  99 to notify the authenticator that he should save the registration in its memory.
 100
 101 #### on login
 102 When calling `WebAuthn\WebAuthn->getGetArgs`, don't provide any `$credentialIds` (the authenticator will look up the ids in its own memory and returns the user ID as userHandle).
 103
 104 #### disadvantage
 105 The RP ID (= domain) is saved on the authenticator. So If an authenticator is lost, its theoretically possible to find the services, which the authenticator is used and login there.
 106
 107 ## Passkeys
 108 Passkeys is a technique that allows sharing credentials stored on the device with other devices. So from a technical standpoint of the server,
 109 there is no difference to client-side discoverable credentials. The difference is only that the phone or computer system is automatically
 110 syncing the credentials between the user’s devices via a cloud service. The cross-device sync of passkeys is managed transparently by the OS.
 111
 112 ### Browser support
 113 Availability of built-in passkeys that automatically synchronize to all of a user’s devices: (see also [passkeys.dev/device-support](https://passkeys.dev/device-support/))
 114 * Apple: iOS 16 / iPadOS 16 / macOS Ventura
 115 * Google: support in Android starting October 2022
 116 * Microsoft Windows is set to deliver support in 2023.
 117 * Firefox see [Bugzilla](https://bugzilla.mozilla.org/show_bug.cgi?id=1792433)
 118
 119 ## Requirements
 120 * PHP >= 8.0 with [OpenSSL](http://php.net/manual/en/book.openssl.php) and [Multibyte String](https://www.php.net/manual/en/book.mbstring.php)
 121 * Browser with [WebAuthn support](https://caniuse.com/webauthn) (Firefox 60+, Chrome 67+, Edge 18+, Safari 13+)
 122
 123 ## Infos about WebAuthn
 124 * [Wikipedia](https://en.wikipedia.org/wiki/WebAuthn)
 125 * [W3C](https://www.w3.org/TR/webauthn/)
 126 * [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)
 127 * [dev.yubico](https://developers.yubico.com/FIDO2/)
 128 * [FIDO Alliance](https://fidoalliance.org)
 129 * [passkeys](https://passkeys.dev/)
 130
 131 ## FIDO2 Hardware
 132 * [Yubico](https://www.yubico.com)
 133 * [Solo](https://solokeys.com) Open Source!
 134 * [Nitrokey](https://www.nitrokey.com/)
 135 * [Feitan](https://fido.ftsafe.com/)
 136 * [TrustKey](https://www.trustkeysolutions.com)
 137 * [Google Titan](https://cloud.google.com/titan-security-key)
 138 * [Egis](https://www.egistec.com/u2f-solution/)
 139 * [OneSpan](https://www.vasco.com/products/two-factor-authenticators/hardware/one-button/digipass-secureclick.html)
 140 * [Hypersecu](https://hypersecu.com/tmp/products/hyperfido)
 141 * [Kensington VeriMark™](https://www.kensington.com/)
 142 * [Token2](https://www.token2.com/shop/category/fido2-keys)