Function bearssl::br_sslio_init [−] [src]

pub unsafe extern "C" fn br_sslio_init(
    ctx: *mut br_sslio_context, 
    engine: *mut br_ssl_engine_context, 
    low_read: Option<unsafe extern "C" fn(_: *mut c_void, _: *mut c_uchar, _: usize) -> c_int>, 
    read_context: *mut c_void, 
    low_write: Option<unsafe extern "C" fn(_: *mut c_void, _: *const c_uchar, _: usize) -> c_int>, 
    write_context: *mut c_void
)

\brief Initialise a simplified I/O wrapper context.

The simplified I/O wrapper offers a simpler read/write API for a SSL engine (client or server), using the provided callback functions for reading data from, or writing data to, the transport medium.

The callback functions have the following semantics:

  • Each callback receives an opaque context value (of type void *) that the callback may use arbitrarily (or possibly ignore).

  • low_read() reads at least one byte, at most len bytes, from the transport medium. Read bytes shall be written in data.

  • low_write() writes at least one byte, at most len bytes, unto the transport medium. The bytes to write are read from data.

  • The len parameter is never zero, and is always lower than 20000.

  • The number of processed bytes (read or written) is returned. Since that number is less than 20000, it always fits on an int.

  • On error, the callbacks return -1. Reaching end-of-stream is an error. Errors are permanent: the SSL connection is terminated.

  • Callbacks SHOULD NOT return 0. This is tolerated, as long as callbacks endeavour to block for some non-negligible amount of time until at least one byte can be sent or received (if a callback returns 0, then the wrapper invokes it again immediately).

  • Callbacks MAY return as soon as at least one byte is processed; they MAY also insist on reading or writing all requested bytes. Since SSL is a self-terminated protocol (each record has a length header), this does not change semantics.

  • Callbacks need not apply any buffering (for performance) since SSL itself uses buffers.

\param ctx wrapper context to initialise. \param engine SSL engine to wrap. \param low_read callback for reading data from the transport. \param read_context context pointer for low_read(). \param low_write callback for writing data on the transport. \param write_context context pointer for low_write().