fernet 2.0.rc1 → 2.0.rc2

data/.rdoc_options

@@ -0,0 +1,16 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- .
+charset: UTF-8
+exclude: 
+hyperlink_all: false
+line_numbers: false
+main_page: 
+markup: tomdoc
+show_hash: false
+tab_width: 8
+title: 
+visibility: :protected
+webcvs: 

data/.travis.yml

@@ -4,6 +4,5 @@ rvm:
   - "1.9.3"
   - "1.9.2"
   - "2.0.0"
-  - "ruby-head"
 
 script: bundle exec rspec -b spec

data/lib/fernet.rb

@@ -10,11 +10,56 @@ require 'fernet/configuration'
 Fernet::Configuration.run
 
 module Fernet
-  def self.generate(secret, message = '', opts = {}, &block)
+  # Public: generates a fernet token
+  #
+  # secret  - a base64 encoded, 32 byte string
+  # message - the message being secured in plain text
+  #
+  # Returns the fernet token as a string
+  #
+  # Examples
+  #
+  #   secret = ...
+  #   token = Fernet.generate(secret, 'my secrets')
+  def self.generate(secret, message = '', opts = {})
     Generator.new(opts.merge({secret: secret, message: message})).
-      generate(&block)
+      generate
   end
 
+  # Public: verifies a fernet token
+  #
+  # secret - the secret used to generate the token
+  # token  - the token to verify as a string
+  # opts - an optional hash containing
+  #   enforce_ttl: whether to enforce TTL in this verification
+  #   ttl: number of seconds token is valid
+  #
+  # Both enforce_ttl and ttl can be configured globally via Configuration
+  #
+  # Returns a verifier object, which responds to valid? and message
+  #
+  # Raises Fernet::Token::InvalidToken if token is invalid and message
+  #   is attempted to be extracted
+  #
+  # Examples
+  #
+  # secret = ...
+  # token = ...
+  # verifier = Fernet.verifier(secret, old_token, enforce_ttl: false)
+  # if verifier.valid?
+  #   verifier.message # original message in plain text
+  # end
+  #
+  # verifier = Fernet.verifier(secret, old_token)
+  # if verifier.valid?
+  #   verifier.message
+  # else
+  #   verifier.errors
+  #   # -> { issued_timestamp: "is too far in the past: token expired" }
+  #   verifier.error_messages
+  #   # -> ["issued_timestamp is too far in the past: token expired"]
+  # end
+  #
   def self.verifier(secret, token, opts = {})
     Verifier.new(opts.merge({secret: secret, token: token}))
   end

data/lib/fernet/bit_packing.rb

@@ -1,14 +1,25 @@
 module Fernet
+  # Internal: wrappers used for consistent bit packing across rubies
+  #
+  # Ruby 1.9.2 and below silently ignore endianness specifiers in
+  # packing/unpacking format directives
   module BitPacking
     extend self
 
-    # N.B. Ruby 1.9.2 and below silently ignore endianness specifiers in
-    # packing/unpacking format directives; we work around it with this
-
+    # Internal - packs a value as a big endian, 64 bit integer
+    #
+    # value - a byte sequence as a string
+    #
+    # Returns array containing each value
     def pack_int64_bigendian(value)
       (0..7).map { |index| (value >> (index * 8)) & 0xFF }.reverse.map(&:chr).join
     end
 
+    # Internal - unpacks a string of big endian, 64 bit integers
+    #
+    # bytes - an array of ints
+    #
+    # Returns the original byte sequence as a string
     def unpack_int64_bigendian(bytes)
       bytes.each_byte.to_a.reverse.each_with_index.
         reduce(0) { |val, (byte, index)| val | (byte << (index * 8)) }

data/lib/fernet/configuration.rb

@@ -1,16 +1,32 @@
 require 'singleton'
 module Fernet
+  # Public - singleton class used to globally set various
+  #          configuration defaults
   class Configuration
     include Singleton
 
