url_signer 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49fa2bf8648727c23d178c1e56fe48292ad9072f
+  data.tar.gz: 838502de43dea1e2811b34d84c5f45c3855980d7
+SHA512:
+  metadata.gz: af6a065fff64fcc206865a2efd0811dbd7e70ccb559ba2ac59afc6fbf8c9311c32fbb9e9135b3e7b911edba5b20c29a77c54fea1828255e4fb0ce2779299eaa4
+  data.tar.gz: 8b12be5dafbde8ae03e3ec96c515a543b807b0283d551335502724168427b21fe38cb744d462b5225c4273032fa7484f4b68cb1c6d2b0460c92a60e58fc8c1d9

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Aurélien Noce
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,48 @@
+# UrlSign
+
+Quickly generate and verify signed urls.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'url_signer'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install url_signer
+
+## Usage
+
+### URL signing
+
+To convert a URL into a signed url, pass it to `UrlSigner.sign`, passing it either a string of an instance of `URI`.
+
+```ruby
+>>> signed_url = UrlSigner.sign('http://google.fr?q=test', key='mykey')
+```
+
+the returned value `signed_url` is an instance of `URI`.
+
+### URL verification
+
+Given a signed URL, you can check its authenticity by calling `UrlSigner.valid?` on it:
+
+```ruby
+>>> UrlSigner.valid?(signed_url)
+true
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/url_sign/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/url_signer/base.rb

@@ -0,0 +1,55 @@
+require 'uri'
+require 'cgi'
+require 'digest/hmac'
+require 'digest/sha1'
+
+module UrlSigner
+  class Base < Struct.new(:url, :key, :hash_method)
+
+    def initialize(url, key: nil, hash_method: nil)
+      # load and check url
+      url = URI.parse(url) if url.kind_of?(String)
+      raise "expecting a String or URI instance" unless url.kind_of?(URI)
+
+      # load and check signing key
+      key ||= ENV['URL_SIGNING_KEY']
+      raise "You need to provided a signing key to your UrlSigner instance" unless key
+
+      # load the hash method
+      hash_method ||= Digest::SHA1
+
+      super(url, key, hash_method)
+    end
+
+    def signature
+      compute_signature(url.host, url.path, params)
+    end
+
+    protected
+
+    def params
+      @params ||= begin
+        raw_params = CGI.parse(query || '')
+        Hash[raw_params.map { |k,v| v.size == 1 ? [k, v[0]] : [k, v] }]
+      end
+    end
+
+    def query
+      url.query
+    end
+
+    def compute_signature(host, path, params)
+      keys = params.keys.sort
+      query_string = keys.map { |k| "#{CGI.escape(k)}=#{CGI.escape(params[k])}" }.join
+      base_string = "#{CGI.escape(host)}&#{CGI.escape(path)}&#{CGI.escape(query_string)}"
+
+      return Digest::HMAC.hexdigest(base_string, key, hash_method)
+    end
+
+    def signed?
+      params.has_key?('signature')
+    end
+
+
+  end
+end

data/lib/url_signer/signer.rb

@@ -0,0 +1,23 @@
+require 'url_signer/base'
+
+module UrlSigner
+  class Signer < Base
+
+    def sign
+      raise "this URL is already signed !" if signed?
+
+      # build new url
+      signed_url = url.dup
+      signed_url.query = extended_query
+      signed_url
+    end
+
+    private
+
+    def extended_query
+      base_query = query ? query + '&' : ''
+      base_query + "signature=#{signature}"
+    end
+
+  end
+end

data/lib/url_signer/verifier.rb

@@ -0,0 +1,26 @@
+require 'url_signer/base'
+
+module UrlSigner
+  class Verifier < Base
+
+    def valid?
+      return false unless signed?
+
+      # extract signature from params
+      remaining_params = params.dup
+      provided_signature = remaining_params.delete('signature')
+
+      # recompute the signature using the secret key
+      recomputed_signature = compute_signature(url.host, url.path, remaining_params)
+
+      safe_compare(provided_signature, recomputed_signature)
+    end
+
+    private
+
+    def safe_compare(signature, other_signature)
+      hash_method.digest(signature) == hash_method.digest(other_signature)
+    end
+
+  end
+end

data/lib/url_signer/version.rb

@@ -0,0 +1,3 @@
+module UrlSigner
+  VERSION = "0.1"
+end

data/lib/url_signer.rb

@@ -0,0 +1,44 @@
+module UrlSigner
+  autoload :Base, 'url_signer/base'
+  autoload :Signer, 'url_signer/signer'
+  autoload :Verifier, 'url_signer/verifier'
+
+  module_function
+
+  # Returns a new <tt>URI</tt> instance by appending a <tt>signature</tt> parameter to the query of +url+.
+  # The method accepts that +url+ can be either a <tt>String</tt> or a <tt>URI</tt> instance.
+  #
+  #   signed_url = UrlSigner.sign('http://google.fr&q=test') # => <URI::HTTP...>
+  #
+  # The following key/value parameters can be given to +options+:
+  # * <tt>:key</tt> - the secret key used for encryption
+  # * <tt>:hash_method</tt> - the hash function to pass to <tt>Digest::HMAC</tt>. Defaults to <tt>Digest::SHA1</tt>.
+  #
+  # Note that if a +URL_SIGNING_KEY+ environment variable is defined, it will be used as a default value for the +:key+ option.
+  def sign(url, *options)
+    temp_signer = UrlSigner::Signer.new(url, *options)
+    temp_signer.sign
+  end
+
+  # Verify the authenticity of the +url+ by checking the value of the <tt>signature</tt> query parameter (if present).
+  # The method accepts that +url+ can be either a <tt>String</tt> or a <tt>URI</tt> instance.
+  #
+  # The following key/value parameters can be given to +options+:
+  # * <tt>:key</tt> - the secret key used for encryption
+  # * <tt>:hash_method</tt> - the hash function to pass to <tt>Digest::HMAC</tt>. Defaults to <tt>Digest::SHA1</tt>.
+  #
+  # Note that if a +URL_SIGNING_KEY+ environment variable is defined, it will be used as a default value for the +:key+ option.
+  #
+  # ==== Examples
+  #
+  #   dummy_url = 'http://google.fr?q=test
+  #   UrlSigner.valid?(dummy_url) # => false
+  #
+  #   signed_url = UrlSigner.sign('http://google.fr&q=test')
+  #   UrlSigner.valid?(signed_url) # => true
+  def valid?(url, *options)
+    temp_verifier = UrlSigner::Verifier.new(url, *options)
+    temp_verifier.valid?
+  end
+
+end

data/spec/base_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+module UrlSigner
+  describe Base do
+    let(:url_string) { 'http://mysite.com/my/path?test=1&retest=2' }
+    let(:url) { URI.parse(url_string) }
+    let(:params) { CGI.parse(url.query) }
+
+    let(:base) { Base.new(url, key: 'testkey') }
+
+    describe "#signature:" do
+      let(:url_with_other_params) { URI.parse('http://mysite.com/my/path?test=2&retest=2') }
+      let(:url_with_other_domain) { URI.parse('http://myothersite.com/my/path?test=1&retest=2') }
+      let(:url_with_other_path) { URI.parse('http://mysite.com/my/other/path?test=1&retest=2') }
+
+      it "depends on the signing key" do
+        other = Base.new(url, key: 'othertestkey')
+        expect(other.signature).not_to eq(base.signature)
+      end
+
+      it "depends on the parameters" do
+        other = Base.new(url_with_other_params, key: 'testkey')
+        expect(other.signature).not_to eq(base.signature)
+      end
+
+      it "depends on the domain" do
+        other = Base.new(url_with_other_domain, key: 'testkey')
+        expect(other.signature).not_to eq(base.signature)
+      end
+
+      it "depends on the path" do
+        other = Base.new(url_with_other_path, key: 'testkey')
+        expect(other.signature).not_to eq(base.signature)
+      end
+    end # #signature
+
+    describe "url parameter:" do
+
+      context "when the url is given as a string," do
+        let(:base_from_string) { Base.new(url_string, key: 'testkey') }
+
+        it "builds a new signer" do
+          expect { Base.new(url_string, key: 'testkey') }.not_to raise_error
+        end
+
+        it "works as usual" do
+          expect{ base_from_string.signature }.not_to raise_error
+        end
+
+        it "is equivalent to the save Signer built from a URI instance" do
+          expect(base_from_string.signature).to eq(base.signature)
+        end
+
+        it "raise if the URL can not be parsed" do
+          expect{ Base.new('not a good idea') }.to raise_error
+        end
+
+      end
+
+      it "raise a descriptive message if an invalid type is passed" do
+        expect{ Signer.new([ 'not a good idea' ]) }.to raise_error
+      end
+
+    end # url parameter:
+
+  end
+end

data/spec/signer_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+module UrlSigner
+  describe Signer do
+    let(:url_string) { 'http://mysite.com/my/path?test=1&retest=2' }
+    let(:url) { URI.parse(url_string) }
+    let(:params) { CGI.parse(url.query) }
+
+    let(:signer) { Signer.new(url, key: 'testkey') }
+
+    describe "#sign:" do
+      let(:signed_url) { signer.sign }
+      let(:signed_params) { CGI.parse(signed_url.query) }
+
+      it "returns a new url" do
+        expect(signed_url).to be_a(URI)
+        expect(signed_url).not_to be(url)
+      end
+
+      it "keeps all the incoming parameters" do
+        signed_params.delete('signature')
+        expect(signed_params).to eq(params)
+      end
+
+      it "adds a signature parameter" do
+        expect(signed_params).to have_key('signature')
+      end
+
+      describe "signature param" do
+        let(:signature_param) { signed_params['signature'][0] }
+
+        it "contains the computed signature" do
+          expect(signature_param).to eq(signer.signature)
+        end
+
+      end # signature param
+
+    end # #sign
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+
+require 'uri'
+require 'cgi'
+require 'rspec'
+require 'url_signer'

data/spec/url_signer_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe UrlSigner do
+  let(:url) { 'http://google.fr' }
+  let(:fake_signer) { double(sign: true, valid?: true) }
+
+  FORWARDED_METHOD = {
+    sign: ::UrlSigner::Signer,
+    valid?: ::UrlSigner::Verifier
+  }
+  FORWARDED_METHOD.each do |method, klass|
+    describe ".#{method}:" do
+
+      it "builds a new #{klass} instance" do
+        expect(klass).to receive(:new).with(url, key: 'toto').and_return(fake_signer)
+
+        # call method by name dynamically
+        UrlSigner.send(method, url, key: 'toto')
+      end
+
+      it "calls ##{method} on the new #{klass} instance" do
+        allow(klass).to receive(:new).and_return(fake_signer)
+        expect(fake_signer).to receive(method)
+
+        # call method by name dynamically
+        UrlSigner.send(method, url, key: 'toto')
+      end
+
+    end
+  end
+
+end

data/spec/verifier_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+
+module UrlSigner
+  describe Verifier do
+    let(:url_string) { 'http://mysite.com/my/path?test=1&retest=2' }
+    let(:url) { URI.parse(url_string) }
+    let(:params) { CGI.parse(url.query) }
+
+    let(:signer) { Signer.new(url, key: 'testkey') }
+
+    describe "#valid?:" do
+      let(:signed_url) { signer.sign }
+
+      context "when an url has been signed," do
+        let(:verifier) { Verifier.new(signed_url, key: 'testkey') }
+
+        it "can verify the url" do
+          expect(verifier.valid?).to be(true)
+        end
+
+        context "when the signed url has been modified," do
+          # will overload signed_url in this context
+          let(:signed_url) {
+            vanilla_url = signer.sign
+            vanilla_url.query += '&toto=titi'
+            vanilla_url
+          }
+
+          it "does not verify the url" do
+            expect(verifier.valid?).to be(false)
+          end
+
+        end
+      end
+
+      context "when an url has not been signed," do
+        let(:verifier) { Verifier.new(url, key: 'testkey') }
+
+        it "does not verify the url" do
+          expect(verifier.valid?).to be(false)
+        end
+      end
+
+    end # #valid?
+
+  end
+end
+

data/url_signer.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'url_signer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "url_signer"
+  spec.version       = UrlSigner::VERSION
+  spec.authors       = ["Aurélien Noce"]
+  spec.email         = ["aurnoce@gmail.com"]
+  spec.summary       = %q{Sign and verify URLs}
+  spec.description   = %q{Simple solution (2 methods) to sign URLs and verify the generated URLs. Use HAMC/SHA1 for signing by default but can be configured.}
+  spec.homepage      = "https://github.com/ushu/url_signer"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.1"
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: url_signer
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Aurélien Noce
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: Simple solution (2 methods) to sign URLs and verify the generated URLs.
+  Use HAMC/SHA1 for signing by default but can be configured.
+email:
+- aurnoce@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/url_signer.rb
+- lib/url_signer/base.rb
+- lib/url_signer/signer.rb
+- lib/url_signer/verifier.rb
+- lib/url_signer/version.rb
+- spec/base_spec.rb
+- spec/signer_spec.rb
+- spec/spec_helper.rb
+- spec/url_signer_spec.rb
+- spec/verifier_spec.rb
+- url_signer.gemspec
+homepage: https://github.com/ushu/url_signer
+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.0.14
+signing_key: 
+specification_version: 4
+summary: Sign and verify URLs
+test_files:
+- spec/base_spec.rb
+- spec/signer_spec.rb
+- spec/spec_helper.rb
+- spec/url_signer_spec.rb
+- spec/verifier_spec.rb
+has_rdoc: