salty_dog 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 30b45203cebf55800a2af8565e63cac6dd99e483
-  data.tar.gz: e635b9214221bc0015775cdfa44fe70c596698fb
+  metadata.gz: 35c2752e30819d70e0038f210d71b46a92d81c85
+  data.tar.gz: 7f79e478fb8f2a658f7ba8a7e499fadfc9309b1c
 SHA512:
-  metadata.gz: 9e669451237166a5db10484a5296069d3f66e603faa435dddf396d1edf1304b343f7fba4d1e0b12d94ca7e42d0bba7d235c5b80352bae9d95a7a7e726e56e83f
-  data.tar.gz: 460199701063cd37f868f0979185a129243f059e07659af2862abdf2c3fc2e7c4d61abefd249a62ed291d4738aecc09a090fab53572156c77412e57829b90368
+  metadata.gz: f6ddfd7b180e95a1cfb0c4f31316a3c62574662a4977eb09de941d10b8f9d9a7146b13af12701c0bfbf0901242dd9a0bee030b8d0b19e4f7b174aa712225382f
+  data.tar.gz: 38a97773ca711de242e850c4fcf7c403a782a600fbeff5c770a4fc8afd679096a6808091e6fc2b4c7165b7ccd68ba24342e230bfb4c0f797ec20909d1ed04514

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].to_s, options[:salt].to_s, @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
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: salty_dog
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Brennon Bortz
@@ -47,6 +47,7 @@ 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