webauthn 2.0.0.beta1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6181693e3c34f1ca289fb2056df36c35a5e144076288eef34e774e2dfc1794b5
-  data.tar.gz: 87883fa3fe7c7bd5da885025b7a571dfedfdfe1c27c6a5c8edeee54956bd98bc
+  metadata.gz: 4094023fc463d77a38548e294121f819e874bfb1c075ca43b1fb38e41cfd53a2
+  data.tar.gz: f410f8d7e000822943be953265a32e8f81423908e6aff282486d5afa4ab62eb4
 SHA512:
-  metadata.gz: a69f7870a89344a5d00b1c75b55dd6e25741719bf2fd79d03e83348530a964ef237f8330dea55edbb58b9fe5ee0522f2f41b5d9d46f7d975112b9dd8a05889bd
-  data.tar.gz: 19b32618b9e83e2618abe361aca398933030fe2963502c8a9054dc291b22678107e3257be5d7a711bdf0d826dc1d444e28d726282fa6306abf336f675e3794df
+  metadata.gz: 23ea57e2264cc45024174e8d7a54bc3d4f373cca916c4453079d5cfccf46caa4dbc5aa4013a54404121274a35e71f97f90a061062a21ca270a8b58d474345fb8
+  data.tar.gz: 3b49c5b5b845fdcfc3b0b647a16aeab07ad219210e8e29835d171e387d6bcc4ac5fe08a4f9d2978ee6db1022363d1c2b06fe0a163a8625038aca51e1d274e903

data/.gitignore

@@ -13,3 +13,4 @@
 /Gemfile.lock
 /gemfiles/*.gemfile.lock
 .byebug_history
+/spec/conformance/metadata.zip

data/.rubocop.yml

@@ -1,12 +1,16 @@
+require:
+  - rubocop-rspec
+
 inherit_mode:
   merge:
     - AllowedNames
 
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.4
   DisabledByDefault: true
   Exclude:
     - "gemfiles/**/*"
+    - "vendor/**/*"
 
 Bundler:
   Enabled: true
@@ -17,18 +21,69 @@ Gemspec:
 Layout:
   Enabled: true
 
-Lint:
+Layout/ClassStructure:
+  Enabled: true
+
+Layout/FirstMethodArgumentLineBreak:
   Enabled: true
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 120
   Exclude:
     - spec/support/seeds.rb
 
+Layout/MultilineAssignmentLayout:
+  Enabled: true
+
+Layout/MultilineMethodArgumentLineBreaks:
+  Enabled: true
+
+Lint:
+  Enabled: true
+
 Naming:
   Enabled: true
 
-Naming/UncommunicativeMethodParamName:
+RSpec/Be:
+  Enabled: true
+
+RSpec/BeforeAfterAll:
+  Enabled: true
+
+RSpec/EmptyExampleGroup:
+  Enabled: true
+
+RSpec/EmptyLineAfterExample:
+  Enabled: true
+
+RSpec/EmptyLineAfterExampleGroup:
+  Enabled: true
+
+RSpec/EmptyLineAfterFinalLet:
+  Enabled: true
+
+RSpec/EmptyLineAfterHook:
+  Enabled: true
+
+RSpec/EmptyLineAfterSubject:
+  Enabled: true
+
+RSpec/HookArgument:
+  Enabled: true
+
+RSpec/LeadingSubject:
+  Enabled: true
+
+RSpec/NamedSubject:
+  Enabled: true
+
+RSpec/ScatteredLet:
+  Enabled: true
+
+RSpec/ScatteredSetup:
+  Enabled: true
+
+Naming/MethodParameterName:
   AllowedNames:
     - rp
 
@@ -38,9 +93,6 @@ Security:
 Style/BlockComments:
   Enabled: true
 
-Style/BracesAroundHashParameters:
-  Enabled: true
-
 Style/CaseEquality:
   Enabled: true
 
@@ -146,9 +198,15 @@ Style/RedundantException:
 Style/RedundantFreeze:
   Enabled: true
 
+Style/RedundantInterpolation:
+  Enabled: true
+
 Style/RedundantParentheses:
   Enabled: true
 
