I/O Abstraction

Module Implementation: OpenSSLCryptoInterfaceBIO

This module exposes OpenSSL's I/O Abstraction concept called BIOs. BIOs come in two flavors, source/sinks and filters. Source/Sinks can be the source or destination of data, such as files or sockets. Filters generally perform some action as data passes through them such as a buffer bio. BIOs can be joined together to form pipelines.

Note: Internal classes are italicized and will only contain a short description.

See the class-side examples in the OpenSSLBIOExamples class for additional usage detail.

BIO

OpenSSLBioChain: Internal Class that tracks BIOs chained together. This is primarily used for memory management.

OpenSSLBioChainRef: Internal Class that tracks BIOs chained together. This is primarily used for memory management.

OSSslBIOMethod: Internal Class that is used as a descriptor for the various BIO flavors.

OSSslBIO

This is the abstract superclass of all I/O Abstraction objects. The class side has factory methods for all bio types. Most of the logic in how BIOs work with data is implemented on the instance side.

Class methods: Factory

newBase64BIO

Convenience Method for creating Base64 BIOs to encode/decode base64 data.

Answers:

<OSSslBase64BIO>

 

newBufferBIO

Convenience Method for creating buffer BIOs with default buffer size (4096)

Answers:

< OSSslBufferBIO>

 

newBufferBIO: bufferSize

Convenience Method for creating buffer BIOs with specified bufferSize in bytes.

Answers:

< OSSslBufferBIO>

 

newFileBIO: filename mode: mode

Convenience Method for creating file BIOs.

Answers:

< OSSslFileBIO>

 

newMemoryBIO

Convenience Method for creating memory BIOs.

Answers:

< OSSslMemoryBIO>

 

newMemoryBIO: aByteObject

Convenience Method for creating memory BIOs initialized with data

Answers:

< OSSslMemoryBIO>

 

newNullBIO

Convenience Method for creating a Null BIOs

Answers:

<OSSslNullBIO>

 

newStaticMemoryBIO: aByteObject

Convenience Method for creating static memory BIOs.

Static memory BIOs use buffer data that we supply rather than making copies. It allows for efficiencies for many APIs since copies are not needed.

Answers:

< OSSslStaticMemoryBIO>

 

newStaticMemoryBIO: aByteObject length: length

Convenience Method for creating static memory BIOs.

Static memory BIOs use buffer data that we supply rather than making copies. It allows for efficiencies for many APIs since copies are not needed.

Answers:

< OSSslStaticMemoryBIO>

 

Instance methods: API

closeOnFree: aBoolean

Answer true if the underlying IO should be closed when this bio is freed. This may have no impact depending on the bio type.

Answers:

<Boolean> - aBoolean

 

eof

Answers true if the eof indicator is set, false otherwise.

Answers:

<Boolean> - true if at eof, false otherwise

 

flush

Flushes any buffered output.

Answers:

<Boolean> true for success, false otherwise

 

gets: anInteger

Performs the BIOs 'gets' operation and places the data in the ByteArray buffer.

Usually this operation will attempt to read a line of data from the BIO of maximum length len. There are exceptions to this however, for example BIO_gets() on a digest BIO will calculate and return the digest and other BIOs may not support BIO_gets() at all.

Arguments:

anInteger - <Integer> number of bytes to get

Answers:

<String> - buffer result

 

gets: anInteger into: aByteObject

Performs the BIOs 'gets' operation and places the data into aByteObject

Usually this operation will attempt to read a line of data from the BIO of maximum length len. There are exceptions to this however, for example BIO_gets() on a digest BIO will calculate and return the digest and other BIOs may not support BIO_gets() at all.

Arguments:

anInteger - <Integer> number of bytes to get

aByteObject - Smalltalk byte objects (ByteArray | EsString)

Answers:

<String> - buffer result

 

gets: anInteger into: bytes length: length

Performs the BIOs 'gets' operation and places the data into bytes with length.

Usually this operation will attempt to read a line of data from the BIO of maximum length len. There are exceptions to this however, for example BIO_gets() on a digest BIO will calculate and return the digest and other BIOs may not support BIO_gets() at all.

Arguments:

anInteger - <Integer> number of bytes to get

bytes - Smalltalk byte objects (ByteArray | EsString)

length - length of bytes

Answers:

< Integer > - number of bytes actually got

 

isFilter

Answer true if this BIO is a source/sink, false otherwise. All BIOs are classified as either source/sink or filters. Subclasses are required to define this classification

