mortal-token 0.0.1

data/LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2012 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
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   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.

data/README.rdoc

@@ -0,0 +1,88 @@
+== 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.
+
+I found myself wanting simple, secure (never a good mix), and not necessarily encrypted auth tokens for some Sinatra apps. 
+I wanted them to expire, but didn't want to keep track of them. Not finding anything, this library emerged. 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 at 00:00.
+
+Steps:
+
+1. Generate a new token
+2. Give the client the resulting hash and salt
+3. *crickets*
+4. Receive a hash and salt from client
+5. Reconstitute the token from the salt, and test if the hashes match
+
+Read the full documentation at {jordanhollinger.com/docs/mortal-token/}[http://jordanhollinger.com/docs/mortal-token/].
+
+== Disclaimer
+
+This is not intended to be the most secure thing ever, but for all I know it's less secure than I think. Suggestions and 
+pull requests are welcomed.
+
+Also, it is very early and the API may go through significant changes.
+
+== Use
+
+Though my example is a Sinatra app, it need not be. In fact, it needn't have anything to do with the Web. It's useful
+anytime you want a self-contained, self-expiring token (w/ salt).
+
+  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?
+      # Create a brand new token. Store the resulting hash and salt.
+      token = MortalToken.new
+      session[:token] = token.hash
+      session[:salt] = token.salt
+
+      redirect '/secret'
+    end
+  end
+
+  get '/secret' do
+    # Attempt to reconstitute the original token, using the salt
+    token = MortalToken.new(session[:salt])
+
+    # Test if the token still is (or ever was) valid
+    if token == session[:token]
+      'Welcome!'
+    else
+      'Go away!'
+    end
+  end
+
+== Checking tokens
+
+These are all valid means of checking a token's validity. In this case, they will all return true. == and === are treated the same.
+
+  token_a = MortalToken.new
+  token_b = MortalToken.new(token_a.salt)
+
+  token_a == token_b
+  token_a == token_b.to_s
+  token_a == token_b.hash
+  token_a.to_s == token_b.to_s
+  token_a.hash == token_b.hash
+  token_a.to_s == token_b.hash
+
+== 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):
+
+  MortalCoil.rounds = 5
+  MortalCoil.valid_across = 2
+  MortalCoil.max_salt_length = 50
+  MortalCoil.min_salt_length = 10
+
+== License
+Copyright 2012 Jordan Hollinger
+
+Licensed under the Apache License

data/lib/mortal-token/defaults.rb

@@ -0,0 +1,10 @@
+class MortalToken
+  # Set defaults
+  self.rounds = 5
+  self.valid_across = 2
+  self.max_salt_length = 50
+  self.min_salt_length = 10
+  # Set a temporary secret key. You should set your own consistent key.
+  # Otherwise, existing tokens will be invalidated each time the library is loaded.
+  self.secret = self.salt
+end

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

@@ -0,0 +1,76 @@
+# A token hash that "self-destructs" after a certain time.
+class MortalToken
+  # Seeds for generating random strings
+  RAND_SEEDS = [(0..9), ('a'..'z'), ('A'..'Z')].map(&:to_a).flatten
+
+  class << self
+    # 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 number of days tokens will be valid across. Defaults to 2, which prevents a
+    # token generated at 23:59 from expiring at 00:00. Changing this will invalidate existing tokens.
+    attr_accessor :valid_across
+    # The maximum salt length, defaults to 50
+    attr_accessor :max_salt_length
+    # The minimum salt length, defaults to 10
+    attr_accessor :min_salt_length
+
+    # Returns a random string of between min_salt_length and max_salt_length alphanumeric charachters
+    def salt
+      max_length = rand(self.max_salt_length + 1)
+      max_length = self.min_salt_length if max_length < self.min_salt_length
+      pool_size = RAND_SEEDS.size
+      (0..max_length).map { RAND_SEEDS[rand(pool_size)] }.join('')
+    end
+  end
+
+  # The token's salt
+  attr_reader :salt
+
+  # To create a brand new token, do *not* pass any arguments.
+  #
+  # If you want to validate a hash from an existing token, pass
+  # the existing token's salt. You should usually leave "start_date" alone.
+  def initialize(salt=nil, start_date=nil)
+    @salt = salt || MortalToken.salt
+    @start_date = start_date || Date.today
+  end
+
+  # Returns the hash value of the token
+  def hash
+    val = [MortalToken.secret, salt, @start_date, end_date].join('_')
+    MortalToken.rounds.times { val = Digest::SHA512.hexdigest(val) }
+    val
+  end
+
+  # Alias to MortalToken::Token.hash
+  def to_s
+    hash
+  end
+
+  # Tests this token against another token or token hash
+  def ==(other_token_or_hash)
+    other_hash = other_token_or_hash.to_s
+    (earliest_date).upto(@start_date) do |date|
+      guess = MortalToken.new(salt, date)
+      return true if guess.to_s == other_hash
+    end
+    return false
+  end
+
+  alias_method :===, :==
+
+  private
+
+  # Returns the end date of this token
+  def end_date
+    @start_date + (MortalToken.valid_across - 1)
+  end
+
+  # Returns the earliest possible date this token could have been valid.
+  # Only useful when checking for validity.
+  def earliest_date
+    @start_date - (MortalToken.valid_across - 1)
+  end
+end

data/lib/mortal-token/version.rb

@@ -0,0 +1,4 @@
+class MortalToken
+  # Library version
+  VERSION = '0.0.1'
+end

data/lib/mortal-token.rb

@@ -0,0 +1,5 @@
+require 'date'
+require 'digest/sha2'
+require 'mortal-token/version'
+require 'mortal-token/mortal-token'
+require 'mortal-token/defaults'

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: mortal-token
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jordan Hollinger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-08-02 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: A simple library for generating self-contained, self-destructing tokens
+email: jordan@jordanhollinger.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/mortal-token.rb
+- lib/mortal-token/defaults.rb
+- lib/mortal-token/mortal-token.rb
+- lib/mortal-token/version.rb
+- README.rdoc
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/jhollinger/mortal-token
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Generate self-destructing tokens
+test_files: []
+