+Style/RedundantPercentQ:
+  Enabled: true
+
 Style/RedundantReturn:
   Enabled: true
 
@@ -182,12 +240,6 @@ Style/TrailingMethodEndStatement:
 Style/TrivialAccessors:
   Enabled: true
 
-Style/UnneededInterpolation:
-  Enabled: true
-
-Style/UnneededPercentQ:
-  Enabled: true
-
 Style/UnpackFirst:
   Enabled: true
 

data/.travis.yml

@@ -1,35 +1,39 @@
-dist: xenial
+dist: bionic
 language: ruby
-cache: bundler
 
-rvm:
-  - ruby-head
-  - 2.7.0-preview1
-  - 2.6.4
-  - 2.5.6
-  - 2.4.7
-  - 2.3.8
+cache:
+  bundler: true
+  directories:
+    - /home/travis/.rvm/
+
+env:
+  - LIBSSL=1.1 RB=2.7.1
+  - LIBSSL=1.1 RB=2.6.6
+  - LIBSSL=1.1 RB=2.5.8
+  - LIBSSL=1.1 RB=2.4.10
+  - LIBSSL=1.1 RB=ruby-head
+  - LIBSSL=1.0 RB=2.7.1
+  - LIBSSL=1.0 RB=2.6.6
+  - LIBSSL=1.0 RB=2.5.8
+  - LIBSSL=1.0 RB=2.4.10
+  - LIBSSL=1.0 RB=ruby-head
 
 gemfile:
   - gemfiles/cose_head.gemfile
   - gemfiles/openssl_head.gemfile
+  - gemfiles/openssl_2_2.gemfile
   - gemfiles/openssl_2_1.gemfile
   - gemfiles/openssl_2_0.gemfile
 
 matrix:
   fast_finish: true
   allow_failures:
-    - rvm: ruby-head
-    - rvm: 2.7.0-preview1
+    - env: LIBSSL=1.1 RB=ruby-head
+    - env: LIBSSL=1.0 RB=ruby-head
     - gemfile: gemfiles/cose_head.gemfile
     - gemfile: gemfiles/openssl_head.gemfile
 
 before_install:
-  - wget http://archive.ubuntu.com/ubuntu/pool/universe/f/faketime/libfaketime_0.9.7-3_amd64.deb
-  - sudo dpkg -i libfaketime_0.9.7-3_amd64.deb
+  - ./script/ci/install-openssl
+  - ./script/ci/install-ruby
   - gem install bundler -v "~> 2.0"
-
-before_script:
-  - export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/faketime/libfaketime.so.1
-  - export DONT_FAKE_MONOTONIC=1
-  - export FAKETIME_NO_CACHE=1

data/Appraisals

@@ -8,6 +8,10 @@ appraise "openssl_head" do
   gem "openssl", git: "https://github.com/ruby/openssl"
 end
 
+appraise "openssl_2_2" do
+  gem "openssl", "~> 2.2.0"
+end
+
 appraise "openssl_2_1" do
   gem "openssl", "~> 2.1.0"
 end

data/CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
 
-## [v2.0.0.beta1] - 2019-09-16
+## [v2.3.0] - 2020-06-27
+
+### Added
+
+- Ability to access extension outputs with `PublicKeyCredential#client_extension_outputs` and `PublicKeyCredential#authenticator_extension_outputs` ([@santiagorodriguez96])
+
+## [v2.2.1] - 2020-06-06
+
+### Fixed
+
+- Fixed compatibility with OpenSSL-C (libssl) v1.0.2 ([@santiagorodriguez96])
+
+## [v2.2.0] - 2020-03-14
+
+### Added
+
+- Verification step that checks the received credential public key algorithm during registration matches one of the configured algorithms
+- [EXPERIMENTAL] Attestation trustworthiness verification default steps for "tpm", "android-key" and "android-safetynet" ([@bdewater], [@padulafacundo]). Still manual configuration needed for "packed" and "fido-u2f".
+
+Note: Expect possible breaking changes for "EXPERIMENTAL" features.
+
+## [v2.1.0] - 2019-12-30
+
+### Added
+
+- Ability to convert stored credential public key back to a ruby object with `WebAuthn::PublicKey.deserialize(stored_public_key)`, included the validation during de-serialization ([@ssuttner], [@padulafacundo])
+- Improved TPM attestation validation by checking "Subject Alternative Name" ([@bdewater])
+- Improved SafetyNet attestation validation by checking timestamp ([@padulafacundo])
+- [EXPERIMENTAL] Ability to optionally "Assess the attestation trustworthiness" during registration by setting `acceptable_attestation_types` and `attestation_root_certificates_finders` configuration values ([@padulafacundo])
+- Ruby 2.7 support without warnings
+
+Note: Expect possible breaking changes for "EXPERIMENTAL" features.
+
+## [v2.0.0] - 2019-10-03
 
 ### Added
 
