darrrr 0.0.3 → 0.1.0

data/lib/darrrr/cryptors/default/encrypted_data.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Darrrr
+  class EncryptedData
+    extend Forwardable
+    CIPHER_OPTIONS = [:encrypt, :decrypt].freeze
+    CIPHER = "aes-256-gcm".freeze
+    CIPHER_VERSION = 0
+    # This is the NIST recommended minimum: http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
+    IV_LENGTH = 12
+    AUTH_TAG_LENGTH = 16
+    PROTOCOL_VERSION = 0
+
+    attr_reader :token_object
+
+    def_delegators :@token_object, :version, :iv, :auth_tag, :ciphertext,
+      :to_binary_s, :num_bytes
+
+    # token_object: an EncryptedDataIO instance
+    # instance.
+    def initialize(token_object)
+      raise TokenFormatError, "Version must be #{PROTOCOL_VERSION}. Supplied: #{token_object.version}" unless token_object.version == CIPHER_VERSION
+      raise TokenFormatError, "Auth Tag must be 16 bytes" unless token_object.auth_tag.length == AUTH_TAG_LENGTH
+      raise TokenFormatError, "IV must be 12 bytes" unless token_object.iv.length == IV_LENGTH
+      @token_object = token_object
+    end
+    private_class_method :new
+
+    def decrypt
+      cipher = self.class.cipher(:decrypt)
+      cipher.iv = self.iv.to_binary_s
+      cipher.auth_tag = self.auth_tag.to_binary_s
+      cipher.auth_data = ""
+      cipher.update(self.ciphertext.to_binary_s) + cipher.final
+    rescue OpenSSL::Cipher::CipherError => e
+      raise CryptoError, "Unable to decrypt data: #{e}"
+    end
+
+    class << self
+      # data: the value to encrypt.
+      #
+      # returns an EncryptedData instance.
+      def build(data)
+        cipher = cipher(:encrypt)
+        iv = SecureRandom.random_bytes(EncryptedData::IV_LENGTH)
+        cipher.iv = iv
+        cipher.auth_data = ""
+
+        ciphertext = cipher.update(data.to_s) + cipher.final
+
+        token = EncryptedDataIO.new.tap do |edata|
+          edata.version = CIPHER_VERSION
+          edata.auth_tag = cipher.auth_tag.bytes
+          edata.iv = iv.bytes
+          edata.ciphertext = ciphertext.bytes
+        end
+
+        new(token)
+      end
+
+      # serialized_data: the binary representation of a token.
+      #
+      # returns an EncryptedData instance.
+      def parse(serialized_data)
+        data = new(EncryptedDataIO.new.read(serialized_data))
+
+        # be extra paranoid, oracles and stuff
+        if data.num_bytes != serialized_data.bytesize
+          raise CryptoError, "Encypted data field includes unexpected extra bytes"
+        end
+
+        data
+      rescue IOError => e
+        raise RecoveryTokenSerializationError, e.message
+      end
+
+      # DRY helper for generating cipher objects
+      def cipher(mode)
+        unless CIPHER_OPTIONS.include?(mode)
+          raise ArgumentError, "mode must be `encrypt` or `decrypt`"
+        end
+
+        OpenSSL::Cipher.new(EncryptedData::CIPHER).tap do |cipher|
+          cipher.send(mode)
+          cipher.key = [Darrrr.this_account_provider.instance_variable_get(:@symmetric_key)].pack("H*")
+        end
+      end
+    end
+  end
+end

data/lib/darrrr/cryptors/default/encrypted_data_io.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Darrrr
+  class EncryptedDataIO < BinData::Record
+    uint8 :version
+    array :auth_tag, :type => :uint8, :initial_length => EncryptedData::AUTH_TAG_LENGTH
+    array :iv, :type => :uint8, :initial_length => EncryptedData::IV_LENGTH
+    array :ciphertext, :type => :uint8, :read_until => :eof
+  end
+end

