darrrr 0.0.2

data/lib/github/delegated_account_recovery/account_provider.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    class AccountProvider
+      include CryptoHelper
+      include Provider
+
+      # Only applicable when acting as a recovery provider
+      PRIVATE_FIELDS = [:symmetric_key, :signing_private_key]
+
+      FIELDS = [:tokensign_pubkeys_secp256r1].freeze
+      URL_FIELDS = [:issuer, :save_token_return, :recover_account_return,
+        :privacy_policy, :icon_152px].freeze
+
+      # These are the fields required by the spec
+      REQUIRED_FIELDS = FIELDS + URL_FIELDS
+
+      attr_accessor(*REQUIRED_FIELDS)
+      attr_accessor(*PRIVATE_FIELDS)
+
+      alias :origin :issuer
+
+      # 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.
+      def unseal_keys
+        tokensign_pubkeys_secp256r1
+      end
+
+      # Used to serve content at /.well-known/delegated-account-recovery/configuration
+      def to_h
+        {
+          "issuer" => self.issuer,
+          "tokensign-pubkeys-secp256r1" => self.tokensign_pubkeys_secp256r1.dup,
+          "save-token-return" => self.save_token_return,
+          "recover-account-return" => self.recover_account_return,
+          "privacy-policy" => self.privacy_policy,
+          "icon-152px" => self.icon_152px
+        }
+      end
+
+      # Generates a binary token with an encrypted arbitrary data payload.
+      #
+      # data: value to encrypt in the token
+      # provider: the recovery provider/audience of the token
+      # binding data: binding data value retrieved from recovery provider to
+      #   provide some assurance the same browser was used.
+      def generate_recovery_token(data:, audience:)
+        RecoveryToken.build(issuer: self, audience: audience, type: RECOVERY_TOKEN_TYPE).tap do |token|
+          token.data = Darrrr.encryptor.encrypt(data)
+        end
+      end
+
+      # Parses a countersigned_token and returns the nested recovery token
+      # WITHOUT verifying any signatures. This should only be used if no user
+      # context can be identified or if we're extracting issuer information.
+      def dangerous_unverified_recovery_token(countersigned_token)
+        parsed_countersigned_token = RecoveryToken.parse(Base64.strict_decode64(countersigned_token))
+        RecoveryToken.parse(parsed_countersigned_token.data)
+      end
+
+      # Validates the countersigned recovery token by verifying the signature
+      # of the countersigned token, parsing out the origin recovery token,
+      # verifying the signature on the recovery token, and finally decrypting
+      # the data in the origin recovery token.
+      #
+      # countersigned_token: our original recovery token wrapped in recovery
+      # token instance that is signed by the recovery provider.
+      #
+      # returns a verified recovery token or raises
+      # an error if the token fails validation.
+      def validate_countersigned_recovery_token!(countersigned_token)
+        # 5. Validate the the issuer field is present in the token,
+        # and that it matches the audience field in the original countersigned token.
+        begin
+          recovery_provider = RecoveryToken.recovery_provider_issuer(Base64.strict_decode64(countersigned_token))
+        rescue RecoveryTokenSerializationError => e
+          raise CountersignedTokenError.new("Countersigned token is invalid: " + e.message, :countersigned_token_parse_error)
+        rescue UnknownProviderError => e
+          raise CountersignedTokenError.new(e.message, :recovery_token_invalid_issuer)
+        end
+
+        # 1. Parse the countersigned-token.
+        # 2. Validate that the version field is 0.
+        # 7. Retrieve the current Recovery Provider configuration as described in Section 2.
+        # 8. Validate that the counter-signed token signature validates with a current element of the countersign-pubkeys-secp256r1 array.
+        begin
+          parsed_countersigned_token = recovery_provider.unseal(Base64.strict_decode64(countersigned_token))
+        rescue TokenFormatError => e
+          raise CountersignedTokenError.new(e.message, :countersigned_invalid_token_version)
+        rescue CryptoError
+          raise CountersignedTokenError.new("Countersigned token has an invalid signature", :countersigned_invalid_signature)
+        end
+
+        # 3. De-serialize the original recovery token from the data field.
+        # 4. Validate the signature on the original recovery token.
+        begin
+          recovery_token = self.unseal(parsed_countersigned_token.data)
+        rescue RecoveryTokenSerializationError => e
+          raise CountersignedTokenError.new("Nested recovery token is invalid: " + e.message, :recovery_token_token_parse_error)
+        rescue TokenFormatError => e
+          raise CountersignedTokenError.new("Nested recovery token format error: #{e.message}", :recovery_token_invalid_token_type)
+        rescue CryptoError
+          raise CountersignedTokenError.new("Nested recovery token has an invalid signature", :recovery_token_invalid_signature)
+        end
+
+        # 5. Validate the the issuer field is present in the countersigned-token,
+        # and that it matches the audience field in the original token.
+
+        countersigned_token_issuer = parsed_countersigned_token.issuer
+        if countersigned_token_issuer.blank? || countersigned_token_issuer != recovery_token.audience || recovery_provider.origin != countersigned_token_issuer
+          raise CountersignedTokenError.new("Validate the the issuer field is present in the countersigned-token, and that it matches the audience field in the original token", :recovery_token_invalid_issuer)
+        end
+
+        # 6. Validate the token binding for the countersigned token, if present.
+        # (the token binding for the inner token is not relevant)
+        # TODO not required, to be implemented later
+
+        # 9. Decrypt the data field from the original recovery token and parse its information, if present.
+        begin
+          recovery_token.decode
+        rescue CryptoError
+          raise CountersignedTokenError.new("Recovery token data could not be decrypted", :indecipherable_opaque_data)
+        end
+
+        # 10. Apply any additional processing which provider-specific data in the opaque data portion may indicate is necessary.
+        begin
+          if DateTime.parse(parsed_countersigned_token.issued_time).utc < (Time.now - CLOCK_SKEW).utc
+            raise CountersignedTokenError.new("Countersigned recovery token issued at time is too far in the past", :stale_token)
+          end
+        rescue ArgumentError
+          raise CountersignedTokenError.new("Invalid countersigned token issued time", :invalid_issued_time)
+        end
+
+        recovery_token
+      end
+    end
+  end
+end

