The pktlab pktctrl module. More...

#include <pktlab.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <poll.h>
#include <sys/select.h>

Include dependency graph for pktctrl.h:

Go to the source code of this file.

Macros
#define	PKTCTRL_SNIKEY_LEN_MIN 1
	Minimum pktlab snikey length.

#define	PKTCTRL_SNIKEY_LEN_MAX 63
	Maximum pktlab snikey length. More...

Enumerations
enum	pktctrl_err { PKTCTRL_SUCCESS = 0 , PKTCTRL_INVAL = 1 , PKTCTRL_MAP_ERR = 2 , PKTCTRL_KEY_NOT_FOUND = 3 , PKTCTRL_SSL_FAILURE = 4 , PKTCTRL_BAD_CERT = 5 , PKTCTRL_BAD_CERTKEY = 6 , PKTCTRL_IN_PROGRESS = 7 , PKTCTRL_UNKNOWN_FAULT = 127 }
	pktctrl module defined error values.

Functions
struct pktctrl_obj *	pktctrl_create_obj (void)
	Get initialized pktctrl session object struct. More...

struct pktctrl_keycert_store *	pktctrl_create_keycert_store (void)
	Get initialized pktctrl key certificate storage struct. More...

int	pktctrl_set_server_keycert (struct pktctrl_keycert_store store, const char snikey, struct pktlab_certificate cert_ls, uint_fast32_t certnum, struct pktlab_publickey root_ls, uint_fast32_t rootnum)
	Load server certificate chain and trusted roots for some snikey into pktctrl key certificate storage struct. More...

int	pktctrl_get_server_keycert (struct pktctrl_keycert_store store, const char snikey, struct pktlab_certificate **cert_ls, uint_fast32_t certnum, struct pktlab_publickey **root_ls, uint_fast32_t rootnum)
	Get loaded server certificate chain and trusted roots for some snikey from server pktctrl key certificate storage struct. More...

int	pktctrl_clear_server_keycert (struct pktctrl_keycert_store store, const char snikey)
	Delete server certificate chain and trusted roots entry for some snikey from server pktctrl key certificate storage struct. More...

int	pktctrl_set_server_keycert_default (struct pktctrl_keycert_store store, const char snikey)
	Set server pktctrl key certificate storage default entry. More...

int	pktctrl_clear_server_keycert_default (struct pktctrl_keycert_store *store)
	Clear server pktctrl key certificate storage default entry. More...

int	pktctrl_set_client_keycert (struct pktctrl_keycert_store store, struct pktlab_certificate cert_ls, uint_fast32_t certnum, struct pktlab_publickey *root_ls, uint_fast32_t rootnum)
	Load client certificate chain and trusted roots into pktctrl key certificate storage struct. More...

int	pktctrl_get_client_keycert (struct pktctrl_keycert_store store, struct pktlab_certificate *cert_ls, uint_fast32_t certnum, struct pktlab_publickey **root_ls, uint_fast32_t rootnum)
	Get loaded client certificate chain and trusted roots from client pktctrl key certificate storage struct. More...

int	pktctrl_clear_client_keycert (struct pktctrl_keycert_store *store)
	Delete client certificate chain and trusted roots from client pktctrl key certificate storage struct. More...

int	pktctrl_accept (int fd, int auth_mode, struct pktlab_privatekey serverkey, struct pktctrl_keycert_store store, struct pktctrl_obj ctrlobj, struct pktlab_certificate *peer_cert_ls, uint_fast32_t peer_cert_num)
	Perform TLS server-side handshake to establish TLS pktctrl session. More...

int	pktctrl_connect (int fd, int auth_mode, const char snikey, struct pktlab_privatekey clientkey, struct pktctrl_keycert_store store, struct pktctrl_obj ctrlobj, struct pktlab_certificate **peer_cert_ls, uint_fast32_t peer_cert_num)
	Perform TLS client-side handshake to establish TLS pktctrl session. More...

int	pktctrl_raw_session (int fd, struct pktctrl_obj *ctrlobj)
	Set up pktctrl session object struct to establish barebone TCP pktctrl session. More...

