mortal-token 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ec1263cb82fe020f0a5cb4ef18fc2b4fd29407f
-  data.tar.gz: c946ebf543665e2be2ab22f9f09d91f8147cf6d3
+  metadata.gz: 6b8a22fd9bc7c9038590081f95128581bdab8d28
+  data.tar.gz: 6d0812debf82f95e6211377aa06467209480ded2
 SHA512:
-  metadata.gz: 40703edd2fc20d6805d7d23f8dc45d06f16ebe89519a9c9520ad8446331a77d81df307c9a3a3d347fe0e75e37b6c38916790f6fff9bb57c146129f883f912c09
-  data.tar.gz: b5bee687a5f663783b952f0d4f522f938648afda737edd672abd6a15c9c22003f7b5d7e3a40a7585af95cbb63a738ff942fa478cc8d280d9fcf4c075a07f80b7
+  metadata.gz: c7522365167e5e715a19a87c996e088c7cbcbee5f585a37a5a638167cb3f7a5fb263b97bc137d3f37f86dd73d5ebb9e26912644d357f6b3eb00fe158fb7572f0
+  data.tar.gz: 5e600b54b463f25eff00709b92b18652ecda7192bdb581ddb51c20a83d3c8e7a091f7f5bf36bb921bae91b8c10c2028d0686623da3140c3ac988a546ce090ea6

data/LICENSE

@@ -1,13 +1,19 @@
-   Copyright 2012 Jordan Hollinger
+Copyright (c) 2015 Jordan Hollinger
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+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:
 
-       http://www.apache.org/licenses/LICENSE-2.0
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+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,44 @@
+# MortalToken, because some tokens shouldn't live forever
+
+MortalToken is a convenience wrapper for HMAC-based authentication. Tokens self-destruct after a specified time period; no need to store and look them up for verification. They may optionally contain a message, which is visible but tamper-proof.
+
+## Simple token with validity check
+
+    require 'mortal-token'
+    MortalToken.secret = 'asdf092$78roasdjfjfaklmsdadASDFopijf98%2ejA#Df@sdf'
+
+    token = MortalToken.create(60 * 60) # 1 hr
+    give_to_client token.to_s
+    token_str = get_from_client
+    if MortalToken.valid? token_str
+      # it's valid
+    else
+      # it's invalid or expired
+    end
+
+## Token with tamper-proof message
+
+    require 'mortal-token'
+    MortalToken.secret = 'asdf092$78roasdjfjfaklmsdadASDFopijf98%2ejA#Df@sdf'
+
+    token = MortalToken.create(60 * 60, 'some message')
+    give_to_client token.to_s
+    token_str = get_from_client
+    token, digest = MortalToken.recover(token_str)
+    if token == digest
+      # It's valid. But remember - the message could have been read by anyone with access to the token.
+      do_stuff_with token.message
+    else
+      # it's invalid or expired
+    end
+
+## 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:
+
+    MortalToken.digest = 'sha512'  # The digest algorithm used by HMAC
+    MortalToken.salt_length = 8    # Number of bits in tokens' salts
+
+## Testing
+
+    rake test

data/lib/mortal-token/config.rb

@@ -0,0 +1,18 @@
+module MortalToken
+  class << self
+    # The master secret token (Keep it secret! Keep it safe!). Changing this will invalidate all existing tokens.
+    attr_accessor :secret
+    # The digest to use. Defaults to 'sha512'.
+    attr_reader :digest
+    # Salt length in bytes. Defaults to 8.
+    attr_accessor :salt_length
+  end
+
+  # Set a new digest type
+  def self.digest=(name)
+    @digest = OpenSSL::Digest.new name
+  end
+
+  self.digest = 'sha512'
+  self.salt_length = 8
+end

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

