alexa_verifier 0.1.0 → 1.0.0

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'alexa_verifier'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/alexa_verifier.rb

@@ -1,122 +1,59 @@
-require 'net/http'
-require 'openssl'
-require 'base64'
-require 'time'
-require 'json'
-
-class AlexaVerifier
-  VERSION = '0.1.0'
-
-  class VerificationError < StandardError; end
-
-  DEFAULT_TIMESTAMP_TOLERANCE = 150
-
-  VALID_CERT_HOSTNAME = 's3.amazonaws.com'
-  VALID_CERT_PATH_START = '/echo.api/'
-  VALID_CERT_PORT = 443
-
-  class Builder
-    attr_accessor :verify_signatures, :verify_timestamps, :timestamp_tolerance
-
-    def initialize
-      @verify_signatures = true
-      @verify_timestamps = true
-      @timestamp_tolerance = DEFAULT_TIMESTAMP_TOLERANCE
-    end
-
-    def create
-      AlexaVerifier.new(verify_signatures, verify_timestamps, timestamp_tolerance)
-    end
-  end
-
-  def self.build(&block)
-    builder = Builder.new
-    block.call(builder)
-    builder.create
-  end
-
-  def initialize(verify_signatures = true, verify_timestamps = true, timestamp_tolerance = DEFAULT_TIMESTAMP_TOLERANCE)
-    @cert_cache = {}
-    @verify_signatures = verify_signatures
-    @verify_timestamps = verify_timestamps
-    @timestamp_tolerance = timestamp_tolerance
-  end
-
-  def verify!(cert_url, signature, request)
-    verify_timestamp!(request) if @verify_timestamps
-
-    if @verify_signatures
-      x509_cert = cert(cert_url)
-      public_key = x509_cert.public_key
-
-      unless public_key.verify(hash_type, Base64.decode64(signature), request)
-        raise VerificationError.new, 'Signature does not match!'
-      end
-    end
-
-    true
-  end
-
-  private
-
-    def verify_timestamp!(request)
-      request_json = JSON.parse(request)
-
-      if request_json['request'].nil? or request_json['request']['timestamp'].nil?
-        raise VerificationError.new, 'Timestamp field not present in request'
-      end
-
-      unless Time.parse(request_json['request']['timestamp']) >= (Time.now - @timestamp_tolerance)
-        raise VerificationError.new, "Request is from more than #{@timestamp_tolerance} seconds ago"
-      end
-    end
-
-    def hash_type
-      OpenSSL::Digest::SHA1.new
-    end
-
-    def cert(cert_url)
-      if @cert_cache[cert_url]
-        @cert_cache[cert_url]
+require 'alexa_verifier/certificate_store'
+require 'alexa_verifier/configuration'
+require 'alexa_verifier/verifier'
+require 'alexa_verifier/version'
+
+# Errors
+require 'alexa_verifier/base_error'
+require 'alexa_verifier/invalid_certificate_error'
+require 'alexa_verifier/invalid_certificate_u_r_i_error'
+require 'alexa_verifier/invalid_request_error'
+
+# Verify that HTTP requests sent to an Alexa skill are sent from Amazon
+# @since 0.1.0
+module AlexaVerifier
+  REQUEST_THRESHOLD = 150 # Requests must be received within X seconds
+
+  class << self
+    attr_reader :verifier
+
+    # Returns our configuration object.
+    #
+    # @return [AlexaVerifier::Configuration] our configuration object
+    def configuration
+      verifier.configuration
+    end
+
+    # Sets a new configuration object.
+    #
+    # @param [AlexaVerifier::Configuration] configuration new configuration object
+    # @return [AlexaVerifier::Configuration] configuration object
+    def configuration=(configuration)
+      verifier.configuration = configuration
+    end
+
+    # Delegate all methods to the verifier object, essentially making the
+    # module object behave like a {Verifier}.
+    def method_missing(m, *args, &block)
+      if verifier.respond_to?(m)
+        verifier.send(m, *args, &block)
       else
-        cert_uri = URI.parse(cert_url)
-        validate_cert_uri!(cert_uri)
-        @cert_cache[cert_url] = OpenSSL::X509::Certificate.new(download_cert(cert_uri))
+        super
       end
     end
 
-    def download_cert(uri)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-      http.start
-
-      response = http.request(Net::HTTP::Get.new(uri.request_uri))
-
-      http.finish
-
-      if response.code == '200'
-        response.body
-      else
-        raise VerificationError, "Failed to download certificate at: #{uri}. Response code: #{response.code}, error: #{response.body}"
-      end
+    # Delegating +respond_to+ to the {Verifier}.
+    def respond_to_missing?(m, include_private = false)
+      verifier.respond_to?(m) || super
     end
 