Answers:

<Boolean>

 

isSourceSink

Answer true if this BIO is a source/sink, false otherwise. All BIOs are classified as either source/sink or filters.

Answers:

<Boolean>

 

numberPendingRead

Answer the number of pending characters in the BIOs read buffer. Not all BIOs support these calls.

Answers:

< Integer> - bytes remaining to be read

 

numberPendingWrite

Answer the number of pending characters in the BIOs write buffer. Not all BIOs support these calls.

Answers:

< Integer> - bytes remaining to be written

 

numberRead

Answer the number of bytes read from the BIO

Answers:

< Integer> - bytes read

 

numberWritten

Answer the number of bytes written to the BIO.

Answers:

< Integer> - bytes written

 

puts: aByteObject

Attempts to write a collection of bytes to the BIO. This method internally null-terminates aByteObject aByteObject must understand #asPSZ.

Arguments:

aByteObject - a byte object (i.e. ByteArray | EsString | OSStringZ)

Answers:

<Integer> - Number of bytes actually written

<OpenSSLError compatible error> - error object

 

read: anInteger

Attempts to read an @anInteger number of bytes into a new ByteArray.

Answers:

<ByteArray> - resulting bytes object

<OpenSSLError compatible error> - error object

 

read: anInteger into: aByteObject

Attempts to read anInteger bytes into bytes aByteObject. It returns the number of bytes read, zero on EOF, or an error object. If anInteger < 0 then 0 is returned and aByteObject is untouched If anInteger is larger than aByteObject size, then aByteObject size will be used.

Arguments:

anInteger - <Integer> number of bytes to get

aByteObject - Smalltalk byte objects (ByteArray | EsString)

Answers:

<ByteArray> - resulting bytes object

<OpenSSLError compatible error> - error object

 

read: anInteger into: bytes length: length

Attempts to read anInteger bytes into bytes which is a buffer of length length. It returns the number of bytes read, zero on EOF, or an error object. If anInteger < 0 then 0 is returned and aByteObject is untouched. If anInteger is larger than aByteObject size, then aByteObject size will be used.

Arguments:

anInteger - <Integer> number of bytes to get

bytes - byte object (ByteArray | EsString | OSObject)

length - length of @bytes

Answers:

<ByteArray> - resulting bytes object

<OpenSSLError compatible error> - error object

 

readString: anInteger

Attempts to read an anInteger number of bytes into a new String.

Answers:

<String> - resulting string

<OpenSSLError compatible error> - error object

 

reset

Typically resets a BIO to some initial state, in the case of file related BIOs, it rewinds the file pointer to the start of the file.

Answers:

<Integer> - 0 on success

<OpenSSLError compatible error> - error object

 

shouldCloseOnFree

Answer true if the underlying IO should be closed when this bio is freed. This may have no impact depending on the bio type.

Answers:

<Boolean>

 

shouldIOSpecialRetry

Answer true if bio encountered a temporary error while performing a special I/O operation, indicating that the caller should retry.

Answers:

<Boolean>

 

shouldRead

Answers true if this bio encountered a temporary error while reading (i.e. EAGAIN), indicating that the caller should retry the read, false otherwise.

Answers:

<Boolean>

 

shouldRetry

Answer true if the reason that caused a failed I/O operation is temporary and thus the operation should be retried. Otherwise, it was a permanent error and answer false.

Answers:

<Boolean>

 

shouldWrite

Answers true if this bio encountered a temporary error while writing (i.e. EAGAIN), indicating that the caller should retry the write, false otherwise.

Answers:

<Boolean>

 

write: aByteObject

Attempts to write a collection of bytes to the BIO.

Arguments:

aByteObject - a collection of bytes THAT MUST ANSWER ITS SIZE (i.e. String | ByteArray | OSStringZ)

Answers:

<Integer> - number of bytes written

<OpenSSLError compatible error> - error if not all bytes could by added to the BIO

 

write: aByteObject length: length

Attempts to write length number of bytes to aByteObject to the BIO.

Arguments:

aByteObject - a collection of bytes THAT MUST ANSWER ITS SIZE (i.e. String | ByteArray | OSStringZ)

Answers:

<Integer> - number of bytes written

<OpenSSLError compatible error> - error if not all bytes could by added to the BIO

 

Instance methods: Chains

|

Performs a #bioPush: with the argument @aBio. This API answers @aBio to facilitate chaining together.

i.e. bio1 | bio2 | bio3

creates a bio chain with bio1 as the head and bio3 as the tail (with bio2 between).