-    # Whether to enforce a message TTL
-    # (true or false)
+    # Public: Returns whether to enforce a message TTL (true or false)
     attr_accessor :enforce_ttl
 
-    # How long messages are considered valid to the verifier
-    # (an integer in seconds)
+    # Public: Returns how many seconds messages are considered valid for
     attr_accessor :ttl
 
+    # Public: used to configure fernet, typically invoked in an initialization
+    #   routine
+    #
+    # Sets the following values:
+    #
+    # * enforce_ttl: true
+    # * ttl: 60
+    #
+    # Yields the singleton configuration object, where above defaults can be
+    #   overridden
+    #
+    # Examples
+    #
+    # Fernet::Configuration.run do |config|
+    #   config.enforce_ttl = false
+    # end
     def self.run
       self.instance.enforce_ttl = true
       self.instance.ttl         = 60

data/lib/fernet/encryption.rb

@@ -1,9 +1,25 @@
 require 'openssl'
 
 module Fernet
+  # Internal: Encapsulates encryption and signing primitives
   module Encryption
     AES_BLOCK_SIZE  = 16.freeze
 
+    # Internal: Encrypts the provided message using a AES-128-CBC cipher with a
+    #   random IV and the provided encryption key
+    #
+    # opts - a hash containing
+    #   message: the message to encrypt
+    #   key: the encryption key
+    #   iv: override for the random IV, only used for testing
+    #
+    # Returns a two-element array containing the ciphertext and the random IV
+    #
+    # Examples
+    #
+    # ciphertext, iv = Fernet::Encryption.encrypt(
+    #   message: 'this is a secret', key: encryption_key
+    # )
     def self.encrypt(opts)
       cipher = OpenSSL::Cipher.new('AES-128-CBC')
       cipher.encrypt
@@ -13,6 +29,21 @@ module Fernet
       [cipher.update(opts[:message]) + cipher.final, iv]
     end
 
+    # Internal: Decrypts the provided ciphertext using a AES-128-CBC cipher with a
+    #   the provided IV and encryption key
+    #
+    # opts - a hash containing
+    #   ciphertext: encrypted message
+    #   key: encryption key used to encrypt the message
+    #   iv: initialization vector used in the ciphertext's cipher
+    #
+    # Returns a two-element array containing the ciphertext and the random IV
+    #
+    # Examples
+    #
+    # ciphertext, iv = Fernet::Encryption.encrypt(
+    #   message: 'this is a secret', key: encryption_key
+    # )
     def self.decrypt(opts)
       decipher = OpenSSL::Cipher.new('AES-128-CBC')
       decipher.decrypt
@@ -21,8 +52,15 @@ module Fernet
       decipher.update(opts[:ciphertext]) + decipher.final
     end
 
-    def self.hmac_digest(key, blob)
-      OpenSSL::HMAC.digest('sha256', key, blob)
+    # Internal: Creates an HMAC signature (sha356 hashing) of the given bytes
+    #   with the provided signing key
+    #
+    # key - the signing key
+    # bytes - blob of bytes to sign
+    #
+    # Returns the HMAC signature as a string
+    def self.hmac_digest(key, bytes)
+      OpenSSL::HMAC.digest('sha256', key, bytes)
     end
   end
 end

data/lib/fernet/generator.rb

@@ -4,9 +4,16 @@ require 'openssl'
 require 'date'
 
 module Fernet
+  # Internal: Generates Fernet tokens
   class Generator
+    # Returns the token's message
     attr_accessor :message
 
+    # Internal: Initializes a generator
+    #
+    # opts - a hash containing the following keys:
+    #   secret: a string containing a secret, optionally Base64 encoded
+    #   message: the message
     def initialize(opts)
       @secret  = opts.fetch(:secret)
       @message = opts[:message]
@@ -14,6 +21,21 @@ module Fernet
       @now     = opts[:now]
     end
 