-    def validate_cert_uri!(cert_uri)
-      unless cert_uri.scheme == 'https'
-        raise VerificationError, "Certificate URI MUST be https: #{cert_uri}"
-      end
-
-      unless cert_uri.port == VALID_CERT_PORT
-        raise VerificationError, "Certificate URI port MUST be #{VALID_CERT_PORT}, was: #{cert_uri.port}"
-      end
+    private
 
-      unless cert_uri.host == VALID_CERT_HOSTNAME
-        raise VerificationError, "Certificate URI hostname must be #{VALID_CERT_HOSTNAME}: #{cert_uri}"
-      end
-
-      unless cert_uri.request_uri.start_with?(VALID_CERT_PATH_START)
-        raise VerificationError, "Certificate URI path must start with #{VALID_CERT_PATH_START}: #{cert_uri}"
-      end
+    # Initialize a new instance of our Verifier to hold global configurations.
+    def initialize_verifier
+      @verifier = AlexaVerifier::Verifier.new
     end
+  end
+
+  initialize_verifier
 end

data/lib/alexa_verifier/base_error.rb

@@ -0,0 +1,4 @@
+module AlexaVerifier
+  class BaseError < StandardError
+  end
+end

data/lib/alexa_verifier/certificate_store.rb

@@ -0,0 +1,98 @@
+module AlexaVerifier
+  # A module used to download, cache and serve certificates from our requests.
+  # @since 0.1
+  module CertificateStore
+    CERTIFICATE_CACHE_TIME = 1800 # 30 minutes
+    CERTIFICATE_SEPARATOR = '-----BEGIN CERTIFICATE-----'.freeze
+
+    class << self
+      # Given a certificate uri, either download the certificate and chain, or
+      # load them from our certificate store.
+      #
+      # @param [String] uri the uri of our certificate
+      # @return [OpenSSL::X509::Certificate, Array<OpenSSL::X509::Certificate>] our certificate file and chain
+      def fetch(uri)
+        store
+
+        if cache_valid?(@store[uri])
+          certificate = @store[uri][:certificate]
+          chain = @store[uri][:chain]
+        else
+          chain = generate_certificate_chain_from_data(download_certificate(uri))
+          certificate = chain.delete_at(0)
+
+          @store[uri] = { timestamp: Time.now, certificate: certificate, chain: chain }
+        end
+
+        [certificate, chain]
+      end
+
+      # Given a certificate uri, remove the certificate from our store.
+      #
+      # @param [String] uri the uri of our certificate
+      # @return [nil|Hash] returns nil if the certificate was not in the store,
+      #   or a Hash representing the deleted certificate
+      def delete(uri)
+        store
+
+        @store.delete(uri)
+      end
+
+      # Returns a copy of our certificate store
+      #
+      # @return [Hash] returns our certificate store
+      def store
+        @store ||= {}
+      end
+
+      private
+
+      # Given a certificate entry from our store, tell us if the cache is still valid
+      #
+      # @param [Hash] certificate_entry the entry we are checking
+      # @return [Boolean] is the certificate cache valid?
+      def cache_valid?(certificate_entry)
+        return false if certificate_entry.nil?
+
+        (Time.now <= (certificate_entry[:timestamp] + CERTIFICATE_CACHE_TIME))
+      end
+
+      # Given a certificate uri, download it and return the certificate data
+      #
+      # @param [String] uri the uri of our certificates
+      # @return [String] certificate data
+      def download_certificate(uri)
+        certificate_uri = URI.parse(uri)
+
+        certificate_data = nil
+
+        Net::HTTP.start(certificate_uri.host, certificate_uri.port, use_ssl: true) do |http|
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+          response = http.request(Net::HTTP::Get.new(certificate_uri))
+
+          raise AlexaVerifier::InvalidCertificateError, "Unable to download certificate from #{certificate_uri} - Got #{response.code} status code" unless response.is_a? Net::HTTPOK
+
+          certificate_data = response.body
+        end
+
+        certificate_data
+      end
+
+      # Given a string of certificate data, which may contain one or more certificates,
+      # convert it into an array of certificate object representing the full chain.
+      #
+      # @param [String] certificate_data the certificate data we should build our chain from
+      # @return [Array<OpenSSL::X509::Certificate>] an array of certificate objects representing our chain
+      def generate_certificate_chain_from_data(certificate_data)
+        split_data = certificate_data.split(CERTIFICATE_SEPARATOR)
+
+        # Remove any empty string artifacts
+        split_data.reject! { |data| data.strip.empty? }
+
+        # Convert our array of split out certificate data strings, into an array of certificate objects
+        split_data.map { |data| OpenSSL::X509::Certificate.new(CERTIFICATE_SEPARATOR + data) }
+      end
+    end
+  end
+end