Arguments:

aBio - <OSSslBIO>

Answers:

<OSSslBIO> - aBio

 

bioChain

Answer the <OpenSSLBioChain> that mirrors the underlying bio chain. The mirror is performed so we can use the same OSObject instances when interating over the chain.

Answers:

< OpenSSLBioChain>

 

bioChain: aBioChain

Set the <OpenSSLBioChain> which holds the bios that are chained together.

Arguments:

aBioChain - <OpenSSLBioChain>

 

bioFreeAll

Frees up an entire BIO chain, it does not halt if an error occurs freeing up an individual BIO in the chain.

 

bioNext

Answers the next BIO in a chain.

Answers:

<OSSslBIO> - next bio

<UndefinedObject> - no next bio

 

bioPop

Answers the next BIO in the chain, or nil if there is no next BIO.

Answers:

<OSSslBIO> - next bio

<UndefinedObject> - no bio after me

 

bioPush: aBIO

Append @aBIO to the end of my chain. Update the mirrored smalltalk chain.

Arguments:

aBIO - <OSSslBIO>

Answers:

<OSSslBIO> - myself

 

doWhileUnlinked: aBlock

Perform the 0-argument <Block> aBlock while this bio is unhooked from the chain. Once aBlock completes its evaluation, this bio is rehooked back to the chain in its original position.

Arguments:

aBlock - <Block> 0-arg block

 

Instance methods: Conversion

asByteArray

Answer the complete data within this bio as ByteArray.

Answers:

< ByteArray>

 

asBytes

Answer the complete data within this bio as ByteArray.

Answers:

< ByteArray>

 

asString

Answer the complete data within this bio as an ASCII String.

Answers:

< String>

 

OSSslBase64BIO

Filter BIO that encodes any data written through it and decodes any data read through it.

Instance methods: Accessing

onOneLineOnly

If true, then all base64 encoded data will be placed on one line AND for decoding, the data will be expected to be on one line.

Answers:

<Boolean> true for encode on 1 line/decode from 1 line, false for multiline

 

onOneLineOnly: aBoolean

If true, then all base64 encoded data will be placed on one line AND for decoding, the data will be expected to be on one line.

Arguments:

aBoolean - <Boolean> true for encode on 1 line/decode from 1 line, false for multiline

 

OSSslBufferBIO

Filter BIO that encodes any data written through it and decodes any data read through it.

Instance methods: Accessing

bufferSize: anInteger

Set the size of both the input and output buffers. The default buffer size (4096) will be used if this isn't explicitly set.

Arguments:

anInteger - <Integer> buffer size in bytes

 

readBufferSize:: anInteger

Set the read input buffer size. The default buffer size (4096) will be used if this isn't explicitly set.

Arguments:

anInteger - <Integer> buffer size in bytes

 

writeBufferSize:: anInteger

Set the write output buffer size. The default buffer size (4096) will be used if this isn't explicitly set.

Arguments:

anInteger - <Integer> buffer size in bytes

 

writeBufferUsedSize

