sideband.h File Reference

exported symbols from sideband.c More...

Data Structures
struct	sb_buffer
	The information contained in a sideband buffer. More...

Macros
#define	SB_DESIGNATORS
	The valid sideband designators. More...
#define	DESIGNATOR(x)   SBD_ ## x
	Just prefix with SBD_. More...
#define	DESIGNATOR(x)   #x
	Just prefix with SBD_. More...
#define	SB_DESIGNATORS_ARRAY   SB_DESIGNATORS
	List of stringified sidedband designators. More...
#define	SBB_INIT(_band, _buf, _numbytes)
	Initialize a sideband buffer. More...

Typedefs
typedef void(*	sb_transformation) (struct iovec *src, struct iovec *dst, void *trafo_context)
	The type of a sideband transformation. More...

Enumerations
enum	sb_designator {   SBD_ANY, SBD_CHALLENGE, SBD_CHALLENGE_RESPONSE, SBD_PROCEED,   SBD_COMMAND, SBD_AWAITING_DATA, SBD_OUTPUT, SBD_DEBUG_LOG,   SBD_INFO_LOG, SBD_NOTICE_LOG, SBD_WARNING_LOG, SBD_ERROR_LOG,   SBD_CRIT_LOG, SBD_EMERG_LOG, SBD_EXIT__SUCCESS, SBD_EXIT__FAILURE,   SBD_BLOB_DATA, SBD_AFS_CB_FAILURE, NUM_SB_DESIGNATORS }
	All valid sideband designators. More...

Functions
struct sb_context *	sb_new_recv (size_t max_size, sb_transformation t, void *trafo_context)
	Prepare to receive a sideband packet. More...
void	sb_get_recv_buffer (struct sb_context *c, struct iovec *iov)
	Obtain a pointer to the next sideband read buffer. More...
int	sb_received (struct sb_context *c, size_t nbytes, struct sb_buffer *result)
	Update the sideband context after data has been received. More...
struct sb_context *	sb_new_send (struct sb_buffer *sbb, bool dont_free, sb_transformation t, void *trafo_context)
	Prepare to write a sideband packet. More...
int	sb_get_send_buffers (struct sb_context *c, struct iovec iov[2])
	Obtain pointer(s) to the sideband send buffer(s). More...
bool	sb_sent (struct sb_context *c, size_t nbytes)
	Update the sideband context after data has been sent. More...
void	sb_free (struct sb_context *c)
	Deallocate all memory associated with a sideband handle. More...

Detailed Description

exported symbols from sideband.c

Macro Definition Documentation

SB_DESIGNATORS

#define SB_DESIGNATORS

The valid sideband designators.

A sideband packet consists of a header and a body. The header is sent prior to the data and contains the length of the buffer and the sideband designator, an integer. This scheme allows receivers to never read more data than what was specified in the header.

The sideband designator indicates the type of the data. The authentication handshake between the command handler (child of para_server) and the client requires to exchange several small packages. Each such package is sent as a sideband package with a dedicated designator.

Other designators are employed for normal command output and for log messages, where each loglevel corresponds to a sideband designator.

Note that the values of this enum are part of the ABI, so never change or remove entries. Appending is OK though.

DESIGNATOR [1/2]

#define DESIGNATOR

(

x

)

SBD_ ## x

Just prefix with SBD_.

One stringified sideband designator.

DESIGNATOR [2/2]

#define DESIGNATOR

(

x

)

#x

Just prefix with SBD_.

One stringified sideband designator.

SB_DESIGNATORS_ARRAY

#define SB_DESIGNATORS_ARRAY   SB_DESIGNATORS

List of stringified sidedband designators.

SBB_INIT

#define SBB_INIT	(		_band,
			_buf,
			_numbytes
	)

Value:

        { \
                .band = _band, \
                .iov = { \
                        .iov_base = _buf, \
                        .iov_len = _numbytes \
                } \
        };

Initialize a sideband buffer.

Typedef Documentation

sb_transformation

typedef void(* sb_transformation) (struct iovec *src, struct iovec *dst, void *trafo_context)

The type of a sideband transformation.

The sideband API allows the filtering of data through an arbitrary transformation, which is useful for crypto purposes. The transformation may either transform the data in place, or return a pointer to a new buffer which contains the transformed source buffer. The internal sideband functions can tell the two types of transformations apart by checking whether the destination buffer coincides with the source buffer.