@@ -1,26 +1,24 @@
-# A token hash that "self-destructs" after a certain time.
-class MortalToken
-  CONFIGS = {} # :nodoc:
-
-  class << self
-    # Returns a new Token. Also alised to #token.
-    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.
-    # If it's a new config, it will inherit the default settings.
-    def config(name=:default)
-      config = (CONFIGS[name] ||= Configuration.new(name))
-      yield config if block_given?
-      config
-    end
+module MortalToken
+  # Create a new token that lasts for N seconds. Message is optional, but must be a string when present.
+  def self.create(seconds, message = nil)
+    expires = Time.now.utc.to_i + seconds
+    salt = SecureRandom.hex MortalToken.salt_length
+    Token.new expires, salt, message
+  end
 
-    alias_method :use, :config
+  # Recover a token and digest created with MortalToken#to_s. Returns [token, digest].
+  # You must then check their validity with "token == digest"
+  def self.recover(token_str)
+    h = JSON.parse Base64.urlsafe_decode64 token_str.to_s
+    token = Token.new h['expires'], h['salt'], h['message']
+    return token, h['digest']
+  rescue ArgumentError, JSON::ParserError
+    nil
+  end
 
-    # Alias all other methods to the default Configuration
-    def method_missing(method, *args, &block)
-      config.send(method, *args, &block)
-    end
+  # Check if a token created with MoralToken#to_s is valid.
+  def self.valid?(token_str)
+    token, digest = recover token_str
+    token == digest
   end
 end

data/lib/mortal-token/token.rb

@@ -1,70 +1,70 @@
-class MortalToken
+module MortalToken
+  # Create a token and check if it's still valid:
+  #
+  #   token = MortalToken.create(300) # 5 min
+  #   give_to_client token.to_s
+  #   token_str = get_from_client
+  #   MoralToken.valid? token_str
+  #
+  # Create a message token. The client *will* be able to read the message, but they *won't* be able to tamper with it.
+  # If your message must aslo be read-proof, you'll have to encrypt it and decrypt it yourself.
+  #
+  #   token = MortalToken.create(300, "message")
+  #   give_to_client token.to_s
+  #   token_str = get_from_client
+  #   token, digest = MortalToken.recover token_str
+  #   if token == digest
+  #     # It's valid
+  #     do_stuff_with token.message
+  #   else
+  #     # The token was invalid or expired
+  #   end
+  #
   class Token
-    UNITS = {days: {increment: 86400}, hours: {increment: 3600}, minutes: {increment: 60}} # :nodoc:
-
-    # The salt value
-    attr_reader :salt
     # 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 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 || self.config.salt
-      @expires = expires ? expires.to_i : calculate_expiry
-    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
+    # String content of token (optional)
+    attr_reader :message
+    # The salt value
+    attr_reader :salt
 
-    # A URL-safe Base64-encoded digest
-    def urlsafe_digest
-      Base64.urlsafe_encode64(self.digest)
+    # Initialize an existing token 
+    def initialize(expires, salt, message = nil)
+      @expires = expires.to_i
+      @salt = salt
+      @message = message ? message.to_s : nil
     end
 
-    # 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
+    # Returns a URL-safe encoding of the token and its digest. Hand it out to users and check it with MoralToken.valid?
+    def to_s
+      h = to_h
+      h[:digest] = digest
+      Base64.urlsafe_encode64 h.to_json
     end
 
-    # Returns salt, expires, digest. Convenient for one-line assignment of all three.
-    def get
-      return salt, expires, digest
+    # Returns HMAC hexdigest of the token
+    def digest
+      raise "MortalToken: you must set a secret!" if MortalToken.secret.nil?
+      @digest ||= OpenSSL::HMAC.hexdigest(MortalToken.digest, MortalToken.secret, to_h.to_json)
     end
 
-    alias_method :to_s, :digest
-
-    # 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
+    # Number of seconds remaining
+    def ttl
+      expires - Time.now.utc.to_i
     end
 
