authmac 1.0.4 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90105d4d9efdd25c6c15260a90dce6a807b82413
-  data.tar.gz: 713c8d6560a0f879af99e5ed4d3ba1152fe2dcba
+  metadata.gz: 829ec585cf6a375f48ac8173e6d0ac78b74cbc80
+  data.tar.gz: 1dac8a149c91af398587addbf5b1438d48ca13db
 SHA512:
-  metadata.gz: bac599e7b2238e0b346b8bb3b5dbc4bf2e7243c464a0b4fab90325264f10a4edf4e49ff39162d1c5b28bebafd9b475293936d79cebe5cbda02d22a58dfa2ac12
-  data.tar.gz: 86f1fa8713e62e8d5ac15cb395bde67d750daddbd339c1b544e5527ce259799ba0d2a53e1b36f618bfbdb4a60d56891113fab3201f34a4334e44395453f856ff
+  metadata.gz: dfd1e0b844b368b2c943861f6c1e7c89c11a96149083477ee48dd735cd54a4da6406d414b2dcb801da6519e75d7edb3df567dfca183af97ddaaf5c1ddebc2f11
+  data.tar.gz: 6e2d287aa49a7aad085e83fa85b0d206f877568148c0216f0b66b1b0b6fc6a7875471e249106eac47aee74aee3248a90c18c7da7b173de7ec4b4b40f850d2ead

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## Version 2.0.0 / 2016-11-08
+
+* BREAKING: keyword arguments for HmacChecker.new
+* Allow nested hashes/arrays to be signed.
+* Add :json message_format to sign a sorted json string, instead of just values.
+
 ## Version 1.0.4 / 2014-06-20
 
 * Added HmacChecker#with_signature which returns the given hash with the HMAC merged in.

data/README.md

@@ -21,7 +21,57 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+```
+checker = Authmac::HmacChecker.new(secret, parameter_separator: '|', digest_function: 'sha1', message_format: :json)
+checker.with_signature(params_to_send)
+```
+
+* message_format: :values or :json. Format of message-string to sign. default :values.
+* digest_function: string to give `OpenSSL::Digest.new(digest_function)`
+* parameter_separator: Used for :values format to separate values.
+
+## Examples
+
+
+```
+params_to_sign = {
+  'some_param' => 'foo',
+  'other_param' => 'bar',
+  'timestamp'    => timestamp.to_s, # 12345678
+  'nonce'        => SecureRandom.urlsafe_base64(4), # ILFtHg
+  'consumer_key' => 'my_key'
+}
+```
+
+Classic syntax: signs values, sorted by key, joined by '|'
+
+```
+checker = Authmac::HmacChecker.new(ENV['consumer_secret'],
+							       parameter_separator: '|',
+							       digest_function: 'sha256')
+params_to_send = checker.with_signature(params_to_sign)
+
+checker.send(:message_string, params_to_sign) # "my_key|ILFtHg|bar|foo|123456789"
+```
+
+Syntax for more complex parameters, signs json, sorted by key (subhashes as well).
+
+```
+params_to_sign['some_param'] = {foo: [1, {bar: 2}]}
+```
+
+```
+checker = Authmac::HmacChecker.new(ENV['consumer_secret'],
+								   digest_function: 'sha256',
+								   message_format: :json)
+params_to_send = checker.with_signature(params_to_sign)
+
+checker.send(:message_string, params_to_sign)
+# '{"consumer_key":"my_key","nonce":"ILFtHg","other_params":"bar",' \
+# '"some_param":{"foo":["1",{"bar":"2"}]},"timestamp":"12345678"}'
+
+```
+
 
 ## Contributing
 

data/example/app.rb

@@ -1,25 +1,35 @@
 require 'sinatra'
 require 'cgi'
 require 'authmac'
+require 'json'
 
 set :app_file, __FILE__
+def hmac_secret
+  "very_secret_string_of_at_least_the_length_of_the_hash_so_64_for_sha256"
+end
 
 get '/' do
   erb :form
 end
 
 post '/sign' do
