webauthn 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e9c0949f662e12a84d1810c564633cd6feec64b1f4ed9352a19260a1840d6fc
-  data.tar.gz: 30725d9ebd21ce4b77b548807a9c57014983e245183bc2c1179e7eb1580d0583
+  metadata.gz: 690e8753529b42c4acc5fa15f621c077ee9822c850aa19e8a322ea5d937dbb8d
+  data.tar.gz: c0aa00203643d32d5bcdc673eced0dbc4185b05ab262fef5aa9fcdbf073de5c4
 SHA512:
-  metadata.gz: f0499fa6c77cc863dfd325ad84e7bf746377b18e6260cbad692add3ac3a1e1508b5652e1536ef9f72a2614026c95ab71a026a73b96212bd54ab4e088e3ad9dd5
-  data.tar.gz: 122fd1cd5689b051a9c39744ee3d02dce099ff9f226d4b2278ae3baf2fe2aff0d1e6dc218bed9e19f3703eafb7a0e0d142055c01c5219449ac5f118a21b94813
+  metadata.gz: 66470f20b0365194b77753a664bdd759a204f62cf60c1dcabbf7181c472696c665e8946cf2c1073aad190cbeb3b6b557120aed8386525911cf65e25f5fb82762
+  data.tar.gz: baea59ad89ba252e6da4ec1ddce5394d3ea484d186e7d48740bae1d136e973e4a34114b91c34d64ea65bb4bee4d2a6468300057a5877dfab269296b16ae1a4b0

data/.travis.yml

@@ -1,10 +1,9 @@
 dist: xenial
-sudo: false
 language: ruby
 cache: bundler
 rvm:
   - ruby-head
-  - 2.6.0
+  - 2.6.1
   - 2.5.3
   - 2.4.5
   - 2.3.8
@@ -14,4 +13,11 @@ matrix:
     - rvm: ruby-head
 
 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
   - 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/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [v1.9.0] - 2019-02-22
+
+### Added
+
+- Added `#verify`, which can be used for getting a meaningful error raised in case of a verification error, as opposed to `#valid?` which returns `false`
+
 ## [v1.8.0] - 2019-01-17
 
 ### Added
@@ -115,6 +121,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
 