int	pktctrl_prepare_select (int nfds, fd_set restrict rset, fd_set restrict wset, bool want_read, bool want_write, struct pktctrl_obj ctrlobj)
	Set up arguments to select() for read/write operation on established pktctrl session based on intention. More...

int	pktctrl_process_select (const fd_set restrict rset, const fd_set restrict wset, struct pktctrl_obj ctrlobj, bool readable, bool *writable)
	Process select() results to identify if read/write operation on established pktctrl session can be performed. More...

int	pktctrl_prepare_poll (struct pollfd restrict pfd, bool want_read, bool want_write, struct pktctrl_obj ctrlobj)

int	pktctrl_process_poll (const struct pollfd restrict pfd, struct pktctrl_obj ctrlobj, bool readable, bool writable)

int	pktctrl_read_message (struct pktctrl_obj ctrlobj, struct pktlab_message *msgptr)
	Read pktctrl message from established pktctrl session. More...

int	pktctrl_write_message (struct pktctrl_obj ctrlobj, const struct pktlab_message msg)
	Write pktctrl message to established pktctrl session. More...

int	pktctrl_flush_write (struct pktctrl_obj *ctrlobj)
	Flush established pktctrl session internal writer buffer. More...

size_t	pktctrl_write_unsent (const struct pktctrl_obj *ctrlobj)
	Get established pktctrl session internal writer buffered content length. More...

ssize_t	pktctrl_read (struct pktctrl_obj obj, void buf, size_t nbyte)
	Read bytes from established pktctrl session. More...

ssize_t	pktctrl_write (struct pktctrl_obj obj, const void buf, size_t nbyte)
	Write bytes to established pktctrl session. More...

int	pktctrl_close (struct pktctrl_obj *obj)
	Close and free an allocated pktctrl session object struct. More...

int	pktctrl_cleanup_keycert_store (struct pktctrl_keycert_store *store)
	Free an allocated pktctrl key certificate storage struct. More...

bool	pktctrl_is_established (struct pktctrl_obj *obj)
	Check if a pktctrl session object is established. More...

bool	pktctrl_is_valid_snikey (const char *snikey)
	Check if '\0'-terminated string is a valid snikey. More...

int	pktctrl_gen_snikey (char **buf)
	Generate random '\0'-terminated valid snikey of PKTCTRL_SNIKEY_LEN_MAX length. More...

Detailed Description

The pktlab pktctrl module.

For pktlab protocol message communication among pktlab entities. Note snikey is the same as SNI in normal TLS context.

Macro Definition Documentation

◆ PKTCTRL_SNIKEY_LEN_MAX

#define PKTCTRL_SNIKEY_LEN_MAX 63

Maximum pktlab snikey length.

Defined to be 63 for TLS library compatibility, as 63 is the maximum domain name label length.

Function Documentation

◆ pktctrl_accept()

int pktctrl_accept	(	int	fd,
		int	auth_mode,
		struct pktlab_privatekey *	serverkey,
		struct pktctrl_keycert_store *	store,
		struct pktctrl_obj *	ctrlobj,
		struct pktlab_certificate ***	peer_cert_ls,
		uint_fast32_t *	peer_cert_num
	)

Perform TLS server-side handshake to establish TLS pktctrl session.

Parameters

[in]	fd	File descriptor for an established TCP connection.
[in]	auth_mode	The certificate chain verification mode to use. One of enum pktlab_auth_mode.
[in]	serverkey	Pointer to a loaded pktlab private key struct to be used as TLS server key.
[in]	store	Pointer to a loaded server pktctrl key certificate storage struct.
[in,out]	ctrlobj	Pointer to an initialized pktctrl session object struct.
[out]	peer_cert_ls	Pointer to return client certificate chain.
[out]	peer_cert_num	The number of returned client certificates.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success. ctrlobj is an established session object upon return.
PKTCTRL_INVAL for bad argument.
PKTCTRL_IN_PROGRESS for TLS handshake in progress.
PKTCTRL_SSL_FAILURE for TLS handshake error.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