Answer the number of write-pending bytes in the write output buffer. This only looks locally at this buffer (as opposed to numberPendingWrite which considers other bios down the chain if nothing is in the buffer.

Answers:

<Integer> - used buffer size in bytes

 

Instance methods: API

fillReadBuffer: aByteObject length: length

Answers the number of lines currently buffered into aByteObject of size length.

Arguments:

aByteObject - byte object (i.e. ByteArray | EsString | OSObject)

 

numberOfBufferedLines

Answers the number of lines currently buffered.

Answers:

<Integer> - number of lines bufferred

OSSslFileBIO

Source/Sink BIO that wraps files.

Class methods: Creation

createNewFromFile: aFilename mode: aMode

Creates a new file BIO with mode mode the meaning of mode is the same as the stdio function fopen().

Arguments:

aFilename - <String>

aMode - <String>

Answers:

<OSSslFileBIO>

<OSSslError>

Instance methods: API

appendFilename: aFilename

Set aFilename to be used by this bio for appending. If an existing file is opened on this bio, it will be closed automatically if the BIO_CLOSE parameter has been set.

Arguments:

aFilename - filename to open for writing

Answers:

<Integer> - 1 for success

<OpenSSLError or compatible error> - error object if failed

 

asBytes

Override: If UPLINK flag is set, then answer an error object.

Answers:

<ByteArray>

<OpenSSLError> - error object

 

asString

Override: If UPLINK flag is set, then answer an error object.

Answers:

< String>

<OpenSSLError> - error object

 

eof

Answers true if the eof indicator is set, false otherwise.

NOTE: If UPLINK is set (usually on uninitialized file) then true is returned.

Answers:

<Boolean> true if at eof, false otherwise

 

flush

Override: If UPLINK flag is set, then answer answer true.

Answers:

<Boolean>

 

readFilename: aFilename

Set aFilename to be used by this bio for reading. If an existing file is opened on this bio, it will be closed automatically if the BIO_CLOSE parameter has been set.

Arguments:

aFilename - filename to open for reading

Answers:

<Integer> - 1 for success

<OpenSSLError or compatible error> - error object if failed

 

readWriteFilename: aFilename

Set aFilename to be used by this bio for read/write. If an existing file is opened on this bio, it will be closed automatically if the BIO_CLOSE parameter has been set.

Arguments:

aFilename - filename to open for read/write

Answers:

<Integer> - 1 for success

<OpenSSLError or compatible error> - error object if failed

 

reset

Override: If UPLINK flag is set, then answer an error object.

Answers:

<Integer> - 0 on success

<OpenSSLError compatible error>

 

seek: numBytes

Sets the file pointer to position numBytes from the start of the file.

Arguments:

numBytes - bytes from start

Answers:

<Integer> - 0 for success

<OpenSSLError or compatible error> - error object if failed

 

tell

Answers the current file position of a file related BIO.

Answers:

<Integer> - current file position

<OpenSSLError compatible error>

 

writeFilename: aFilename

Set aFilename to be used by this bio for writing. If an existing file is opened on this bio, it will be closed automatically if the BIO_CLOSE parameter has been set.

Arguments:

aFilename - filename to open for writing

Answers:

<Integer> - 1 for success

<OpenSSLError or compatible error> - error object if failed

 

OSSslMemoryBIO

Source/Sink BIOs that read/write in-memory.

Class methods: Creation

createNewFromBytes: aByteObject

Answer a new In-Memory BIO from @aByteObject. The argument must be one that converts to bytes in a platform function.

Arguments:

aByteObject - Byte object that know their size. Examples are <ByteArray | EsString | OSStringZ>

Answers:

<OSSslBIO> - new instance

<OpenSSLError compatible error> - error object

 

createNewFromBytes: aByteObject length: length

Answer a new In-Memory BIO from @aByteObject. The argument must be one that converts to bytes in a platform function.

Arguments:

aByteObject - Byte object that know their size. Examples are <ByteArray | EsString | OSStringZ>

length - <Integer> set up to @length amount from the @anOSObjectOrByteArray

Answers:

<OSSslBIO> - new instance

<OpenSSLError compatible error> - error object

 

Instance methods: API

asBytes

Answer the complete data within this bio as a ByteArray. This uses a specific feature of memory bios for quick access.

Answers:

< ByteArray>

 

asString

Answer the complete data within this bio as a String. This uses a specific feature of memory bios for quick access.

Answers:

<String>

 

closeOnFree: aBoolean

Always have the close marker set otherwise memory would leak.

 

isReadOnlyMemory

Answer true if this memory BIO is read only, false otherwise.

Answers:

<Boolean>

OSSslStaticMemoryBIO

Source/Sink BIO that is optimized for read/write to constant in-memory data.

Class methods: Creation

createNewFromBytes: aByteObject length: length

Answer a new In-Memory Static BIO from @aByteObject. The argument must be one that converts to bytes in a platform function. The argument must also either be in fixed space or moved to fixed space since this is what OpenSSL refers to and we don't want it GCd.

Arguments:

aByteObject - <ByteArray | EsString | OSPtr>

length - <Integer> set up to @length amount from the @aByteObject

Answers:

< OSSslStaticMemoryBIO > - new instance

<OpenSSLError compatible error> - error object

 

createWeakReferenceTo: anAddressOrErrorObject

Create a new reference to the provided address anAddressOrErrorObject. This new instance will NOT own the memory at address. This new instance may call free, but it will have no impact on native memory.

Specific to static bios, the address to the existing memory is queried so we can set it as the static memory

Arguments:

anAddressOrErrorObject - <Integer> address or <OpenSSLError> error object

Answers:

< OSSslStaticMemoryBIO > - new instance

<OpenSSLError compatible error> - error object

 

Class methods: Memory Management

free

Free the static memory if I am the owner of it.

 

OSSslNullBIO

Null sink BIO, similar in function to /dev/null on UNIX.