data/lib/darrrr/provider.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Darrrr
+  module Provider
+    RECOVERY_PROVIDER_CACHE_LENGTH = 60.seconds
+    MAX_RECOVERY_PROVIDER_CACHE_LENGTH = 5.minutes
+    REQUIRED_CRYPTO_OPS = [:sign, :verify, :encrypt, :decrypt].freeze
+    include Constants
+
+    def self.included(base)
+      base.instance_eval do
+        # this represents the account/recovery provider on this web app
+        class << self
+          attr_accessor :this
+
+          def configure(&block)
+            raise ArgumentError, "Block required to configure #{self.name}" unless block_given?
+            raise ProviderConfigError, "#{self.name} already configured" if self.this
+            self.this = self.new.tap { |provider| provider.instance_eval(&block).freeze }
+            self.this.privacy_policy = Darrrr.privacy_policy
+            self.this.icon_152px = Darrrr.icon_152px
+            self.this.issuer = Darrrr.authority
+          end
+        end
+      end
+    end
+
+    def initialize(provider_origin = nil, attrs: nil)
+      self.issuer = provider_origin
+      load(attrs) if attrs
+    end
+
+    # Returns the crypto API to be used. A thread local instance overrides the
+    # globally configured value which overrides the default encryptor.
+    def encryptor
+      Thread.current[encryptor_key()] || @encryptor || DefaultEncryptor
+    end
+
+    # Overrides the global `encryptor` API to use
+    #
+    # encryptor: a class/module that responds to all +REQUIRED_CRYPTO_OPS+.
+    def custom_encryptor=(encryptor)
+      if valid_encryptor?(encryptor)
+        @encryptor = encryptor
+      else
+        raise ArgumentError, "custom encryption class must respond to all of #{REQUIRED_CRYPTO_OPS}"
+      end
+    end
+
+    def with_encryptor(encryptor)
+      raise ArgumentError, "A block must be supplied" unless block_given?
+      unless valid_encryptor?(encryptor)
+        raise ArgumentError, "custom encryption class must respond to all of #{REQUIRED_CRYPTO_OPS}"
+      end
+
+      Thread.current[encryptor_key()] = encryptor
+      yield
+    ensure
+      Thread.current[encryptor_key()] = nil
+    end
+
+    private def valid_encryptor?(encryptor)
+      REQUIRED_CRYPTO_OPS.all? {|m| encryptor.respond_to?(m)}
+    end
+
+    # Lazily loads attributes if attrs is nil. It makes an http call to the
+    # recovery provider's well-known config location and caches the response
+    # if it's valid json.
+    #
+    # attrs: optional way of building the provider without making an http call.
+    def load(attrs = nil)
+      body = attrs || fetch_config!
+      set_attrs!(body)
+      self
+    end
+
+    private def faraday
+      Faraday.new do |f|
+        f.adapter(Faraday.default_adapter)
+      end
+    end
+
+    private def cache_config(response)
+      match = /max-age=(\d+)/.match(response.headers["cache-control"])
+      cache_age = if match
+        [match[1].to_i, MAX_RECOVERY_PROVIDER_CACHE_LENGTH].min
+      else
+        RECOVERY_PROVIDER_CACHE_LENGTH
+      end
+      Darrrr.cache.try(:set, cache_key, response.body, cache_age)
+    end
+
+    private def cache_key
+      "recovery_provider_config:#{self.origin}:configuration"
+    end
+
+    private def fetch_config!
+      unless body = Darrrr.cache.try(:get, cache_key)
+        response = faraday.get([self.origin, Darrrr::WELL_KNOWN_CONFIG_PATH].join("/"))
+        if response.success?
+          cache_config(response)
+        else
+          raise ProviderConfigError.new("Unable to retrieve recovery provider config for #{self.origin}: #{response.status}: #{response.body[0..100]}")
+        end
+
+        body = response.body
+      end
+
+      JSON.parse(body)
+    rescue ::JSON::ParserError
+      raise ProviderConfigError.new("Unable to parse recovery provider config for #{self.origin}:#{body[0..100]}")
+    end
+
+    private def set_attrs!(context)
+      self.class::REQUIRED_FIELDS.each do |attr|
+        value = context[attr.to_s.tr("_", "-")]
+        self.instance_variable_set("@#{attr}", value)
+      end
+
+      if errors.any?
+        raise ProviderConfigError.new("Unable to parse recovery provider config for #{self.origin}: #{errors.join(", ")}")
+      end
+    end
+
+    private def errors
+      errors = []
+      self.class::REQUIRED_FIELDS.each do |field|
+        unless self.instance_variable_get("@#{field}")
+          errors << "#{field} not set"
+        end
+      end
+
+      self.class::URL_FIELDS.each do |field|
+        begin
+          uri = Addressable::URI.parse(self.instance_variable_get("@#{field}"))
+          if !Darrrr.allow_unsafe_urls && uri.try(:scheme) != "https"
+            errors << "#{field} must be an https URL"
+          end
+        rescue Addressable::URI::InvalidURIError
+          errors << "#{field} must be a valid URL"
+        end
+      end
+
+      if self.is_a? RecoveryProvider
+        unless self.token_max_size.to_i > 0
+          errors << "token max size must be an integer"
+        end
+      end
+
+      unless self.unseal_keys.try(:any?)
+        errors << "No public key provided"
+      end
+
+      errors
+    end
+  end
+end