+    # Internal: generates a secret token
+    #
+    # Yields itself, useful for setting or overriding the message
+    #
+    # Returns the token as a string
+    #
+    # Examples
+    # generator = Generator.new(secret: some_secret)
+    # token = generator.generate do |g|
+    #   g.message = 'this is my message'
+    # end
+    #
+    # generator = Generator.new(secret: some_secret,
+    #                           message: 'this is my message')
+    # token = generator.generate
     def generate
       yield self if block_given?
 
@@ -24,13 +46,16 @@ module Fernet
       token.to_s
     end
 
+    # Public: string representation of this generator, masks secret to avoid
+    #   leaks
     def inspect
       "#<Fernet::Generator @secret=[masked] @message=#{@message.inspect}>"
     end
     alias to_s inspect
 
+    # Deprecated: used to set the message
     def data=(message)
-      puts "[WARNING] 'data' is deprecated, use 'message' instead"
+      puts "[WARNING] 'data=' is deprecated, use 'message=' instead"
       @message = message
     end
   end

data/lib/fernet/secret.rb

@@ -1,23 +1,45 @@
 require 'base64'
+
 module Fernet
+  # Internal: Encapsulates a secret key, a 32-byte sequence consisting
+  #   of an encryption and a signing key.
   class Secret
     class InvalidSecret < RuntimeError; end
 
+    # Internal - Initialize a Secret
+    #
+    # secret - the secret, optionally encoded with either standard or
+    #          URL safe variants of Base64 encoding
+    #
+    # Raises Fernet::Secret::InvalidSecret if it cannot be decoded or is
+    #   not of the expected length
     def initialize(secret)
-      @secret = Base64.urlsafe_decode64(secret)
-      unless @secret.bytesize == 32
-        raise InvalidSecret, "Secret must be 32 bytes, instead got #{@secret.bytesize}"
+      if secret.bytesize == 32
+        @secret = secret
+      else
+        begin
+          @secret = Base64.urlsafe_decode64(secret)
+        rescue ArgumentError
+          @secret = Base64.decode64(secret)
+        end
+        unless @secret.bytesize == 32
+          raise InvalidSecret,
+            "Secret must be 32 bytes, instead got #{@secret.bytesize}"
+        end
       end
     end
 
+    # Internal: Returns the portion of the secret token used for encryption
     def encryption_key
       @secret.slice(16, 16)
     end
 
+    # Internal: Returns the portion of the secret token used for signing
     def signing_key
       @secret.slice(0, 16)
     end
 
+    # Public: String representation of this secret, masks to avoid leaks.
     def to_s
       "<Fernet::Secret [masked]>"
     end

data/lib/fernet/token.rb

@@ -3,34 +3,51 @@ require 'base64'
 require 'valcro'
 
 module Fernet
+  # Internal: encapsulates a fernet token structure and validation
   class Token
     include Valcro
 
     class InvalidToken < StandardError; end
 
+    # Internal: the default token version
     DEFAULT_VERSION = 0x80.freeze
+    # Internal: max allowed clock skew for calculating TTL
     MAX_CLOCK_SKEW  = 60.freeze
 
+    # Internal: initializes a Token object
+    #
+    # token - the string representation of this token
+    # opts  - a has containing
+    #   secret: the secret, optionally base 64 encoded (required)
+    #   enforce_ttl: whether to enforce TTL upon validation. Defaults to value
+    #                set in Configuration.enforce_ttl
+    #   ttl: number of seconds token is valid, defaults to Configuration.ttl
     def initialize(token, opts = {})
       @token       = token
+      @secret      = Secret.new(opts.fetch(:secret))
       @enforce_ttl = opts.fetch(:enforce_ttl) { Configuration.enforce_ttl }
       @ttl         = opts[:ttl] || Configuration.ttl
       @now         = opts[:now]
     end
 
+    # Internal: returns the token as a string
     def to_s
       @token
     end
 
