Class: SymmetricEncryption::Reader

Inherits:
Object
  • Object
show all
Defined in:
lib/symmetric_encryption/reader.rb

Overview

Read from encrypted files and other IO streams

Features:

  • Decryption on the fly whilst reading files

  • Large file support by only buffering small amounts of data in memory

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ios, options = {}) ⇒ Reader

Decrypt data before reading from the supplied stream



112
113
114
115
116
117
118
119
120
121
 
# File 'lib/symmetric_encryption/reader.rb', line 112

def initialize(ios,options={})
  @ios            = ios
  @buffer_size    = options.fetch(:buffer_size, 4096).to_i
  @version        = options[:version]
  @header_present = false

  raise "Buffer size cannot be smaller than 128" unless @buffer_size >= 128

  read_header
end

Class Method Details

.empty?(filename_or_stream) ⇒ Boolean

Returns [true|false] whether the file or stream contains any data excluding the header should it have one

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/symmetric_encryption/reader.rb', line 96

def self.empty?(filename_or_stream)
  open(filename_or_stream) {|file| file.eof? }
end

.header_present?(filename) ⇒ Boolean

Returns [true|false] whether the file contains the encryption header

Returns:

  • (Boolean) 


101
102
103
 
# File 'lib/symmetric_encryption/reader.rb', line 101

def self.header_present?(filename)
  ::File.open(filename, 'rb') {|file| new(file).header_present?}
end

.open(filename_or_stream, options = {}, &block) ⇒ Object

Open a file for reading, or use the supplied IO Stream

Parameters:

filename_or_stream:
  The filename to open if a string, otherwise the stream to use
  The file or stream will be closed on completion, use .initialize to
  avoid having the stream closed automatically

options:
  :mode
       See File.open for open modes
       Default: 'rb'

  :buffer_size
       Amount of data to read at a time
       Minimum Value 128
       Default: 4096

The following options are only used if the stream/file has no header
  :compress [true|false]
       Uses Zlib to decompress the data after it is decrypted
       Note: This option is only used if the file does not have a header
             indicating whether it is compressed
       Default: false

  :version
       Version of the encryption key to use when decrypting and the
       file/stream does not include a header at the beginning
       Default: Current primary key

Note: Decryption occurs before decompression

# Example: Read and decrypt a line at a time from a file SymmetricEncryption::Reader.open(‘test_file’) do |file|

file.each_line {|line| p line }

end

# Example: Read and decrypt entire file in memory # Not recommended for large files SymmetricEncryption::Reader.open(‘test_file’) {|f| f.read }

# Example: Reading a limited number of bytes at a time from the file SymmetricEncryption::Reader.open(‘test_file’) do |file|

file.read(1)
file.read(5)
file.read

end

# Example: Read and decrypt 5 bytes at a time until the end of file is reached SymmetricEncryption::Reader.open(‘test_file’) do |file|

while !file.eof? do
  file.read(5)
end

end

# Example: Read, Unencrypt and decompress data in a file SymmetricEncryption::Reader.open(‘encrypted_compressed.zip’, :compress => true) do |file|

file.each_line {|line| p line }

end

# Example: Reading from a CSV file

require ‘fastercsv’ begin

csv = FasterCSV.new(SymmetricEncryption::Reader.open('csv_encrypted'))
csv.each {|row| p row}

ensure

csv.close if csv

end



79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/symmetric_encryption/reader.rb', line 79

def self.open(filename_or_stream, options={}, &block)
  raise "options must be a hash" unless options.respond_to?(:each_pair)
  mode     = options.fetch(:mode, 'rb')
  compress = options.fetch(:compress, false)
  ios      = filename_or_stream.is_a?(String) ? ::File.open(filename_or_stream, mode) : filename_or_stream

  begin
    file = self.new(ios, options)
    file = Zlib::GzipReader.new(file) if !file.eof? && (file.compressed? || compress)
    block ? block.call(file) : file
  ensure
    file.close if block && file
  end
end

Instance Method Details

#close(close_child_stream = true) ⇒ Object

Close the IO Stream

Note: Also closes the passed in io stream or file

It is recommended to call Symmetric::EncryptedStream.open or Symmetric::EncryptedStream.io rather than creating an instance of Symmetric::EncryptedStream directly to ensure that the encrypted stream is closed before the stream itself is closed



155
156
157
 
# File 'lib/symmetric_encryption/reader.rb', line 155

def close(close_child_stream = true)
  @ios.close if close_child_stream
end

#compressed? ⇒ Boolean

Returns whether the stream being read is compressed

Should be called before any reads are performed to determine if the file or stream is compressed.

Returns true when the header is present in the stream and it is compressed Returns false when the header is present in the stream and it is not compressed Returns nil when the header is not present in the stream

Note: The file will not be decompressed automatically when compressed.

To decompress the data automatically call SymmetricEncryption.open

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/symmetric_encryption/reader.rb', line 134

def compressed?
  @compressed
end

#each_line(sep_string = "\n") ⇒ Object Also known as: each

ios.each(sep_string=“n”) {|line| block } => ios ios.each_line(sep_string=“n”) {|line| block } => ios Executes the block for every line in ios, where lines are separated by sep_string. ios must be opened for reading or an IOError will be raised.



240
241
242
243
244
245
 