data/lib/darrrr/recovery_provider.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Darrrr
+  class RecoveryProvider
+    include Provider
+    include CryptoHelper
+
+    INTEGER_FIELDS = [:token_max_size]
+    BASE64_FIELDS = [:countersign_pubkeys_secp256r1]
+    URL_FIELDS = [
+      :issuer, :save_token,
+      :recover_account, :privacy_policy
+    ]
+    REQUIRED_FIELDS = URL_FIELDS + INTEGER_FIELDS + BASE64_FIELDS
+
+    attr_reader *(REQUIRED_FIELDS - [:countersign_pubkeys_secp256r1])
+    attr_writer *REQUIRED_FIELDS
+    attr_writer :signing_private_key, :token_max_size
+    attr_accessor :save_token_async_api_iframe # optional
+
+    alias :origin :issuer
+
+    # optional field
+    attr_accessor :icon_152px
+
+    # Used to serve content at /.well-known/delegated-account-recovery/configuration
+    def to_h
+      {
+        "issuer" => self.issuer,
+        "countersign-pubkeys-secp256r1" => self.unseal_keys.dup,
+        "token-max-size" => self.token_max_size,
+        "save-token" => self.save_token,
+        "recover-account" => self.recover_account,
+        "save-token-async-api-iframe" => self.save_token_async_api_iframe,
+        "privacy-policy" => self.privacy_policy
+      }
+    end
+
+    # The CryptoHelper defines an `unseal` method that requires us to define
+    # a `unseal_keys` method that will return the set of keys that are valid
+    # when verifying the signature on a sealed key.
+    #
+    # returns the value of `countersign_pubkeys_secp256r1` or executes a proc
+    # passing `self` as the first argument.
+    def unseal_keys(context = nil)
+      if @countersign_pubkeys_secp256r1.respond_to?(:call)
+        @countersign_pubkeys_secp256r1.call(context)
+      else
+        @countersign_pubkeys_secp256r1
+      end
+    end
+
+    # The URL representing the location of the token. Used to initiate a recovery.
+    #
+    # token_id: the shared ID representing a token.
+    def recovery_url(token_id)
+      [self.recover_account, "?token_id=", URI.escape(token_id)].join
+    end
+
+    def encryptor_key
+      :darrrr_recovery_provider_encryptor
+    end
+
+    # Takes a binary representation of a token and signs if for a given
+    # account provider. Do not pass in a RecoveryToken object. The wrapping
+    # data structure is identical to the structure it's wrapping in format.
+    #
+    # token: the to_binary_s or binary representation of the recovery token
+    #
+    # returns a Base64 encoded representation of the countersigned token
+    # and the signature over the token.
+    def countersign_token(token, context = nil)
+      begin
+        account_provider = RecoveryToken.account_provider_issuer(token)
+      rescue RecoveryTokenSerializationError, UnknownProviderError
+        raise TokenFormatError, "Could not determine provider"
+      end
+
+      counter_recovery_token = RecoveryToken.build(
+        issuer: self,
+        audience: account_provider,
+        type: COUNTERSIGNED_RECOVERY_TOKEN_TYPE
+      )
+
+      counter_recovery_token.data = token
+      seal(counter_recovery_token, context)
+    end
+
+    # Validate the token according to the processing instructions for the
+    # save-token endpoint.
+    #
+    # Returns a validated token
+    def validate_recovery_token!(token, context = {})
+      errors = []
+
+      # 1. Authenticate the User. The exact nature of how the Recovery Provider authenticates the User is beyond the scope of this specification.
+      # handled in before_filter
+
+      # 4. Retrieve the Account Provider configuration as described in Section 2 using the issuer field of the token as the subject.
+      begin
+        account_provider = RecoveryToken.account_provider_issuer(token)
+      rescue RecoveryTokenSerializationError, UnknownProviderError, TokenFormatError => e
+        raise RecoveryTokenError, "Could not determine provider: #{e.message}"
+      end
+
+      # 2. Parse the token.
+      # 3. Validate that the version value is 0.
+      # 5. Validate the signature over the token according to processing rules for the algorithm implied by the version.
+      begin
+        recovery_token = account_provider.unseal(token, context)
+      rescue CryptoError => e
+        raise RecoveryTokenError.new("Unable to verify signature of token")
+      rescue TokenFormatError => e
+        raise RecoveryTokenError.new(e.message)
+      end
+
+      # 6. Validate that the audience field of the token identifies an origin which the provider considers itself authoritative for. (Often the audience will be same-origin with the Recovery Provider, but other values may be acceptable, e.g. "https://mail.example.com" and "https://social.example.com" may be acceptable audiences for "https://recovery.example.com".)
+      unless self.origin == recovery_token.audience
+        raise RecoveryTokenError.new("Unnacceptable audience")
+      end
+
+      if DateTime.parse(recovery_token.issued_time).utc < (Time.now - CLOCK_SKEW).utc
+        raise RecoveryTokenError.new("Issued at time is too far in the past")
+      end
+
+      recovery_token
+    end
+  end
+end