data/lib/github/delegated_account_recovery/constants.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    module Constants
+      PROTOCOL_VERSION = 0
+      PRIME_256_V1 = "prime256v1" # AKA secp256r1
+      GROUP = OpenSSL::PKey::EC::Group.new(PRIME_256_V1)
+      DIGEST = OpenSSL::Digest::SHA256
+      TOKEN_ID_BYTE_LENGTH = 16
+      RECOVERY_TOKEN_TYPE = 0
+      COUNTERSIGNED_RECOVERY_TOKEN_TYPE = 1
+      WELL_KNOWN_CONFIG_PATH = ".well-known/delegated-account-recovery/configuration"
+      CLOCK_SKEW = 5 * 60
+    end
+
+    include Constants
+  end
+end

data/lib/github/delegated_account_recovery/crypto_helper.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    module CryptoHelper
+      include Constants
+      # Signs the provided token and joins the data with the signature.
+      #
+      # token: a RecoveryToken instance
+      #
+      # returns a base64 value for the binary token string and the signature
+      # of the token.
+      def seal(token)
+        raise RuntimeError, "signing private key must be set" unless self.signing_private_key
+        binary_token = token.to_binary_s
+        signature = Darrrr.encryptor.sign(binary_token, self.signing_private_key)
+        Base64.strict_encode64([binary_token, signature].join)
+      end
+
+      # Splits the payload by the token size, treats the remaining portion as
+      # the signature of the payload, and verifies the signature is valid for
+      # the given payload.
+      #
+      # token_and_signature: binary string consisting of [token_binary_str, signature].join
+      # keys - An array of public keys to use for signature verification.
+      #
+      # returns a RecoveryToken if the payload has been verified and
+      # deserializes correctly. Raises exceptions if any crypto fails.
+      # Raises an error if the token's version field is not valid.
+      def unseal(token_and_signature)
+        token = RecoveryToken.parse(token_and_signature)
+
+        unless token.version.to_i == PROTOCOL_VERSION
+          raise TokenFormatError, "Version field must be #{PROTOCOL_VERSION}"
+        end
+
+        token_data, signature = partition_signed_token(token_and_signature, token)
+        self.unseal_keys.each do |key|
+          return token if Darrrr.encryptor.verify(token_data, signature, key)
+        end
+        raise CryptoError, "Recovery token signature was invalid"
+      end
+
+      # Split the binary token into the token data and the signature over the
+      # data.
+      #
+      # token_and_signature: binary serialization of the token and signature for the token
+      # recovery_token: a RecoveryToken object parsed from token_and_signature
+      #
+      # returns a two element array of [token, signature]
+      private def partition_signed_token(token_and_signature, recovery_token)
+        token_length = recovery_token.num_bytes
+        [token_and_signature[0...token_length], token_and_signature[token_length..-1]]
+      end
+    end
+  end
+end

