webauthn 1.18.0 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a6a15357ab32b764ce0694b5a6cc4950e9298e377c8a93f8b664befb67dffcb
-  data.tar.gz: 3481eba4bbdd21676eda5015c9ebc9d11a92422ab0d57b6fed1da31b2ebc9d14
+  metadata.gz: 6181693e3c34f1ca289fb2056df36c35a5e144076288eef34e774e2dfc1794b5
+  data.tar.gz: 87883fa3fe7c7bd5da885025b7a571dfedfdfe1c27c6a5c8edeee54956bd98bc
 SHA512:
-  metadata.gz: 78f3d1242e008dac5a7d1b66944f6e64dd2a11baced08a454ca587d5bb7b5a93b2e51052d044f8c34034355ab2536af96438b9178e9b6536e92366cd55fbe495
-  data.tar.gz: 1e4ecf4a58bad0213e0893834f57f5564ce9b2d9d76ad214e35a85d7ede4d693d0d9f55a289fe998ac4ee4479279d7c521afef98fd7ddce1eec1f849d346948d
+  metadata.gz: a69f7870a89344a5d00b1c75b55dd6e25741719bf2fd79d03e83348530a964ef237f8330dea55edbb58b9fe5ee0522f2f41b5d9d46f7d975112b9dd8a05889bd
+  data.tar.gz: 19b32618b9e83e2618abe361aca398933030fe2963502c8a9054dc291b22678107e3257be5d7a711bdf0d826dc1d444e28d726282fa6306abf336f675e3794df

data/.rubocop.yml

@@ -1,3 +1,7 @@
+inherit_mode:
+  merge:
+    - AllowedNames
+
 AllCops:
   TargetRubyVersion: 2.3
   DisabledByDefault: true
@@ -24,6 +28,10 @@ Metrics/LineLength:
 Naming:
   Enabled: true
 
+Naming/UncommunicativeMethodParamName:
+  AllowedNames:
+    - rp
+
 Security:
   Enabled: true
 

data/.travis.yml

@@ -5,12 +5,14 @@ cache: bundler
 rvm:
   - ruby-head
   - 2.7.0-preview1
-  - 2.6.3
-  - 2.5.5
-  - 2.4.6
+  - 2.6.4
+  - 2.5.6
+  - 2.4.7
   - 2.3.8
 
 gemfile:
+  - gemfiles/cose_head.gemfile
+  - gemfiles/openssl_head.gemfile
   - gemfiles/openssl_2_1.gemfile
   - gemfiles/openssl_2_0.gemfile
 
@@ -19,6 +21,8 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: 2.7.0-preview1
+    - 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

data/Appraisals

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+appraise "cose_head" do
+  gem "cose", git: "https://github.com/cedarcode/cose-ruby"
+end
+
+appraise "openssl_head" do
+  gem "openssl", git: "https://github.com/ruby/openssl"
+end
+
 appraise "openssl_2_1" do
   gem "openssl", "~> 2.1.0"
 end

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [v2.0.0.beta1] - 2019-09-16
+
+### Added
+
+- Smarter new public API methods:
+  - `WebAuthn.generate_user_id`
+  - `WebAuthn::Credential.options_for_create`
+  - `WebAuthn::Credential.options_for_get`
+  - `WebAuthn::Credential.from_create`
+  - `WebAuthn::Credential.from_get`
+  - 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)
+
+### Changed
+
+- `WebAuthn::AuthenticatorAssertionResponse#verify` no longer accepts `allowed_credentials:` keyword argument.
+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 not padding the
+returned base64url-encoded `id` value.
+
+### Deprecated
+
+- `WebAuthn.credential_creation_options` method. Please consider using `WebAuthn::Credential.options_for_create`.
+- `WebAuthn.credential_request_options` method. Please consider using `WebAuthn::Credential.options_for_get`.
+
+### Removed
+
+- `WebAuthn::AuthenticatorAssertionResponse.new` no longer accepts `credential_id`. No replacement needed, just don't
+pass it.
+
+### BREAKING CHANGES
+
+- `WebAuthn::AuthenticatorAssertionResponse.new` no longer accepts `credential_id`. No replacement needed, just don't
+pass it.
+
+- `WebAuthn::AuthenticatorAssertionResponse#verify` no longer accepts `allowed_credentials:` keyword argument.
+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 not padding the
+returned base64url-encoded `id` value.
+
 ## [v1.18.0] - 2019-07-27
 
 ### Added
