hkdf 0.1.0

data/README.md

@@ -0,0 +1,23 @@
+# HKDF [![Build Status](https://secure.travis-ci.org/jtdowney/hkdf.png?branch=master)](http://travis-ci.org/jtdowney/hkdf)
+
+This is a ruby implementation of [RFC 5869](http://tools.ietf.org/html/rfc5869): HMAC-based Extract-and-Expand Key Derivation Function. The goal of HKDF is to take some source key material and generate suitable cryptographic keys from it.
+
+## Usage
+
+```ruby
+hkdf = HKDF.new('source key material')
+hkdf.next_bytes(32)
+ => "\f#\xF4b\x98\x9B\x7Fw>|/|k\xF4k\xB7\xB9\x11e\xC5\x92\xD1\fH\xFDG\x94vt\xB4\x14\xCE"
+```
+
+The default algorithm is HMAC-SHA256, you can override this and other defaults by providing an options hash during construction.
+
+```ruby
+hkdf = HKDF.new('source key material', :salt => 'NaCl', :algorithm => 'SHA1', :info => 'the 411')
+hkdf.next_bytes(16)
+ => "\xC0<\x13\x85\x8C\x84z\xCE\xC7\xCE+\xFF\x1C\xEB\xE6\xBC"
+```
+
+## License
+
+The HKDF gem is released under the [MIT license](http://www.opensource.org/licenses/MIT).

data/lib/hkdf.rb

@@ -0,0 +1,60 @@
+require 'openssl'
+
+class HKDF
+  def initialize(source, options = {})
+    options = {:algorithm => 'SHA256', :info => '', :salt => nil}.merge(options)
+
+    @digest = OpenSSL::Digest.new(options[:algorithm])
+    @info = options[:info]
+
+    salt = options[:salt]
+    salt = 0.chr * @digest.digest_length if salt.nil? or salt.empty?
+
+    @prk = OpenSSL::HMAC.digest(@digest, salt, source)
+    @position = 0
+    @blocks = []
+    @blocks << ''
+  end
+
+  def algorithm
+    @digest.name
+  end
+
+  def max_length
+    @digest.digest_length * 255
+  end
+
+  def seek(position)
+    raise RangeError.new("cannot seek past #{max_length}") if position > max_length
+
+    @position = position
+  end
+
+  def rewind
+    seek(0)
+  end
+
+  def next_bytes(length)
+    new_position = length + @position
+    raise RangeError.new("requested #{length} bytes, only #{max_length} available") if new_position > max_length
+
+    _generate_blocks(new_position)
+
+    start = @position
+    @position = new_position
+
+    @blocks.join('').slice(start, length)
+  end
+
+  def next_hex_bytes(length)
+    next_bytes(length).unpack('H*').first
+  end
+
+  def _generate_blocks(length)
+    start = @blocks.size
+    block_count = (length.to_f / @digest.digest_length).ceil
+    start.upto(block_count) do |n|
+      @blocks << OpenSSL::HMAC.digest(@digest, @prk, @blocks[n - 1] + @info + n.chr)
+    end
+  end
+end

data/spec/hkdf_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe HKDF do
+  before(:each) do
+    @algorithm = 'SHA256'
+    @source = 'source'
+    @hkdf = HKDF.new(@source, :algorithm => @algorithm)
+  end
+
+  describe 'initialize' do
+    it 'defaults the algorithm to SHA-256' do
+      HKDF.new(@source).algorithm.should == 'SHA256'
+    end
+
+    it 'takes an optional digest algorithm' do
+      @hkdf = HKDF.new('source', :algorithm => 'SHA1')
+      @hkdf.algorithm.should == 'SHA1'
+    end
+
+    it 'defaults salt to all zeros of digest length' do
+      salt = 0.chr * 32
+
+      @hkdf_salt = HKDF.new(@source, :algorithm => @algorithm, :salt => salt)
+      @hkdf_nosalt = HKDF.new(@source, :algorithm => @algorithm)
+      @hkdf_salt.next_bytes(32) == @hkdf_nosalt.next_bytes(32)
+    end
+
+    it 'sets salt to all zeros of digest 32 if empty' do
+      @hkdf_blanksalt = HKDF.new(@source, :algorithm => @algorithm, :salt => '')
+      @hkdf_nosalt = HKDF.new(@source, :algorithm => @algorithm)
+      @hkdf_blanksalt.next_bytes(32) == @hkdf_nosalt.next_bytes(32)
+    end
+
+    it 'defaults info to an empty string' do
+      @hkdf_info = HKDF.new(@source, :algorithm => @algorithm, :info => '')
+      @hkdf_noinfo = HKDF.new(@source, :algorithm => @algorithm)
+      @hkdf_info.next_bytes(32) == @hkdf_noinfo.next_bytes(32)
+    end
+  end
+
+  describe 'max_length' do
+    it 'is 255 times the digest length' do
+      @hkdf.max_length.should == 255 * 32
+    end
+  end
+
+  describe 'next_bytes' do
+    it 'raises an error if requested size is > max_length' do
+      expect { @hkdf.next_bytes(@hkdf.max_length + 1) }.should raise_error(RangeError, /requested \d+ bytes, only \d+ available/)
+      expect { @hkdf.next_bytes(@hkdf.max_length) }.should_not raise_error(RangeError, /requested \d+ bytes, only \d+ available/)
+    end
+
+    it 'raises an error if requested size + current position is > max_length' do
+      expect do
+        @hkdf.next_bytes(32)
+        @hkdf.next_bytes(@hkdf.max_length - 31)
+      end.should raise_error(RangeError, /requested \d+ bytes, only \d+ available/)
+    end
+
+    it 'advances the stream position' do
+      @hkdf.next_bytes(32).should_not == @hkdf.next_bytes(32)
+    end
+
+    test_vectors.each do |name, options|
+      it "matches output from the '#{name}' test vector" do
+        options[:algorithm] = options[:Hash]
+
+        hkdf = HKDF.new(options[:IKM], options)
+        hkdf.next_bytes(options[:L].to_i).should == options[:OKM]
+      end
+    end
+  end
+
+  describe 'next_hex_bytes' do
+    it 'returns the next bytes as hex' do
+      @hkdf.next_hex_bytes(20).should == 'fb496612b8cb82cd2297770f83c72b377af16d7b'
+    end
+  end
+
+  describe 'seek' do
+    it 'sets the position anywhere in the stream' do
+      @hkdf.next_bytes(10)
+      output = @hkdf.next_bytes(32)
+      @hkdf.seek(10)
+      @hkdf.next_bytes(32).should == output
+    end
+
+    it 'raises an error if requested to seek past end of stream' do
+      expect { @hkdf.seek(@hkdf.max_length + 1) }.should raise_error(RangeError, /cannot seek past \d+/)
+      expect { @hkdf.seek(@hkdf.max_length) }.should_not raise_error(RangeError, /cannot seek past \d+/)
+    end
+  end
+
+  describe 'rewind' do
+    it 'resets the stream position to the beginning' do
+      output = @hkdf.next_bytes(32)
+      @hkdf.rewind
+      @hkdf.next_bytes(32).should == output
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+require 'hkdf'
+
+def test_vectors
+  test_lines = File.readlines('spec/test_vectors.txt').map(&:strip).reject(&:empty?)
+
+  vectors = {}
+  test_lines.each_slice(8) do |lines|
+    name = lines.shift
+    values = lines.inject({}) do |hash, line|
+      key, value = line.split('=').map(&:strip)
+      value = '' unless value
+      value = [value.slice(2..-1)].pack('H*') if value.start_with?('0x')
+      hash[key.to_sym] = value
+      hash
+    end
+    vectors[name] = values
+  end
+  vectors
+end

data/spec/test_vectors.txt

@@ -0,0 +1,53 @@
+Basic test case with SHA256
+Hash   = SHA256
+IKM    = 0x0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b
+salt   = 0x000102030405060708090a0b0c
+info   = 0xf0f1f2f3f4f5f6f7f8f9
+L      = 42
+PRK    = 0x077709362c2e32df0ddc3f0dc47bba6390b6c73bb50f9c3122ec844ad7c2b3e5
+OKM    = 0x3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865
+
+Test with SHA256 and longer inputs/outputs
+Hash   = SHA256
+IKM    = 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f
+salt   = 0x606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeaf
+info   = 0xb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff
+L      = 82
+PRK    = 0x06a6b88c5853361a06104c9ceb35b45cef760014904671014a193f40c15fc244
+OKM    = 0xb11e398dc80327a1c8e7f78c596a49344f012eda2d4efad8a050cc4c19afa97c59045a99cac7827271cb41c65e590e09da3275600c2f09b8367793a9aca3db71cc30c58179ec3e87c14c01d5c1f3434f1d87
+
+Test with SHA256 and empty salt/info
+Hash   = SHA256
+IKM    = 0x0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b
+salt   =
+info   =
+L      = 42
+PRK    = 0x19ef24a32c717b167f33a91d6f648bdf96596776afdb6377ac434c1c293ccb04
+OKM    = 0x8da4e775a563c18f715f802a063c5a31b8a11f5c5ee1879ec3454e5f3c738d2d9d201395faa4b61a96c8
+
+Basic test case with SHA1
+Hash   = SHA1
+IKM    = 0x0b0b0b0b0b0b0b0b0b0b0b
+salt   = 0x000102030405060708090a0b0c
+info   = 0xf0f1f2f3f4f5f6f7f8f9
+L      = 42
+PRK    = 0x9b6c18c432a7bf8f0e71c8eb88f4b30baa2ba243
+OKM    = 0x085a01ea1b10f36933068b56efa5ad81a4f14b822f5b091568a9cdd4f155fda2c22e422478d305f3f896
+
+Test with SHA1 and longer inputs/outputs
+Hash   = SHA1
+IKM    = 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f
+salt   = 0x606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeaf
+info   = 0xb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff
+L      = 82
+PRK    = 0x8adae09a2a307059478d309b26c4115a224cfaf6
+OKM    = 0x0bd770a74d1160f7c9f12cd5912a06ebff6adcae899d92191fe4305673ba2ffe8fa3f1a4e5ad79f3f334b3b202b2173c486ea37ce3d397ed034c7f9dfeb15c5e927336d0441f4c4300e2cff0d0900b52d3b4
+
+Test with SHA1 and empty salt/info
+Hash   = SHA1
+IKM    = 0x0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b
+salt   =
+info   =
+L      = 42
+PRK    = 0xda8c8a73c7fa77288ec6f5e7c297786aa0d32d01
+OKM    = 0x0ac1af7002b3d761d1e55298da9d0506b9ae52057220a306e07b6b87e8df21d0ea00033de03984d34918

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: hkdf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- John Downey
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70196819801820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70196819801820
+description: ! 'A ruby implementation of RFC5869: HMAC-based Extract-and-Expand Key
+  Derivation Function (HKDF). The goal of HKDF is to take some source key material
+  and generate suitable cryptographic keys from it.'
+email:
+- jdowney@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/hkdf.rb
+- README.md
+- spec/hkdf_spec.rb
+- spec/spec_helper.rb
+- spec/test_vectors.txt
+homepage: http://github.com/jtdowney/hkdf
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: HMAC-based Key Derivation Function
+test_files:
+- spec/hkdf_spec.rb
+- spec/spec_helper.rb
+- spec/test_vectors.txt