mortal-token 0.1.0 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6ec1263cb82fe020f0a5cb4ef18fc2b4fd29407f
+  data.tar.gz: c946ebf543665e2be2ab22f9f09d91f8147cf6d3
+SHA512:
+  metadata.gz: 40703edd2fc20d6805d7d23f8dc45d06f16ebe89519a9c9520ad8446331a77d81df307c9a3a3d347fe0e75e37b6c38916790f6fff9bb57c146129f883f912c09
+  data.tar.gz: b5bee687a5f663783b952f0d4f522f938648afda737edd672abd6a15c9c22003f7b5d7e3a40a7585af95cbb63a738ff942fa478cc8d280d9fcf4c075a07f80b7

data/README.rdoc

@@ -1,11 +1,10 @@
 == MortalToken, because some tokens shouldn't live forever
 
-MortalToken is a library for creating tokens that self-destruct after a specified time. No need to store and look up the 
-token; it is self-verifying and self-expiring.
+MortalToken is a convenience wrapper for HMAC-based authentication. The tokens self-destruct after a specified time
+period; no need to store and look them up for verification.
 
-The default lifespan is two of your Earth days. This does *not* mean "48 hours from when it was created". It means that 
-the key will be valid throughout "today" and "tomorrow". If the lifespan were one day, a key created at 23:59 would expire 
-in one minute at 00:00.
+The default lifespan is one hour. For a Web-based application, you might extend this to many hours, or you
+might cut it back to only a few minutes, issuing a new token for each request/response cycle.
 
 My original use case was login auth tokens for some simple Sinatra apps. I can also see it being useful for API auth.
 Of course there are potential uses outside of HTTP, too.
@@ -13,17 +12,16 @@ Of course there are potential uses outside of HTTP, too.
 Steps:
 
 1. Generate a new token
-2. Give the client the resulting hash and salt
+2. Give the client the resulting digest, salt, and expiry timestamp
 3. Time passes
