hkdf 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 32e2c102c323f4510551f669261ce3fe39c11dc3
-  data.tar.gz: f2585bdce88e509b0d7acf699b0313029fb767ab
+SHA256:
+  metadata.gz: b3981a10daf0d498be5d757d585f60d5b7ed39510da169fd57caaf05cfd19b55
+  data.tar.gz: 639210e0fa56a62d07483f2e67e8df7b20d35fb55f0ca55296509f1a029c906c
 SHA512:
-  metadata.gz: 303d49a8b562e90325cc90fe5bb1ce6294de07973d6f974f136c50bc9ae23e02cb09f36c725be7394e610bd4526beea9f61b9b5aee67fa7f370a0e553a4b1713
-  data.tar.gz: 1037d09b22dac87dea10a86a8ec1dea9f84390d43d5a9d5ace084e1d6c02a0e50ce57015a916dad6fe75f58683487cee911043168f63119c15da12ea17347685
+  metadata.gz: 62d0e251f2ecc9f713571a38388851a3781667c3de53f339061a7663fdb09f9a78705df12828151b5d252a59754cd401ab80dd95e36f96a255018f1721b4203d
+  data.tar.gz: 8be1132f9dc82666401d1034e509c3ce02aff76f63c0c033b716d50836d805747e90cc1358105176e0df9c9cbc2658aa6a23e1140d0c4c52ff11d9cc02f3a4d0

data/README.md

