Class: Confium::SecureBytes

Inherits:
Object
  • Object
show all
Defined in:
lib/confium/secure_bytes.rb

Defined Under Namespace

Classes: ClearedError

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(raw) ⇒ SecureBytes

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of SecureBytes.



36
37
38
39
40
41
42
 
# File 'lib/confium/secure_bytes.rb', line 36

def initialize(raw)
  @buffer = raw.dup.force_encoding(Encoding::ASCII_8BIT)
  @cleared = false
  # Register finalizer to zeroize if the object is GC'd without
  # an explicit #clear call.
  ObjectSpace.define_finalizer(self, finalizer_proc)
end

Class Method Details

.wrap(raw) ⇒ Confium::SecureBytes

Create a SecureBytes wrapping a copy of the given String. The original String's contents are NOT modified; callers should zeroize the original separately if needed.

Parameters:

  • raw (String) —

    binary String (any encoding; bytes are copied)

Returns:



31
32
33
 
# File 'lib/confium/secure_bytes.rb', line 31

def self.wrap(raw)
  new(raw)
end

Instance Method Details

#bytes ⇒ String

Non-destructive read of the wrapped bytes.

Returns:

  • (String) —

    binary String (ASCII-8BIT encoding)

Raises:



47
48
49
50
51
 
# File 'lib/confium/secure_bytes.rb', line 47

def bytes
  raise ClearedError if @cleared

  @buffer.dup
end

#bytes! ⇒ String

Destructive read: returns a copy, then zeroizes the original.

Returns:

  • (String) —

    binary String

Raises:



56
57
58
59
60
61
62
 
# File 'lib/confium/secure_bytes.rb', line 56

def bytes!
  raise ClearedError if @cleared

  copy = @buffer.dup
  clear
  copy
end

#clear ⇒ self

Zeroize the buffer immediately. Idempotent.

Returns:

  • (self) 


80
81
82
83
84
85
86
87
88
 
# File 'lib/confium/secure_bytes.rb', line 80

def clear
  return self if @cleared

  # Overwrite every byte with 0x00 in place.
  @buffer.replace("\x00" * @buffer.bytesize)
  @buffer = nil
  @cleared = true
  self
end

#cleared? ⇒ Boolean

Whether the buffer has been cleared.

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/confium/secure_bytes.rb', line 74

def cleared?
  @cleared
end

#inspect ⇒ String

String representation for debugging. Does NOT expose the raw bytes.

Returns:

  • (String) 


92
93
94
95
96
97
98
 
# File 'lib/confium/secure_bytes.rb', line 92

def inspect
  if @cleared
    "#<Confium::SecureBytes:0x#{object_id.to_s(16)} CLEARED>"
  else
    "#<Confium::SecureBytes:0x#{object_id.to_s(16)} #{length} bytes>"
  end
end

#length ⇒ Integer Also known as: size

Number of bytes. Returns 0 after #clear.

Returns:

  • (Integer) 


66
67
68
 
# File 'lib/confium/secure_bytes.rb', line 66

def length
  @cleared ? 0 : @buffer.bytesize
end