data/lib/darrrr/recovery_token.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Handles binary serialization/deserialization of recovery token data. It does
+# not manage signing/verification of tokens.
+# Only account providers will ever call the decode function
+module Darrrr
+  class RecoveryToken
+    extend Forwardable
+
+    attr_reader :token_object
+
+    def_delegators :@token_object, :token_id, :issuer, :issued_time, :options,
+      :audience, :binding_data, :data, :version, :to_binary_s, :num_bytes, :data=, :token_type=, :token_type
+
+    BASE64_CHARACTERS = /\A[0-9a-zA-Z+\/=]+\z/
+
+    # Typically, you would not call `new` directly but instead use `build`
+    # and `parse`
+    #
+    # token_object: a RecoveryTokenWriter/RecoveryTokenReader instance
+    def initialize(token_object)
+      @token_object = token_object
+    end
+    private_class_method :new
+
+    def decode(context = nil)
+      Darrrr.this_account_provider.encryptor.decrypt(self.data, Darrrr.this_account_provider, context)
+    end
+
+    # A globally known location of the token, used to initiate a recovery
+    def state_url
+      [Darrrr.recovery_provider(self.audience).recover_account, "id=#{CGI::escape(token_id.to_hex)}"].join("?")
+    end
+
+    class << self
+      # data: the value that will be encrypted by EncryptedData.
+      # recovery_provider: the provider for which we are building the token.
+      # binding_data: a value retrieved from the recovery provider for this
+      # token.
+      #
+      # returns a RecoveryToken.
+      def build(issuer:, audience:, type:)
+        token = RecoveryTokenWriter.new.tap do |token|
+          token.token_id = token_id
+          token.issuer = issuer.origin
+          token.issued_time = Time.now.utc.iso8601
+          token.options = 0 # when the token-status endpoint is implemented, change this to 1
+          token.audience = audience.origin
+          token.version = Darrrr::PROTOCOL_VERSION
+          token.token_type = type
+        end
+        new(token)
+      end
+
+      # token ID generates a random array of bytes.
+      # this method only exists so that it can be stubbed.
+      def token_id
+        SecureRandom.random_bytes(16).bytes.to_a
+      end
+
+      # serialized_data: a binary string representation of a RecoveryToken.
+      #
+      # returns a RecoveryToken.
+      def parse(serialized_data)
+        new RecoveryTokenReader.new.read(serialized_data)
+      rescue IOError => e
+        message = e.message
+        if serialized_data =~ BASE64_CHARACTERS
+          message = "#{message}: did you forget to Base64.strict_decode64 this value?"
+        end
+        raise RecoveryTokenSerializationError, message
+      end
+
+      # Extract a recovery provider from a token based on the token type.
+      #
+      # serialized_data: a binary string representation of a RecoveryToken.
+      #
+      # returns the recovery provider for the coutnersigned token or raises an
+      #   error if the token is a recovery token
+      def recovery_provider_issuer(serialized_data)
+        issuer(serialized_data, Darrrr::COUNTERSIGNED_RECOVERY_TOKEN_TYPE)
+      end
+
+      # Extract an account provider from a token based on the token type.
+      #
+      # serialized_data: a binary string representation of a RecoveryToken.
+      #
+      # returns the account provider for the recovery token or raises an error
+      #   if the token is a countersigned token
+      def account_provider_issuer(serialized_data)
+        issuer(serialized_data, Darrrr::RECOVERY_TOKEN_TYPE)
+      end
+
+      # Convenience method to find the issuer of the token
+      #
+      # serialized_data: a binary string representation of a RecoveryToken.
+      #
+      # raises an error if the token is the not the expected type
+      # returns the account provider or recovery provider instance based on the
+      #   token type
+      private def issuer(serialized_data, token_type)
+        parsed_token = parse(serialized_data)
+        raise TokenFormatError, "Token type must be #{token_type}" unless parsed_token.token_type == token_type
+
+        issuer = parsed_token.issuer
+        case token_type
+        when Darrrr::RECOVERY_TOKEN_TYPE
+          Darrrr.account_provider(issuer)
+        when Darrrr::COUNTERSIGNED_RECOVERY_TOKEN_TYPE
+          Darrrr.recovery_provider(issuer)
+        else
+          raise RecoveryTokenError, "Could not determine provider"
+        end
+      end
+    end
+  end
+end