If the transformation allocates a new buffer, it must allocate one extra byte for NULL termination.

Enumeration Type Documentation

sb_designator

enum sb_designator

All valid sideband designators.

Enumerator
SBD_ANY
SBD_CHALLENGE
SBD_CHALLENGE_RESPONSE
SBD_PROCEED
SBD_COMMAND
SBD_AWAITING_DATA
SBD_OUTPUT
SBD_DEBUG_LOG
SBD_INFO_LOG
SBD_NOTICE_LOG
SBD_WARNING_LOG
SBD_ERROR_LOG
SBD_CRIT_LOG
SBD_EMERG_LOG
SBD_EXIT__SUCCESS
SBD_EXIT__FAILURE
SBD_BLOB_DATA
SBD_AFS_CB_FAILURE
NUM_SB_DESIGNATORS

Function Documentation

sb_new_recv()

struct sb_context* sb_new_recv	(	size_t	max_size,
		sb_transformation	t,
		void *	trafo_context
	)

Prepare to receive a sideband packet.

Parameters

max_size	Do not allocate more than this many bytes.
t	Optional sideband transformation.
trafo_context	Passed verbatim to t.

trafo_context is ignored if t is NULL.

Returns

An opaque sideband handle.

References zalloc().

Referenced by recv_sb().

sb_get_recv_buffer()

void sb_get_recv_buffer	(	struct sb_context *	c,
		struct iovec *	iov
	)

Obtain a pointer to the next sideband read buffer.

Parameters

c	The sideband handle.
iov	Result IO vector.

This fills in iov to point to the buffer to which the next chunk of received data should be written.

References sb_buffer::iov, and SIDEBAND_HEADER_SIZE.

Referenced by recv_sb().

sb_received()

int sb_received	(	struct sb_context *	c,
		size_t	nbytes,
		struct sb_buffer *	result
	)

Update the sideband context after data has been received.

Parameters

c	The sideband handle.
nbytes	The number of bytes that have been received.
result	The received sideband packet.

Returns

Negative on errors, zero if more data needs to be read to complete this sideband packet, one if the sideband packet has been received completely.

Only if the function returns one, the sideband buffer pointed to by result is set to point to the received data.

References sb_buffer::iov, and SIDEBAND_HEADER_SIZE.

Referenced by recv_sb().

sb_new_send()

struct sb_context* sb_new_send	(	struct sb_buffer *	sbb,
		bool	dont_free,
		sb_transformation	t,
		void *	trafo_context
	)

Prepare to write a sideband packet.

Parameters

sbb	Data and meta data to send.
dont_free	Do not try to deallocate the sideband buffer.
t	See sb_new_recv().
trafo_context	See sb_new_recv().

It's OK to supply a zero-sized buffer in sbb. In this case only the band designator is sent through the sideband channel. Otherwise, if dont_free is false, the buffer of sbb is freed after the data has been sent.

Returns

See sb_new_recv().

References zalloc().

Referenced by send_sb().

sb_get_send_buffers()

int sb_get_send_buffers	(	struct sb_context *	c,
		struct iovec	iov[2]
	)

Obtain pointer(s) to the sideband send buffer(s).

Parameters

c	The sideband handle.
iov	Array of two I/O vectors.

Returns

The number of buffers that need to be sent, either 1 or 2.

This function fills out the buffers described by iov. The result can be passed to xwritev() or similar.

See also

sb_get_recv_buffer().

References sb_buffer::iov, iov_valid(), and SIDEBAND_HEADER_SIZE.

Referenced by send_sb().

sb_sent()

bool sb_sent	(	struct sb_context *	c,
		size_t	nbytes
	)

Update the sideband context after data has been sent.

Parameters

c	The sideband handle.
nbytes	The number of sent bytes.

Returns

False if more data must be sent to complete the sideband transfer, true if the transfer is complete. In this case all resources are freed and the sideband handle must not be used any more.

References sb_buffer::iov, sb_free(), and SIDEBAND_HEADER_SIZE.

Referenced by send_sb().

sb_free()

void sb_free

(

struct sb_context *

c

)

Deallocate all memory associated with a sideband handle.

Parameters

c	The sideband handle.

c must point to a handle previously returned by sb_new_recv() or sb_new_send(). It c is NULL, the function does nothing.

Referenced by recv_sb(), sb_sent(), and send_sb().