@@ -13,7 +46,7 @@
   - All the above automatically handle encoding/decoding for necessary values. The specific encoding scheme can
     be set (or even turned off) in `WebAutnn.configuration.encoding=`. Defaults to `:base64url`.
 - `WebAuthn::FakeClient#get` better fakes a real client by including `userHandle` in the returned hash.
-- Expose AAGUID and attestationCertificateKey for MDS lookup during attestation (@bdwater)
+- Expose AAGUID and attestationCertificateKey for MDS lookup during attestation ([@bdewater])
 
 ### Changed
 
@@ -21,8 +54,9 @@
 Please replace with `public_key:` and `sign_count:` keyword arguments. If you're not performing sign count
 verification, signal opt-out with `sign_count: false`.
 
-- `WebAuthn::FakeClient#create` and `WebAuthn::FakeClient#get` better fakes a real client by using camelBack string
-keys instead of snake_case symbol keys in the returned hash.
+- `WebAuthn::FakeClient#create` and `WebAuthn::FakeClient#get` better fakes a real client by using lowerCamelCase
+string keys instead of snake_case symbol keys in the returned hash.
+
 - `WebAuthn::FakeClient#create` and `WebAuthn::FakeClient#get` better fakes a real client by not padding the
 returned base64url-encoded `id` value.
 
@@ -45,8 +79,8 @@ pass it.
 Please replace with `public_key:` and `sign_count:` keyword arguments. If you're not performing sign count
 verification, signal opt-out with `sign_count: false`.
 
-- `WebAuthn::FakeClient#create` and `WebAuthn::FakeClient#get` better fakes a real client by using camelBack string
-keys instead of snake_case symbol keys in the returned hash.
+- `WebAuthn::FakeClient#create` and `WebAuthn::FakeClient#get` better fakes a real client by using lowerCamelCase
+string keys instead of snake_case symbol keys in the returned hash.
 
 - `WebAuthn::FakeClient#create` and `WebAuthn::FakeClient#get` better fakes a real client by not padding the
 returned base64url-encoded `id` value.
@@ -55,23 +89,23 @@ returned base64url-encoded `id` value.
 
 ### Added
 