-4. Receive a hash and salt from client
-5. Reconstitute the token from the salt, and test if the hashes match. If not, the token has expired (or was forged).
-
-Read the full documentation at {jordanhollinger.com/docs/mortal-token/}[http://jordanhollinger.com/docs/mortal-token/].
+4. Receive a digest, salt, and expiry timestamp from client
+5. Reconstitute the token from salt and timestamp, then see if the digests match. If not, the token has expired (or was forged).
 
 == Warning
 
-This is, at best, alpha-quality software. It "works" in that it doesn't usually blow up, but it is not guaranteed to be "right".
-Don't use it in production, or at least not in any important production. May contain traces of peanut oil.
+It is up to *you* to transmit the digest, salt, and expiry timestamp securely. If it's intercepted, someone could impersonate 
+your client until the token expires. In other words, this is only *part* of an authentication solution. Use with caution. May
+contain traces of peanut.
 
 == Install
 
@@ -32,58 +30,72 @@ Don't use it in production, or at least not in any important production. May con
 Or add it to your Gemfile
   gem "mortal-token"
 
-== Example with Sinatra
+== Example use with Sinatra
 
   require 'sinatra'
   require 'mortal-token'
 
-  # You MUST set a secret key! Otherwise, anyone who looks at the source code will be able to forge tokens.
   MortalToken.secret = 'asdf092$78roasdjfjfaklmsdadASDFopijf98%2ejA#Df@sdf'
 
   post '/login' do
     if login_ok?
       token = MortalToken.new
-      session[:token] = token.hash
+      # Or "token = MortalToken.new(current_user.id)" to set your own salt and verify who owns the session.
       session[:salt] = token.salt
+      session[:expires] = token.expires
+      session[:digest] = token.digest
       redirect '/secret'
     end
   end
 
   get '/secret' do
-    token = MortalToken.new(session[:salt])
-    if token == session[:token]
+    if MortalToken.check(session[:salt], session[:expires]).against(session[:digest])
       'Nice token!'
     else
       'Your token is expired or forged!'
     end
   end
 
-== Checking token validity
+== Automatically re-issue nearly expired tokens
+
+  MortalToken.check(session[:salt], session[:expires]).against(session[:digest]) do |token|
+    session[:salt], session[:expires], session[:digest] = MortalToken.new.get if token.expires_soon?
+  end
+
+== Checking token validity explained
+
+    MortalToken.check(salt, expires).against(digest)
+
+is syntactic sugar for
+
+    reconstituted_token = MortalToken.new(salt, expires)
+    reconstituted_token == digest
 
-A token's == and === methods accept another token or a hash. In the example above, an attempt has been made to reconstitute
-the original token (using it's salt) on the left. If successful, it will be able to regenerate the hash on the right. But if
-too much time has passed, the hashes will differ and we can conclude that the token has expired.
+A token's == and === methods accept another token or a digest. In the example above, an attempt has been made to reconstitute
+the original token using it's salt and expiry timestamp. To be considered "equal", the reconstituted token's digest must
+match the original digest AND the timestamp must be in the future. Unless both of those conditions are met, then token is
+considered invalid or expired.
 
 == Tweak token parameters
 
 You may tweak certain parameters of the library in order to make it more secure, less, faster, etc.
 These are the defaults (see the MortalToken class for documentation about each parameter):
 
-  MortalToken.rounds = 5            # rounds of hashing
-  MortalToken.units = :days         # or :hours, :minutes
-  MortalToken.valid_across = 2      # tokens are valid across N units
-  MortalToken.max_salt_length = 50
-  MortalToken.min_salt_length = 10
+  MortalToken.valid_for = 1         # tokens are valid for N units
+  MortalToken.units = :hours        # or :days, :minutes
+  MortalToken.digest = 'sha256'     # The digest algorithm used by HMAC
+  MortalToken.max_salt_length = 50  # Maximum token salt length
+  MortalToken.min_salt_length = 10  # Minimum token salt length
 
 == Multiple configurations
 
-Your application may want to use MortalTokens in various contexts, where the same parameters may not make sense (probably units and valid_across).
-You may define different scopes and give them each their own config. Always define the default scope first (as above). Other scopes will inherit
-its secret.
+Your application may want to use MortalTokens in various contexts, where the same parameters may not make sense (probably units and valid_for).
+You may define different scopes and give them each their own config. Always define the default scope first (above). Other scopes will inherit
+its secret unless you specify another.
 
   MortalToken.config(:foo) do |config|
     config.units = :minutes
-    config.valid_across = 10
+    config.valid_for = 10
   end
 
   token = MortalToken.use(:foo).token

data/lib/mortal-token/configuration.rb

@@ -7,13 +7,12 @@ class MortalToken
     attr_reader :name
     # The master secret token (Keep it secret! Keep it safe!). Changing this will invalidate all existing tokens.
     attr_accessor :secret
-    # The number of encryption rounds. Defaults to 5. Changing this will invalidate existing tokens.
-    attr_accessor :rounds
-    # The units that life is measured in - :days, :hours or :minutes
+    # The digest to use (passed to OpenSSL::Digest.new). Defaults to 'sha256'.
+    attr_accessor :digest
+    # The units that life is measured in - :days, :hours or :minutes (defaults to :hours)
     attr_reader :units
-    # The number of units tokens will be valid across. Defaults to 2, which (for :days) prevents a
-    # token generated at 23:59 from expiring at 00:00. Changing this will invalidate existing tokens.
-    attr_accessor :valid_across
+    # The number of units tokens will be valid across. Defaults to 1. Changing this will invalidate existing tokens.
+    attr_accessor :valid_for
     # The maximum salt length, defaults to 50
     attr_accessor :max_salt_length
     # The minimum salt length, defaults to 10
@@ -22,23 +21,27 @@ class MortalToken
     # Instantiates a new Configuration object default values
     def initialize(name)
       @name = name
-      @rounds = 5
-      @units = :days
-      @valid_across = 2
+      @digest = 'sha256'
+      @units = :hours
+      @valid_for = 1
       @max_salt_length = 50
       @min_salt_length = 10
-      # A temporary secret key. Use your own!!
-      @secret = CONFIGS[:default] ? CONFIGS[:default].salt : self.salt
+      @secret = CONFIGS[:default].secret if CONFIGS[:default]
     end
 
     # Return a new token using this configuration
-    def token(salt=nil, time=nil)
-      Token.new(salt, time, self)
+    def token(salt=nil, expires=nil)
+      Token.new(salt, expires, self)
+    end
+
+    # Returns a token reconstitued from the timestamp and salt
+    def check(salt, expires)
+      Token.new(salt, expires, self)
     end
 
     # Set the units that life is measured in - :days, :hours or :minutes
     def units=(unit)
-      raise ArgumentError, "MortalToken.units must be one of #{UNITS.keys.join(', ')}" unless UNITS.keys.include? unit
+      raise ArgumentError, "MortalToken.units must be one of #{Token::UNITS.keys.join(', ')}" unless Token::UNITS.keys.include? unit
       @units = unit
     end
 
@@ -48,5 +51,9 @@ class MortalToken
       pool_size = RAND_SEEDS.size
       (0..max_length).map { RAND_SEEDS[rand(pool_size)] }.join('')
     end
+
+    def _digest # :nodoc:
+      @_digest ||= OpenSSL::Digest.new(self.digest)
+    end
   end
 end

data/lib/mortal-token/mortal-token.rb

@@ -1,12 +1,11 @@
 # A token hash that "self-destructs" after a certain time.
 class MortalToken
   CONFIGS = {} # :nodoc:
-  UNITS = {days: {increment: 1, format: '%Y-%m-%d'}, hours: {increment: 3600, format: '%Y-%m-%d_%H'}, minutes: {increment: 60, format: '%Y-%m-%d_%H:%M'}} # :nodoc:
 
   class << self
     # Returns a new Token. Also alised to #token.
-    def new(salt=nil, time=nil)
-      config.token(salt, time)
+    def new(salt=nil, expires=nil)
+      config.token(salt, expires)
     end
 
     # Returns a new or existing MortalToken::Configuration. If you pass a block, it will pass it the config object.

data/lib/mortal-token/token.rb

@@ -1,66 +1,70 @@
 class MortalToken
   class Token
-    # The token's salt
+    UNITS = {days: {increment: 86400}, hours: {increment: 3600}, minutes: {increment: 60}} # :nodoc:
+
+    # The salt value
     attr_reader :salt
-    attr_accessor :config
+    # The expiry time as a Unix timestamp
+    attr_reader :expires
+    attr_reader :config # :nodoc:
 
-    # To create a brand new token, do *not* pass any arguments. To validate a hash from
-    # an existing token, pass the existing token's salt.
-    def initialize(salt=nil, start_time=nil, config=nil)
+    # To create a brand new token, do *not* pass any arguments. To validate a digest from
+    # an existing token, pass the existing token's exiry timestamp.
+    def initialize(salt=nil, expires=nil, config=nil)
       @config = config || MortalToken.config
-      @salt = salt || config.salt
-      @start_time = start_time || (config.units == :days ? Date.today : Time.now.utc)
+      @salt = salt || self.config.salt
+      @expires = expires ? expires.to_i : calculate_expiry
     end
 
-    # Returns the hash value of the token
-    def hash
-      @hash ||= (0..config.rounds-1).inject("#{config.secret}_#{salt}_#{end_time.strftime(strfmt)}") do |val, i|
-        Digest::SHA512.hexdigest(val)
-      end
+    # Returns the hash digest of the token
+    def digest
+      raise "MortalToken: you must set a secret!" if config.secret.nil?
+      @digest ||= OpenSSL::HMAC.digest(config._digest, config.secret, "#{expires.to_s}:#{salt}")
     end
 
-    alias_method :to_s, :hash
+    # A URL-safe Base64-encoded digest
+    def urlsafe_digest
+      Base64.urlsafe_encode64(self.digest)
+    end
 
-    # Tests this token against another token or token hash
-    def ==(other_token_or_hash)
-      each_time do |time|
-        guess = config.token(salt, time)
-        return true if guess.to_s == other_token_or_hash.to_s
-      end
-      return false
+    # Returns true if the token expires soon. Default check: within 5 min.
+    def expires_soon?(min=5)
+      Time.now.utc.to_i + (min * 60) >= expires
     end
 
-    alias_method :===, :==
+    # Returns salt, expires, digest. Convenient for one-line assignment of all three.
+    def get
+      return salt, expires, digest
+    end
 
-    private
+    alias_method :to_s, :digest
 
-    # Iterates over each possible time unit and passes it to the block
-    def each_time(&block)
-      time = earliest_time
-      while time <= end_time
-        block.call(time)
-        time += increment
+    # Tests this token against another token or token hash. Accepts a block. If the check passes,
+    # this token will be passed to the block.
+    def against(other_token_or_digest)
+      if self == other_token_or_digest
+        yield self if block_given?
+        true
+      else
+        false
       end
     end
 
-    # Returns the end date/time of this token
-    def end_time
-      @start_time + (config.valid_across - 1) * increment
+    # Tests this token against another token or token hash. Even if it matches, returns false if
+    # the expire time is past.
+    def ==(other_token_or_digest)
+      other = other_token_or_digest.to_s
+      (self.digest == other || self.urlsafe_digest == other) && self.expires > Time.now.utc.to_i
     end
 
-    # Returns the earliest possible date/time this token could have been valid.
-    def earliest_time
-      @start_time - (config.valid_across - 1) * increment
-    end
+    alias_method :===, :==
 
-    # Returns the incrementor for the configured unit
-    def increment
-      UNITS[config.units][:increment]
-    end
+    private
 
-    # Returns the string formater for the configured unit
-    def strfmt
-      UNITS[config.units][:format]
+    # Returns the end date/time of this token
+    def calculate_expiry
+      expire_time = Time.now.utc.to_i + ((config.valid_for) * UNITS[config.units][:increment])
+      expire_time.to_i
     end
   end
 end

data/lib/mortal-token/version.rb

@@ -1,4 +1,4 @@
 class MortalToken
   # Library version
-  VERSION = '0.1.0'
+  VERSION = '1.0.0'
 end

data/lib/mortal-token.rb

@@ -1,6 +1,7 @@
-require 'date'
 require 'time'
-require 'digest/sha2'
+require 'base64'
+require 'openssl'
+
 require 'mortal-token/version'
 require 'mortal-token/token'
 require 'mortal-token/configuration'

metadata

@@ -1,70 +1,50 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: mortal-token
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 0
-  version: 0.1.0
+version: !ruby/object:Gem::Version
+  version: 1.0.0
 platform: ruby
-authors: 
+authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-08-03 00:00:00 -04:00
-default_executable: 
+date: 2014-06-03 00:00:00.000000000 Z
 dependencies: []
-
-description: An EXPERIMENTAL library for generating self-contained, self-destructing tokens
+description: An wrapper library for generating self-contained, self-destructing tokens
+  with HMAC
 email: jordan@jordanhollinger.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/mortal-token.rb
 - lib/mortal-token/mortal-token.rb
 - lib/mortal-token/token.rb
-- lib/mortal-token/version.rb
 - lib/mortal-token/configuration.rb
+- lib/mortal-token/version.rb
 - README.rdoc
 - LICENSE
-has_rdoc: true
 homepage: http://github.com/jhollinger/mortal-token
 licenses: []
-
+metadata: {}
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+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: 1.3.7
+rubygems_version: 2.0.14
 signing_key: 
-specification_version: 3
-summary: Generate self-destructing tokens (experimental)
+specification_version: 4
+summary: Generate self-destructing tokens
 test_files: []
-