Class: AEAD::Nonce

Inherits:
Object
  • Object
show all
Includes:
MonitorMixin
Defined in:
lib/aead/nonce.rb

Overview

Generates RFC 5114-compliant nonces.

Constant Summary collapse

COUNTER_OCTET_SIZE =

Number of octets in the counter field.

4
COUNTER_INITIAL_VALUE =

Initial value of the counter field (4 octets zeroed out)

'%08x' % 0
COUNTER_MAXIMUM_VALUE =

Maximum possible value of the counter before rolling over (4 octets all set to one).

'%08x' % (2 ** (COUNTER_OCTET_SIZE * 8) - 1)
COUNTER_BATCH_SIZE =

Number of nonces to reserve between state file updates. 256 is convenient in that it leads to pleasant state files and represents a reasonable medium between frequent file locks and wasted nonce values when the process terminates.

0xff
MAC_MULTICAST_MASK =

The LSB of the most-significant octet of the MAC is the multicast bit, and should be set on generated MAC addresses to distinguish them from real ones

0x010000000000
STATE_FILE =

The statefile is not configurable. All processes on a single machine must share the same state file.

Pathname.new('/var/tmp/ruby-aead').expand_path
PACK_FORMAT =

Packed format of the nonce state. As recommended by RFC 5116. From MSB to LSB: octets 1 - 8 : fixed (hardware id + random id) octets 9 - 12: counter

"H12 H4 H8"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Nonce

Initializes the nonce generator. Resumes the counter from disk if it has generated nonces before.



83
84
85
86
87
 
# File 'lib/aead/nonce.rb', line 83

def initialize
  self.state_file = STATE_FILE

  super # so the Monitor is initialized
end

Class Method Details

.generate ⇒ String

Generates an RFC 5114-compliant nonce suitable for use in AEAD encryption modes.

Returns:

  • (String) —

    a 12-byte nonce



72
73
74
75
 
# File 'lib/aead/nonce.rb', line 72

def self.generate
  @instance ||= self.new
  @instance.shift
end

.stub_for_testing!(file = Tempfile.new('ruby-aead')) ⇒ Object

Globally replaces the state file with a tempfile, so testing doesn't waste valuable nonces in the global state file.

Parameters:

  • file (String) (defaults to: Tempfile.new('ruby-aead')) —

    the tempfile to use



52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/aead/nonce.rb', line 52

def self.stub_for_testing!(file = Tempfile.new('ruby-aead'))
  define_method :state_file_with_stub_for_testing do
    path = file.respond_to?(:path) ? file.path : file.to_s
    path = Pathname.new(path)

    @state_file_stubbed_for_testing ||= Pathname.new(path)
  end

  alias_method :state_file_without_stub_for_testing, :state_file unless
    self.instance_methods.include?(:state_file_without_stub_for_testing)

  alias_method :state_file, :state_file_with_stub_for_testing
end

Instance Method Details

#shift(count = nil) ⇒ String+

Returns a nonce from the generator. If a count is passed, returns an array of nonces.

Parameters:

  • count (nil, Integer) (defaults to: nil) —

    the number of nonces to return

Returns:

  • (String, Array<String>) —

    a single nonce or array of nonces



96
97
98
99
100
101
102
103
 
# File 'lib/aead/nonce.rb', line 96

def shift(count = nil)
  # short-circuit with a single nonce if no argument
  return self.state.pack(PACK_FORMAT) if count.nil?

  count.times.map do
    self.state.pack(PACK_FORMAT)
  end
end