http_signature 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ce69899c93af8245c7a11f207ae55d487ecc360df04c231d5ae1089afe897a6b
+  data.tar.gz: c26e3a5d0a06e97b03354cab9f3e20dc0fee3d06aca01ddd03fb55a7ab9c022e
+SHA512:
+  metadata.gz: 0b96af0ec445b8b0f298d74e0743035ff2818d85c827892a8366cdf171338b9bf24cd5183b3317de58bcff01e191b60935e0ec4bc84fef7dcf05bc4d6d622666
+  data.tar.gz: 5b709409aa43df9606c5fadfc202721664db25005b7935e5aeb62df7755f22b8fd536f13c5972fb321a361d11e6c9e02ef77e96d553bf7766b9417b40958f6c6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rpc.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    http-signature (0.0.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.10.3)
+    rake (12.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  http-signature!
+  minitest
+  rake
+
+BUNDLED WITH
+   1.16.0

data/README.md

@@ -0,0 +1,168 @@
+# HTTP Signature
+[![CircleCI](https://circleci.com/gh/bolmaster2/http-signature.svg?style=svg)](https://circleci.com/gh/bolmaster2/http-signature)
+
+Create and validate HTTP request signature according to this draft: https://tools.ietf.org/html/draft-cavage-http-signatures-08
+
+Aims to only implement the creation and validation of the signature without any external dependencies.
+The idea is to implement adapters to popular http libraries to make it easy to use.
+
+## Usage
+
+### Basic
+The most basic usage without any extra headers. The default algorithm is `hmac-sha256`.
+```ruby
+HTTPSignature.create(
+  url: 'https://example.com/foo',
+  key_id: 'Test',
+  key: 'secret 🙈'
+)
+# 'keyId="Test",algorithm="hmac-sha256",headers="(request-target)",signature="OQ/dHqRW9vFmrW/RCHg7O2Fqx+3uqxJw81p6k9Rcyo4="'
+```
+
+### With headers, query parameters and a body
+Uses both query parameters (in query string) and a `json` body as a `POST` request.
+Also shows how to set `rsa-sha256` as algorithm. The `digest` is as you see basically
+a `sha-256` digest of the request body.
+
+```ruby
+params = {
+  param: 'value',
+  pet: 'dog'
+}
+
+body = '{"hello": "world"}'
+
+headers = {
+  'date': 'Thu, 05 Jan 2014 21:31:40 GMT',
+  'content-type': 'application/json',
+  'digest': HTTPSignature.create_digest(body),
+  'content-length': body.length
+}
+
+HTTPSignature.create(
+  url: 'https://example.com/foo',
+  method: :post,
+  query_string_params: params,
+  headers: headers,
+  key_id: 'Test',
+  algorithm: 'rsa-sha256',
+  key: File.read('key.pem'),
+  body: body
+)
+```
+
+### With digest header auto-added
+When digest header is omitted it's auto added as last header generated from the `body`:
+
+```ruby
+body = '{"foo": "bar"}'
+
+HTTPSignature.create(
+  url: 'https://example.com/foo',
+  key_id: 'Test',
+  key: 'secret 🙈',
+  body: body
+)
+# 'keyId="Test",algorithm="hmac-sha256",headers="(request-target) digest",signature="3Jm5jnCSKX3fYLd58RqRdafZKeuSbUEPhn7grCGx4vg="'
+```
+
+### Validate asymmetric signature
+With an asymmetric algorithm you can't just recreate the same header and see if they
+check out, because you need the private key to do that and because the one validating
+the signature should only have access to the public key, you need to validate it with that.
+
+Imagine the incoming HTTP request looks like this:
+```
+POST /foo HTTP/1.1
+Host: example.com
+Date: Thu, 05 Jan 2014 21:31:40 GMT
+Content-Type: application/json
+Content-Length: 18
+Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+Signature: keyId="Test-1",algorithm="rsa-sha256",headers="(request-target) host date content-type content-length digest",signature="YGPVM1tGHD7CHgTmroy9apLtVazdESzMl4vj1koYHNCMmTEDor4Om5TDZDFaJdny5dF3gq+PQQuPwyknNEvACmSjwVXzljPFxaY/JMZTqAdD0yHTP2Rx0Y/J4GwgKARWTZUmccfVYsXp86PhIlCymzleZzYCzj6shyg9NB7Ht+k="
+
+{"hello": "world"}
+```
+
+Let's assume we have this request ☝️ in a `request` object for the sake of the example:
+```ruby
+HTTPSignature.valid?(
+  url: request.url,
+  method: request.method,
+  headers: request.headers,
+  body: request.body,
+  key: OpenSSL::PKey::RSA.new('public_key.pem'),
+  algorithm: 'rsa-sha256'
+)
+```
+
+## Setup
+```
+bundle install
+```
+
+## Test
+The tests are written with `minitest` using specs. Run them all with `rake`:
+```bash
+rake test
+```
+Or a single with pattern matching:
+```bash
+rake test TEST=test/http_signature_test.rb TESTOPTS="--name=/appends\ the\ query_string_params/"
+```
+
+## Example usage
+### Faraday middleware on outgoing requests
+Example of using it on an outgoing request.
+```ruby
+# TODO: Move this into gem
+class AddRequestSignature < Faraday::Middleware
+  def call(env)
+    if env[:body]
+      env[:request_headers].merge!('Digest' => HTTPSignature.create_digest(env[:body]))
+    end
+
+    # Choose which headers to sign
+    headers_filter = %w{ Host Date Digest }
+    headers_to_sign = env[:request_headers].select { |k, v| headers_filter.include?(k.to_s) }
+
+    signature = HTTPSignature.create(
+      url: env[:url],
+      method: env[:method],
+      headers: headers_to_sign,
+      key: ENV.fetch('REQUEST_SIGNATURE_KEY'),
+      key_id: ENV.fetch('REQUEST_SIGNATURE_KEY_ID'),
+      algorithm: 'hmac-sha256',
+      body: env[:body] ? env[:body] : ''
+    )
+
+    env[:request_headers].merge!('Signature' => signature)
+
+    @app.call(env)
+  end
+end
+
+# Tell faraday to use the middleware. Read more about it here: https://github.com/lostisland/faraday#advanced-middleware-usage
+Faraday.new('http://example.com') do |faraday|
+  faraday.use(AddRequestSignature)
+  faraday.adapter(Faraday.default_adapter)
+end
+
+response = conn.get('/')
+```
+
+### Rack middleware
+I've written a quite sloppy but totally usable rack middleware that validates every incoming request.
+[See it here](examples/rack_middleware.rb). Soon I'll add it to the gem.
+
+## License
+This project is licensed under the terms of the [MIT license](https://opensource.org/licenses/MIT).
+
+## Todo
+- Structure and add middlewares into gem
+- Add more example of use with different http libraries
+- Implement algorithms:
+  - ecdsa-sha256
+- When creating the signing string, follow the spec exactly:
+  https://tools.ietf.org/html/draft-cavage-http-signatures-08#section-2.3,
+  e.g, concatenate multiple instances of the same headers and remove surrounding whitespaces

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end

data/examples/faraday_middleware.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'http_signature'
+
+class AddRequestSignature < Faraday::Middleware
+  def call(env)
+    if env[:body]
+      env[:request_headers].merge!('Digest' => HTTPSignature.create_digest(env[:body]))
+    end
+
+    # Choose which headers to sign
+    filtered_headers = %w{ Host Date Digest }
+    headers_to_sign = env[:request_headers].select { |k, v| filtered_headers.include?(k.to_s) }
+
+    headers.select { |header| headers_to_sign.includes(header) }.to_h
+
+    signature = HTTPSignature.create(
+      url: env[:url],
+      method: env[:method],
+      headers: headers,
+      key: ENV.fetch('REQUEST_SIGNATURE_KEY'),
+      key_id: ENV.fetch('REQUEST_SIGNATURE_KEY_ID'),
+      algorithm: 'hmac-sha256',
+      body: env[:body] ? env[:body] : ''
+    )
+
+    env[:request_headers].merge!('Signature' => signature)
+
+    @app.call(env)
+  end
+end

data/examples/rack_middleware.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'http_signature'
+
+# Rack middleware using http-signature gem to validate signature on every incoming request
+class ValidateRequestSignature
+  KEY = ENV.fetch('REQUEST_SIGNATURE_KEY')
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+    return [401, {}, ['No signature header']] unless request.get_header("HTTP_SIGNATURE")
+
+    request_body = request.body.gets
+    request_headers = parse_request_headers(request)
+    begin
+      parsed_signature = parse_signature(request_headers)
+    rescue
+      return [401, {}, ['Invalid signature :(']]
+    end
+    headers_to_sign = request_headers.select { |k, v| parsed_signature['headers'].include?(k) }
+
+    params = {
+      url: request.path,
+      method: request.request_method,
+      headers: headers_to_sign,
+      key: KEY,
+      key_id: parsed_signature['keyId'],
+      algorithm: parsed_signature['algorithm'],
+      body: request_body ? request_body : '',
+      query_string_params: Rack::Utils.parse_nested_query(request.query_string)
+    }
+
+    valid_signature =
+      if parsed_signature['algorithm'].include?('rsa')
+        HTTPSignature.valid?(**params)
+      else
+        HTTPSignature.create(**params) == request_headers['signature']
+      end
+
+    if valid_signature
+      @app.call(env)
+    else
+      [401, {}, ['Invalid signature :(']]
+    end
+  end
+
+  private
+
+  def parse_request_headers(request)
+    request_headers = {}
+
+    request.each_header do |header|
+      if header[0].include?('HTTP_') && header[0] != 'HTTP_VERSION'
+        request_headers[header[0].gsub('HTTP_', '').gsub("_", "-").downcase] = header[1]
+      end
+    end
+
+    request_headers
+  end
+
+  def parse_signature(request_headers)
+    Rack::Utils.parse_nested_query(
+      request_headers['signature'].gsub(',', '&')
+    ).map do |k, v|
+      [k, v.tr('"', '')]
+    end.to_h
+  end
+end

data/http_signature.gemspec

@@ -0,0 +1,23 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = 'http_signature'
+  spec.version       = '0.0.2'
+  spec.authors       = ['Joel Larsson']
+  spec.email         = ['bolmaster2@gmail.com']
+
+  spec.summary       = 'Create and validate HTTP request signature'
+  spec.description   = 'Create and validate HTTP request signature according to this draft: https://tools.ietf.org/html/draft-cavage-http-signatures-08'
+  spec.homepage      = 'https://github.com/bolmaster2/http-signature'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'minitest'
+end

data/lib/http_signature.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+require 'base64'
+require 'uri'
+
+module HTTPSignature
+  # Create signature based on the data sent in
+  #
+  # @param url [String] Full request url, can include query string as well
+  # @param query_string_params [Hash] Query string parameters, appends params to
+  # url if query string is already found in it
+  # @param body [String] Request body as a string, i.e., the "raw" request body
+  # @param headers [Hash] Request headers to include in the signature
+  # @param key [String] Key/secret that is used by the corresponding `algorithm`
+  # @param key_id [String] Key id
+  # @param method [Symbol] Request method, default is `:get`
+  # @param algorithm [String] Algorithm to use when signing, check `supported_algorithms` for
+  # @return [String] The signature header value to use in "Signature" header
+  def self.create(url:, query_string_params: {}, body: '', headers: {}, key:,
+    key_id: SecureRandom.hex(8),
+    method: :get,
+    algorithm: 'hmac-sha256'
+  )
+
+    raise 'Unsupported algorithm :(' unless supported_algorithms.include?(algorithm)
+
+    uri = URI(url)
+    path = uri.path
+    headers = add_digest(headers, body)
+    headers = convert_headers(headers)
+    query = create_query_string(uri, query_string_params)
+
+    string_to_sign = create_signing_string(method: method, path: path,
+      query: query, headers: headers)
+
+    signature = sign(string_to_sign, key: key, algorithm: algorithm)
+    create_signature_header(key_id: key_id, headers: headers, signature: signature,
+      algorithm: algorithm)
+  end
+
+  def self.sign(string, key:, algorithm:)
+    case algorithm
+    when 'hmac-sha256'
+      OpenSSL::HMAC.digest('SHA256', key, string)
+    when 'hmac-sha512'
+      OpenSSL::HMAC.digest('SHA512', key, string)
+    when 'rsa-sha256'
+      k = OpenSSL::PKey::RSA.new(key)
+      k.sign(OpenSSL::Digest::SHA256.new, string)
+    when 'rsa-sha512'
+      k = OpenSSL::PKey::RSA.new(key)
+      k.sign(OpenSSL::Digest::SHA512.new, string)
+    end
+  end
+
+  def self.create_signature_header(key_id:, headers: [], signature:, algorithm:)
+    headers = headers.map { |h| h.split(':').first }
+    header_fields = ['(request-target)'].concat(headers).join(' ')
+
+    [
+      "keyId=\"#{key_id}\"",
+      "algorithm=\"#{algorithm}\"",
+      "headers=\"#{header_fields}\"",
+      "signature=\"#{Base64.strict_encode64(signature)}\""
+    ].join(',')
+  end
+
+  # TODO: Support them all: rsa-sha1, rsa-sha512, dsa-sha1, hmac-sha1
+  def self.supported_algorithms
+    ['hmac-sha256', 'hmac-sha512', 'rsa-sha256', 'rsa-sha512']
+  end
+
+  # Create the digest header based on the request body
+  # @param body [String] Raw request body string
+  # @return [String] SHA256 and base64 digested string with prefix: 'SHA-256='
+  def self.create_digest(body)
+    'SHA-256=' + Digest::SHA256.base64digest(body)
+  end
+
+  # Creates the string to sign
+  # See details here: https://tools.ietf.org/html/draft-cavage-http-signatures-08#section-2.3
+  # TODO: Concatenate multiple instances of the same headers
+  # Also remove leading and trailing whitespace
+  # @return [String]
+  def self.create_signing_string(method:, path:, query:, headers:)
+    [
+      "(request-target): #{method.upcase} #{path}#{query}",
+    ].concat(headers).join("\n")
+  end
+
+  # Check if signature is valid. Using the exact same parameters as .create
+  # minus `key_id`
+  #
+  # @param url [String] Full request url, can include query string as well
+  # @param query_string_params [Hash] Query string parameters, appends params to
+  # url if query string is already found in it
+  # @param body [String] Request body as a string, i.e., the "raw" request body
+  # @param headers [Hash] Request headers to include in the signature
+  # @param key [String] Key/secret that is used by the corresponding `algorithm`
+  # @param method [Symbol] Request method, default is `:get`
+  # @param algorithm [String] Algorithm to use when signing, check `supported_algorithms` for
+  # @return [Boolean] Valid or not, Crypto is kinda binary in this case :)
+  def self.valid?(url:, query_string_params: {}, body: '', headers: {}, key:, method:, algorithm:)
+    raise 'Key needs to be public' unless key.public?
+
+    # TODO: A lot of the code here is exactly as `.create`, i.e., this could be DRYed :point_down:
+    uri = URI(url)
+    path = uri.path
+    signature = headers.delete(:signature)
+    headers = convert_headers(headers)
+    query = create_query_string(uri, query_string_params)
+
+    string_to_sign = create_signing_string(
+      method: method, path: path, query: query, headers: headers
+    )
+
+    key.verify(
+      get_digest(algorithm), get_signature_from_header(signature), string_to_sign
+    )
+  end
+
+  # Maps algoritgm string to digest object
+  # @param algorithm [String]
+  # @return [OpenSSL::Digest] Instance of `OpenSSL::Digest::SHA256` or OpenSSL::Digest::SHA512
+  def self.get_digest(algorithm)
+    {
+      'rsa-sha256' => OpenSSL::Digest::SHA256.new,
+      'rsa-sha512' => OpenSSL::Digest::SHA512.new
+    }[algorithm]
+  end
+
+  # Extract the actual signature from the whole "Signature" header
+  # @param header [String]
+  # @return [String]
+  def self.get_signature_from_header(header)
+    Base64.strict_decode64(header.match(/signature\=\"(.*)\"/)[1])
+  end
+
+  # When query string params is also set on the url, append the params defined
+  # in `query_string_params` and make a joint query string
+  def self.create_query_string(uri, query_string_params)
+    if uri.query || !query_string_params.empty?
+      delimiter = uri.query.nil? ? '' : '&'
+      '?' + (query_string_params.empty? ? '' : [uri.query.to_s, delimiter, URI.encode_www_form(query_string_params)].join)
+    end
+  end
+  # Convert a header hash into an array with header strings
+  # { header: 'value'} -> ['header: value']
+  def self.convert_headers(headers)
+    headers.map do |key, value|
+      [key.to_s.downcase.strip, value.strip].join(': ')
+    end
+  end
+
+  def self.add_digest(headers, body)
+    headers[:digest] = create_digest(body) unless body.empty?
+
+    headers
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: http_signature
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Joel Larsson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Create and validate HTTP request signature according to this draft:
+  https://tools.ietf.org/html/draft-cavage-http-signatures-08'
+email:
+- bolmaster2@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- examples/faraday_middleware.rb
+- examples/rack_middleware.rb
+- http_signature.gemspec
+- lib/http_signature.rb
+homepage: https://github.com/bolmaster2/http-signature
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: Create and validate HTTP request signature
+test_files: []