ctrlobj & fd should be freed & closed after pktctrl_accept() returned PKTCTRL_SSL_FAILURE or PKTCTRL_UNKNOWN_FAULT.
If peer_cert_ls and peer_cert_num are both non-NULL, verified client certificates (if any) are returned.
If fd is non-blocking, PKTCTRL_IN_PROGRESS may be returned. One should then use pktctrl_prepare_select() and pktctrl_process_select() with select() in sys/select.h to retry later.
If fd is blocking, pktctrl_accept() should block until success or failure.
When TLS handshake is ongoing for a ctrlobj/fd (i.e. pktctrl_accept() hasn't returned or returned PKTCTRL_IN_PROGRESS), the passed in arguments should remain unchanged (including in scope/not freed).
See also pktlab_create_privatekey(), pktlab_load_privatekey_pem(), pktlab_load_privatekey_der(), pktlab_load_privatekey_raw(), pktctrl_create_keycert_store(), pktctrl_set_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_create_obj(), pktctrl_close(), pktctrl_read_message(), pktctrl_write_message().

◆ pktctrl_cleanup_keycert_store()

int pktctrl_cleanup_keycert_store ( struct pktctrl_keycert_store * store )

Free an allocated pktctrl key certificate storage struct.

Parameters

[in,out] store Pointer to an allocated pktctrl key certificate storage struct to free.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

Note the loaded keys and certificates are NOT freed.
Do not call pktctrl_cleanup_keycert_store() again if failed.

◆ pktctrl_clear_client_keycert()

int pktctrl_clear_client_keycert ( struct pktctrl_keycert_store * store )

Delete client certificate chain and trusted roots from client pktctrl key certificate storage struct.

Parameters

[in,out] store Pointer to a client pktctrl key certificate storage struct.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

pktctrl_clear_client_keycert() works the same as if calling pktctrl_set_client_keycert() with NULL cert_ls and NULL root_ls.
Note though cleared, the loaded cert_ls and root_ls (and their content) are NOT freed.
See also pktctrl_create_keycert_store(), pktctrl_set_client_keycert(), pktctrl_get_client_keycert(), pktctrl_cleanup_keycert_store().

◆ pktctrl_clear_server_keycert()

int pktctrl_clear_server_keycert	(	struct pktctrl_keycert_store *	store,
		const char *	snikey
	)

Delete server certificate chain and trusted roots entry for some snikey from server pktctrl key certificate storage struct.

Parameters

[in,out]	store	Pointer to a server pktctrl key certificate storage struct.
[in]	snikey	Pointer to the target '\0'-terminated snikey.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_MAP_ERR for internal map error.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

store should be freed after pktctrl_clear_server_keycert() returned PKTCTRL_MAP_ERR.
pktctrl_clear_server_keycert() works the same as if calling pktctrl_set_server_keycert() with NULL cert_ls and NULL root_ls. The corresponding entry is deleted for the supplied snikey.
Note though entry is deleted, the loaded cert_ls and root_ls (and their content) are NOT freed.
See also pktctrl_create_keycert_store(), pktctrl_set_server_keycert(), pktctrl_get_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_clear_server_keycert_default(), pktctrl_cleanup_keycert_store().

◆ pktctrl_clear_server_keycert_default()

int pktctrl_clear_server_keycert_default ( struct pktctrl_keycert_store * store )

Clear server pktctrl key certificate storage default entry.

Parameters

[in,out] store Pointer to a server pktctrl key certificate storage struct.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

See also pktctrl_create_keycert_store(), pktctrl_set_server_keycert(), pktctrl_get_server_keycert(), pktctrl_clear_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_cleanup_keycert_store().

◆ pktctrl_close()

int pktctrl_close ( struct pktctrl_obj * obj )

Close and free an allocated pktctrl session object struct.

Parameters

[in,out] obj Pointer to an allocated pktctrl session object struct to free.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

pktctrl_close() also performs TLS shutdown if applicable.
Note the underlying file descriptor is NOT closed.
Do not call pktctrl_close() again if failed.

◆ pktctrl_connect()

int pktctrl_connect	(	int	fd,
		int	auth_mode,
		const char *	snikey,
		struct pktlab_privatekey *	clientkey,
		struct pktctrl_keycert_store *	store,
		struct pktctrl_obj *	ctrlobj,
		struct pktlab_certificate ***	peer_cert_ls,
		uint_fast32_t *	peer_cert_num
	)

Perform TLS client-side handshake to establish TLS pktctrl session.

Parameters

[in]	fd	File descriptor for an established TCP connection.
[in]	auth_mode	The certificate chain verification mode to use. One of enum pktlab_auth_mode.
[in]	snikey	Pointer to a '\0'-terminated snikey or NULL.
[in]	clientkey	Pointer to a loaded pktlab private key struct to be used as TLS client key.
[in]	store	Pointer to a loaded client pktctrl key certificate storage struct.
[in,out]	ctrlobj	Pointer to an initialized pktctrl session object struct.
[out]	peer_cert_ls	Pointer to return client certificate chain.
[out]	peer_cert_num	The number of returned client certificates.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success. ctrlobj is an established session object upon return.
PKTCTRL_INVAL for bad argument.
PKTCTRL_BAD_CERT for certificate rejected by underlying TLS implementation.
PKTCTRL_BAD_CERTKEY for private key rejected by underlying TLS implementation.
PKTCTRL_IN_PROGRESS for TLS handshake in progress.
PKTCTRL_SSL_FAILURE for TLS handshake error.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

ctrlobj & fd should be freed & closed after pktctrl_connect() returned error other than PKTCTRL_INVAL or PKTCTRL_IN_PROGRESS.
If peer_cert_ls and peer_cert_num are both non-NULL, verified server certificates are returned.
If fd is non-blocking, PKTCTRL_IN_PROGRESS may be returned. One should then use pktctrl_prepare_select() and pktctrl_process_select() with select() in sys/select.h to retry later.
If fd is blocking, pktctrl_connect() should block until success or failure.
When TLS handshake is ongoing for a ctrlobj/fd (i.e. pktctrl_connect() hasn't returned or returned PKTCTRL_IN_PROGRESS), the passed in arguments should remain unchanged (including in scope/not freed).
See also pktlab_create_privatekey(), pktlab_load_privatekey_pem(), pktlab_load_privatekey_der(), pktlab_load_privatekey_raw(), pktctrl_create_keycert_store(), pktctrl_set_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_create_obj(), pktctrl_close(), pktctrl_read_message(), pktctrl_write_message().

◆ pktctrl_create_keycert_store()

struct pktctrl_keycert_store * pktctrl_create_keycert_store ( void )

Get initialized pktctrl key certificate storage struct.

Returns: An allocated and initialized pktctrl key certificate storage struct, or NULL if failed.

The returned allocated struct should be freed with pktctrl_cleanup_keycert_store().
See also pktctrl_set_server_keycert(), pktctrl_get_server_keycert(), pktctrl_clear_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_clear_server_keycert_default(), pktctrl_set_client_keycert(), pktctrl_get_client_keycert(), pktctrl_clear_client_keycert(), pktctrl_cleanup_keycert_store().

◆ pktctrl_create_obj()

struct pktctrl_obj * pktctrl_create_obj ( void )

Get initialized pktctrl session object struct.

Returns: An allocated and initialized pktctrl session object struct, or NULL if failed.

The returned allocated struct should be freed with pktctrl_close().

◆ pktctrl_flush_write()

int pktctrl_flush_write ( struct pktctrl_obj * ctrlobj )

Flush established pktctrl session internal writer buffer.

Parameters

[in,out] ctrlobj Pointer to an established pktctrl session object struct.

pktctrl_flush_write() functions the same as pktlab_flush_writer() except passing in an established pktctrl session object struct than a writer. Note one does not need to create a writer for ctrlobj as an internal one is used.
See pktlab_flush_writer() for more information on behavior.

◆ pktctrl_gen_snikey()

int pktctrl_gen_snikey ( char ** buf )

Generate random '\0'-terminated valid snikey of PKTCTRL_SNIKEY_LEN_MAX length.

Parameters

[in,out] buf Pointer to return allocated snikey.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success. *buf points to a valid snikey upon return.
PKTCTRL_INVAL for bad argument.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

The returned buf should be freed with free() in stdlib.h.

◆ pktctrl_get_client_keycert()

int pktctrl_get_client_keycert	(	struct pktctrl_keycert_store *	store,
		struct pktlab_certificate ***	cert_ls,
		uint_fast32_t *	certnum,
		struct pktlab_publickey ***	root_ls,
		uint_fast32_t *	rootnum
	)

Get loaded client certificate chain and trusted roots from client pktctrl key certificate storage struct.

Parameters

[in]	store	Pointer to a client pktctrl key certificate storage struct.
[out]	cert_ls	Pointer to return the loaded client certificate chain.
[out]	certnum	Pointer to return the number of client certificates loaded.
[out]	root_ls	Pointer to return the loaded trusted roots.
[out]	rootnum	Pointer to return the number of trusted roots loaded.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

It is allowed for cert_ls/certnum/root_ls/rootnum to be NULL. No value is returned in that case.
See also pktctrl_create_keycert_store(), pktctrl_set_client_keycert(), pktctrl_clear_client_keycert(), pktctrl_cleanup_keycert_store().

◆ pktctrl_get_server_keycert()

int pktctrl_get_server_keycert	(	struct pktctrl_keycert_store *	store,
		const char *	snikey,
		struct pktlab_certificate ***	cert_ls,
		uint_fast32_t *	certnum,
		struct pktlab_publickey ***	root_ls,
		uint_fast32_t *	rootnum
	)

Get loaded server certificate chain and trusted roots for some snikey from server pktctrl key certificate storage struct.

Parameters

[in]	store	Pointer to a server pktctrl key certificate storage struct.
[in]	snikey	Pointer to the target '\0'-terminated snikey.
[out]	cert_ls	Pointer to return the loaded server certificate chain.
[out]	certnum	Pointer to return the number of server certificates loaded.
[out]	root_ls	Pointer to return the loaded trusted roots.
[out]	rootnum	Pointer to return the number of trusted roots loaded.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_KEY_NOT_FOUND for snikey not present in internal map.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

It is allowed for cert_ls/certnum/root_ls/rootnum to be NULL. No value is returned in that case.
See also pktctrl_create_keycert_store(), pktctrl_set_server_keycert(), pktctrl_clear_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_clear_server_keycert_default(), pktctrl_cleanup_keycert_store().

◆ pktctrl_is_established()

bool pktctrl_is_established ( struct pktctrl_obj * obj )

Check if a pktctrl session object is established.

Parameters

[in] obj Pointer to a pktctrl session object struct.

Returns: true if obj is established, false otherwise.

◆ pktctrl_is_valid_snikey()

bool pktctrl_is_valid_snikey ( const char * snikey )

Check if '\0'-terminated string is a valid snikey.

Parameters

[in] snikey Pointer to a '\0'-terminated string.

Returns: true if string is valid snikey, false otherwise.

A valid snikey is a string of length in [PKTCTRL_SNIKEY_LEN_MIN,PKTCTRL_SNIKEY_LEN_MAX] consisting only of lowercase letters (a-z) and digits (0-9).

◆ pktctrl_prepare_select()

int pktctrl_prepare_select	(	int *	nfds,
		fd_set *restrict	rset,
		fd_set *restrict	wset,
		bool	want_read,
		bool	want_write,
		struct pktctrl_obj *	ctrlobj
	)

Set up arguments to select() for read/write operation on established pktctrl session based on intention.

Parameters

[in,out]	nfds	Pointer to update the nfds value to select on the ctrlobj fd.
[in,out]	rset	Read fdset. May be set for ctrlobj fd.
[in,out]	wset	Write fdset. May be set for ctrlobj fd.
[in]	want_read	Intention on wanting to read from ctrlobj.
[in]	want_write	Intention on wanting to write to ctrlobj.
[in]	ctrlobj	Pointer to an established pktctrl session object struct.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success. rset and wset are set based on the read/write intention passed in. nfds is updated to cover the ctrlobj fd.
PKTCTRL_INVAL for bad argument.

In case of intending to call select() to continue on the TLS handshake, both want_read and want_write should be set.
rset and wset is not zeroed by pktctrl_prepare_select().
Note pktctrl_prepare_select() should be used when setting up a select call for a ctrlobj fd, as pktctrl_prepare_select() contains internal logic on handling scenarios where for a TLS connection, to read may require selecting on write and vice versa.
See also pktctrl_create_obj(), pktctrl_accept(), pktctrl_connect(), pktctrl_raw_session(), pktctrl_process_select().

◆ pktctrl_process_select()

int pktctrl_process_select	(	const fd_set *restrict	rset,
		const fd_set *restrict	wset,
		struct pktctrl_obj *	ctrlobj,
		bool *	readable,
		bool *	writable
	)

Process select() results to identify if read/write operation on established pktctrl session can be performed.

Parameters

[in]	rset	select()-set read fdset.
[in]	wset	select()-set write fdset.
[in]	ctrlobj	Pointer to an established pktctrl session object struct.
[out]	readable	Pointer to return if read operation can be performed on ctrlobj.
[out]	writable	Pointer to return if write operation can be performed on ctrlobj.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success. readable and writable are set.
PKTCTRL_INVAL for bad argument.

The in progress TLS handshake (pktctrl_accept()/pktctrl_connect()) for ctrlobj can be continued when either readable or writable is set.
Note pktctrl_process_select() should be used when parsing a select call return values for a ctrlobj fd, as pktctrl_process_select() contains internal logic on handling scenarios where for a TLS connection, readable may require write being set and vice versa.
See also pktctrl_create_obj(), pktctrl_accept(), pktctrl_connect(), pktctrl_raw_session(), pktctrl_prepare_select().

◆ pktctrl_raw_session()

int pktctrl_raw_session	(	int	fd,
		struct pktctrl_obj *	ctrlobj
	)

Set up pktctrl session object struct to establish barebone TCP pktctrl session.

Parameters

[in]	fd	File descriptor for an established TCP connection.
[in,out]	ctrlobj	Pointer to an initialized pktctrl session object struct.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success. ctrlobj is an established session object upon return.
PKTCTRL_INVAL for bad argument.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

ctrlobj & fd should be freed & closed after pktctrl_raw_session() returned PKTCTRL_UNKNOWN_FAULT.
pktctrl_raw_session() should not block whether fd is blocking or not.
pktctrl_raw_session() is especially useful when writing experiment programs that work with the pktlabec general experiment controller. See pktlabec repo README for more information.
See also pktctrl_create_obj(), pktctrl_read_message(), pktctrl_write_message().

◆ pktctrl_read()

ssize_t pktctrl_read	(	struct pktctrl_obj *	obj,
		void *	buf,
		size_t	nbyte
	)

Read bytes from established pktctrl session.

Parameters

[in,out]	obj	Pointer to an established pktctrl session object struct.
[out]	buf	Pointer to buffer for storing the read bytes.
[in]	buflen	Attempted read length (must be > 0).

Returns: The number of bytes read, 0 for EOF, or < 0 for error (see errno for more information).

pktctrl_read() should not be called after calling pktctrl_read_message() with obj.
To read pktlab protocol messages, pktctrl_read_message() is recommended instead.

◆ pktctrl_read_message()

int pktctrl_read_message	(	struct pktctrl_obj *	ctrlobj,
		struct pktlab_message **	msgptr
	)

Read pktctrl message from established pktctrl session.

Parameters

[in,out]	ctrlobj	Pointer to an established pktctrl session object struct.
[out]	msgptr	Pointer to return an allocated fields-set msg that was read.

pktctrl_read_message() functions the same as pktlab_read_message() except passing in an established pktctrl session object struct than a reader. Note one does not need to create a reader for ctrlobj as an internal one is used.
See pktlab_read_message() for more information on behavior.

◆ pktctrl_set_client_keycert()

int pktctrl_set_client_keycert	(	struct pktctrl_keycert_store *	store,
		struct pktlab_certificate **	cert_ls,
		uint_fast32_t	certnum,
		struct pktlab_publickey **	root_ls,
		uint_fast32_t	rootnum
	)

Load client certificate chain and trusted roots into pktctrl key certificate storage struct.

Parameters

[in,out]	store	Pointer to an initialized/client pktctrl key certificate storage struct.
[in]	cert_ls	Array of pointers to loaded pktlab certificate structs to be loaded as the client certificate chain.
[in]	certnum	The number of certificates being loaded.
[in]	root_ls	Array of pointers to loaded pktlab public key structs to be loaded as the remote party certificate chain trusted roots.
[in]	rootnum	The number of public keys being loaded.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

When an initialized pktctrl key certificate storage struct is called with pktctrl_set_client_keycert() successfully, the key certificate storage is marked as a "client" key certificate storage and can only be used with pktctrl_connect() afterwards for TLS client-side connection establishment.
The loaded cert_ls and root_ls are used to perform the TLS handshake. Note no ordering on cert_ls is needed EXCEPT the first certificate should contain the public key corresponding to clientkey in pktctrl_connect(). No ordering on root_ls is needed.
It is allowed for cert_ls to be NULL. This will result in not supplying any client certificate during the TLS handshake.
It is allowed for root_ls to be NULL as well. This will result in accepting whatever root the server certificate chain contains during the TLS handshake (the certificate chain form is still checked).
Certificate struct(s) in cert_ls (and cert_ls itself) and public key struct(s) in root_ls (and root_ls itself) must not go out of scope/freed when store is still being used as they are not copied by this function into store.
When cert_ls/root_ls is NULL, certnum/rootnum must be 0 and vice versa.
See also pktctrl_create_keycert_store(), pktctrl_get_client_keycert(), pktctrl_clear_client_keycert(), pktctrl_cleanup_keycert_store().

◆ pktctrl_set_server_keycert()

int pktctrl_set_server_keycert	(	struct pktctrl_keycert_store *	store,
		const char *	snikey,
		struct pktlab_certificate **	cert_ls,
		uint_fast32_t	certnum,
		struct pktlab_publickey **	root_ls,
		uint_fast32_t	rootnum
	)

Load server certificate chain and trusted roots for some snikey into pktctrl key certificate storage struct.

Parameters

[in,out]	store	Pointer to an initialized/server pktctrl key certificate storage struct.
[in]	snikey	Pointer to the target '\0'-terminated snikey.
[in]	cert_ls	Array of pointers to loaded pktlab certificate structs to be loaded as the server certificate chain.
[in]	certnum	The number of certificates being loaded.
[in]	root_ls	Array of pointers to loaded pktlab public key structs to be loaded as the remote party certificate chain trusted roots.
[in]	rootnum	The number of public keys being loaded.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_MAP_ERR for internal map error.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

store should be freed after pktctrl_set_server_keycert() returned PKTCTRL_MAP_ERR.
When an initialized pktctrl key certificate storage struct is called with pktctrl_set_server_keycert() successfully, the key certificate storage is marked as a "server" key certificate storage and can only be used with pktctrl_accept() afterwards for TLS server-side connection establishment.
Effectively, each successful non-NULL cert_ls call will result in an insertion/update of an entry (key being the snikey while values being cert_ls and root_ls) in the internal storage map. Afterwards, when supplying the storage to pktctrl_accept() call, the internal map is looked up to see if there is an entry matching the incoming TLS client supplied snikey. If such an entry exists, the corresponding cert_ls and root_ls is used to perform the TLS handshake. Note if no such entry exists, the handshake is failed. No ordering on cert_ls is needed EXCEPT the first certificate should contain the public key corresponding to serverkey in pktctrl_accept(). No ordering on root_ls is needed.
OTOH, for successful NULL cert_ls calls (root_ls must be NULL in these kind of calls), the corresponding entry is deleted for the supplied snikey.
It is allowed for root_ls to be NULL for the non-NULL cert_ls case. This will result in accepting whatever root the client certificate chain contains during the TLS handshake (the certificate chain form is still checked).
Certificate struct(s) in cert_ls (and cert_ls itself) and public key struct(s) in root_ls (and root_ls itself) must not go out of scope/freed when store is still being used as they are not copied by this function into store.
When cert_ls/root_ls is NULL, certnum/rootnum must be 0 and vice versa.
See also pktctrl_create_keycert_store(), pktctrl_get_server_keycert(), pktctrl_clear_server_keycert(), pktctrl_set_server_keycert_default(), pktctrl_clear_server_keycert_default(), pktctrl_cleanup_keycert_store().

◆ pktctrl_set_server_keycert_default()

int pktctrl_set_server_keycert_default	(	struct pktctrl_keycert_store *	store,
		const char *	snikey
	)

Set server pktctrl key certificate storage default entry.

Parameters

[in,out]	store	Pointer to a server pktctrl key certificate storage struct.
[in]	snikey	Pointer to the target '\0'-terminated snikey.

Returns

An enum pktctrl_err value:

PKTCTRL_SUCCESS for success.
PKTCTRL_INVAL for bad argument.
PKTCTRL_KEY_NOT_FOUND for snikey not present in internal map.
PKTCTRL_UNKNOWN_FAULT for other unknown errors.

Note when setting a snikey to be the default entry, whenever an incoming TLS client forgoes providing any snikey for TLS handshake, the cert_ls and root_ls for the set snikey entry is used to continue the handshake.
Subsequent successful pktctrl_set_server_keycert_default() call overwrites the set default entry.
Setting default entry is not required prior to calling pktctrl_accept().
See also pktctrl_create_keycert_store(), pktctrl_set_server_keycert(), pktctrl_get_server_keycert(), pktctrl_clear_server_keycert(), pktctrl_clear_server_keycert_default(), pktctrl_cleanup_keycert_store().

◆ pktctrl_write()

ssize_t pktctrl_write	(	struct pktctrl_obj *	obj,
		const void *	buf,
		size_t	nbyte
	)

Write bytes to established pktctrl session.

Parameters

[in,out]	obj	Pointer to an established pktctrl session object struct.
[in]	buf	Target write bytes.
[in]	buflen	Attempted write length (must be > 0).

Returns: The number of bytes written, or < 0 for error (see errno for more information).

pktctrl_write() should not be called after calling pktctrl_write_message() with obj.
To write pktlab protocol messages, pktctrl_write_message() is recommended instead.

◆ pktctrl_write_message()

int pktctrl_write_message	(	struct pktctrl_obj *	ctrlobj,
		const struct pktlab_message *	msg
	)

Write pktctrl message to established pktctrl session.

Parameters

[in,out]	ctrlobj	Pointer to an established pktctrl session object struct.
[in]	msg	Pointer to a fields-set msg struct.

pktctrl_write_message() functions the same as pktlab_write_message() except passing in an established pktctrl session object struct than a writer. Note one does not need to create a writer for ctrlobj as an internal one is used.
See pktlab_write_message() for more information on behavior.

◆ pktctrl_write_unsent()

size_t pktctrl_write_unsent ( const struct pktctrl_obj * ctrlobj )

Get established pktctrl session internal writer buffered content length.

Parameters

[in] ctrlobj Pointer to an established pktctrl session object struct.

pktctrl_write_unsent() functions the same as pktlab_writer_unsent() except passing in an established pktctrl session object struct than a writer. Note one does not need to create a writer for ctrlobj as an internal one is used.
See pktlab_writer_unsent() for more information on behavior.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PKTCTRL_SNIKEY_LEN_MAX

Function Documentation

◆ pktctrl_accept()

◆ pktctrl_cleanup_keycert_store()

◆ pktctrl_clear_client_keycert()

◆ pktctrl_clear_server_keycert()

◆ pktctrl_clear_server_keycert_default()

◆ pktctrl_close()

◆ pktctrl_connect()

◆ pktctrl_create_keycert_store()

◆ pktctrl_create_obj()

◆ pktctrl_flush_write()

◆ pktctrl_gen_snikey()

◆ pktctrl_get_client_keycert()

◆ pktctrl_get_server_keycert()

◆ pktctrl_is_established()

◆ pktctrl_is_valid_snikey()

◆ pktctrl_prepare_select()

◆ pktctrl_process_select()

◆ pktctrl_raw_session()

◆ pktctrl_read()

◆ pktctrl_read_message()

◆ pktctrl_set_client_keycert()

◆ pktctrl_set_server_keycert()

◆ pktctrl_set_server_keycert_default()

◆ pktctrl_write()

◆ pktctrl_write_message()

◆ pktctrl_write_unsent()