Module: OpenSSL::Buffering

Includes:
Enumerable
Included in:
SSL::SSLSocket
Defined in:
lib/openssl/buffering.rb

Overview

OpenSSL IO buffering mix-in module.

This module allows an OpenSSL::SSL::SSLSocket to behave like an IO.

You typically won’t use this module directly, you can see it implemented in OpenSSL::SSL::SSLSocket.

Defined Under Namespace

Classes: Buffer

Constant Summary collapse

BLOCK_SIZE =

Default size to read from or write to the SSLSocket for buffer operations.

1024*16

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#sync ⇒ Object

The “sync mode” of the SSLSocket.

See IO#sync for full details.



53
54
55
 
# File 'lib/openssl/buffering.rb', line 53

def sync
  @sync
end

Instance Method Details

#<<(s) ⇒ Object

Writes s to the stream. s will be converted to a String using .to_s method.



414
415
416
417
 
# File 'lib/openssl/buffering.rb', line 414

def <<(s)
  do_write(s)
  self
end

#close ⇒ Object

Closes the SSLSocket and flushes any unwritten data.



476
477
478
479
 
# File 'lib/openssl/buffering.rb', line 476

def close
  flush rescue nil
  sysclose
end

#each(eol = $/) ⇒ Object Also known as: each_line

Executes the block for every line in the stream where lines are separated by eol.

See also #gets



252
253
254
255
256
 
# File 'lib/openssl/buffering.rb', line 252

def each(eol=$/)
  while line = self.gets(eol)
    yield line
  end
end

#each_byte ⇒ Object

Calls the given block once for each byte in the stream.



293
294
295
296
297
 
# File 'lib/openssl/buffering.rb', line 293

def each_byte # :yields: byte
  while c = getc
    yield(c.ord)
  end
end

#eof? ⇒ Boolean Also known as: eof

Returns true if the stream is at file which means there is no more data to be read.

Returns:

  • (Boolean) 


324
325
326
327
 
# File 'lib/openssl/buffering.rb', line 324

def eof?
  fill_rbuff if !@eof && @rbuffer.empty?
  @eof && @rbuffer.empty?
end

#flush ⇒ Object

Flushes buffered data to the SSLSocket.



464
465
466
467
468
469
470
471
 
# File 'lib/openssl/buffering.rb', line 464

def flush
  osync = @sync
  @sync = true
  do_write ""
  return self
ensure
  @sync = osync
end

#getbyte ⇒ Object

call-seq:

ssl.getbyte => 81