data/lib/alexa_verifier/configuration.rb

@@ -0,0 +1,53 @@
+module AlexaVerifier
+  # Stores our configuration information
+  # @since 0.2.0
+  class Configuration
+    attr_accessor :enabled, :verify_uri, :verify_timeliness, :verify_certificate, :verify_signature
+
+    # Create a new instance of our configuration object that has all of our settings enabled
+    def initialize
+      @enabled            = true
+      @verify_uri         = true
+      @verify_timeliness  = true
+      @verify_certificate = true
+      @verify_signature   = true
+    end
+
+    # Is AlexaVerifier enabled?
+    #
+    # This setting overrides all other settings
+    #
+    # @return [Boolean]
+    def enabled?
+      @enabled
+    end
+
+    # Should we verify the certificate URI?
+    #
+    # @return [Boolean]
+    def verify_uri?
+      @enabled ? @verify_uri : @enabled
+    end
+
+    # Should we verify the request's timeliness?
+    #
+    # @return [Boolean]
+    def verify_timeliness?
+      @enabled ? @verify_timeliness : @enabled
+    end
+
+    # Should we verify that the certificate is 'valid'?
+    #
+    # @return [Boolean]
+    def verify_certificate?
+      @enabled ? @verify_certificate : @enabled
+    end
+
+    # Should we verify that the request was signed with our certificate?
+    #
+    # @return [Boolean]
+    def verify_signature?
+      @enabled ? @verify_signature : @enabled
+    end
+  end
+end

data/lib/alexa_verifier/invalid_certificate_error.rb

@@ -0,0 +1,8 @@
+module AlexaVerifier
+  # An error that is raised when the certificate referenced from a request is
+  # invalid.
+  #
+  # @since 0.1
+  class InvalidCertificateError < AlexaVerifier::BaseError
+  end
+end

data/lib/alexa_verifier/invalid_certificate_u_r_i_error.rb

@@ -0,0 +1,31 @@
+module AlexaVerifier
+  # An error that is raised when the certificate URI from a request is invalid.
+  # @since 0.1
+  class InvalidCertificateURIError < AlexaVerifier::BaseError
+    # Create a new instance of our InvalidCertificateURIError
+    #
+    # @param [String] message the main message we want to include
+    # @param [String] value an optional value used when creating a message.
+    #
+    # @example Error without a value
+    #   AlexaVerifier::InvalidCertificateURIError.new(
+    #     'No URI Passed'
+    #   ) #=> #<AlexaVerifier::InvalidCertificateURIError
+    #             @message="Invalid certificate URI : No URI Passed.">
+    #
+    # @example Error with a valuex
+    #   AlexaVerifier::InvalidCertificateURIError.new(
+    #     "Expected 'a'",
+    #     'b'
+    #   ) #=> #<AlexaVerifier::InvalidCertificateURIError
+    #             @message="Invalid certificate URI : Expected 'a'. Got: 'b'.">
+    #
+    # @return [AlexaVerifier::InvalidCertificateURIError] a new instance
+    def initialize(message, value = nil)
+      error_message = "Invalid certificate URI : #{message}."
+      error_message = "#{error_message} Got: '#{value}'." if value
+
+      super(error_message)
+    end
+  end
+end

data/lib/alexa_verifier/invalid_request_error.rb

@@ -0,0 +1,8 @@
+module AlexaVerifier
+  # An error that is raised when the certificate referenced from a request is
+  # invalid.
+  #
+  # @since 0.1
+  class InvalidRequestError < AlexaVerifier::BaseError
+  end
+end

data/lib/alexa_verifier/verifier.rb