-  @checker = Authmac::HmacChecker.new("very_secret", '|', 'sha256')
-  @params_with_timestamp = params.merge('timestamp' => Time.now.to_i)
-  @hmac    = @checker.sign(@params_with_timestamp)
-  @params_with_hmac      = @params_with_timestamp.merge('hmac' => @hmac)
+  @params = params.select { |_k, v| v != '' }
+  @secret = hmac_secret
+  @checker = Authmac::HmacChecker.new(hmac_secret, '|', 'sha256')
+  @params_to_sign = @params.merge \
+    'timestamp'    => Time.now.to_i.to_s,
+    'version'      => '3',
+    'nonce'        => 'implementing_apps_should_store_this_to_prevent_replays',
+    'consumer_key' => 'key_to_find_secret'
+  @hmac    = @checker.sign(@params_to_sign)
+  @params_with_hmac      = @params_to_sign.merge('hmac' => @hmac)
   @link                  = @params_with_hmac.map{|k,v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
 
   erb :sign
 end
 
 get '/auth' do
-  hmac_checker      = Authmac::HmacChecker.new("very_secret", '|', 'sha256')
+  hmac_checker      = Authmac::HmacChecker.new(hmac_secret, '|', 'sha256')
   timestamp_checker = Authmac::TimestampChecker.new(30, 10)
   authenticator     = Authmac::Authenticator.new(hmac_checker, timestamp_checker)
   @validation       = authenticator.validate(params)
@@ -31,4 +41,4 @@ get '/auth' do
   elsif @validation.timestamp_failure?
     erb :auth_timestamp_failure
   end
-end
+end

data/example/public/app.css

@@ -0,0 +1,13 @@
+code {
+  white-space: pre;
+  display: block;
+  background: #eee;
+  margin-left: 2em;
+  padding: 1em;
+  overflow: auto;
+}
+
+.info {
+  margin-left: 2em;
+  font-size: .9em;
+}

data/example/views/form.erb

@@ -4,6 +4,7 @@
 <form method="post" action="/sign">
   Professional ID: <input type="text" name="userid" />   <br/>
   Patient ID:      <input type="text" name="clientid" /> <br/>
-
+  Professional First Name: <input type="text" name="user_firstname" /> <br />
+  Professional Last Name: <input type="text" name="user_lastname" /> <br />
   <input type="submit" value="Generate URL" />
 </form>

data/example/views/sign.erb

@@ -1,22 +1,29 @@
 <!DOCTYPE html>
+<link rel="stylesheet" type="text/css" href="/app.css">
+
 <title>HMAC Generator</title>
 <h1>Okay, here's what I've got</h1>
 
-<p>These are the values we used to generate the hash:
-<code><%= @params.inspect %></code></p>
+<p>These are the values we used to generate the hash:</p>
+<code><%= JSON.pretty_generate @params %></code>
+<p class="info">Removed blank params here, we won't send them to the provider, if we had, they should have been in the string_to_sign e.g. "1|2||4".</p>
 
-<p>Then we add the timestamp parameter:
-<code><%= @params_with_timestamp.inspect %></code></p>
+<p>Then we add the timestamp and other parameter we want:</p>
+<code>params = <%= JSON.pretty_generate @params_to_sign %></code>
+<p class="info">timestamp is the only key that is required. <br />
+  version, nonce and consumer_key are app-specific and can be anything you want, just make sure you calculate the hmac over all the params you send.
+ </p>
 
-<p>To calculate the HMAC, we generate the following string based on this:
-<code><%= @checker.send(:message_string, @params_with_timestamp) %></code></p>
+<p>To calculate the HMAC, we sort the params by key alfabetically and join the values with a '|' in between:</p>
+<code>string_to_sign = <%= @checker.send(:message_string, @params_to_sign) %></code>
 
-<p>And use this secret for the HMAC generation:
-<code>very_secret</code></p>
+<p>And use the configured secret for the HMAC generation:</p>
+<code>hmac_secret = '<%= @secret %>'</code>
 
-<p>Then we add the HMAC:
-<code><%= @params_with_hmac.inspect %></code></p>
+<p>Then we add the HMAC to the params:</p>
+<code># Authmac::HmacChecker.new(hmac_secret, '|', 'sha256').sign(params)
+<%= JSON.pretty_generate @params_with_hmac %></code>
 
-<p>Then, this is a nice URL to use. We URL-escape each value, and keep in mind that the order of HTTP-parameters does not matter:</p>
+<p>Then, this is a nice URL to use. We URL-escape each value, and keep in mind that the order of HTTP-methods does not matter:</p>
 
 <a href="/auth?<%= @link %>">Link</a>

data/lib/authmac/hmac_checker.rb

@@ -2,10 +2,16 @@ require 'openssl'
 
 module Authmac
   class HmacChecker
-    def initialize(secret, parameter_separator = '|', digest_function = 'sha1')
+    # @param message_format [symbol] `:values` or `:json`.
+    #   `:json` will use a sorted json string to sign.
+    #   `:values` will use the sorted values separated by `parameter_separator` to sign.
+    def initialize(secret, message_format: :values,
+                           parameter_separator: '|',
+                           digest_function: 'sha1')
       @secret = secret
       @digest = digest_function
       @separator = parameter_separator
+      @message_format = message_format
       fail Authmac::SecretError, 'secret too short, see rfc2104' unless @secret.bytes.size >= digester.digest_length * 2
     end
 
@@ -28,12 +34,35 @@ module Authmac
     end
 
     def message_string(hash)
-      hash_values_sorted_by_key(hash).join(@separator)
+      fail ArgumentError, 'hash arg not a hash' unless hash.is_a? Hash
+
+      case @message_format
+      when :values
+        hash_values_sorted_by_key(hash).flatten.join(@separator)
+      when :json
+        require 'json'
+        JSON.generate(params_sorted_by_key(hash))
+      else
+        fail ArgumentError, 'unknown message_format'
+      end
     end
 
     def hash_values_sorted_by_key(hash)
       hash.sort_by {|key, value| key }.map(&:last)
     end
+
+    # stringifies and sorts hashes by key at all levels.
+    def params_sorted_by_key(params)
+      case params
+      when Hash
+        params.map     { |k, v| [k.to_s, params_sorted_by_key(v)] }
+              .sort_by { |k, v| k }
+              .to_h
+      when Array
+        params.map { |val| params_sorted_by_key(val) }
+      else
+        params
+      end
+    end
   end
 end
-

data/lib/authmac/version.rb

@@ -1,3 +1,3 @@
 module Authmac
-  VERSION = '1.0.4'
+  VERSION = '2.0.0'
 end

data/spec/authmac/hmac_checker_spec.rb

@@ -2,11 +2,11 @@ require 'authmac/hmac_checker'
 
 module Authmac
   describe HmacChecker do
-    let(:checker) { HmacChecker.new('very secret random key of sufficient size', '|', 'sha1') }
+    let(:checker) { HmacChecker.new('very secret random key of sufficient size') }
 
     it 'raises an error for a secret shorter than the hmac output' do
       expect {
-        HmacChecker.new('way too short key', '|', 'sha1')
+        HmacChecker.new('way too short key')
       }.to raise_error SecretError, 'secret too short, see rfc2104'
     end
 
@@ -45,6 +45,42 @@ module Authmac
                                   hmacify('parameter|another'))).to be_truthy
         end
       end