Get the next 8bit byte from ‘ssl`. Returns `nil` on EOF



106
107
108
 
# File 'lib/openssl/buffering.rb', line 106

def getbyte
  read(1)&.ord
end

#getc ⇒ Object

Reads one character from the stream. Returns nil if called at end of file.



286
287
288
 
# File 'lib/openssl/buffering.rb', line 286

def getc
  read(1)
end

#gets(eol = $/, limit = nil) ⇒ Object

Reads the next “line” from the stream. Lines are separated by eol. If limit is provided the result will not be longer than the given number of bytes.

eol may be a String or Regexp.

Unlike IO#gets the line read will not be assigned to $_.

Unlike IO#gets the separator must be provided if a limit is provided.



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/openssl/buffering.rb', line 228

def gets(eol=$/, limit=nil)
  idx = @rbuffer.index(eol)
  until @eof
    break if idx
    fill_rbuff
    idx = @rbuffer.index(eol)
  end
  if eol.is_a?(Regexp)
    size = idx ? idx+$&.size : nil
  else
    size = idx ? idx+eol.size : nil
  end
  if size && limit && limit >= 0
    size = [size, limit].min
  end
  consume_rbuff(size)
end

#initialize ⇒ Object

Creates an instance of OpenSSL’s buffering IO module.



63
64
65
66
67
68
 
# File 'lib/openssl/buffering.rb', line 63

def initialize(*)
  # super
  @eof = false
  @rbuffer = Buffer.new
  @sync = @io.sync
end

#print(*args) ⇒ Object

Writes args to the stream.

See IO#print for full details.



443
444
445
446
447
448
 
# File 'lib/openssl/buffering.rb', line 443

def print(*args)
  s = Buffer.new
  args.each{ |arg| s << arg.to_s }
  do_write(s)
  nil
end

#printf(s, *args) ⇒ Object

Formats and writes to the stream converting parameters under control of the format string.

See Kernel#sprintf for format string details.



456
457
458
459
 
# File 'lib/openssl/buffering.rb', line 456

def printf(s, *args)
  do_write(s % args)
  nil
end

#puts(*args) ⇒ Object

Writes args to the stream along with a record separator.

See IO#puts for full details.



424
425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/openssl/buffering.rb', line 424

def puts(*args)
  s = Buffer.new
  if args.empty?
    s << "\n"
  else
    args.each do |arg|
      s << arg.to_s
      s.sub!(/(?<!\n)\z/, "\n")
    end
  end
  do_write(s)
  nil
end

#read(size = nil, buf = nil) ⇒ Object

Reads size bytes from the stream. If buf is provided it must reference a string which will receive the data.

See IO#read for full details.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/openssl/buffering.rb', line 116

def read(size=nil, buf=nil)
  if size == 0
    if buf
      buf.clear
      return buf
    else
      return ""
    end
  end
  until @eof
    break if size && size <= @rbuffer.size
    fill_rbuff
  end
  ret = consume_rbuff(size) || ""
  if buf
    buf.replace(ret)
    ret = buf
  end
  (size && ret.empty?) ? nil : ret
end

#read_nonblock(maxlen, buf = nil, exception: true) ⇒ Object

Reads at most maxlen bytes in the non-blocking manner.

When no data can be read without blocking it raises OpenSSL::SSL::SSLError extended by IO::WaitReadable or IO::WaitWritable.

IO::WaitReadable means SSL needs to read internally so read_nonblock should be called again when the underlying IO is readable.

IO::WaitWritable means SSL needs to write internally so read_nonblock should be called again after the underlying IO is writable.

OpenSSL::Buffering#read_nonblock needs two rescue clause as follows:

# emulates blocking read (readpartial).
begin
  result = ssl.read_nonblock(maxlen)
rescue IO::WaitReadable
  IO.select([io])
  retry
rescue IO::WaitWritable
  IO.select(nil, [io])
  retry
end

Note that one reason that read_nonblock writes to the underlying IO is when the peer requests a new TLS/SSL handshake. See openssl the FAQ for more details. www.openssl.org/support/faq.html

By specifying a keyword argument exception to false, you can indicate that read_nonblock should not raise an IO::Wait*able exception, but return the symbol :wait_writable or :wait_readable instead. At EOF, it will return nil instead of raising EOFError.



189
190
191
192
193
194
195
 
# File 'lib/openssl/buffering.rb', line 189

def read_nonblock(maxlen, buf=nil, exception: true)
  # JRuby: sysread does `maxlen == 0` short-circuit check internally
  if @rbuffer.empty?
    return sysread_nonblock(maxlen, buf, exception: exception)
  end
  do_consume_rbuff(maxlen, buf)
end

#readchar ⇒ Object

Reads a one-character string from the stream. Raises an EOFError at end of file.

Raises:

  • (EOFError) 


303
304
305
306
 
# File 'lib/openssl/buffering.rb', line 303

def readchar
  raise EOFError if eof?
  getc
end

#readline(eol = $/) ⇒ Object

Reads a line from the stream which is separated by eol.

Raises EOFError if at end of file.

Raises:

  • (EOFError) 


277
278
279
280
 
# File 'lib/openssl/buffering.rb', line 277

def readline(eol=$/)
  raise EOFError if eof?
  gets(eol)
end

#readlines(eol = $/) ⇒ Object

Reads lines from the stream which are separated by eol.

See also #gets



264
265
266
267
268
269
270
 
# File 'lib/openssl/buffering.rb', line 264

def readlines(eol=$/)
  ary = []
  while line = self.gets(eol)
    ary << line
  end
  ary
end

#readpartial(maxlen, buf = nil) ⇒ Object

Reads at most maxlen bytes from the stream. If buf is provided it must reference a string which will receive the data.

See IO#readpartial for full details.



143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/openssl/buffering.rb', line 143

def readpartial(maxlen, buf=nil)
  # JRuby: sysread does `maxlen == 0` short-circuit check internally
  if @rbuffer.empty?
    begin
      return sysread(maxlen, buf)
    rescue Errno::EAGAIN
      retry
    end
  end
  do_consume_rbuff(maxlen, buf)
end

#ungetc(c) ⇒ Object

Pushes character c back onto the stream such that a subsequent buffered character read will return it.

Unlike IO#getc multiple bytes may be pushed back onto the stream.

Has no effect on unbuffered reads (such as #sysread).



316
317
318
 
# File 'lib/openssl/buffering.rb', line 316

def ungetc(c)
  @rbuffer[0,0] = c.chr
end

#write(*s) ⇒ Object

Writes s to the stream. If the argument is not a String it will be converted using .to_s method. Returns the number of bytes written.



361
362
363
364
365
366
 
# File 'lib/openssl/buffering.rb', line 361

def write(*s)
  s.inject(0) do |written, str|
    do_write(str)
    written + str.bytesize
  end
end

#write_nonblock(s, exception: true) ⇒ Object

Writes s in the non-blocking manner.

If there is buffered data, it is flushed first. This may block.

write_nonblock returns number of bytes written to the SSL connection.

When no data can be written without blocking it raises OpenSSL::SSL::SSLError extended by IO::WaitReadable or IO::WaitWritable.

IO::WaitReadable means SSL needs to read internally so write_nonblock should be called again after the underlying IO is readable.

IO::WaitWritable means SSL needs to write internally so write_nonblock should be called again after underlying IO is writable.

So OpenSSL::Buffering#write_nonblock needs two rescue clause as follows.

# emulates blocking write.
begin
  result = ssl.write_nonblock(str)
rescue IO::WaitReadable
  IO.select([io])
  retry
rescue IO::WaitWritable
  IO.select(nil, [io])
  retry
end

Note that one reason that write_nonblock reads from the underlying IO is when the peer requests a new TLS/SSL handshake. See the openssl FAQ for more details. www.openssl.org/support/faq.html

By specifying a keyword argument exception to false, you can indicate that write_nonblock should not raise an IO::Wait*able exception, but return the symbol :wait_writable or :wait_readable instead.



405
406
407
408
 
# File 'lib/openssl/buffering.rb', line 405

def write_nonblock(s, exception: true)
  flush
  syswrite_nonblock(s, exception: exception)
end