@@ -0,0 +1,125 @@
+require_relative 'verifier/certificate_verifier'
+require_relative 'verifier/certificate_u_r_i_verifier'
+
+module AlexaVerifier
+  # A namespace for all of our verifiers to live under
+  # @since 0.1
+  class Verifier
+    attr_accessor :configuration
+
+    # Create a new AlexaVerifier::Verifier object
+    #
+    # @yield the configuration block
+    # @yieldparam config [AlexaVerifier::Configuration] the configuration object
+    def initialize
+      @configuration = AlexaVerifier::Configuration.new
+
+      yield @configuration if block_given?
+    end
+
+    # Validate a request object from Rack.
+    # Raise an error if it is not valid.
+    #
+    # @param [Rack::Request::Env] request a Rack HTTP Request
+    #
+    # @raise [AlexaVerifier::InvalidCertificateURIError]
+    #   there was a problem validating the certificate URI from your request
+    #
+    # @return [nil] will always return nil
+    def valid!(request)
+      signature_certificate_url = request.env['HTTP_SIGNATURECERTCHAINURL']
+
+      AlexaVerifier::Verifier::CertificateURIVerifier.valid!(signature_certificate_url) if @configuration.verify_uri?
+
+      raw_body = request.body.read
+      request.body && request.body.rewind # call the rewind method if it exists (handles Sinatra specifically)
+
+      check_that_request_is_timely(raw_body) if @configuration.verify_timeliness?
+
+      check_that_request_is_valid(signature_certificate_url, request, raw_body)
+
+      true
+    end
+
+    # Validate a request object from Rack.
+    # Return a boolean.
+    #
+    # @param [Rack::Request::Env] request a Rack HTTP Request
+    # @return [Boolean] is the request valid?
+    def valid?(request)
+      begin
+        valid!(request)
+      rescue AlexaVerifier::BaseError => e
+        puts e
+
+        return false
+      end
+
+      true
+    end
+
+    # Used to configure AlexaVerifier.
+    #
+    # @example
+    #    AlexaVerifier.configure do |c|
+    #      c.some_config_option = true
+    #    end
+    #
+    # @yield the configuration block
+    # @yieldparam config [AlexaVerifier::Configuration] the configuration object
+    def configure
+      yield @configuration
+    end
+
+    private
+
+    # Prevent replays of requests by checking that they are timely.
+    #
+    # @param [String] raw_body the raw body of our https request
+    # @raise [AlexaVerifier::InvalidRequestError] raised when the timestamp is not timely, or is not set
+    def check_that_request_is_timely(raw_body)
+      request_json = JSON.parse(raw_body)
+
+      raise AlexaVerifier::InvalidRequestError, 'Timestamp field not present in request' if request_json.fetch('request', {}).fetch('timestamp', nil).nil?
+
+      request_is_timely = (Time.parse(request_json['request']['timestamp'].to_s) >= (Time.now - REQUEST_THRESHOLD))
+      raise AlexaVerifier::InvalidRequestError, "Request is from more than #{REQUEST_THRESHOLD} seconds ago" unless request_is_timely
+    end
+
+    # Check that our request is valid.
+    #
+    # @param [String] signature_certificate_url the url for our signing certificate
+    # @param [Rack::Request::Env] request the request object
+    # @param [String] raw_body the raw body of our https request
+    def check_that_request_is_valid(signature_certificate_url, request, raw_body)
+      certificate, chain = AlexaVerifier::CertificateStore.fetch(signature_certificate_url) if @configuration.verify_certificate? || @configuration.verify_signature?
+
+      begin
+        AlexaVerifier::Verifier::CertificateVerifier.valid!(certificate, chain) if @configuration.verify_certificate?
+
+        check_that_request_was_signed(certificate.public_key, request, raw_body) if @configuration.verify_signature?
+      rescue AlexaVerifier::InvalidCertificateError, AlexaVerifier::InvalidRequestError => error
+        # We don't want to cache a certificate that fails our checks as it could lock us out of valid requests for the cache length
+        AlexaVerifier::CertificateStore.delete(signature_certificate_url)
+
+        raise error
+      end
+    end
+
+    # Check that our request was signed by a given public key.
+    #
+    # @param [OpenSSL::PKey::PKey] certificate_public_key the public key we are checking
+    # @param [Rack::Request::Env] request the request object we are checking
+    # @param [String] raw_body the raw body of our https request
+    # @raise [AlexaVerifier::InvalidRequestError] raised if our signature does not match the certificate provided
+    def check_that_request_was_signed(certificate_public_key, request, raw_body)
+      signed_by_certificate = certificate_public_key.verify(
+        OpenSSL::Digest::SHA1.new,
+        Base64.decode64(request.env['HTTP_SIGNATURE']),
+        raw_body
+      )
+
+      raise AlexaVerifier::InvalidRequestError, 'Signature does not match certificate provided' unless signed_by_certificate
+    end
+  end
+end