+
+      context 'with json message_string' do
+        let(:checker) { HmacChecker.new('very secret random key of sufficient size', message_format: :json) }
+
+        it 'creates a sorted json string' do
+          hash = {first: '1', third: '6', second: {b: ['3', {c: '4', d: '5'}], a: '2'}}
+          expect(checker.send :message_string, hash)
+            .to eq '{"first":"1","second":{"a":"2","b":["3",{"c":"4","d":"5"}]},"third":"6"}'
+        end
+
+        context 'for a hash with nested hashes' do
+          it 'succeeds with correct hmac' do
+            expect(checker.validate({first: '1', second: {a: '2', b: '3'}, third: '4'},
+                                    hmacify('{"first":"1","second":{"a":"2","b":"3"},"third":"4"}'))).to be_truthy
+          end
+
+          it 'sorts hash values based on their keys' do
+            expect(checker.validate({first: '1', third: '4', second: {b: '3', a: '2'}},
+                                    hmacify('{"first":"1","second":{"a":"2","b":"3"},"third":"4"}'))).to be_truthy
+          end
+        end
+
+        context 'for a hash with nested hashes and arrays' do
+          it 'succeeds with correct hmac' do
+            expect(checker.validate({first: '1', second: {a: '2', b: ['3', '4']}, third: '5'},
+                                    hmacify('{"first":"1","second":{"a":"2","b":["3","4"]},"third":"5"}')))
+                          .to be_truthy
+          end
+
+          it 'sorts hash values based on their keys' do
+            expect(checker.validate({first: '1', third: '6', second: {b: ['3', {c: '4', d: '5'}], a: '2'}},
+                                    hmacify( '{"first":"1","second":{"a":"2","b":["3",{"c":"4","d":"5"}]},"third":"6"}')))
+                          .to be_truthy
+          end
+        end
+      end
     end
 
     describe '#with_signature' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authmac
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 2.0.0
 platform: ruby
 authors:
 - Marten Veldthuis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-20 00:00:00.000000000 Z
+date: 2016-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -56,6 +56,7 @@ files:
 - authmac.gemspec
 - circle.yml
 - example/app.rb
+- example/public/app.css
 - example/views/auth_hmac_failure.erb
 - example/views/auth_success.erb
 - example/views/auth_timestamp_failure.erb
@@ -87,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Single Sign-On implementation based on HMAC.
@@ -95,4 +96,3 @@ test_files:
 - spec/authmac/hmac_checker_spec.rb
 - spec/authmac/timestamp_checker_spec.rb
 - spec/authmac_spec.rb
-has_rdoc: