salty_dog 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b6e3d2c400d8da82752ae6862e1de092d9596e1b
+  data.tar.gz: c22eabb1c6afff27a88fe6927114e2fd0a782dd3
+SHA512:
+  metadata.gz: 1a523b3345361daf452930cb9cc23de6fb3ee2fff54d015835a47bdb4fbe5f5ce7abfe271e34712f2c58715f2bd0b8fb2710a5c08fe76ad70e9f789e3aa7d343
+  data.tar.gz: 74675135cd008d478a1376232b614ac804946be2246c984c107d056466b9f76dad8ca853ffdec2316d098a514aa2ef240852ecd9be38936a29561ba40056b3ae

data/lib/salty_dog/salty_dog.rb

@@ -0,0 +1,143 @@
+require 'openssl'
+
+module SaltyDog
+
+  ##
+  # PBKDF2 encapsulates the identically-named password-based key derivation
+  # function outlined in PKCS[http://www.rsa.com/rsalabs/node.asp?id=2127] #5: Password-Based Cryptography Standard. PBKDF1, as set 
+  # forth in the same document, has been recommended for removal from use, and
+  # thus is not implemented in SaltyDog. If you just need to generate keys,
+  # skip down to ::digest:
+
+  class PBKDF2
+
+    ##
+    # According to the recommendation, the hash functions that are supported
+    # for HMAC (pseudorandom number generation) are SHA1, SHA224, SHA256,
+    # SHA384, AND SHA512. These are provided here.
+
+    ALLOWED_DIGESTS = [:sha1, :sha224, :sha256, :sha384, :sha512]
+    
+    ##
+    # The primary point of entry for SaltyDog::PBKDF2. The available options
+    # are:
+    #
+    # - :digest - One of +:sha1+, +:sha224+, +:sha256+, +:sha384+, or
+    # +:sha512+. Defaults to +:sha512+.
+    # - :password - A password for use in deriving the key. Required, and must be a string.
+    # - :salt - A salt that is concatenated to the password in key derivation.
+    # Required, and must ba a string.
+    # - :length - The desired length, in bytes, of the derived key. Required.
+    # - :iterations - The number of iterations to be used in key derivation.
+    # Defaults to 10000.
+    #
+    # Returns a hex-string representing the derived key.
+
+    def self.digest(options = {})
+      digest = options[:digest] || :sha512
+      self.build_digest(digest)
+      
+      check_key_length_requirements(options[:length])
+      @length = options[:length]
+      @iterations = options[:iterations] || 10000
+
+      @l = (@length / @digest.length).ceil
+      @r = @length - (@l - 1) * @digest.length
+
+      self.calculate_key(@digest, options[:password], options[:salt], @l, @r, @iterations).unpack('H*')[0]
+    end
+
+    ##
+    # Build the derived key. Called directly by SaltyDog::PBKDF2.digest.
+
+    def self.build_digest(digest)
+      if !ALLOWED_DIGESTS.include?(digest)
+        raise PBKDF2Error, 'Invalid digest'
+      end
+
+      klass = "OpenSSL::Digest::#{digest.to_s.upcase}"
+      @digest = Object::const_get(klass).new
+    end
+
+    ##
+    # Check desired key length requirements. These are:
+    #
+    # - Must be present
+    # - Must be strictly positive
+    # - Must be no larger than (2^32 - 1) * digest length of the chosen hash
+    # function
+    #
+    # Raises a PBKDF2Error if any of these requirements are not met.
+    
+    def self.check_key_length_requirements(length)
+      raise PBKDF2Error, 'A key length must be provided' if !length
+      raise PBKDF2Error, 'Desired key is too long' if ((2**32 - 1) * @digest.length) < length
+      raise PBKDF2Error, 'Desired key length must be positive' if length < 0
+    end
+
+    ##
+    # XOR two strings +x+ and +y+.
+    #
+    # Raises a PBKDF2Error if +a+ and +b+ are not the same length.
+    #
+    # Returns a string of bytes representing the XORed value.
+
+    def self.xor(x, y)
+      raise PBKDF2Error, 'XOR arguments are not the same length' if x.length - y.length != 0 
+      output = "".encode('ASCII-8BIT')
+
+      x.bytes.zip(y.bytes) { |x,y| output << (x^y) }
+      output
+    end
+
+    ##
+    # Uses a pseudorandom function based on the digest function provided to
+    # SaltyDog::PBKDF2.digest to generate input for each iteration round.
+
+    def self.prf(digest, password, seed)
+      raise PBKDF2Error if !password || !seed
+      OpenSSL::HMAC.digest(digest, password, seed)
+    end
+
+    ##
+    # Within each iteration, SaltyDog::PBKDF2.xor_sum XORs each block of output
+    # from SaltyDog::PBKDF2.prf. The result of this chain of XORs is provided
+    # to ::calculate_key to be used as a block of the final derived key.
+
+    def self.xor_sum(digest, password, salt, iterations, block_number)
+      packed_index = [block_number].pack("N")
+      seed = salt + packed_index
+      final = self.prf(digest, password, seed)
+      u = final
+
+      for i in 2..iterations do
+        u = self.prf(digest, password, u)
+        final = self.xor(final, u)
+      end
+
+      final
+    end
+
+    ##
+    # The workhorse of SaltyDog::PBKDF2. ::calculate_key initiates the
+    # specified number of iterations of hashing in calculating each block of
+    # the derived key. All blocks are then concatenated together in computing
+    # the final derived key.
+
+    def self.calculate_key(digest, password, salt, l, r, iterations)
+      t = ""
+
+      for i in 1..l+1 do
+        t << self.xor_sum(digest, password, salt, iterations, i)
+      end
+
+      total_length = digest.length * (l-1) + r
+      sliced = t.slice(0..total_length - 1)
+      sliced
+    end
+  end
+
+  class PBKDF2Error < StandardError
+  end
+end
+

data/lib/salty_dog.rb

@@ -0,0 +1 @@
+require 'salty_dog/salty_dog'

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: salty_dog
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brennon Bortz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: turn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.6
+description: A complete, RFC compliant implementation of PBKDF2. As opposed to other
+  PBKDF2 gems, all parameters to the key-derivation function are completely and easily
+  customizable.
+email: brennon@brennonbortz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/salty_dog.rb
+- lib/salty_dog/salty_dog.rb
+homepage: http://github.com/brennon/salty_dog
+licenses:
+- BSD-3
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --main
+- README.md
+require_paths:
+- lib
+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: 2.0.3
+signing_key: 
+specification_version: 4
+summary: PBKDF2, Ruby-style
+test_files: []