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.