data/lib/github/delegated_account_recovery/cryptors/default/default_encryptor.rb

@@ -0,0 +1,66 @@
+module GitHub
+  module DelegatedAccountRecovery
+    module DefaultEncryptor
+      class << self
+        include Constants
+
+        # Encrypts the data in an opaque way
+        #
+        # data: the secret to be encrypted
+        #
+        # returns a byte array representation of the data
+        def encrypt(data)
+          EncryptedData.build(data).to_binary_s
+        end
+
+        # Decrypts the data
+        #
+        # ciphertext: the byte array to be decrypted
+        #
+        # returns a string
+        def decrypt(ciphertext)
+          EncryptedData.parse(ciphertext).decrypt
+        end
+
+
+        # payload: binary serialized recovery token (to_binary_s).
+        #
+        # key: the private EC key used to sign the token
+        #
+        # returns signature in ASN.1 DER r + s sequence
+        def sign(payload, key)
+          digest = DIGEST.new.digest(payload)
+          ec = OpenSSL::PKey::EC.new(Base64.strict_decode64(key))
+          ec.dsa_sign_asn1(digest)
+        end
+
+        # payload: token in binary form
+        # signature: signature of the binary token
+        # key: the EC public key used to verify the signature
+        #
+        # returns true if signature validates the payload
+        def verify(payload, signature, key)
+          public_key_hex = format_key(key)
+          pkey = OpenSSL::PKey::EC.new(GROUP)
+          public_key_bn = OpenSSL::BN.new(public_key_hex, 16)
+          public_key = OpenSSL::PKey::EC::Point.new(GROUP, public_key_bn)
+          pkey.public_key = public_key
+
+          pkey.verify(DIGEST.new, signature, payload)
+        rescue OpenSSL::PKey::ECError, OpenSSL::PKey::PKeyError => e
+          raise CryptoError, "Unable verify recovery token"
+        end
+
+        private def format_key(key)
+          sequence, bit_string = OpenSSL::ASN1.decode(Base64.decode64(key)).value
+          unless bit_string.try(:tag) == OpenSSL::ASN1::BIT_STRING
+            raise CryptoError, "DER-encoded key did not contain a bit string"
+          end
+          bit_string.value.unpack("H*").first
+        rescue OpenSSL::ASN1::ASN1Error => e
+          raise CryptoError, "Invalid public key format. The key must be in ASN.1 format. #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/github/delegated_account_recovery/cryptors/default/encrypted_data.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    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 ArgumentError, "Version must be #{PROTOCOL_VERSION}. Supplied: #{token_object.version}" unless token_object.version == CIPHER_VERSION
+        raise ArgumentError, "Auth Tag must be 16 bytes" unless token_object.auth_tag.length == AUTH_TAG_LENGTH
+        raise ArgumentError, "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.symmetric_key].pack("H*")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/github/delegated_account_recovery/cryptors/default/encrypted_data_io.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    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
+end

data/lib/github/delegated_account_recovery/provider.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    module Provider
+      RECOVERY_PROVIDER_CACHE_LENGTH = 60.seconds
+      MAX_RECOVERY_PROVIDER_CACHE_LENGTH = 5.minutes
+      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 = DelegatedAccountRecovery.privacy_policy
+              self.this.icon_152px = DelegatedAccountRecovery.icon_152px
+              self.this.issuer = DelegatedAccountRecovery.authority
+            end
+          end
+        end
+      end
+
+      def initialize(provider_origin = nil, attrs: nil)
+        self.issuer = provider_origin
+        load(attrs) if attrs
+      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
+        DelegatedAccountRecovery.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 = DelegatedAccountRecovery.cache.try(:get, cache_key)
+          response = faraday.get([self.origin, DelegatedAccountRecovery::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 !DelegatedAccountRecovery.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
+end