+[v1.9.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.8.0...v1.9.0/
 [v1.8.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.7.0...v1.8.0/
 [v1.7.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.6.0...v1.7.0/
 [v1.6.0]: https://github.com/cedarcode/webauthn-ruby/compare/v1.5.0...v1.6.0/

data/README.md

@@ -63,7 +63,7 @@ NOTE: You can find a working example on how to use this gem in a __Rails__ app i
 credential_creation_options = WebAuthn.credential_creation_options
 
 # Store the newly generated challenge somewhere so you can have it
-# for the validation phase.
+# for the verification phase.
 #
 # You can read it from the resulting options:
 credential_creation_options[:challenge]
@@ -72,7 +72,7 @@ credential_creation_options[:challenge]
 # to call `navigator.credentials.create({ "publicKey": credentialCreationOptions })`
 ```
 
-#### Validation phase
+#### Verification phase
 
 ```ruby
 # These should be ruby `String`s encoded as binary data, e.g. `Encoding:ASCII-8BIT`.
@@ -80,10 +80,10 @@ credential_creation_options[:challenge]
 # 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 `#valid?` method.
+# 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 `#valid`
+# on the user-agent encoded data before calling `#verify`
 attestation_object = "..."
 client_data_json = "..."
 
@@ -93,17 +93,19 @@ attestation_response = WebAuthn::AuthenticatorAttestationResponse.new(
 )
 
 # This value needs to match `window.location.origin` evaluated by
-# the User Agent as part of the validation phase.
+# the User Agent as part of the verification phase.
 original_origin = "https://www.example.com"
 
-if attestation_response.valid?(original_challenge, original_origin)
+begin
+  attestation_response.verify(original_challenge, original_origin)
+
   # 1. Register the new user and
   # 2. Keep Credential ID and Credential Public Key under storage
   #    for future authentications
   #    Access by invoking:
   #      `attestation_response.credential.id`
   #      `attestation_response.credential.public_key`
-else
+rescue WebAuthn::VerificationError => e
   # Handle error
 end
 ```
@@ -119,7 +121,7 @@ credential_request_options = WebAuthn.credential_request_options
 credential_request_options[:allowCredentials] << { id: credential_id, type: "public-key" }
 
 # Store the newly generated challenge somewhere so you can have it
-# for the validation phase.
+# for the verification phase.
 #
 # You can read it from the resulting options:
 credential_request_options[:challenge]
@@ -128,7 +130,7 @@ credential_request_options[:challenge]
 # to call `navigator.credentials.get({ "publicKey": credentialRequestOptions })`
 ```
 
-#### Validation phase
+#### Verification phase
 
 Assuming you have the previously stored Credential Public Key, now in variable `credential_public_key`
 
@@ -138,10 +140,10 @@ Assuming you have the previously stored Credential Public Key, now in variable `
 # 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 `#valid?` method.
+# 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 `#valid`
+# on the user-agent encoded data before calling `#verify`
 authenticator_data = "..."
 client_data_json = "..."
 signature = "..."
@@ -153,7 +155,7 @@ assertion_response = WebAuthn::AuthenticatorAssertionResponse.new(
 )
 
 # This value needs to match `window.location.origin` evaluated by
-# the User Agent as part of the validation phase.
+# the User Agent as part of the verification phase.
 original_origin = "https://www.example.com"
 
 # This hash must have the id and its corresponding public key of the
@@ -163,17 +165,28 @@ allowed_credential = {
   public_key: credential_public_key
 }
 
-if assertion_response.valid?(original_challenge, original_origin, allowed_credential: allowed_credential)
+begin
+  assertion_response.verify(original_challenge, original_origin, allowed_credentials: [allowed_credential])
+
   # Sign in the user
-else
+rescue WebAuthn::VerificationError => e
   # Handle error
 end
 ```
 
+## Testing Your Integration
+
+The Webauthn spec requires for data that is signed and authenticated. As a result, it can be difficult to create valid test authenticator data when testing your integration. Webauthn-ruby exposes [WebAuthn::FakeAuthenticator](https://github.com/cedarcode/webauthn-ruby/blob/master/lib/webauthn/fake_authenticator.rb) for you to use in your tests. Example usage can be found in [webauthn-ruby/spec/webauthn/authenticator_assertion_response_spec.rb](https://github.com/cedarcode/webauthn-ruby/blob/master/spec/webauthn/authenticator_assertion_response_spec.rb).
+
 ## Development
 
 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).
 
 ### Commit message format

data/lib/webauthn/authenticator_assertion_response.rb

@@ -3,6 +3,9 @@
 require "webauthn/authenticator_response"
 
 module WebAuthn
+  class CredentialVerificationError < VerificationError; end
+  class SignatureVerificationError < VerificationError; end
+
   class AuthenticatorAssertionResponse < AuthenticatorResponse
     def initialize(credential_id:, authenticator_data:, signature:, **options)
       super(options)
@@ -12,10 +15,13 @@ module WebAuthn
       @signature = signature
     end
 
-    def valid?(original_challenge, original_origin, allowed_credentials:, rp_id: nil)
-      super(original_challenge, original_origin, rp_id: rp_id) &&
-        valid_credential?(allowed_credentials) &&
-        valid_signature?(credential_public_key(allowed_credentials))
+    def verify(original_challenge, original_origin, allowed_credentials:, rp_id: nil)
+      super(original_challenge, original_origin, rp_id: rp_id)
+
+      verify_item(:credential, allowed_credentials)
+      verify_item(:signature, credential_public_key(allowed_credentials))
+
+      true
     end
 
     def authenticator_data

data/lib/webauthn/authenticator_attestation_response.rb

@@ -10,6 +10,8 @@ require "webauthn/attestation_statement"
 require "webauthn/client_data"
 
 module WebAuthn
+  class AttestationStatementVerificationError < VerificationError; end
+
   class AuthenticatorAttestationResponse < AuthenticatorResponse
     attr_reader :attestation_type, :attestation_trust_path
 
@@ -19,14 +21,11 @@ module WebAuthn
       @attestation_object = attestation_object
     end
 
-    def valid?(original_challenge, original_origin, rp_id: nil)
-      valid_response = super
-      return false unless valid_response
+    def verify(original_challenge, original_origin, rp_id: nil)
+      super
 
-      valid_attestation = attestation_statement.valid?(authenticator_data, client_data.hash)
-      return false unless valid_attestation
+      verify_item(:attestation_statement)
 
-      @attestation_type, @attestation_trust_path = valid_attestation
       true
     end
 
@@ -58,5 +57,9 @@ module WebAuthn
     def type
       WebAuthn::TYPES[:create]
     end
+
+    def valid_attestation_statement?
+      @attestation_type, @attestation_trust_path = attestation_statement.valid?(authenticator_data, client_data.hash)
+    end
   end
 end

data/lib/webauthn/authenticator_response.rb

@@ -1,18 +1,37 @@
 # frozen_string_literal: true
 
+require "webauthn/error"
+
 module WebAuthn
+  class VerificationError < Error; end
+
+  class AuthenticatorDataVerificationError < VerificationError; end
+  class ChallengeVerificationError < VerificationError; end
+  class OriginVerificationError < VerificationError; end
+  class RpIdVerificationError < VerificationError; end
+  class TypeVerificationError < VerificationError; end
+  class UserPresenceVerificationError < VerificationError; end
+
   class AuthenticatorResponse
     def initialize(client_data_json:)
       @client_data_json = client_data_json
     end
 
-    def valid?(original_challenge, original_origin, rp_id: nil)
-      valid_type? &&
-        valid_challenge?(original_challenge) &&
-        valid_origin?(original_origin) &&
-        valid_rp_id?(rp_id || rp_id_from_origin(original_origin)) &&
-        authenticator_data.valid? &&
-        authenticator_data.user_flagged?
+    def verify(original_challenge, original_origin, rp_id: nil)
+      verify_item(:type)
+      verify_item(:challenge, original_challenge)
+      verify_item(:origin, original_origin)
+      verify_item(:authenticator_data)
+      verify_item(:rp_id, rp_id || rp_id_from_origin(original_origin))
+      verify_item(:user_presence)
+
+      true
+    end
+
+    def valid?(*args)
+      verify(*args)
+    rescue WebAuthn::VerificationError
+      false
     end
 
     def client_data
@@ -23,6 +42,16 @@ module WebAuthn
 
     attr_reader :client_data_json
 
+    def verify_item(item, *args)
+      if send("valid_#{item}?", *args)
+        true
+      else
+        camelized_item = item.to_s.split('_').map { |w| w.capitalize }.join
+        error_const_name = "WebAuthn::#{camelized_item}VerificationError"
+        raise Object.const_get(error_const_name)
+      end
+    end
+
     def valid_type?
       client_data.type == type
     end
@@ -39,6 +68,14 @@ module WebAuthn
       OpenSSL::Digest::SHA256.digest(rp_id) == authenticator_data.rp_id_hash
     end
 
+    def valid_authenticator_data?
+      authenticator_data.valid?
+    end
+
+    def valid_user_presence?
+      authenticator_data.user_flagged?
+    end
+
     def rp_id_from_origin(original_origin)
       URI.parse(original_origin).host
     end

data/lib/webauthn/security_utils.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securecompare"
+
 module WebAuthn
   module SecurityUtils
     # Constant time string comparison, for variable length strings.
@@ -10,26 +12,9 @@ module WebAuthn
     def secure_compare(first_string, second_string)
       first_string_sha256 = ::Digest::SHA256.hexdigest(first_string)
       second_string_sha256 = ::Digest::SHA256.hexdigest(second_string)
-      fixed_length_secure_compare(first_string_sha256, second_string_sha256) && first_string == second_string
-    end
-    module_function :secure_compare
 
-    private
-
-    # Constant time string comparison, for fixed length strings.
-    # This code was adapted from Rails ActiveSupport::SecurityUtils
-    #
-    # The values compared should be of fixed length, such as strings
-    # that have already been processed by HMAC. Raises in case of length mismatch.
-    def fixed_length_secure_compare(first_string, second_string)
-      raise ArgumentError, "string length mismatch." unless first_string.bytesize == second_string.bytesize
-
-      l = first_string.unpack "C#{first_string.bytesize}"
-
-      res = 0
-      second_string.each_byte { |byte| res |= byte ^ l.shift }
-      res == 0
+      SecureCompare.compare(first_string_sha256, second_string_sha256) && first_string == second_string
     end
-    module_function :fixed_length_secure_compare
+    module_function :secure_compare
   end
 end

data/lib/webauthn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WebAuthn
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

data/webauthn.gemspec

@@ -33,10 +33,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency "cose", "~> 0.1.0"
   spec.add_dependency "jwt", [">= 1.5", "< 3.0"]
   spec.add_dependency "openssl", "~> 2.0"
+  spec.add_dependency "securecompare", "~> 1.0"
 
   spec.add_development_dependency "bundler", ">= 1.17", "< 3.0"
-  spec.add_development_dependency "byebug", "~> 10.0"
+  spec.add_development_dependency "byebug", "~> 11.0"
   spec.add_development_dependency "rake", "~> 12.3"
   spec.add_development_dependency "rspec", "~> 3.8"
-  spec.add_development_dependency "rubocop", "0.61.1"
+  spec.add_development_dependency "rubocop", "0.65.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: webauthn
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Gonzalo Rodriguez
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-17 00:00:00.000000000 Z
+date: 2019-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cbor
@@ -73,6 +73,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: securecompare
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -99,14 +113,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '11.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '11.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -141,14 +155,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.61.1
+        version: 0.65.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.61.1
+        version: 0.65.0
 description: 
 email:
 - gonzalo@cedarcode.com