-- Ability to migrate U2F credentials to WebAuthn ([#211](https://github.com/cedarcode/webauthn-ruby/pull/211)) (@bdewater + @jdongelmans)
-- Ability to skip attestation statement verification ([#219](https://github.com/cedarcode/webauthn-ruby/pull/219)) (@MaximeNdutiye)
-- Ability to configure default credential options timeout ([#243](https://github.com/cedarcode/webauthn-ruby/pull/243)) (@MaximeNdutiye)
+- Ability to migrate U2F credentials to WebAuthn ([#211](https://github.com/cedarcode/webauthn-ruby/pull/211)) ([@bdewater] + [@jdongelmans])
+- Ability to skip attestation statement verification ([#219](https://github.com/cedarcode/webauthn-ruby/pull/219)) ([@MaximeNdutiye])
+- Ability to configure default credential options timeout ([#243](https://github.com/cedarcode/webauthn-ruby/pull/243)) ([@MaximeNdutiye])
 - AttestedCredentialData presence verification ([#237](https://github.com/cedarcode/webauthn-ruby/pull/237))
 - FakeClient learns how to increment sign count ([#225](https://github.com/cedarcode/webauthn-ruby/pull/225))
 
 ### Fixed
 
-- Properly verify SafetyNet certificates from input ([#233](https://github.com/cedarcode/webauthn-ruby/pull/233)) (@bdewater)
-- FakeClient default origin URL ([#242](https://github.com/cedarcode/webauthn-ruby/pull/242)) (@kalebtesfay)
+- Properly verify SafetyNet certificates from input ([#233](https://github.com/cedarcode/webauthn-ruby/pull/233)) ([@bdewater])
+- FakeClient default origin URL ([#242](https://github.com/cedarcode/webauthn-ruby/pull/242)) ([@kalebtesfay])
 
 ## [v1.17.0] - 2019-06-18
 
 ### Added
 
-- Support ES384, ES512, PS384, PS512, RS384 and RS512 credentials. Off by default. Enable by adding any of them to `WebAuthn.configuration.algorithms` array. Thank you @bdewater.
-- Support [Signature Counter](https://www.w3.org/TR/webauthn/#signature-counter) verification. Thank you @bdewater.
+- Support ES384, ES512, PS384, PS512, RS384 and RS512 credentials. Off by default. Enable by adding any of them to `WebAuthn.configuration.algorithms` array ([@bdewater])
+- Support [Signature Counter](https://www.w3.org/TR/webauthn/#signature-counter) verification ([@bdewater])
 
 ## [v1.16.0] - 2019-06-13
 
@@ -79,7 +113,7 @@ returned base64url-encoded `id` value.
 
 - Ability to enforce [user verification](https://www.w3.org/TR/webauthn/#user-verification) with extra argument in the `#verify` method.
 - Support RS1 (RSA w/ SHA-1) credentials. Off by default. Enable by adding `"RS1"` to `WebAuthn.configuration.algorithms` array.
-- Support PS256 (RSA Probabilistic Signature Scheme w/ SHA-256) credentials. On by default. Thank you @bdewater.
+- Support PS256 (RSA Probabilistic Signature Scheme w/ SHA-256) credentials. On by default ([@bdewater])
 
 ## [v1.15.0] - 2019-05-16
 
@@ -101,11 +135,11 @@ returned base64url-encoded `id` value.
 - Verify 'none' attestation statement is really empty.
 - Verify 'packed' attestation statement certificates start/end dates.
 - Verify 'packed' attestation statement signature algorithm.
-- Verify 'fiod-u2f attestation statement AAGUID is zeroed out. Thank you @bdewater.
+- Verify 'fiod-u2f attestation statement AAGUID is zeroed out ([@bdewater])
 - Verify 'android-key' attestation statement signature algorithm.
 - Verify assertion response signature algorithm.
 - Verify collectedClientData.tokenBinding format.
-- `WebAuthn.credential_creation_options` now accept `rp_name`, `user_id`, `user_name` and `display_name` as keyword arguments. Thank you @bdewater.
+- `WebAuthn.credential_creation_options` now accept `rp_name`, `user_id`, `user_name` and `display_name` as keyword arguments ([@bdewater])
 
 ## [v1.12.0] - 2019-04-03
 
@@ -127,11 +161,11 @@ Note #2: You don't need to do any convesion before passing the public key in `Au
 
 ### Added
 
-- `WebAuthn::AuthenticatorAttestationResponse#verify` supports `android-key` attestation statements. Thank you @bdewater!
+- `WebAuthn::AuthenticatorAttestationResponse#verify` supports `android-key` attestation statements ([@bdewater])
 
 ### Fixed
 
-- Verify matching AAGUID if needed when verifying `packed` attestation statements. Thank you @bdewater!
+- Verify matching AAGUID if needed when verifying `packed` attestation statements ([@bdewater])
 
 ## [v1.10.0] - 2019-03-05
 
@@ -149,7 +183,7 @@ Note #2: You don't need to do any convesion before passing the public key in `Au
 
 ### Added
 
-- Make challenge validation inside `#valid?` method resistant to timing attacks. Thank you @tomek-bt!
+- Make challenge validation inside `#valid?` method resistant to timing attacks (@tomek-bt)
 - Support for ruby 2.6
 
 ### Changed
@@ -161,7 +195,7 @@ Note #2: You don't need to do any convesion before passing the public key in `Au
 ### Added
 
 - _Registration_ ceremony
-  - `WebAuthn::AuthenticatorAttestationResponse` exposes attestation type and trust path via `#attestation_type` and `#attestation_trust_path` methods. Thank you @bdewater!
+  - `WebAuthn::AuthenticatorAttestationResponse` exposes attestation type and trust path via `#attestation_type` and `#attestation_trust_path` methods ([@bdewater])
 
 ## [v1.6.0] - 2018-11-01
 
@@ -173,21 +207,21 @@ Note #2: You don't need to do any convesion before passing the public key in `Au
 
 ### Added
 
-- Works with ruby 2.3. Thank you @bdewater!
+- Works with ruby 2.3 ([@bdewater])
 
 ## [v1.4.0] - 2018-10-11
 
 ### Added
 
 - _Registration_ ceremony
-  - `WebAuthn::AuthenticatorAttestationResponse.valid?` supports `android-safetynet` attestation statements. Thank you @bdewater!
+  - `WebAuthn::AuthenticatorAttestationResponse.valid?` supports `android-safetynet` attestation statements ([@bdewater])
 
 ## [v1.3.0] - 2018-10-11
 
 ### Added
 
 - _Registration_ ceremony
-  - `WebAuthn::AuthenticatorAttestationResponse.valid?` supports `packed` attestation statements. Thank you @sorah!
+  - `WebAuthn::AuthenticatorAttestationResponse.valid?` supports `packed` attestation statements ([@sorah])
 
 ## [v1.2.0] - 2018-10-08
 
@@ -205,7 +239,7 @@ Note: Both additions should help making it compatible with Chrome for Android 70
 ### Added
 
 - _Registration_ ceremony
-  - `WebAuthn::AuthenticatorAttestationResponse.valid?` optionally accepts rp_id. Thank you @sorah!
+  - `WebAuthn::AuthenticatorAttestationResponse.valid?` optionally accepts rp_id ([@sorah])
 - _Authentication_ ceremony
   - `WebAuthn::AuthenticatorAssertionResponse.valid?` optionally accepts rp_id.
 
@@ -260,7 +294,11 @@ Note: Both additions should help making it compatible with Chrome for Android 70
   - `WebAuthn::AuthenticatorAttestationResponse.valid?` can be used to validate fido-u2f attestations returned by the browser
 - Works with ruby 2.5
 
-[v2.0.0.beta1]: https://github.com/cedarcode/webauthn-ruby/compare/v1.18.0...v2.0.0.beta1/
+[v2.3.0]: https://github.com/cedarcode/webauthn-ruby/compare/v2.2.1...v2.3.0/
+[v2.2.1]: https://github.com/cedarcode/webauthn-ruby/compare/v2.2.0...v2.2.1/
+[v2.2.0]: https://github.com/cedarcode/webauthn-ruby/compare/v2.1.0...v2.2.0/
+[v2.1.0]: https://github.com/cedarcode/webauthn-ruby/compare/v2.0.0...v2.1.0/
+[v2.0.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.18.0...v2.0.0/
 [v1.18.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.17.0...v1.18.0/
 [v1.17.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.16.0...v1.17.0/
 [v1.16.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.15.0...v1.16.0/
@@ -282,3 +320,12 @@ Note: Both additions should help making it compatible with Chrome for Android 70
 [v1.0.0]: https://github.com/cedarcode/webauthn-ruby/compare/v0.2.0...v1.0.0/
 [v0.2.0]: https://github.com/cedarcode/webauthn-ruby/compare/v0.1.0...v0.2.0/
 [v0.1.0]: https://github.com/cedarcode/webauthn-ruby/compare/v0.0.0...v0.1.0/
+
+[@bdewater]: https://github.com/bdewater
+[@jdongelmans]: https://github.com/jdongelmans
+[@kalebtesfay]: https://github.com/kalebtesfay
+[@MaximeNdutiye]: https://github.com/MaximeNdutiye
+[@sorah]: https://github.com/sorah
+[@ssuttner]: https://github.com/ssuttner
+[@padulafacundo]: https://github.com/padulafacundo
+[@santiagorodriguez96]: https://github.com/santiagorodriguez96

data/CONTRIBUTING.md

@@ -14,11 +14,6 @@
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests and code-style checks. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-Some tests require stubbing time with [libfaketime](https://github.com/wolfcw/libfaketime) in order to pass, otherwise they're skipped. You can install this library with your package manager. Follow libfaketime's instructions for your OS to preload the library before running the tests, and use the `DONT_FAKE_MONOTONIC=1 FAKETIME_NO_CACHE=1` options. E.g. when installed via homebrew on macOS:
-```shell
-DYLD_INSERT_LIBRARIES=/usr/local/Cellar/libfaketime/2.9.7_1/lib/faketime/libfaketime.1.dylib DYLD_FORCE_FLAT_NAMESPACE=1 DONT_FAKE_MONOTONIC=1 FAKETIME_NO_CACHE=1 bundle exec rspec
-```
-
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ### Styleguide

data/README.md

@@ -1,5 +1,5 @@
 __Note__: You are viewing the README for the development version of webauthn-ruby.
-For the current release version see https://github.com/cedarcode/webauthn-ruby/blob/1-stable/README.md.
+For the current release version see https://github.com/cedarcode/webauthn-ruby/blob/2-stable/README.md.
 
 # webauthn-ruby
 
@@ -64,12 +64,12 @@ Known conformant pairs are, for example:
 - Google Chrome for Android 70+ and Android's Fingerprint-based platform authenticator
 - Microsoft Edge and Windows 10 platform authenticator
 - Mozilla Firefox for Desktop and Yubico's Security Key roaming authenticator via USB
+- Safari in iOS 13.3+ and YubiKey 5 NFC via NFC
 
-For a detailed picture about what is conformant and what not, you can refer to:
-
-- [apowers313/fido2-webauthn-status](https://github.com/apowers313/fido2-webauthn-status)
-- [FIDO certified products](https://fidoalliance.org/certification/fido-certified-products)
+For a complete list:
 
+- User Agents (Clients): [Can I Use: Web Authentication API](https://caniuse.com/#search=webauthn)
+- Authenticators: [FIDO certified products](https://fidoalliance.org/certification/fido-certified-products) (search for Type=Authenticator and Specification=FIDO2)
 
 ## Install
 
@@ -108,11 +108,11 @@ WebAuthn.configure do |config|
   config.rp_name = "Example Inc."
 
   # Optionally configure a client timeout hint, in milliseconds.
-  # This hint specifies how long the browser should wait for an
-  # attestation or an assertion response.
+  # This hint specifies how long the browser should wait for any
+  # interaction with the user.
   # This hint may be overridden by the browser.
   # https://www.w3.org/TR/webauthn/#dom-publickeycredentialcreationoptions-timeout
-  config.credential_options_timeout = 120000
+  # config.credential_options_timeout = 120_000
 
   # You can optionally specify a different Relying Party ID
   # (https://www.w3.org/TR/webauthn/#relying-party-identifier)
@@ -127,7 +127,12 @@ WebAuthn.configure do |config|
   # used in your client-side (user agent) code before sending the credential to the server.
   # Supported values: `:base64url` (default), `:base64` or `false` to disable all encoding.
   #
-  # config.encoding = false
+  # config.encoding = :base64url
+
+  # Possible values: "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "RS1"
+  # Default: ["ES256", "PS256", "RS256"]
+  #
+  # config.algorithms << "ES384"
 end
 ```
 
@@ -145,7 +150,7 @@ if !user.webauthn_id
 end
 
 options = WebAuthn::Credential.options_for_create(
-  user: { id: user.webauthn_id, name: user.name }
+  user: { id: user.webauthn_id, name: user.name },
   exclude: user.credentials.map { |c| c.webauthn_id }
 )
 
@@ -247,25 +252,177 @@ rescue WebAuthn::Error => e
 end
 ```
 
+### Extensions
+
+> The mechanism for generating public key credentials, as well as requesting and generating Authentication assertions, as defined in Web Authentication API, can be extended to suit particular use cases. Each case is addressed by defining a registration extension and/or an authentication extension.
+
+> When creating a public key credential or requesting an authentication assertion, a WebAuthn Relying Party can request the use of a set of extensions. These extensions will be invoked during the requested ceremony if they are supported by the WebAuthn Client and/or the WebAuthn Authenticator. The Relying Party sends the client extension input for each extension in the get() call (for authentication extensions) or create() call (for registration extensions) to the WebAuthn client. [[source](https://www.w3.org/TR/webauthn-2/#sctn-extensions)]
+
+Extensions can be requested in the initiation phase in both Credential Registration and Authentication ceremonies by adding the extension parameter when generating the options for create/get:
+
+```ruby
+# Credential Registration
+creation_options = WebAuthn::Credential.options_for_create(
+  user: { id: user.webauthn_id, name: user.name },
+  exclude: user.credentials.map { |c| c.webauthn_id },
+  extensions: { appidExclude: domain.to_s }
+)
+
+# OR
+
+# Credential Authentication
+options = WebAuthn::Credential.options_for_get(
+  allow: user.credentials.map { |c| c.webauthn_id },
+  extensions: { appid: domain.to_s }
+)
+```
+
+Consequently, after these `options` are sent to the WebAuthn client:
+
+> The WebAuthn client performs client extension processing for each extension that the client supports, and augments the client data as specified by each extension, by including the extension identifier and client extension output values.
+
+> For authenticator extensions, as part of the client extension processing, the client also creates the CBOR authenticator extension input value for each extension (often based on the corresponding client extension input value), and passes them to the authenticator in the create() call (for registration extensions) or the get() call (for authentication extensions).
+
+> The authenticator, in turn, performs additional processing for the extensions that it supports, and returns the CBOR authenticator extension output for each as specified by the extension. Part of the client extension processing for authenticator extensions is to use the authenticator extension output as an input to creating the client extension output. [[source](https://www.w3.org/TR/webauthn-2/#sctn-extensions)]
+
+Finally, you can check the values returned for each extension by calling `client_extension_outputs` and `authenticator_extension_outputs` respectively.
+For example, following the initialization phase for the Credential Authentication ceremony specified in the above example:
+
+```ruby
+webauthn_credential = WebAuthn::Credential.from_get(credential_get_result_hash)
+
+webauthn_credential.client_extension_outputs #=> { "appid" => true }
+webauthn_credential.authenticator_extension_outputs #=> nil
+```
+
+A list of all currently defined extensions:
+
+  - [Last published version](https://www.w3.org/TR/webauthn-2/#sctn-defined-extensions)
+  - [Next version (in draft)](https://w3c.github.io/webauthn/#sctn-defined-extensions)
+
 ## API
 
-_Pending_
+#### `WebAuthn.generate_user_id`
+
+Generates a [WebAuthn User Handle](https://www.w3.org/TR/webauthn-2/#user-handle) that follows the WebAuthn spec recommendations.
+
+```ruby
+WebAuthn.generate_user_id # "lWoMZTGf_ml2RoY5qPwbwrkxrvTqWjGOxEoYBgxft3zG-LlrICvE-y8bxFi06zMyIOyNsJoWx4Fa2TOqoRmnxA"
+```
+
+#### `WebAuthn::Credential.options_for_create(options)`
+
+Helper method to build the necessary [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialcreationoptions)
+to be used in the client-side code to call `navigator.credentials.create({ "publicKey": publicKeyCredentialCreationOptions })`.
+
+```ruby
+creation_options = WebAuthn::Credential.options_for_create(
+  user: { id: user.webauthn_id, name: user.name }
+  exclude: user.credentials.map { |c| c.webauthn_id }
+)
+
+# Store the newly generated challenge somewhere so you can have it
+# for the verification phase.
+session[:creation_challenge] = creation_options.challenge
+
+# Send `creation_options` back to the browser, so that they can be used
+# to call `navigator.credentials.create({ "publicKey": creationOptions })`
+#
+# You can call `creation_options.as_json` to get a ruby hash with a JSON representation if needed.
+
+# If inside a Rails controller, `render json: creation_options` will just work.
+# I.e. it will encode and convert the options to JSON automatically.
+```
 
-## Attestation Statement Formats
+#### `WebAuthn::Credential.options_for_get([options])`
+
+Helper method to build the necessary [PublicKeyCredentialRequestOptions](https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialrequestoptions)
+to be used in the client-side code to call `navigator.credentials.get({ "publicKey": publicKeyCredentialRequestOptions })`.
+
+```ruby
+request_options = WebAuthn::Credential.options_for_get(allow: user.credentials.map { |c| c.webauthn_id })
+
+# Store the newly generated challenge somewhere so you can have it
+# for the verification phase.
+session[:authentication_challenge] = request_options.challenge
+
+# Send `request_options` back to the browser, so that they can be used
+# to call `navigator.credentials.get({ "publicKey": requestOptions })`
+
+# You can call `request_options.as_json` to get a ruby hash with a JSON representation if needed.
+
+# If inside a Rails controller, `render json: request_options` will just work.
+# I.e. it will encode and convert the options to JSON automatically.
+```
+
+#### `WebAuthn::Credential.from_create(credential_create_result)`
+
+```ruby
+credential_with_attestation = WebAuthn::Credential.from_create(params[:publicKeyCredential])
+```
+
+#### `WebAuthn::Credential.from_get(credential_get_result)`
+
+```ruby
+credential_with_assertion = WebAuthn::Credential.from_get(params[:publicKeyCredential])
+```
+
+#### `PublicKeyCredentialWithAttestation#verify(challenge)`
+
+Verifies the created WebAuthn credential is [valid](https://www.w3.org/TR/webauthn-2/#sctn-registering-a-new-credential).
+
+```ruby
+credential_with_attestation.verify(session[:creation_challenge])
+```
+
+#### `PublicKeyCredentialWithAssertion#verify(challenge, public_key:, sign_count:)`
+
+Verifies the asserted WebAuthn credential is [valid](https://www.w3.org/TR/webauthn-2/#sctn-verifying-assertion).
+
+Mainly, that the client provided a valid cryptographic signature for the corresponding stored credential public
+key, among other extra validations.
+
+```ruby
+credential_with_assertion.verify(
+  session[:authentication_challenge],
+  public_key: stored_credential.public_key,
+  sign_count: stored_credential.sign_count
+)
+```
+
+#### `PublicKeyCredential#client_extension_outputs`
+
+```ruby
+credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])
+
+credential.client_extension_outputs
+```
+
+#### `PublicKeyCredential#authenticator_extension_outputs`
+
+```ruby
+credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])
+
+credential.authenticator_extension_outputs
+```
+
+## Attestation
+
+### Attestation Statement Format
 
 | Attestation Statement Format | Supported? |
 | -------- | :--------: |
 | packed (self attestation) | Yes |
 | packed (x5c attestation) | Yes |
-| packed (ECDAA attestation) | No |
 | tpm (x5c attestation) | Yes |
-| tpm (ECDAA attestation) | No |
 | android-key | Yes |
 | android-safetynet | Yes |
 | fido-u2f | Yes |
 | none | Yes |
 
-NOTE: Be aware that it is up to you to do "trust path validation" (steps 15 and 16 in [Registering a new credential](https://www.w3.org/TR/webauthn/#registering-a-new-credential)) if that's a requirement of your Relying Party policy. The gem doesn't perform that validation for you right now.
+### Attestation Types
+
+You can define what trust policy to enforce by setting `acceptable_attestation_types` config to a subset of `['None', 'Self', 'Basic', 'AttCA', 'Basic_or_AttCA']` and `attestation_root_certificates_finders` to an object that responds to `#find` and returns the corresponding root certificate for each registration. The `#find` method will be called passing keyword arguments `attestation_format`, `aaguid` and `attestation_certificate_key_id`.
 
 ## Testing Your Integration