@@ -209,6 +260,7 @@ 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/
 [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/

data/README.md

@@ -1,6 +1,9 @@
+__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.
+
 # webauthn-ruby
 
-![banner](webauthn-ruby.png)
+![banner](assets/webauthn-ruby.png)
 
 [![Gem](https://img.shields.io/gem/v/webauthn.svg?style=flat-square)](https://rubygems.org/gems/webauthn)
 [![Travis](https://img.shields.io/travis/cedarcode/webauthn-ruby/master.svg?style=flat-square)](https://travis-ci.org/cedarcode/webauthn-ruby)
@@ -30,7 +33,9 @@ a user [credential](https://www.w3.org/TR/webauthn/#public-key-credential), incl
 
 ## Security
 
-If you have discovered a security bug, please send an email to security@cedarcode.com instead of posting to the GitHub issue tracker.
+Please report security vulnerabilities to security@cedarcode.com.
+
+_More_: [SECURITY](SECURITY.md)
 
 ## Background
 
@@ -117,126 +122,129 @@ WebAuthn.configure do |config|
   # the suffix "example.com"
   #
   # config.rp_id = "example.com"
+
+  # Configure preferred binary-to-text encoding scheme. This should match the encoding scheme
+  # 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
 end
 ```
 
-### Registration
+### Credential Registration
+
+> The ceremony where a user, a Relying Party, and the user’s client (containing at least one authenticator) work in concert to create a public key credential and associate it with the user’s Relying Party account. Note that this includes employing a test of user presence or user verification.
+> [[source](https://www.w3.org/TR/webauthn-2/#registration-ceremony)]
 
 #### Initiation phase
 
 ```ruby
-credential_creation_options = WebAuthn.credential_creation_options
+# Generate and store the WebAuthn User ID the first time the user registers a credential
+if !user.webauthn_id
+  user.update!(webauthn_id: WebAuthn.generate_user_id)
+end
+
+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] = options.challenge
+
+# Send `options` back to the browser, so that they can be used
+# to call `navigator.credentials.create({ "publicKey": options })`
 #
-# You can read it from the resulting options:
-credential_creation_options[:challenge]
+# You can call `options.as_json` to get a ruby hash with a JSON representation if needed.
 
-# Send `credential_creation_options` to the browser, so that they can be used
-# to call `navigator.credentials.create({ "publicKey": credentialCreationOptions })`
+# If inside a Rails controller, `render json: options` will just work.
+# I.e. it will encode and convert the options to JSON automatically.
+
+# For your frontend code, you might find @github/webauthn-json npm package useful.
+# Especially for handling the necessary decoding of the options, and sending the
+# `PublicKeyCredential` object back to the server.
 ```
 
 #### Verification phase
 
 ```ruby
-# These should be ruby `String`s encoded as binary data, e.g. `Encoding:ASCII-8BIT`.
-#
-# If the user-agent is a web browser, you would use some encoding algorithm to send what
-# `navigator.credentials.create` returned through the wire.
-#
-# Then you need to decode that data before passing it to the `#verify` method.
-#
-# E.g. in https://github.com/cedarcode/webauthn-rails-demo-app we use `Base64.strict_decode64`
-# on the user-agent encoded data before calling `#verify`
-attestation_object = "..."
-client_data_json = "..."
-
-attestation_response = WebAuthn::AuthenticatorAttestationResponse.new(
-  attestation_object: attestation_object,
-  client_data_json: client_data_json
-)
-
+# Assuming you're using @github/webauthn-json package to send the `PublicKeyCredential` object back
+# in params[:publicKeyCredential]:
+webauthn_credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])
 
 begin
-  attestation_response.verify(expected_challenge)
-
-  # 1. Register the new user and
-  # 2. Keep Credential ID, Credential Public Key and Sign Count under storage
-  #    for future authentications
-  #    Access by invoking:
-  #      `attestation_response.credential.id`
-  #      `attestation_response.credential.public_key`
-  #      `attestation_response.authenticator_data.sign_count`
-rescue WebAuthn::VerificationError => e
+  webauthn_credential.verify(session[:creation_challenge])
+
+  # Store Credential ID, Credential Public Key and Sign Count for future authentications
+  user.credentials.create!(
+    webauthn_id: webauthn_credential.id,
+    public_key: webauthn_credential.public_key,
+    sign_count: webauthn_credential.sign_count
+  )
+rescue WebAuthn::Error => e
   # Handle error
 end
 ```
 
-### Authentication
+### Credential Authentication
 
-#### Initiation phase
+> The ceremony where a user, and the user’s client (containing at least one authenticator) work in concert to cryptographically prove to a Relying Party that the user controls the credential private key associated with a previously-registered public key credential (see Registration). Note that this includes a test of user presence or user verification. [[source](https://www.w3.org/TR/webauthn-2/#authentication-ceremony)]
 
-Assuming you have the previously stored Credential ID, now in variable `credential_id`
+#### Initiation phase
 
 ```ruby
-credential_request_options = WebAuthn.credential_request_options
-credential_request_options[:allowCredentials] << { id: credential_id, type: "public-key" }
+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.
-#
-# You can read it from the resulting options:
-credential_request_options[:challenge]
+session[:authentication_challenge] = options.challenge
+
+# Send `options` back to the browser, so that they can be used
+# to call `navigator.credentials.get({ "publicKey": options })`
+
+# You can call `options.as_json` to get a ruby hash with a JSON representation if needed.
+
+# If inside a Rails controller, `render json: options` will just work.
+# I.e. it will encode and convert the options to JSON automatically.
 
-# Send `credential_request_options` to the browser, so that they can be used
-# to call `navigator.credentials.get({ "publicKey": credentialRequestOptions })`
+# For your frontend code, you might find @github/webauthn-json npm package useful.
+# Especially for handling the necessary decoding of the options, and sending the
+# `PublicKeyCredential` object back to the server.
 ```
 
 #### Verification phase
 
-Assuming you have the previously stored Credential Public Key, now in variable `credential_public_key`
+You need to look up the stored credential for a user by matching the `id` attribute from the PublicKeyCredential 
+interface returned by the browser to the stored `credential_id`. The corresponding `public_key` and `sign_count` 
+attributes must be passed as keyword arguments to the `verify` method call.
 
 ```ruby
-# These should be ruby `String`s encoded as binary data, e.g. `Encoding:ASCII-8BIT`.
-#
-# If the user-agent is a web browser, you would use some encoding algorithm to send what
-# `navigator.credentials.get` returned through the wire.
-#
-# Then you need to decode that data before passing it to the `#verify` method.
-#
-# E.g. in https://github.com/cedarcode/webauthn-rails-demo-app we use `Base64.strict_decode64`
-# on the user-agent encoded data before calling `#verify`
-selected_credential_id = "..."
-authenticator_data = "..."
-client_data_json = "..."
-signature = "..."
-
-assertion_response = WebAuthn::AuthenticatorAssertionResponse.new(
-  credential_id: selected_credential_id,
-  authenticator_data: authenticator_data,
-  client_data_json: client_data_json,
-  signature: signature
-)
+# Assuming you're using @github/webauthn-json package to send the `PublicKeyCredential` object back
+# in params[:publicKeyCredential]:
+webauthn_credential = WebAuthn::Credential.from_get(params[:publicKeyCredential])
 
-# This hash must have the id and its corresponding public key of the
-# previously stored credential for the user that is attempting to sign in.
-allowed_credential = {
-  id: credential_id,
-  public_key: credential_public_key,
-  sign_count: sign_count,
-}
+stored_credential = user.credentials.find_by(webauthn_id: webauthn_credential.id)
 
 begin
-  assertion_response.verify(expected_challenge, allowed_credentials: [allowed_credential])
-
-  # Sign in the user
-rescue WebAuthn::VerificationError => e
+  webauthn_credential.verify(
+    session[:authentication_challenge],
+    public_key: stored_credential.public_key,
+    sign_count: stored_credential.sign_count
+  )
+
+  # Update the stored credential sign count with the value from `webauthn_credential.sign_count`
+  stored_credential.update!(sign_count: webauthn_credential.sign_count)
+
+  # Continue with successful sign in or 2FA verification...
+
+rescue WebAuthn::SignCountVerificationError => e
+  # Cryptographic verification of the authenticator data succeeded, but the signature counter was less then or equal
+  # to the stored value. This can have several reasons and depending on your risk tolerance you can choose to fail or
+  # pass authentication. For more information see https://www.w3.org/TR/webauthn/#sign-counter
+rescue WebAuthn::Error => e
   # Handle error
 end
-
-# Find the selected credential in your data storage using `selected_credential_id`
-# Update the stored sign count with the value from `assertion_response.authenticator_data.sign_count`
 ```
 
 ## API

data/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.18.z   | :white_check_mark: |
+| 1.17.z   | :white_check_mark: |
+| 1.16.z   | :white_check_mark: |
+| 1.15.z   | :white_check_mark: |
+| < 1.15   | :x:                |
+
+## Reporting a Vulnerability
+
+If you have discovered a security bug, please send an email to security@cedarcode.com
+instead of posting to the GitHub issue tracker.
+
+Thank you!

data/gemfiles/cose_head.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "cose", git: "https://github.com/cedarcode/cose-ruby"
+
+gemspec path: "../"

data/gemfiles/openssl_head.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "openssl", git: "https://github.com/ruby/openssl"
+
+gemspec path: "../"

data/lib/webauthn.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 require "webauthn/configuration"
+require "webauthn/credential"
 require "webauthn/credential_creation_options"
 require "webauthn/credential_request_options"
-require "webauthn/public_key_credential"
 require "webauthn/version"
+
+module WebAuthn
+  TYPE_PUBLIC_KEY = "public-key"
+
+  def self.generate_user_id
+    configuration.encoder.encode(SecureRandom.random_bytes(64))
+  end
+end

data/lib/webauthn/attestation_statement/android_safetynet.rb

@@ -20,6 +20,10 @@ module WebAuthn
           [WebAuthn::AttestationStatement::ATTESTATION_TYPE_BASIC, attestation_certificate]
       end
 
+      def attestation_certificate
+        attestation_response.certificate_chain[0]
+      end
+
       private
 
       # FIXME: This should be a responsibility of AndroidSafetynet::AttestationResponse#verify
@@ -46,10 +50,6 @@ module WebAuthn
         attestation_response.cts_profile_match?
       end
 
-      def attestation_certificate
-        attestation_response.certificate_chain[0]
-      end
-
       def signing_certificates
         attestation_response.certificate_chain[1..-1]
       end

data/lib/webauthn/attestation_statement/base.rb

@@ -26,6 +26,10 @@ module WebAuthn
         raise NotImpelementedError
       end
 
+      def attestation_certificate
+        attestation_certificate_chain&.first
+      end
+
       private
 
       attr_reader :statement
@@ -42,10 +46,6 @@ module WebAuthn
         end
       end
 
-      def attestation_certificate
-        attestation_certificate_chain&.first
-      end
-
       def attestation_certificate_chain
         @attestation_certificate_chain ||= raw_attestation_certificates&.map do |raw_certificate|
           OpenSSL::X509::Certificate.new(raw_certificate)