-    def secret=(secret)
-      @secret = Secret.new(secret)
-    end
-
+    # Internal: Validates this token and returns true if it's valid
+    #
+    # Returns a boolean set to true if it's valid, false otherwise
     def valid?
       validate
       super
     end
 
+    # Internal: returns the decrypted message in this token
+    #
+    # Raises InvalidToken if it cannot be decrypted or is invalid
+    #
+    # Returns a string containing the original message in plain text
     def message
       if valid?
         begin
@@ -45,22 +62,27 @@ module Fernet
       end
     end
 
-    def self.generate(params)
-      unless params[:secret]
+    # Internal: generates a Fernet Token
+    #
+    # opts - a hash containing
+    #   secret: a string containing the secret, optionally base64 encoded
+    #   message: the message in plain text
+    def self.generate(opts)
+      unless opts[:secret]
         raise ArgumentError, 'Secret not provided'
       end
-      secret = Secret.new(params[:secret])
+      secret = Secret.new(opts.fetch(:secret))
       encrypted_message, iv = Encryption.encrypt(key:     secret.encryption_key,
-                                                 message: params[:message],
-                                                 iv:      params[:iv])
-      issued_timestamp = (params[:now] || Time.now).to_i
+                                                 message: opts[:message],
+                                                 iv:      opts[:iv])
+      issued_timestamp = (opts[:now] || Time.now).to_i
 
       payload = [DEFAULT_VERSION].pack("C") +
         BitPacking.pack_int64_bigendian(issued_timestamp) +
         iv +
         encrypted_message
       mac = OpenSSL::HMAC.digest('sha256', secret.signing_key, payload)
-      new(Base64.urlsafe_encode64(payload + mac))
+      new(Base64.urlsafe_encode64(payload + mac), secret: opts.fetch(:secret))
     end
 
   private
@@ -92,13 +114,12 @@ module Fernet
       if valid_base64?
         if unknown_token_version?
           errors.add :version, "is unknown"
+        elsif enforce_ttl? && !issued_recent_enough?
+          errors.add :issued_timestamp, "is too far in the past: token expired"
         else
           unless signatures_match?
             errors.add :signature, "does not match"
           end
-          if enforce_ttl? && !issued_recent_enough?
-            errors.add :issued_timestamp, "is too far in the past: token expired"
-          end
           if unacceptable_clock_slew?
             errors.add :issued_timestamp, "is too far in the future"
           end

data/lib/fernet/verifier.rb

@@ -4,34 +4,49 @@ require 'openssl'
 require 'date'
 
 module Fernet
+  # Public: verifies Fernet Tokens
   class Verifier
     class UnknownTokenVersion < RuntimeError; end
 
     attr_reader :token
     attr_accessor :ttl, :enforce_ttl
 
+    # Internal: initializes a Verifier
+    #
+    # opts - a hash containing
+    #   secret: the secret used to create the token (required)
+    #   token: the fernet token string (required)
+    #   enforce_ttl: whether to enforce TTL, defaults to Configuration.enforce_ttl
+    #   ttl: number of seconds the token is valid
     def initialize(opts = {})
       enforce_ttl = opts.has_key?(:enforce_ttl) ? opts[:enforce_ttl] : Configuration.enforce_ttl
       @token = Token.new(opts.fetch(:token),
+                           secret: opts.fetch(:secret),
                            enforce_ttl: enforce_ttl,
                            ttl: opts[:ttl],
                            now: opts[:now])
-      @token.secret = opts.fetch(:secret)
     end
 
+    # Public: whether the verifier is valid. A verifier is valid if it's token
+    #   is valid.
+    #
+    # Returns a boolean set to true if the token is valid, false otherwise
     def valid?
       @token.valid?
     end
 
+    # Public: Returns the token's message
     def message
       @token.message
     end
 
+    # Deprecated: returns the token's message
     def data
       puts "[WARNING] data is deprected. Use message instead"
       message
     end
 