# File 'lib/symmetric_encryption/reader.rb', line 240

def each_line(sep_string = "\n")
  while !eof?
    yield gets(sep_string)
  end
  self
end

#eof? ⇒ Boolean

Returns whether the end of file has been reached for this stream

Returns:

  • (Boolean) 


250
251
252
 
# File 'lib/symmetric_encryption/reader.rb', line 250

def eof?
  (@read_buffer.size == 0) && @ios.eof?
end

#flush ⇒ Object

Flush the read stream

Needed by XLS gem



161
162
163
 
# File 'lib/symmetric_encryption/reader.rb', line 161

def flush
  @ios.flush
end

#gets(sep_string, length = nil) ⇒ Object

Reads a single decrypted line from the file up to and including the optional sep_string. A sep_string of nil reads the entire contents of the file Returns nil on eof The stream must be opened for reading or an IOError will be raised.



221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/symmetric_encryption/reader.rb', line 221

def gets(sep_string,length=nil)
  return read(length) if sep_string.nil?

  # Read more data until we get the sep_string
  while (index = @read_buffer.index(sep_string)).nil? && !@ios.eof?
    break if length && @read_buffer.length >= length
    read_block
  end
  index ||= -1
  data = @read_buffer.slice!(0..index)
  @pos += data.length
  return nil if data.length == 0 && eof?
  data
end

#header_present? ⇒ Boolean

After opening a file Returns [true|false] whether the file being read has an encryption header

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/symmetric_encryption/reader.rb', line 107

def header_present?
  @header_present
end

#pos ⇒ Object

Return the number of bytes read so far from the input stream



255
256
257
 
# File 'lib/symmetric_encryption/reader.rb', line 255

def pos
  @pos
end

#read(length = nil) ⇒ Object

Read from the stream and return the decrypted data See IOS#read

Reads at most length bytes from the I/O stream, or to the end of file if length is omitted or is nil. length must be a non-negative integer or nil.

At end of file, it returns nil if no more data is available, or the last remaining bytes



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/symmetric_encryption/reader.rb', line 179

def read(length=nil)
  data = nil
  if length
    return '' if length == 0
    return nil if @ios.eof? && (@read_buffer.length == 0)
    # Read length bytes
    while (@read_buffer.length < length) && !@ios.eof?
      read_block
    end
    if @read_buffer.length > length
      data = @read_buffer.slice!(0..length-1)
    else
      data = @read_buffer
      @read_buffer = ''
    end
  else
    # Capture anything already in the buffer
    data = @read_buffer
    @read_buffer = ''

    if !@ios.eof?
      # Read entire file
      buf = @ios.read || ''
      data << @stream_cipher.update(buf) if buf && buf.length > 0
      data << @stream_cipher.final
    end
  end
  @pos += data.length
  data
end

#readline(sep_string = "\n") ⇒ Object

Reads a single decrypted line from the file up to and including the optional sep_string. Raises EOFError on eof The stream must be opened for reading or an IOError will be raised.



213
214
215
 
# File 'lib/symmetric_encryption/reader.rb', line 213

def readline(sep_string = "\n")
  gets(sep_string) || raise(EOFError.new("End of file reached when trying to read a line"))
end

#rewind ⇒ Object

Rewind back to the beginning of the file



260
261
262
263
264
 
# File 'lib/symmetric_encryption/reader.rb', line 260

def rewind
  @read_buffer = ''
  @ios.rewind
  read_header
end

#seek(amount, whence = IO::SEEK_SET) ⇒ Object

Seeks to a given offset (Integer) in the stream according to the value of whence:

IO::SEEK_CUR  | Seeks to _amount_ plus current position
--------------+----------------------------------------------------
IO::SEEK_END  | Seeks to _amount_ plus end of stream (you probably
              | want a negative value for _amount_)
--------------+----------------------------------------------------
IO::SEEK_SET  | Seeks to the absolute location given by _amount_

WARNING: IO::SEEK_SET will jump to the beginning of the file and

then re-read upto the point specified

WARNING: IO::SEEK_END will read the entire file and then again

upto the point specified



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/symmetric_encryption/reader.rb', line 278

def seek(amount, whence=IO::SEEK_SET)
  offset = 0
  case whence
  when IO::SEEK_SET
    offset = amount
    rewind
  when IO::SEEK_CUR
    if amount >= 0
      offset = amount
    else
      offset = @pos + amount
      rewind
    end
  when IO::SEEK_END
    rewind
    # Read and decrypt entire file a block at a time to get its total
    # unencrypted size
    size = 0
    while !eof
      read_block
      size += @read_buffer.size
      @read_buffer = ''
    end
    rewind
    offset = size + amount
  else
    raise "unknown whence:#{whence} supplied to seek()"
  end
  read(offset) if offset > 0
  0
end

#size ⇒ Object

Return the size of the file rounded up to the nearest encryption block size

Needed by XLS gem



167
168
169
 
# File 'lib/symmetric_encryption/reader.rb', line 167

def size
  @ios.size
end

#version ⇒ Object

Returns the Cipher encryption version used to encrypt this file Returns nil when the header was not present in the stream and no :version

option was supplied

Note: When no header is present, the version is set to the one supplied

in the options



144
145
146
 
# File 'lib/symmetric_encryption/reader.rb', line 144

def version
  @version
end