@@ -1,4 +1,6 @@
-# HKDF [![Build Status](https://secure.travis-ci.org/jtdowney/hkdf.png?branch=master)](http://travis-ci.org/jtdowney/hkdf)
+# HKDF
+
+[![CI](https://github.com/jtdowney/hkdf/actions/workflows/ci.yml/badge.svg)](https://github.com/jtdowney/hkdf/actions/workflows/ci.yml)
 
 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.
 
@@ -6,7 +8,7 @@ This is a ruby implementation of [RFC 5869](http://tools.ietf.org/html/rfc5869):
 
 ```ruby
 hkdf = HKDF.new('source key material')
-hkdf.next_bytes(32)
+hkdf.read(32)
  => "\f#\xF4b\x98\x9B\x7Fw>|/|k\xF4k\xB7\xB9\x11e\xC5\x92\xD1\fH\xFDG\x94vt\xB4\x14\xCE"
 ```
 
@@ -14,14 +16,18 @@ The default algorithm is HMAC-SHA256, you can override this and other defaults b
 
 ```ruby
 hkdf = HKDF.new('source key material', :salt => 'NaCl', :algorithm => 'SHA1', :info => 'the 411')
-hkdf.next_bytes(16)
+hkdf.read(16)
  => "\xC0<\x13\x85\x8C\x84z\xCE\xC7\xCE+\xFF\x1C\xEB\xE6\xBC"
 ```
 
-You can also give an IO object as the source. It will be read in as a stream to generate the key. The optional argument ```:read_size``` can be used to control how many bytes are read from the IO at a time.
+You can also give an IO object as the source. It will be read in as a stream to generate the key. The optional argument `:read_size` can be used to control how many bytes are read from the IO at a time.
 
 ```ruby
 hkdf = HKDF.new(File.new('/tmp/filename'), :read_size => 512)
-hkdf.next_bytes(32)
+hkdf.read(32)
  => "\f#\xF4b\x98\x9B\x7Fw>|/|k\xF4k\xB7\xB9\x11e\xC5\x92\xD1\fH\xFDG\x94vt\xB4\x14\xCE"
 ```
+
+## Requirements
+
+- Ruby >= 2.4

data/lib/hkdf.rb

@@ -1,74 +1,96 @@
-require 'openssl'
-require 'stringio'
+# frozen_string_literal: true
 
-class HKDF
-  DefaultAlgorithm = 'SHA256'
-  DefaultReadSize = 512 * 1024
+require "openssl"
+require "stringio"
 
+# Provide HMAC-based Extract-and-Expand Key Derivation Function (HKDF) for Ruby.
+class HKDF
+  # Default hash algorithm to use for HMAC.
+  DEFAULT_ALGOTIHM = "SHA256"
+  # Default buffer size for reading source IO.
+  DEFAULT_READ_SIZE = 512 * 1024
+
+  # Create a new HKDF instance with then provided +source+ key material.
+  #
+  # Options:
+  # - +algorithm:+ hash function to use (defaults to SHA-256)
+  # - +info:+ optional context and application specific information
+  # - +salt:+ optional salt value (a non-secret random value)
+  # - +read_size:+ buffer size when reading from a source IO
   def initialize(source, options = {})
     source = StringIO.new(source) if source.is_a?(String)
 
-    algorithm = options.fetch(:algorithm, DefaultAlgorithm)
+    algorithm = options.fetch(:algorithm, DEFAULT_ALGOTIHM)
     @digest = OpenSSL::Digest.new(algorithm)
-    @info = options.fetch(:info, '')
+    @info = options.fetch(:info, "")
 
     salt = options[:salt]
-    salt = 0.chr * @digest.digest_length if salt.nil? or salt.empty?
-    read_size = options.fetch(:read_size, DefaultReadSize)
+    salt = 0.chr * @digest.digest_length if salt.nil? || salt.empty?
+    read_size = options.fetch(:read_size, DEFAULT_READ_SIZE)
 
-    @prk = _generate_prk(salt, source, read_size)
+    @prk = generate_prk(salt, source, read_size)
     @position = 0
-    @blocks = []
-    @blocks << ''
+    @blocks = [""]
   end
 
+  # Returns the hash algorithm this instance was configured with.
   def algorithm
     @digest.name
   end
 
+  # Maximum length that can be derived per the RFC.
   def max_length
     @max_length ||= @digest.digest_length * 255
   end
 
+  # Adjust the reading position to an arbitrary offset. Will raise +RangeError+ if you attempt to seek longer than
+  # +#max_length+.
   def seek(position)
-    raise RangeError.new("cannot seek past #{max_length}") if position > max_length
+    raise RangeError, "cannot seek past #{max_length}" if position > max_length
 
     @position = position
   end
 
+  # Adjust reading position back to the beginning.
   def rewind
     seek(0)
   end
 
-  def next_bytes(length)
+  # Read the next +length+ bytes from the stream. Will raise +RangeError+ if you attempt to read beyond +#max_length+.
+  def read(length)
     new_position = length + @position
-    raise RangeError.new("requested #{length} bytes, only #{max_length} available") if new_position > max_length
+    raise RangeError, "requested #{length} bytes, only #{max_length} available" if new_position > max_length
 
-    _generate_blocks(new_position)
+    generate_blocks(new_position)
 
     start = @position
     @position = new_position
 
-    @blocks.join('').slice(start, length)
+    @blocks.join.slice(start, length)
   end
 
-  def next_hex_bytes(length)
-    next_bytes(length).unpack('H*').first
+  # Read the next +length+ bytes from the stream and return them hex encoded. Will raise +RangeError+ if you attempt to
+  # read beyond +#max_length+.
+  def read_hex(length)
+    read(length).unpack1("H*")
   end
 
+  # :nodoc:
   def inspect
     "#{to_s[0..-2]} algorithm=#{@digest.name.inspect} info=#{@info.inspect}>"
   end
 
-  def _generate_prk(salt, source, read_size)
+  private
+
+  def generate_prk(salt, source, read_size)
     hmac = OpenSSL::HMAC.new(salt, @digest)
-    while block = source.read(read_size)
+    while (block = source.read(read_size))
       hmac.update(block)
     end
     hmac.digest
   end
 
-  def _generate_blocks(length)
+  def generate_blocks(length)
     start = @blocks.size
     block_count = (length.to_f / @digest.digest_length).ceil
     start.upto(block_count) do |n|

data/lib/hkdf/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class HKDF
+  # :nodoc:
+  VERSION = "1.0.0"
+end

data/spec/hkdf_spec.rb

@@ -1,132 +1,139 @@
-require 'spec_helper'
+# frozen_string_literal: true
+
+require "spec_helper"
 
 describe HKDF do
-  let(:source) { 'source' }
   subject(:hkdf) do
-    HKDF.new(source)
+    described_class.new(source)
   end
 
-  describe 'initialize' do
-    it 'accepts an IO or a string as a source' do
-      output1 = HKDF.new(source).next_bytes(32)
-      output2 = HKDF.new(StringIO.new(source)).next_bytes(32)
+  let(:source) { "source" }
+
+  describe "initialize" do
+    it "accepts an IO or a string as a source" do
+      output1 = described_class.new(source).read(32)
+      output2 = described_class.new(StringIO.new(source)).read(32)
       expect(output1).to eq(output2)
     end
 
-    it 'reads in an IO at a given read size' do
-      io = StringIO.new(source)
-      expect(io).to receive(:read).with(1)
-
-      HKDF.new(io, :read_size => 1)
+    it "reads in an IO at a given read size" do
+      io = instance_spy(StringIO, :io, read: nil)
+      described_class.new(io, read_size: 1)
+      expect(io).to have_received(:read).with(1)
     end
 
-    it 'reads in the whole IO' do
-      hkdf1 = HKDF.new(source, :read_size => 1)
-      hkdf2 = HKDF.new(source)
+    it "reads in the whole IO" do
+      hkdf1 = described_class.new(source, read_size: 1)
+      hkdf2 = described_class.new(source)
 
-      expect(hkdf1.next_bytes(32)).to eq(hkdf2.next_bytes(32))
+      expect(hkdf1.read(32)).to eq(hkdf2.read(32))
     end
 
-    it 'defaults the algorithm to SHA-256' do
-      expect(HKDF.new(source).algorithm).to eq('SHA256')
+    it "defaults the algorithm to SHA-256" do
+      expect(described_class.new(source).algorithm).to eq("SHA256")
     end
 
-    it 'takes an optional digest algorithm' do
-      hkdf = HKDF.new('source', :algorithm => 'SHA1')
-      expect(hkdf.algorithm).to eq('SHA1')
+    it "takes an optional digest algorithm" do
+      hkdf = described_class.new("source", algorithm: "SHA1")
+      expect(hkdf.algorithm).to eq("SHA1")
     end
 
-    it 'defaults salt to all zeros of digest length' do
+    it "defaults salt to all zeros of digest length" do
       salt = 0.chr * 32
 
-      hkdf_salt = HKDF.new(source, :salt => salt)
-      hkdf_nosalt = HKDF.new(source)
-      expect(hkdf_salt.next_bytes(32)).to eq(hkdf_nosalt.next_bytes(32))
+      hkdf_salt = described_class.new(source, salt: salt)
+      hkdf_nosalt = described_class.new(source)
+      expect(hkdf_salt.read(32)).to eq(hkdf_nosalt.read(32))
     end
 
-    it 'sets salt to all zeros if empty' do
-      hkdf_blanksalt = HKDF.new(source, :salt => '')
-      hkdf_nosalt = HKDF.new(source)
-      expect(hkdf_blanksalt.next_bytes(32)).to eq(hkdf_nosalt.next_bytes(32))
+    it "sets salt to all zeros if empty" do
+      hkdf_blanksalt = described_class.new(source, salt: "")
+      hkdf_nosalt = described_class.new(source)
+      expect(hkdf_blanksalt.read(32)).to eq(hkdf_nosalt.read(32))
     end
 
-    it 'defaults info to an empty string' do
-      hkdf_info = HKDF.new(source, :info => '')
-      hkdf_noinfo = HKDF.new(source)
-      expect(hkdf_info.next_bytes(32)).to eq(hkdf_noinfo.next_bytes(32))
+    it "defaults info to an empty string" do
+      hkdf_info = described_class.new(source, info: "")
+      hkdf_noinfo = described_class.new(source)
+      expect(hkdf_info.read(32)).to eq(hkdf_noinfo.read(32))
     end
   end
 
-  describe 'max_length' do
-    it 'is 255 times the digest length' do
+  describe "max_length" do
+    it "is 255 times the digest length" do
       expect(hkdf.max_length).to eq(255 * 32)
     end
   end
 
-  describe 'next_bytes' do
-    it 'raises an error if requested size is > max_length' do
+  describe "read" do
+    it "does not raise if reading <= max_length" do
       expect do
-        hkdf.next_bytes(hkdf.max_length + 1)
-      end.to raise_error(RangeError, /requested \d+ bytes, only \d+ available/)
+        hkdf.read(hkdf.max_length)
+      end.not_to raise_error
+    end
 
+    it "raises an error if requested size is > max_length" do
       expect do
-        hkdf.next_bytes(hkdf.max_length)
-      end.to_not raise_error
+        hkdf.read(hkdf.max_length + 1)
+      end.to raise_error(RangeError, /requested \d+ bytes, only \d+ available/)
     end
 
-    it 'raises an error if requested size + current position is > max_length' do
+    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)
+        hkdf.read(32)
+        hkdf.read(hkdf.max_length - 31)
       end.to raise_error(RangeError, /requested \d+ bytes, only \d+ available/)
     end
 
-    it 'advances the stream position' do
-      expect(hkdf.next_bytes(32)).not_to eq(hkdf.next_bytes(32))
+    it "advances the stream position" do
+      expect(hkdf.read(32)).not_to eq(hkdf.read(32))
     end
 
-    test_vectors.each do |name, options|
+    TestVectors.vectors.each do |name, options|
       it "matches output from the '#{name}' test vector" do
         options[:algorithm] = options[:Hash]
 
-        hkdf = HKDF.new(options[:IKM], options)
-        expect(hkdf.next_bytes(options[:L].to_i)).to eq(options[:OKM])
+        hkdf = described_class.new(options[:IKM], options)
+        expect(hkdf.read(options[:L].to_i)).to eq(options[:OKM])
       end
     end
   end
 
-  describe 'next_hex_bytes' do
-    it 'returns the next bytes as hex' do
-      expect(hkdf.next_hex_bytes(20)).to eq('fb496612b8cb82cd2297770f83c72b377af16d7b')
+  describe "read_hex" do
+    it "returns the next bytes as hex" do
+      expect(hkdf.read_hex(20)).to eq("fb496612b8cb82cd2297770f83c72b377af16d7b")
     end
   end
 
-  describe 'seek' do
-    it 'sets the position anywhere in the stream' do
-      hkdf.next_bytes(10)
-      output = hkdf.next_bytes(32)
+  describe "seek" do
+    it "sets the position anywhere in the stream" do
+      hkdf.read(10)
+      output = hkdf.read(32)
       hkdf.seek(10)
-      expect(hkdf.next_bytes(32)).to eq(output)
+      expect(hkdf.read(32)).to eq(output)
+    end
+
+    it "does not raise if <= max_length" do
+      expect { hkdf.seek(hkdf.max_length) }.not_to raise_error
     end
 
-    it 'raises an error if requested to seek past end of stream' do
+    it "raises an error if requested to seek past end of stream" do
       expect { hkdf.seek(hkdf.max_length + 1) }.to raise_error(RangeError, /cannot seek past \d+/)
-      expect { hkdf.seek(hkdf.max_length) }.to_not raise_error
     end
   end
 
-  describe 'rewind' do
-    it 'resets the stream position to the beginning' do
-      output = hkdf.next_bytes(32)
+  describe "rewind" do
+    it "resets the stream position to the beginning" do
+      output = hkdf.read(32)
       hkdf.rewind
-      expect(hkdf.next_bytes(32)).to eq(output)
+      expect(hkdf.read(32)).to eq(output)
     end
   end
 
-  describe 'inspect' do
-    it 'returns minimal information' do
-      hkdf = HKDF.new('secret', info: 'public')
-      expect(hkdf.inspect).to match(/^#<HKDF:0x[\h]+ algorithm="SHA256" info="public">$/)
+  describe "inspect" do
+    it "returns minimal information" do
+      hkdf = described_class.new("secret", info: "public")
+      expect(hkdf.inspect).to match(/^#<HKDF:0x[0-9a-f]+ algorithm="SHA256" info="public">$/)
     end
   end
 end

data/spec/spec_helper.rb

@@ -1,23 +1,8 @@
-require 'hkdf'
+# frozen_string_literal: true
 
-RSpec.configure do |config|
-  config.order = 'random'
-end
+require "hkdf"
+require_relative "support/test_vectors"
 
-def test_vectors
-  test_parts = File.readlines('spec/fixtures/test_vectors.txt').
-    map(&:strip).
-    reject(&:empty?).
-    each_slice(8)
-
-  test_parts.reduce({}) do |vectors, lines|
-    name = lines.shift
-    values = lines.reduce({}) 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.merge(key.to_sym => value)
-    end
-    vectors.merge(name => values)
-  end
+RSpec.configure do |config|
+  config.order = "random"
 end

data/spec/support/test_vectors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module TestVectors
+  module_function
+
+  # :nodoc:
+  def vectors
+    test_parts = File.readlines("spec/fixtures/test_vectors.txt")
+                     .map(&:strip)
+                     .reject(&:empty?)
+                     .each_slice(8)
+
+    test_parts.reduce({}) do |vectors, lines|
+      name = lines.shift
+      values = split_test_vector(lines)
+      vectors.merge(name => values)
+    end
+  end
+
+  # :nodoc:
+  def split_test_vector(lines)
+    lines.reduce({}) do |hash, line|
+      key, value = line.split("=").map(&:strip)
+      value ||= ""
+      value = [value.slice(2..-1)].pack("H*") if value.start_with?("0x")
+      hash.merge(key.to_sym => value)
+    end
+  end
+end

metadata

@@ -1,60 +1,88 @@
 --- !ruby/object:Gem::Specification
 name: hkdf
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - John Downey
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-11-09 00:00:00.000000000 Z
+date: 2021-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 10.5.0
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 10.5.0
+        version: '3.9'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.4.0
+        version: '1.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.4.0
-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.'
+        version: 0.5.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+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: []
@@ -64,14 +92,16 @@ files:
 - LICENSE
 - README.md
 - lib/hkdf.rb
+- lib/hkdf/version.rb
 - spec/fixtures/test_vectors.txt
 - spec/hkdf_spec.rb
 - spec/spec_helper.rb
+- spec/support/test_vectors.rb
 homepage: http://github.com/jtdowney/hkdf
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -79,19 +109,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
 summary: HMAC-based Key Derivation Function
 test_files:
 - spec/fixtures/test_vectors.txt
 - spec/hkdf_spec.rb
 - spec/spec_helper.rb
+- spec/support/test_vectors.rb