+    # Public: String representation of this verifier, masks the secret to avoid leaks.
     def inspect
       "#<Fernet::Verifier @secret=[masked] @token=#{@token} @message=#{@message.inspect} @ttl=#{@ttl} @enforce_ttl=#{@enforce_ttl}>"
     end
@@ -42,15 +57,6 @@ module Fernet
       @must_verify || @valid.nil?
     end
 
-    def token_recent_enough?
-      if enforce_ttl?
-        good_till = @issued_at + (ttl.to_f / 24 / 60 / 60)
-        (good_till.to_i >= now.to_i) && acceptable_clock_skew?
-      else
-        true
-      end
-    end
-
     def acceptable_clock_skew?
       @issued_at < (now + MAX_CLOCK_SKEW)
     end
@@ -63,10 +69,6 @@ module Fernet
       end.zero?
     end
 
-    def enforce_ttl?
-      @enforce_ttl
-    end
-
     def now
       @now ||= Time.now
     end

data/lib/fernet/version.rb

@@ -1,3 +1,3 @@
 module Fernet
-  VERSION = "2.0.rc1"
+  VERSION = "2.0.rc2"
 end

data/spec/fernet_spec.rb

@@ -8,32 +8,21 @@ describe Fernet do
   let(:bad_secret) { 'badICDH6x3M7duQeM8dJEMK4Y5TkBIsYDw1lPy35RiY=' }
 
   it 'can verify tokens it generates' do
-    token = Fernet.generate(secret) do |generator|
-      generator.message = 'harold@heroku.com'
-    end
-
-    verifier = Fernet.verifier(secret, token)
-    expect(verifier).to be_valid
-    expect(verifier.message).to eq('harold@heroku.com')
-  end
-
-  it 'can generate tokens without a block' do
     token = Fernet.generate(secret, 'harold@heroku.com')
+
     verifier = Fernet.verifier(secret, token)
     expect(verifier).to be_valid
     expect(verifier.message).to eq('harold@heroku.com')
   end
 
   it 'fails with a bad secret' do
-    token = Fernet.generate(secret) do |generator|
-      generator.message = 'harold@heroku.com'
-    end
+    token = Fernet.generate(secret, 'harold@heroku.com')
 
     verifier = Fernet.verifier(bad_secret, token)
     expect(verifier.valid?).to be_false
     expect {
       verifier.message
-    }.to raise_error
+    }.to raise_error Fernet::Token::InvalidToken
   end
 
   it 'fails if the token is too old' do
@@ -77,9 +66,7 @@ describe Fernet do
       config.enforce_ttl = true
       config.ttl = 0
     end
-    token = Fernet.generate(secret) do |generator|
-      generator.message = 'password1'
-    end
+    token = Fernet.generate(secret, 'password1')
     verifier = Fernet.verifier(secret, token)
     verifier.enforce_ttl = false
     expect(verifier.valid?).to be_true

data/spec/secret_spec.rb

@@ -2,23 +2,16 @@ require 'spec_helper'
 require 'fernet/secret'
 
 describe Fernet::Secret do
-  it "expects base64 encoded 32 byte strings" do
-    secret = Base64.urlsafe_encode64("A"*32)
-    expect do
-      Fernet::Secret.new(secret)
-    end.to_not raise_error
+  it "can resolve a URL safe base64 encoded 32 byte string" do
+    resolves_input(Base64.urlsafe_encode64("A"*16 + "B"*16))
   end
 
-  it "extracts encryption and signing keys" do
-    secret = Base64.urlsafe_encode64("A"*16 + "B"*16)
-    fernet_secret = Fernet::Secret.new(secret)
-    expect(
-      fernet_secret.signing_key
-    ).to eq("A"*16)
+  it "can resolve a base64 encoded 32 byte string" do
+    resolves_input(Base64.encode64("A"*16 + "B"*16))
+  end
 