-    # Tests this token against another token or token hash. Even if it matches, returns false if
-    # the expire time is past.
+    # 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
+      other = other_token_or_digest.respond_to?(:digest) ? other_token_or_digest.digest : other_token_or_digest
+      self.digest == other && self.ttl > 0
     end
 
     alias_method :===, :==
 
     private
 
-    # 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
+    def to_h
+      {salt: salt, expires: expires, message: message}
     end
   end
 end

data/lib/mortal-token/version.rb

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

data/lib/mortal-token.rb

@@ -1,8 +1,10 @@
 require 'time'
+require 'json'
 require 'base64'
 require 'openssl'
+require 'securerandom'
 
+require 'mortal-token/mortal-token'
 require 'mortal-token/version'
+require 'mortal-token/config'
 require 'mortal-token/token'
-require 'mortal-token/configuration'
-require 'mortal-token/mortal-token'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mortal-token
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-03 00:00:00.000000000 Z
+date: 2015-12-09 00:00:00.000000000 Z
 dependencies: []
 description: An wrapper library for generating self-contained, self-destructing tokens
   with HMAC
@@ -17,15 +17,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - lib/mortal-token.rb
+- lib/mortal-token/config.rb
 - lib/mortal-token/mortal-token.rb
 - lib/mortal-token/token.rb
-- lib/mortal-token/configuration.rb
 - lib/mortal-token/version.rb
-- README.rdoc
-- LICENSE
 homepage: http://github.com/jhollinger/mortal-token
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -33,17 +34,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Generate self-destructing tokens

data/README.rdoc

@@ -1,106 +0,0 @@
-== MortalToken, because some tokens shouldn't live forever
-
-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 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.
-
-Steps:
-
-1. Generate a new token
-2. Give the client the resulting digest, salt, and expiry timestamp
-3. Time passes
-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
-
-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
-
-  [sudo] gem install mortal-token
-
-Or add it to your Gemfile
-  gem "mortal-token"
-
-== Example use with Sinatra
-
-  require 'sinatra'
-  require 'mortal-token'
-
-  MortalToken.secret = 'asdf092$78roasdjfjfaklmsdadASDFopijf98%2ejA#Df@sdf'
-
-  post '/login' do
-    if login_ok?
-      token = MortalToken.new
-      # 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
-    if MortalToken.check(session[:salt], session[:expires]).against(session[:digest])
-      'Nice token!'
-    else
-      'Your token is expired or forged!'
-    end
-  end
-
-== 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 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.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_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_for = 10
-  end
-
-  token = MortalToken.use(:foo).token
-
-== License
-Copyright 2012 Jordan Hollinger
-
-Licensed under the Apache License

data/lib/mortal-token/configuration.rb

@@ -1,59 +0,0 @@
-class MortalToken
-  # Holds a specific a configuration of parameters
-  class Configuration
-    RAND_SEEDS = [(0..9), ('a'..'z'), ('A'..'Z')].map(&:to_a).flatten # :nodoc;
-
-    # The configuration's name
-    attr_reader :name
-    # The master secret token (Keep it secret! Keep it safe!). Changing this will invalidate all existing tokens.
-    attr_accessor :secret
-    # 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 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
-    attr_accessor :min_salt_length
-
-    # Instantiates a new Configuration object default values
-    def initialize(name)
-      @name = name
-      @digest = 'sha256'
-      @units = :hours
-      @valid_for = 1
-      @max_salt_length = 50
-      @min_salt_length = 10
-      @secret = CONFIGS[:default].secret if CONFIGS[:default]
-    end
-
-    # Return a new token using this configuration
-    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 #{Token::UNITS.keys.join(', ')}" unless Token::UNITS.keys.include? unit
-      @units = unit
-    end
-
-    # Returns a random string of between min_salt_length and max_salt_length alphanumeric charachters
-    def salt
-      max_length = [self.min_salt_length, rand(self.max_salt_length + 1)].max
-      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