-    expect(
-      fernet_secret.encryption_key
-    ).to eq("B"*16)
+  it "can resolve a 32 byte string without encoding" do
+    resolves_input("A"*16 + "B"*16)
   end
 
   it "fails loudly when an invalid secret is provided" do
@@ -27,4 +20,16 @@ describe Fernet::Secret do
       Fernet::Secret.new(secret)
     end.to raise_error(Fernet::Secret::InvalidSecret)
   end
+
+  def resolves_input(input)
+    secret = Fernet::Secret.new(input)
+
+    expect(
+      secret.signing_key
+    ).to eq("A"*16)
+
+    expect(
+      secret.encryption_key
+    ).to eq("B"*16)
+  end
 end

data/spec/token_spec.rb

@@ -11,8 +11,7 @@ describe Fernet::Token, 'validation' do
     bogus_hmac = "1" * 32
     Fernet::Encryption.stub(hmac_digest: bogus_hmac)
 
-    token = Fernet::Token.new(generated.to_s)
-    token.secret = secret
+    token = Fernet::Token.new(generated.to_s, secret: secret)
 
     expect(token.valid?).to be_false
     expect(token.errors[:signature]).to include("does not match")
@@ -23,9 +22,8 @@ describe Fernet::Token, 'validation' do
                                        message: 'hello',
                                        now: Time.now - 61)
     token = Fernet::Token.new(generated.to_s, enforce_ttl: true,
-                                              ttl: 60)
-    token.secret = secret
-
+                                              ttl: 60,
+                                              secret: secret)
     expect(token.valid?).to be_false
     expect(token.errors[:issued_timestamp]).to include("is too far in the past: token expired")
   end
@@ -34,23 +32,21 @@ describe Fernet::Token, 'validation' do
     generated = Fernet::Token.generate(secret:  secret,
                                        message: 'hello',
                                        now:     Time.at(Time.now.to_i + 61))
-    token = Fernet::Token.new(generated.to_s)
-    token.secret = secret
+    token = Fernet::Token.new(generated.to_s, secret: secret)
 
     expect(token.valid?).to be_false
     expect(token.errors[:issued_timestamp]).to include("is too far in the future")
   end
 
   it 'is invalid with bad base64' do
-    token = Fernet::Token.new('bad')
-    token.secret = secret
+    token = Fernet::Token.new('bad', secret: secret)
 
     expect(token.valid?).to be_false
     expect(token.errors[:token]).to include("invalid base64")
   end
 
   it 'is invalid with an unknown token version' do
-    token  = Fernet::Token.new(Base64.urlsafe_encode64("xxxxxx"))
+    token = Fernet::Token.new(Base64.urlsafe_encode64("xxxxxx"), secret: secret)
 
     expect(token.valid?).to be_false
     expect(token.errors[:version]).to include("is unknown")
@@ -63,8 +59,7 @@ describe Fernet::Token, 'message' do
     generated = Fernet::Token.generate(secret:  secret,
                                        message: 'hello',
                                        now:     Time.now + 61)
-    token = Fernet::Token.new(generated.to_s)
-    token.secret = secret
+    token = Fernet::Token.new(generated.to_s, secret: secret)
 
     !token.valid? or raise "invalid token"
 
@@ -77,7 +72,6 @@ describe Fernet::Token, 'message' do
   it 'gives back the original message in plain text' do
     token = Fernet::Token.generate(secret: secret,
                                    message: 'hello')
-    token.secret = secret
     token.valid? or raise "invalid token"
 
     expect(token.message).to eq('hello')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fernet
 version: !ruby/object:Gem::Version
-  version: 2.0.rc1
+  version: 2.0.rc2
   prerelease: 4
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-19 00:00:00.000000000 Z
+date: 2013-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: valcro
@@ -52,6 +52,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .gitmodules
+- .rdoc_options
 - .rspec
 - .travis.yml
 - Gemfile