General utilities for pktlab. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include <arpa/inet.h>
#include <sys/time.h>
#include <sys/uio.h>

Include dependency graph for pktlab.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	pktlab_xdescr_dattr_pair
	Structure for encoding/decoding experiment descriptor (xdescr)/endpoint attribute (dattr) in xpub and xsub messages. More...

struct	pktlab_channel
	Structure for encoding/decoding channel lists in xpub and xsub messages. More...

struct	pktlab_uri
	Structure for storing decoded pktlab URI information. More...

struct	pktlab_vmem_region

struct	pktlab_message
	Structure for storing the decoded form of pktlab messages. More...

struct	pktlab_cert_info
	Structure for storing decoded pktlab certificate information. More...

Macros
#define	PKTLAB_IP4_ADDR_LEN PKTLAB_IPV4_WO_MSK_ADDR_LEN

#define	PKTLAB_IP4_MASK_LEN (PKTLAB_IPV4_W_MSK_ADDR_LEN-PKTLAB_IPV4_W_MSK_ADDR_LEN)

#define	PKTLAB_IP6_ADDR_LEN PKTLAB_IPV6_ADDR_LEN

#define	PKTLAB_IPV4_W_MSK_ADDR_LEN 8

#define	PKTLAB_IPV4_WO_MSK_ADDR_LEN 4

#define	PKTLAB_IPV6_ADDR_LEN 16

#define	PKTLAB_ADDRLEN_MAX PKTLAB_IP6_ADDR_LEN

#define	PKTLAB_PORTLEN_MAX 2

#define	PKTLAB_DEFAULT_ADDR_STR "127.0.0.1"

#define	PKTLAB_DEFAULT_EXP_PORT_STR "20556"
	Default controller experiment listening port string.

#define	PKTLAB_DEFAULT_PUB_PORT_STR "20556"
	Default broker experiment publication port string.

#define	PKTLAB_DEFAULT_SUB_PORT_STR "20557"
	Default broker experiment subscription port string.

#define	PKTLAB_DEFAULT_SPEC_STR PKTLAB_DEFAULT_ADDR_STR ":" PKTLAB_DEFAULT_EXP_PORT_STR

#define	PKTLAB_MAX_SKT_CNT 0x100
	Endpoint maximum pktlab socket count.

#define	PKTLAB_MAX_LADDR_CNT 0x100
	Endpoint maximum exportable local addresses.

#define	PKTLAB_MAX_LDNSADDR_CNT 0x10
	Endpoint maximum exportable local DNS addresses.

#define	PKTLAB_SHA256_DIGEST_LEN 32

#define	PKTLAB_ED25519_SIG_LEN 64

#define	PKTLAB_TICKS_PER_SECOND UINT64_C(1000000000)

#define	PKTLAB_TIME_MAX UINT64_MAX

#define	PKTLAB_XDESCR_DATTR_PAIR_SEP '='

#define	PKTLAB_XDESCR_DATTR_PAIR_END ';'

#define	PKTLAB_XDESCR_DATTR_NAMELEN_MIN 0x1
	Minimum xdescr/dattr pair name length.

#define	PKTLAB_XDESCR_DATTR_NAMELEN_MAX 0x20
	Maximum xdescr/dattr pair name length.

#define	PKTLAB_XDESCR_DATTR_VALUELEN_MIN 0x1
	Minimum xdescr/dattr pair value length.

#define	PKTLAB_XDESCR_DATTR_VALUELEN_MAX 0x100
	Maximum xdescr/dattr pair value length.

#define	PKTLAB_CHANNELID_LEN_MIN 1

#define	PKTLAB_CHANNELID_LEN_MAX PKTLAB_SHA256_DIGEST_LEN

#define	PKTLAB_VMEMADDR_CURPKT (0x0)

#define	PKTLAB_VMEMADDR_CURPKT_DATA (PKTLAB_VMEMADDR_CURPKT)

#define	PKTLAB_VMEMADDR_CURPKT_LEN (PKTLAB_VMEMADDR_CURPKT+0x1000000)

#define	PKTLAB_VMEMADDR_CURPKT_SKTID (PKTLAB_VMEMADDR_CURPKT+0x1000010)

#define	PKTLAB_VMEMADDR_CURPKT_SL (0x1000011)

#define	PKTLAB_VMEMADDR_CURPKT_DATA_FL (sizeof(uint8_t)*0x1000000)

#define	PKTLAB_VMEMADDR_CURPKT_LEN_FL (sizeof(uint32_t))

#define	PKTLAB_VMEMADDR_CURPKT_SKTID_FL (sizeof(uint8_t))

#define	PKTLAB_VMEMADDR_SYSPARAM (0x10000000)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4NO (PKTLAB_VMEMADDR_SYSPARAM)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6NO (PKTLAB_VMEMADDR_SYSPARAM+0x1)

#define	PKTLAB_VMEMADDR_SYSPARAM_TRANSSUP (PKTLAB_VMEMADDR_SYSPARAM+0x2)

#define	PKTLAB_VMEMADDR_SYSPARAM_BUFMAXDUP (PKTLAB_VMEMADDR_SYSPARAM+0x6)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4LS (PKTLAB_VMEMADDR_SYSPARAM+0x100)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6LS (PKTLAB_VMEMADDR_SYSPARAM+0x1000)

#define	PKTLAB_VMEMADDR_SYSPARAM_TIME (PKTLAB_VMEMADDR_SYSPARAM+0x10000)

#define	PKTLAB_VMEMADDR_SYSPARAM_BUFMAX (PKTLAB_VMEMADDR_SYSPARAM+0x10010)

#define	PKTLAB_VMEMADDR_SYSPARAM_BUFUSED (PKTLAB_VMEMADDR_SYSPARAM+0x10014)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4DNSNO (PKTLAB_VMEMADDR_SYSPARAM+0x20000)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6DNSNO (PKTLAB_VMEMADDR_SYSPARAM+0x20001)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4DNSLS (PKTLAB_VMEMADDR_SYSPARAM+0x20010)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6DNSLS (PKTLAB_VMEMADDR_SYSPARAM+0x20100)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4HDRMOD (PKTLAB_VMEMADDR_SYSPARAM+0x20200)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6HDRMOD (PKTLAB_VMEMADDR_SYSPARAM+0x20210)

#define	PKTLAB_VMEMADDR_SYSPARAM_HOSTID (PKTLAB_VMEMADDR_SYSPARAM+0x30000)

#define	PKTLAB_VMEMADDR_SYSPARAM_LATLONG (PKTLAB_VMEMADDR_SYSPARAM+0x30100)

#define	PKTLAB_VMEMADDR_SYSPARAM_OSINFO (PKTLAB_VMEMADDR_SYSPARAM+0x30200)

#define	PKTLAB_VMEMADDR_SYSPARAM_SL (0x30400)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4NO_FL (sizeof(uint8_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6NO_FL (sizeof(uint8_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_TRANSSUP_FL (sizeof(uint32_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4LS_FL (sizeof(uint8_t)PKTLAB_IPV4_W_MSK_ADDR_LEN0x100)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6LS_FL (sizeof(uint8_t)PKTLAB_IPV6_ADDR_LEN0x100)

#define	PKTLAB_VMEMADDR_SYSPARAM_TIME_FL (sizeof(pktlab_time_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_BUFMAX_FL (sizeof(uint32_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_BUFUSED_FL (sizeof(uint32_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4DNSNO_FL (sizeof(uint8_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6DNSNO_FL (sizeof(uint8_t))

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4DNSLS_FL (sizeof(uint8_t)PKTLAB_IPV4_WO_MSK_ADDR_LEN0x10)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6DNSLS_FL (sizeof(uint8_t)PKTLAB_IPV6_ADDR_LEN0x10)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP4HDRMOD_FL (sizeof(uint8_t)*0xC)

#define	PKTLAB_VMEMADDR_SYSPARAM_IP6HDRMOD_FL (sizeof(uint8_t)*0x8)

#define	PKTLAB_VMEMADDR_SYSPARAM_HOSTID_FL (sizeof(char)*0x100)

#define	PKTLAB_VMEMADDR_SYSPARAM_LATLONG_FL (sizeof(char)*0x40)

#define	PKTLAB_VMEMADDR_SYSPARAM_OSINFO_FL (sizeof(char)*0x200)

#define	PKTLAB_VMEMADDR_SKTINFO (0x20000000)

#define	PKTLAB_VMEMADDR_SKTINFO_BLKLEN (0x400)

#define	PKTLAB_VMEMADDR_SKTINFO_FAMILY (0x0)

#define	PKTLAB_VMEMADDR_SKTINFO_PROTO (0x1)

#define	PKTLAB_VMEMADDR_SKTINFO_STAT (0x2)

#define	PKTLAB_VMEMADDR_SKTINFO_LADDR (0x10)

#define	PKTLAB_VMEMADDR_SKTINFO_RADDR (0x20)

#define	PKTLAB_VMEMADDR_SKTINFO_LPORT (0x30)

#define	PKTLAB_VMEMADDR_SKTINFO_RPORT (0x32)

#define	PKTLAB_VMEMADDR_SKTINFO_RBUFSZ (0x40)

#define	PKTLAB_VMEMADDR_SKTINFO_RBUFUSED (0x44)

#define	PKTLAB_VMEMADDR_SKTINFO_DROPSTAT (0x50)

#define	PKTLAB_VMEMADDR_SKTINFO_NSENDERR (0x60)

#define	PKTLAB_VMEMADDR_SKTINFO_NSENDERRTAG (0x61)

#define	PKTLAB_VMEMADDR_SKTINFO_NOTIFMASK (0x70)

#define	PKTLAB_VMEMADDR_SKTINFO_CTFL (0x100)

#define	PKTLAB_VMEMADDR_SKTINFO_SL (PKTLAB_VMEMADDR_SKTINFO_BLKLEN*0x100)

#define	PKTLAB_VMEMADDR_SKTINFO_PROTO_FL (sizeof(uint8_t))

#define	PKTLAB_VMEMADDR_SKTINFO_STAT_FL (sizeof(int8_t))

#define	PKTLAB_VMEMADDR_SKTINFO_LADDR_FL (sizeof(uint8_t)*PKTLAB_ADDRLEN_MAX)

#define	PKTLAB_VMEMADDR_SKTINFO_RADDR_FL (sizeof(uint8_t)*PKTLAB_ADDRLEN_MAX)

#define	PKTLAB_VMEMADDR_SKTINFO_LPORT_FL (sizeof(uint16_t))

#define	PKTLAB_VMEMADDR_SKTINFO_RPORT_FL (sizeof(uint16_t))

#define	PKTLAB_VMEMADDR_SKTINFO_RBUFSZ_FL (sizeof(uint32_t))

#define	PKTLAB_VMEMADDR_SKTINFO_RBUFUSED_FL (sizeof(uint32_t))

#define	PKTLAB_VMEMADDR_SKTINFO_DROPSTAT_FL (sizeof(uint32_t)*2)

#define	PKTLAB_VMEMADDR_SKTINFO_NSENDERR_FL (sizeof(int8_t))

#define	PKTLAB_VMEMADDR_SKTINFO_NSENDERRTAG_FL (sizeof(uint16_t))

#define	PKTLAB_VMEMADDR_SKTINFO_NOTIFMASK_FL (sizeof(uint16_t))

#define	PKTLAB_VMEMADDR_SKTINFO_CTFL_FL (sizeof(uint8_t)*0x80)

#define	PKTLAB_VMEMADDR_NSENDTSTP (0x30000000)

#define	PKTLAB_VMEMADDR_MONSCRATCH (0x40000000)

#define	PKTLAB_VMEMADDR_MONPERSIST (0x50000000)

#define	PKTLAB_VMEMADDR_NSENDTSTP_SL (sizeof(pktlab_time_t)*0x10000)

#define	PKTLAB_VMEMADDR_MONSCRATCH_SL (sizeof(uint8_t)*0x10000000)

#define	PKTLAB_VMEMADDR_MONPERSIST_SL (sizeof(uint8_t)*0x10000000)

#define	PKTLAB_RAW_SUP_BIT_INDX 0

#define	PKTLAB_TCP_SUP_BIT_INDX 1

#define	PKTLAB_UDP_SUP_BIT_INDX 2

#define	PKTLAB_NOTIFMASK_NTAG (0x1 << 1)

#define	PKTLAB_NOTIFMASK_NSTAT (0x1 << 2)

#define	PKTLAB_NOTIFMASK_NDATA (0x1 << 3)

#define	PKTLAB_NOTIFMASK_NDROP (0x1 << 4)

#define	PKTLAB_MREAD_MAX UINT32_C(0x10000)

#define	PKTLAB_NDATA_MAX UINT32_C(0x10000)

#define	PKTLAB_IP4_PROTO 0x4
	Defined IPv4 protocol family value. More...

#define	PKTLAB_IP6_PROTO 0x6
	Defined IPv6 protocol family value. More...

#define	PKTLAB_RAW_PROTO 0x00
	Defined raw socket protocol value. More...

#define	PKTLAB_TCP_PROTO 0x06
	Defined TCP socket protocol value. More...

#define	PKTLAB_UDP_PROTO 0x11
	Defined UDP socket protocol value. More...

#define	PKTLAB_NCTL_TCP_FIN 0x1
	Defined nctl TCP fin command. More...

#define	PKTLAB_TCPEV_ESTABLISHED 0x0
	Defined nstat code value - TCP connection established event.

#define	PKTLAB_TCPEV_RESET 0x1
	Defined nstat code value - TCP connection reset event.

#define	PKTLAB_TCPEV_TIMEOUT 0x2
	Defined nstat code value - TCP connection timeout event.

#define	PKTLAB_TCPEV_PEERCLOSED 0x3
	Defined nstat code value - TCP connection peer closed event.

#define	PKTLAB_TCPEV_UNKNOWN 0xFF
	Defined nstat code value - TCP connection unknown event.

#define	PKTLAB_HLEN 4
	Encoded pktlab message header length.

#define	PKTLAB_ENCODE_IOVCNT 5
	Minimum required iovec elements for pktlab_encode_message().

#define	PKTLAB_ENCODE_BUFSZ (PKTLAB_HLEN+32)
	Minimum required buffer size for pktlab_encode_message().

#define	PKTLAB_PUBLICKEY_LEN 32
	Raw public key length for pktlab keys in bytes. More...

#define	PKTLAB_PRIVATEKEY_LEN 32
	Raw private key length for pktlab keys in bytes. More...

#define	PKTLAB_KEYID_LEN PKTLAB_SHA256_DIGEST_LEN
	Key identifier length for pktlab keys in bytes. More...

#define	PKTLAB_SIGNATURE_LEN PKTLAB_ED25519_SIG_LEN
	Raw signature length for pktlab keys in bytes. More...

#define	PKTLAB_DEL_TYPE_EXPPRIV 0x1
	Defined delegated privilege type value - experiment privilege.

#define	PKTLAB_DEL_TYPE_REPPRIV 0x2
	Defined delegated privilege type value - representation privilege.

#define	PKTLAB_FILTER_DIGEST_LEN PKTLAB_SHA256_DIGEST_LEN
	pktlab filter program digest length. More...

#define	PKTLAB_MONITOR_DIGEST_LEN PKTLAB_SHA256_DIGEST_LEN
	pktlab monitor program digest length. More...

#define	PKTLAB_EXT_CERT_TYPE "1.2.3.1"

#define	PKTLAB_EXT_CERT_DESCRIPTION "1.2.3.3"

#define	PKTLAB_EXT_FILTER_DIGESTS "1.2.3.5"

#define	PKTLAB_EXT_MONITOR_DIGESTS "1.2.3.6"

#define	PKTLAB_EXT_PRIORITY "1.2.3.7"

#define	PKTLAB_EXT_DEL_TYPE "1.2.3.8"

#define	PKTLAB_CERTTYPE_STR_SUBCMD "subcmd"

#define	PKTLAB_CERTTYPE_STR_PUBCMD "pubcmd"

#define	PKTLAB_CERTTYPE_STR_EXPPRIV "exppriv"

#define	PKTLAB_CERTTYPE_STR_DELPRIV "delpriv"

#define	PKTLAB_CERTTYPE_STR_AGENT "agent"

#define	PKTLAB_CERTTYPE_STR_UNKNOWN "unknown"

#define	pktlab_get16n pktlab_get16b

#define	pktlab_get24n pktlab_get24b

#define	pktlab_get32n pktlab_get32b

#define	pktlab_get64n pktlab_get64b

#define	pktlab_set16n pktlab_set16b

#define	pktlab_set24n pktlab_set24b

#define	pktlab_set32n pktlab_set32b

#define	pktlab_set64n pktlab_set64b

Typedefs
typedef uint64_t	pktlab_time_t
	Variable type for pktlab time. More...

typedef void(*	pktlab_vmem_reader_t) (const struct pktlab_vmem_region restrict rgn, uint_fast32_t off, uint_fast32_t len, void restrict dst)

typedef void(*	pktlab_vmem_writer_t) (const struct pktlab_vmem_region restrict rgn, uint_fast32_t off, uint_fast32_t len, const void restrict src)

typedef ssize_t(*	pktlab_read_t) (void aux, void buf, size_t buflen)
	Function pointer type for reader read function. More...

typedef ssize_t(*	pktlab_write_t) (void aux, const void buf, size_t nbyte)
	Function pointer type for writer write function. More...

Enumerations
enum	pktlab_filter_type { PKTLAB_CBPF = 0x0 , PKTLAB_EBPF = 0x1 }
	pktlab defined filter types. More...

enum	pktlab_uri_type { EXP_URI_TYPE = 0 , BROKER_URI_TYPE = 1 , MALFORMED_URI_TYPE = -1 }
	pktlab defined URI types. More...

enum	pktlab_rawhdr_info { PKTLAB_RAWHDR_NOCHG = 0 , PKTLAB_RAWHDR_CHG = 1 , PKTLAB_RAWHDR_0FILL = 2 }

enum	pktlab_socket_state { PKTLAB_SKTST_FREE = 0 , PKTLAB_SKTST_OPENING = 1 , PKTLAB_SKTST_OPEN = 2 , PKTLAB_SKTST_EOF = 3 , PKTLAB_SKTST_WFIN = 4 , PKTLAB_SKTST_END = 5 , PKTLAB_SKTST_REFUSED = -1 , PKTLAB_SKTST_RESET = -2 , PKTLAB_SKTST_TIMEDOUT = -3 , PKTLAB_SKTST_UNREACH = -4 , PKTLAB_SKTST_UNKFAULT = -128 }

enum	pktlab_nsend_err { PKTLAB_NSEND_SUCCESS = 0 , PKTLAB_NSEND_NORES = 1 , PKTLAB_NSEND_BADPKT = 2 , PKTLAB_NSEND_TIMEDOUT = 3 , PKTLAB_NSEND_RESET = 4 , PKTLAB_NSEND_UNREACH = 5 , PKTLAB_NSEND_WFIN = 6 , PKTLAB_NSEND_UNKFAULT = 127 }

enum	pktlab_message_type { PKTLAB_UNDEF_MESSAGE = 0x00 , PKTLAB_CDATA_MESSAGE = 0x20 , PKTLAB_START_MESSAGE = 0x21 , PKTLAB_END_MESSAGE = 0x22 , PKTLAB_YIELD_MESSAGE = 0X23 , PKTLAB_CONT_MESSAGE = 0X24 , PKTLAB_MREAD_MESSAGE = 0x28 , PKTLAB_MWRITE_MESSAGE = 0x29 , PKTLAB_NOPEN_MESSAGE = 0x2A , PKTLAB_NCLOSE_MESSAGE = 0x2B , PKTLAB_NSEND_MESSAGE = 0x2C , PKTLAB_NCAP_MESSAGE = 0x2D , PKTLAB_NCTL_MESSAGE = 0x2E , PKTLAB_XCERT_MESSAGE = 0x30 , PKTLAB_XPUB_MESSAGE = 0x31 , PKTLAB_XSUB_MESSAGE = 0x38 , PKTLAB_RESULT_MESSAGE = 0x40 , PKTLAB_MDATA_MESSAGE = 0x41 , PKTLAB_NTAG_MESSAGE = 0x60 , PKTLAB_NSTAT_MESSAGE = 0x61 , PKTLAB_NDATA_MESSAGE = 0x62 , PKTLAB_NDROP_MESSAGE = 0x63 , PKTLAB_SUSPD_MESSAGE = 0x68 , PKTLAB_RESUMD_MESSAGE = 0x69 , PKTLAB_XNOTIFY_MESSAGE = 0x70 , PKTLAB_XREG_MESSAGE = 0x80 }
	pktlab defined message types. More...

enum	pktlab_status { PKTLAB_SUCCESS = 0 , PKTLAB_ECTLBADMSG = 0x10 , PKTLAB_ECTLNOTSUP = 0x11 , PKTLAB_ECRTNOMATCH = 0x20 , PKTLAB_ECRTATTACH = 0x21 , PKTLAB_ECRTBADFRM = 0x22 , PKTLAB_ECRTNOSPACE = 0x23 , PKTLAB_ESYSNOBUFS = 0x30 , PKTLAB_ESYSNOPERM = 0x31 , PKTLAB_ESKTINUSE = 0x32 , PKTLAB_ESKTNOTOPEN = 0x33 , PKTLAB_ESKTNOPRFAM = 0x34 , PKTLAB_ESKTNOPROTO = 0x35 , PKTLAB_ESKTNOADDR = 0x36 , PKTLAB_ESKTNOMATCH = 0x37 , PKTLAB_ESKTBADFILT = 0x38 , PKTLAB_ETCPNOPORT = 0x40 , PKTLAB_ETCPNOSEND = 0x41 , PKTLAB_EUDPNOPORT = 0x42 , PKTLAB_EPUBBADCH = 0x50 , PKTLAB_EPUBBADADDR = 0x51 , PKTLAB_EPUBBADENDT = 0x52 , PKTLAB_EPUBBADPR = 0x53 , PKTLAB_EPUBBADXD = 0x54 , PKTLAB_ESUBBADCH = 0x60 , PKTLAB_EUNKFAULT = 0xFFFF }
	pktlab defined errid values. More...

enum	pktlab_cert_type { PKTLAB_CERT_SUBCMD = 0 , PKTLAB_CERT_PUBCMD = 1 , PKTLAB_CERT_EXPPRIV = 2 , PKTLAB_CERT_DELPRIV = 3 , PKTLAB_CERT_AGENT = 4 , PKTLAB_CERT_UNKNOWN = 127 }
	pktlab defined certificate types.

enum	pktlab_decode_rst { PKTLAB_DECODE_SUCCESS = 0 , PKTLAB_DECODE_INVAL = 1 , PKTLAB_DECODE_BAD_SIGALG = 2 , PKTLAB_DECODE_BAD_SIGNATURE = 3 , PKTLAB_DECODE_BAD_X509_VER = 4 , PKTLAB_DECODE_USING_UNUSED_FIELD = 5 , PKTLAB_DECODE_BAD_CERT_TYPE = 6 , PKTLAB_DECODE_BAD_KEYUSAGE = 7 , PKTLAB_DECODE_BAD_SERIAL = 8 , PKTLAB_DECODE_BAD_VALIDITY = 9 , PKTLAB_DECODE_BAD_SUBJ_PUBKEY = 10 , PKTLAB_DECODE_BAD_AID = 11 , PKTLAB_DECODE_BAD_SID = 12 , PKTLAB_DECODE_BAD_BC = 13 , PKTLAB_DECODE_BAD_CERT_DESC = 14 , PKTLAB_DECODE_BAD_PRIORITY = 15 , PKTLAB_DECODE_BAD_FILTER_DIGESTS = 16 , PKTLAB_DECODE_BAD_MONITOR_DIGESTS = 17 , PKTLAB_DECODE_BAD_DEL_TYPE = 18 , PKTLAB_DECODE_UNKNOWN_FAULT = 127 }
	pktlab certificate decoding result values. More...

enum	pktlab_auth_mode { PKTLAB_CONTROLLER_AUTH_ENDPOINT = 0 , PKTLAB_ENDPOINT_AUTH_CONTROLLER = 1 , PKTLAB_AUTH_AGENT = 2 , PKTLAB_NO_VERIFY = 127 }
	pktlab certificate chain verification mode values. More...

enum	pktlab_verify_rst { PKTLAB_VERIFY_SUCCESS = 0 , PKTLAB_VERIFY_INVAL = 1 , PKTLAB_VERIFY_BAD_CERT = 2 , PKTLAB_VERIFY_NOT_ENOUGH_CERT = 3 , PKTLAB_VERIFY_TOO_MANY_CERT = 4 , PKTLAB_VERIFY_UNEXPECTED_CERT = 5 , PKTLAB_VERIFY_EXPIRED_CERT = 6 , PKTLAB_VERIFY_NO_MATCHING_SIGN_KEY = 7 , PKTLAB_VERIFY_PATHLEN_EXCEEDED = 8 , PKTLAB_VERIFY_END_OF_PHASES = 9 , PKTLAB_VERIFY_BAD_DEL_TYPE = 10 , PKTLAB_VERIFY_UNKNOWN_FAULT = 127 }
	pktlab certificate chain verification result values. More...

enum	pktlab_parse_cert_chain_rst { PKTLAB_PARSE_CHAIN_SUCCESS = 0 , PKTLAB_PARSE_CHAIN_INVAL = 1 , PKTLAB_PARSE_CHAIN_BAD_CHAIN = 2 , PKTLAB_PARSE_CHAIN_BAD_KEY = 3 , PKTLAB_PARSE_CHAIN_UNKNOWN_FAULT = 127 }
	pktlab certificate chain parsing result values. More...

Functions
pktlab_time_t	pktlab_time_now (void)
	Get current pktlab time. More...

static pktlab_time_t	pktlab_time_sec (uint_fast32_t sec)
	Convert seconds to pktlab ticks. More...

static pktlab_time_t	pktlab_timeval_to_time (const struct timeval *tv)
	Convert time period in struct timeval to pktlab ticks. More...

static void	pktlab_time_to_timeval (pktlab_time_t t, struct timeval *tv)
	Convert time period in pktlab ticks to struct timeval. More...

static uint_fast32_t	pktlab_time_to_unix_time (pktlab_time_t t)
	Convert a pktlab time to Unix time (in second precision). More...

pktlab_time_t	pktlab_tm_to_time (const struct tm *tm)
	Convert time in struct tm to pktlab time. More...

int	pktlab_decode_xdescr (const char xdescr, uint_fast32_t xdescrlen, struct pktlab_xdescr_dattr_pair pairs, uint_fast32_t paircnt)
	Decode an encoded experiment descriptor (xdescr) string. More...

int	pktlab_encode_xdescr (const struct pktlab_xdescr_dattr_pair pairs, uint_fast32_t paircnt, char buf, uint_fast32_t buflen, uint_fast32_t *used)
	Encode an experiment descriptor (xdescr) string. More...

int	pktlab_decode_dattr (const char dattr, uint_fast32_t dattrlen, struct pktlab_xdescr_dattr_pair pairs, uint_fast32_t paircnt)
	Decode an encoded endpoint attribute (dattr) string. More...

int	pktlab_encode_dattr (const struct pktlab_xdescr_dattr_pair pairs, uint_fast32_t paircnt, char buf, uint_fast32_t buflen, uint_fast32_t *used)
	Encode an endpoint attribute (dattr) string. More...

bool	pktlab_xdescr_dattr_match (const char xdescr, uint_fast32_t xdescrlen, const char dattr, uint_fast32_t dattrlen)
	Match an experiment descriptor (xdescr) string to an endpoint attribute (dattr) string. More...

int	pktlab_encode_chlist (const struct pktlab_channel channels, void chlistptr, uint_fast32_t chlistlen)
	Encode a channel list. More...

int	pktlab_decode_chlist (const void chlistptr, uint_fast32_t chlistlen, struct pktlab_channel *channels)
	Decode a channel list. More...

void	pktlab_free_channels (struct pktlab_channel *channels)
	Free an allocated channel linked list. More...

int	pktlab_parse_uri (struct pktlab_uri restrict uri_info, const void restrict ptr, uint_fast32_t len)
	Decode a pktlab URI. More...

void	pktlab_vmem_read (const struct pktlab_vmem_region restrict rgn, uint_fast32_t rgncnt, uint_fast32_t addr, uint_fast32_t len, void restrict dst)

void	pktlab_vmem_write (const struct pktlab_vmem_region restrict rgn, uint_fast32_t rgncnt, uint_fast32_t addr, uint_fast32_t len, const void restrict src)

void	pktlab_buffer_reader (const struct pktlab_vmem_region restrict rgn, uint_fast32_t addr, uint_fast32_t len, void restrict dst)

void	pktlab_buffer_writer (const struct pktlab_vmem_region restrict rgn, uint_fast32_t addr, uint_fast32_t len, const void restrict src)

size_t	pktlab_decode_message (struct pktlab_message restrict msg, const void restrict ptr, size_t len)
	Decode pktlab message. More...

int	pktlab_encode_message (const struct pktlab_message restrict msg, void restrict buf, struct iovec *restrict iov)
	Encode pktlab message. More...

struct pktlab_message *	pktlab_create_result_message (enum pktlab_status status)
	Get fields-set pktlab result message. More...

struct pktlab_reader *	pktlab_create_reader (pktlab_read_t read, void *aux)
	Get initialized pktlab reader struct. More...

void	pktlab_close_reader (struct pktlab_reader *r)
	Close and free pktlab reader struct. More...

void *	pktlab_reader_readaux (const struct pktlab_reader *r)
	Get pktlab reader struct aux information. More...

int	pktlab_read_message (struct pktlab_reader restrict r, struct pktlab_message *restrict msgptr)
	pktlab reader read message. More...

struct pktlab_writer *	pktlab_create_writer (pktlab_write_t write, void *aux)
	Get initialized pktlab writer struct. More...

void	pktlab_close_writer (struct pktlab_writer *w)
	Close and free pktlab writer struct. More...

int	pktlab_flush_writer (struct pktlab_writer *w)
	Flush pktlab writer internal buffer. More...

size_t	pktlab_writer_unsent (const struct pktlab_writer *w)
	Get writer internal buffered content length. More...

void *	pktlab_writer_writeaux (const struct pktlab_writer *w)
	Get pktlab writer struct aux information. More...

int	pktlab_write_message (struct pktlab_writer restrict w, const struct pktlab_message restrict msg)
	pktlab writer write message. More...

const char *	pktlab_sktstate_name (enum pktlab_socket_state state)
	Get text description of pktlab endpoint skt state. More...

struct pktlab_publickey *	pktlab_create_publickey (void)
	Allocate initialized pktlab public key struct. More...

int	pktlab_load_publickey_pem (const char pem, uint_fast32_t pemlen, struct pktlab_publickey k)
	Load pktlab public key struct via PEM-encoded public key char array. More...

int	pktlab_load_publickey_der (const uint8_t der, uint_fast32_t derlen, struct pktlab_publickey k)
	Load pktlab public key struct via raw SubjectPublicKeyInfo byte array. More...

int	pktlab_load_publickey_raw (const uint8_t bytes, uint_fast32_t len, struct pktlab_publickey k)
	Load pktlab public key struct via raw public key byte array. More...

int	pktlab_cleanup_publickey (struct pktlab_publickey *k)
	Free an allocated pktlab public key struct. More...

int	pktlab_get_publickey_bytes (const struct pktlab_publickey k, void buf, uint_fast32_t buflen)
	Get raw public key byte array from loaded pktlab public key struct. More...

int	pktlab_get_key_identifier (const struct pktlab_publickey k, void buf, uint_fast32_t buflen)
	Get key identifier for a loaded pktlab public key struct. More...

struct pktlab_privatekey *	pktlab_create_privatekey (void)
	Allocate initialized pktlab private key struct. More...

int	pktlab_load_privatekey_pem (const char pem, uint_fast32_t pemlen, const char passphrase, struct pktlab_privatekey *k)
	Load pktlab private key struct via PEM-encoded private key char array. More...

int	pktlab_load_privatekey_der (const uint8_t der, uint_fast32_t derlen, const char passphrase, struct pktlab_privatekey *k)
	Load pktlab private key struct via raw PKCS8 byte array. More...

int	pktlab_load_privatekey_raw (const uint8_t bytes, uint_fast32_t len, struct pktlab_privatekey k)
	Load pktlab private key struct via raw private key byte array. More...

int	pktlab_cleanup_privatekey (struct pktlab_privatekey *k)
	Free an allocated pktlab private key struct. More...

int	pktlab_get_privatekey_bytes (const struct pktlab_privatekey k, void buf, uint_fast32_t buflen)
	Get raw private key byte array from loaded pktlab private key struct. More...

struct pktlab_publickey *	pktlab_get_publickey_from_privatekey (const struct pktlab_privatekey *k)
	Get loaded pktlab public key struct from loaded pktlab private key struct. More...

struct pktlab_certificate *	pktlab_create_cert (void)
	Allocate initialized pktlab certificate struct. More...

int	pktlab_load_cert_pem (const char pem, uint_fast32_t pemlen, struct pktlab_certificate cert)
	Load pktlab certificate struct via PEM-encoded pktlab certificate char array. More...

int	pktlab_load_cert_der (const uint8_t der, uint_fast32_t derlen, struct pktlab_certificate cert)
	Load pktlab certificate struct via DER-encode pktlab certificate byte array. More...

int	pktlab_get_cert_der (const struct pktlab_certificate cert, void der, uint_fast32_t derlen)
	Get DER-encoded pktlab certificate bytes from loaded pktlab certificate struct. More...

int	pktlab_decode_certificate (const struct pktlab_certificate cert, const struct pktlab_publickey signkey, struct pktlab_cert_info **ptr)
	Decode pktlab certificate information from loaded pktlab certificate struct. More...

int	pktlab_verify_certificate_signature (const struct pktlab_certificate cert, const struct pktlab_publickey signkey)
	Verify the pktlab certificate signature. More...

int	pktlab_cleanup_cert (struct pktlab_certificate *cert)
	Free an allocated pktlab certificate struct. More...

const char *	pktlab_cert_type_name (int cert_type)
	Get pktlab certificate type string from pktlab certificate type value. More...

int	pktlab_cert_type_name_to_id (const char *name)
	Get pktlab certificate type value from pktlab certificate type string. More...

int	pktlab_get_agent_key (const struct pktlab_certificate agent_cert, uint8_t agent_pubkey)
	Get pktlab agent certificate subject (signee) public key. More...

int	pktlab_verify_cert_chain (int auth_mode, struct pktlab_certificate cert_ls, struct pktlab_publickey root_ls, struct pktlab_certificate **verified_cert_ls, uint_fast32_t certnum, uint_fast32_t rootnum, uint_fast32_t verified_certnum, uint_fast32_t *used_root_indx)
	Verify pktlab certificate chain. More...

int	pktlab_parse_endpoint_rep_cert_chain (struct pktlab_certificate *cert_ls, uint_fast32_t certnum, const uint8_t endpoint_key, struct pktlab_publickey root_eop_key, uint8_t subable_channels, uint_fast32_t channelnum)
	Parse pktlab endpoint representation privilege certificate chain for subscribable channel information. More...

int	pktlab_parse_controller_exp_cert_chain (struct pktlab_certificate *cert_ls, uint_fast32_t certnum, const uint8_t controller_key, struct pktlab_publickey trusted_eop_key, uint8_t ftdigests, uint_fast32_t ftcnt, uint8_t *mtdigests, uint_fast32_t mtcnt, char **priorities, uint_fast32_t pcnt, uint8_t *subable_channel)
	Parse pktlab controller experiment privilege certificate chain for subscribable channel and experiment privilege information. More...

static uint_fast8_t	pktlab_get8 (const void *ptr)
	Get 8-bit unsigned integer from byte array. More...

static uint_fast16_t	pktlab_get16b (const void *ptr)

static uint_fast16_t	pktlab_get16l (const void *ptr)

static uint_fast32_t	pktlab_get24b (const void *ptr)

static uint_fast32_t	pktlab_get24l (const void *ptr)

static uint_fast32_t	pktlab_get32b (const void *ptr)

static uint_fast32_t	pktlab_get32l (const void *ptr)

static uint_fast64_t	pktlab_get64b (const void *ptr)

static uint_fast64_t	pktlab_get64l (const void *ptr)

static void	pktlab_set8 (void *ptr, uint_fast8_t val)
	Set 8-bit unsigned integer to byte array. More...

static void	pktlab_set16b (void *ptr, uint_fast16_t val)

static void	pktlab_set16l (void *ptr, uint_fast16_t val)

static void	pktlab_set24b (void *ptr, uint_fast32_t val)

static void	pktlab_set24l (void *ptr, uint_fast32_t val)

static void	pktlab_set32b (void *ptr, uint_fast32_t val)

static void	pktlab_set32l (void *ptr, uint_fast32_t val)

static void	pktlab_set64b (void *ptr, uint_fast64_t val)

static void	pktlab_set64l (void *ptr, uint_fast64_t val)

static uint_fast16_t	pktlab_hton16 (uint_fast16_t x)
	Convert 16-bit unsigned integer from host byte order to network byte order. More...

static uint_fast32_t	pktlab_hton32 (uint_fast32_t x)

static uint_fast64_t	pktlab_hton64 (uint_fast64_t x)

static uint_fast16_t	pktlab_ntoh16 (uint_fast16_t x)

static uint_fast32_t	pktlab_ntoh32 (uint_fast32_t x)

static uint_fast64_t	pktlab_ntoh64 (uint_fast64_t x)

static bool	pktlab_getbit8 (uint_fast8_t bits, uint_fast8_t pos)
	Get bit from unsigned integer at bit position. More...

static bool	pktlab_getbit16 (uint_fast16_t bits, uint_fast8_t pos)

static bool	pktlab_getbit32 (uint_fast32_t bits, uint_fast8_t pos)

static bool	pktlab_getbit64 (uint_fast64_t bits, uint_fast8_t pos)

static uint_fast8_t	pktlab_setbit8 (uint_fast8_t bits, uint_fast8_t pos)
	Set bit in unsigned integer at bit position. More...

static uint_fast16_t	pktlab_setbit16 (uint_fast16_t bits, uint_fast8_t pos)

static uint_fast32_t	pktlab_setbit32 (uint_fast32_t bits, uint_fast8_t pos)

static uint_fast64_t	pktlab_setbit64 (uint_fast64_t bits, uint_fast8_t pos)

static uint_fast8_t	pktlab_clrbit8 (uint_fast8_t bits, uint_fast8_t pos)
	Clear bit in unsigned integer at bit position. More...

static uint_fast16_t	pktlab_clrbit16 (uint_fast16_t bits, uint_fast8_t pos)

static uint_fast32_t	pktlab_clrbit32 (uint_fast32_t bits, uint_fast8_t pos)

static uint_fast64_t	pktlab_clrbit64 (uint_fast64_t bits, uint_fast8_t pos)

Detailed Description

General utilities for pktlab.

Macro Definition Documentation

◆ PKTLAB_FILTER_DIGEST_LEN

#define PKTLAB_FILTER_DIGEST_LEN PKTLAB_SHA256_DIGEST_LEN

pktlab filter program digest length.

In pktlab, the filter program digest of some filter program is the SHA256 hash of the filter program bytes.

◆ PKTLAB_IP4_PROTO

#define PKTLAB_IP4_PROTO 0x4

Defined IPv4 protocol family value.

For setting the "family" fields in the pktlab_message struct

◆ PKTLAB_IP6_PROTO

#define PKTLAB_IP6_PROTO 0x6

Defined IPv6 protocol family value.

For setting the "family" fields in the pktlab_message struct

◆ PKTLAB_KEYID_LEN

#define PKTLAB_KEYID_LEN PKTLAB_SHA256_DIGEST_LEN

Key identifier length for pktlab keys in bytes.

The key identifier for a pktlab key is the SHA-256 checksum of the pktlab key raw public key. PKTLAB_KEYID_LEN is thus the length of a SHA-256 checksum.

◆ PKTLAB_MONITOR_DIGEST_LEN

#define PKTLAB_MONITOR_DIGEST_LEN PKTLAB_SHA256_DIGEST_LEN

pktlab monitor program digest length.

In pktlab, the monitor program digest of some monitor program is the SHA256 hash of the monitor program bytes.

◆ PKTLAB_NCTL_TCP_FIN

#define PKTLAB_NCTL_TCP_FIN 0x1

Defined nctl TCP fin command.

For setting the nctl message "command" field in the pktlab_message struct.
The command requests the endpoint to shutdown the writing end of some TCP socket.

◆ PKTLAB_PRIVATEKEY_LEN

#define PKTLAB_PRIVATEKEY_LEN 32

Raw private key length for pktlab keys in bytes.

I.e. Raw Ed25519 private key length.

◆ PKTLAB_PUBLICKEY_LEN

#define PKTLAB_PUBLICKEY_LEN 32

Raw public key length for pktlab keys in bytes.

I.e. Raw Ed25519 public key length.

◆ PKTLAB_RAW_PROTO

#define PKTLAB_RAW_PROTO 0x00

Defined raw socket protocol value.

For setting the "proto" fields in the pktlab_message struct

◆ PKTLAB_SIGNATURE_LEN

#define PKTLAB_SIGNATURE_LEN PKTLAB_ED25519_SIG_LEN

Raw signature length for pktlab keys in bytes.

I.e. Raw Ed25519 signature length.

◆ PKTLAB_TCP_PROTO

#define PKTLAB_TCP_PROTO 0x06

Defined TCP socket protocol value.

For setting the "proto" fields in the pktlab_message struct

◆ PKTLAB_UDP_PROTO

#define PKTLAB_UDP_PROTO 0x11

Defined UDP socket protocol value.

For setting the "proto" fields in the pktlab_message struct

Typedef Documentation

◆ pktlab_read_t

typedef ssize_t(* pktlab_read_t) (void *aux, void *buf, size_t buflen)

Function pointer type for reader read function.

The expected behavior of a pktlab_read_t function: per function call with valid input, the function should either (1) read in x \in [1, buflen] consecutive bytes and place them in buf in order from the start of buf (returning the number of bytes read), (2) return 0 for EOF, or (3) return a negative value for other failures (potentially setting errno). If no byte is read due to the system being busy (e.g. read would block), the function should set errno to EAGAIN or EWOULDBLOCK. If no byte is read due to signal interruption, the function should set errno to EINTR.

◆ pktlab_time_t

typedef uint64_t pktlab_time_t

Variable type for pktlab time.

Note pktlab time is in pktlab ticks (1 pktlab tick = 1 nanosecond) from the Unix Epoch.

◆ pktlab_write_t

typedef ssize_t(* pktlab_write_t) (void *aux, const void *buf, size_t nbyte)

Function pointer type for writer write function.

The expected behavior of a pktlab_write_t function: per function call with valid input, the function should either send out x \in [1, nbyte] bytes stored in buf in order from the start of buf (returning the number of bytes sent) or fail with a negative return value (potentially setting errno). If no byte is sent due to the system being busy (e.g. write would block), the function should set errno to EAGAIN or EWOULDBLOCK. If no byte is sent due to signal interruption, the function should set errno to EINTR.

Enumeration Type Documentation

◆ pktlab_auth_mode

enum pktlab_auth_mode

pktlab certificate chain verification mode values.

PKTLAB_AUTH_AGENT is used for authentication between broker and controller/endpoint (both directions).

Enumerator
PKTLAB_CONTROLLER_AUTH_ENDPOINT	Controller authenticate endpoint case.
PKTLAB_ENDPOINT_AUTH_CONTROLLER	Endpoint authenticate controller case.
PKTLAB_AUTH_AGENT	Agent authentication case.
PKTLAB_NO_VERIFY	No verify case (accept all certificates and return them; USE AT YOUR OWN RISK!)

◆ pktlab_decode_rst

enum pktlab_decode_rst

pktlab certificate decoding result values.

Returned by pktlab_decode_certificate() to indicate pktlab certificate decoding result.

Enumerator
PKTLAB_DECODE_SUCCESS	Success.
PKTLAB_DECODE_INVAL	Bad arguments passed to decoding function
PKTLAB_DECODE_BAD_SIGALG	Not using Ed25519 signature algorithm. Note this is used for both signed and unsigned sigalg.
PKTLAB_DECODE_BAD_SIGNATURE	Bad cert signature.
PKTLAB_DECODE_BAD_X509_VER	Bad X509 ver.
PKTLAB_DECODE_USING_UNUSED_FIELD	Cert contains fields that should not be used.
PKTLAB_DECODE_BAD_CERT_TYPE	Bad cert type.
PKTLAB_DECODE_BAD_KEYUSAGE	Bad keyusage.
PKTLAB_DECODE_BAD_SERIAL	Bad serial.
PKTLAB_DECODE_BAD_VALIDITY	Bad validity (i.e. not_before/not_after).
PKTLAB_DECODE_BAD_SUBJ_PUBKEY	Bad subject public key.
PKTLAB_DECODE_BAD_AID	Bad authority key identifier.
PKTLAB_DECODE_BAD_SID	Bad subject key identifier.
PKTLAB_DECODE_BAD_BC	Bad basic constraints.
PKTLAB_DECODE_BAD_CERT_DESC	Bad pktlab certificate description.
PKTLAB_DECODE_BAD_PRIORITY	Bad pktlab priority string.
PKTLAB_DECODE_BAD_FILTER_DIGESTS	Bad pktlab filter digests.
PKTLAB_DECODE_BAD_MONITOR_DIGESTS	Bad pktlab monitor digests.
PKTLAB_DECODE_BAD_DEL_TYPE	Bad pktlab delegation type.
PKTLAB_DECODE_UNKNOWN_FAULT	Unknwon error during decoding.

◆ pktlab_filter_type

enum pktlab_filter_type

pktlab defined filter types.

Enumerator
PKTLAB_CBPF	Classic BPF
PKTLAB_EBPF	Extended BPF (not supported yet)

◆ pktlab_message_type

enum pktlab_message_type

pktlab defined message types.

For setting the "type" field in the pktlab_message struct.

◆ pktlab_parse_cert_chain_rst

enum pktlab_parse_cert_chain_rst

pktlab certificate chain parsing result values.

Returned by pktlab_parse_endpoint_rep_cert_chain() and pktlab_parse_controller_exp_cert_chain() to indicate pktlab certificate chain parsing result.

◆ pktlab_status

enum pktlab_status

pktlab defined errid values.

For setting the "errid" field in the pktlab_message struct.

◆ pktlab_uri_type

enum pktlab_uri_type

pktlab defined URI types.

Enumerator
EXP_URI_TYPE	Experiment controller URI type. In URI: "exp"
BROKER_URI_TYPE	Broker URI type. In URI: "broker"
MALFORMED_URI_TYPE	Malformed/unknown URI type.

◆ pktlab_verify_rst

enum pktlab_verify_rst

pktlab certificate chain verification result values.

Returned by pktlab_verify_cert_chain() to indicate pktlab certificate chain verification result.

Enumerator
PKTLAB_VERIFY_SUCCESS	Success.
PKTLAB_VERIFY_INVAL	Bad arguments passed to verification function.
PKTLAB_VERIFY_BAD_CERT	Bad certificate passed (general).
PKTLAB_VERIFY_NOT_ENOUGH_CERT	Cert chain too short (i.e. passed chain shorter than minimum chain len).
PKTLAB_VERIFY_TOO_MANY_CERT	Cert chain too long (i.e. passed chain longer than maximum chain len).
PKTLAB_VERIFY_UNEXPECTED_CERT	Cert with unexpected type appearing in chain.
PKTLAB_VERIFY_EXPIRED_CERT	Cert expired.
PKTLAB_VERIFY_NO_MATCHING_SIGN_KEY	Cannot find the signing key for a cert in the cert chain.
PKTLAB_VERIFY_PATHLEN_EXCEEDED	Pathlen constraint for a cert exceeded in the chain.
PKTLAB_VERIFY_END_OF_PHASES	No more phases left in the checking process.
PKTLAB_VERIFY_BAD_DEL_TYPE	Privilege delegation cert having incorrect delegation type.
PKTLAB_VERIFY_UNKNOWN_FAULT	Unknown fault in verification function.

Function Documentation

◆ pktlab_cert_type_name()

const char * pktlab_cert_type_name ( int cert_type )

Get pktlab certificate type string from pktlab certificate type value.

Parameters

[in] cert_type pktlab certificate type value.

Returns: Pointer to a pktlab certificate type string or NULL if undefined cert_type value.

◆ pktlab_cert_type_name_to_id()

int pktlab_cert_type_name_to_id ( const char * name )

Get pktlab certificate type value from pktlab certificate type string.

Parameters

[in] name Pointer to a '\0'-terminated pktlab certificate type string.

Returns: pktlab certificate type value corresponding to name or PKTLAB_CERT_UNKNOWN for undefined pktlab certificate type value.

◆ pktlab_cleanup_cert()

int pktlab_cleanup_cert ( struct pktlab_certificate * cert )

Free an allocated pktlab certificate struct.

Parameters

[in,out] cert Pointer to an allocated pktlab certificate struct to free.

Returns: 0 if success. < 0 if failed.

Do not call pktlab_cleanup_cert() again if failed.

◆ pktlab_cleanup_privatekey()

int pktlab_cleanup_privatekey ( struct pktlab_privatekey * k )

Free an allocated pktlab private key struct.

Parameters

[in,out] k Pointer to an allocated pktlab private key struct to free.

Returns: 0 if success. < 0 if failed.

Do not call pktlab_cleanup_privatekey() again if failed.

◆ pktlab_cleanup_publickey()

int pktlab_cleanup_publickey ( struct pktlab_publickey * k )

Free an allocated pktlab public key struct.

Parameters

[in,out] k Allocated pktlab public key struct to free.

Returns: 0 if success. < 0 if failed.

Do not call pktlab_cleanup_publickey() again if failed.

◆ pktlab_close_reader()

void pktlab_close_reader ( struct pktlab_reader * r )

Close and free pktlab reader struct.

Parameters

[in,out] r Allocated pktlab reader struct to free.

Note reader aux (passed in during pktlab_create_reader()) is not freed or closed.

◆ pktlab_close_writer()

void pktlab_close_writer ( struct pktlab_writer * w )

Close and free pktlab writer struct.

Parameters

[in,out] w Allocated pktlab writer struct to free.

Note writer aux (passed in during pktlab_create_writer()) is not freed or closed.

◆ pktlab_clrbit8()

static uint_fast8_t pktlab_clrbit8	(	uint_fast8_t	bits,
		uint_fast8_t	pos
	)

inlinestatic

Clear bit in unsigned integer at bit position.

Parameters

[in]	bits	Target unsigned interger to clear bit.
[in]	pos	Target bit position (0-indexed).

Returns: Clear result.

Note there also exist similar functions (pktlab_clrbitN) that clear bit in larger unsigned integers (N being either 16, 32, or 64).
Clearing bit for pos >= N will be ignored with unchanged bits value returned.

◆ pktlab_create_cert()

struct pktlab_certificate * pktlab_create_cert ( void )

Allocate initialized pktlab certificate struct.

Returns: Pointer to an allocated initialized pktlab certificate struct.

The allocated pktlab certificate struct should be freed with pktlab_cleanup_cert().

◆ pktlab_create_privatekey()

struct pktlab_privatekey * pktlab_create_privatekey ( void )

Allocate initialized pktlab private key struct.

Returns: Pointer to an allocated initialized pktlab private key struct.

The allocated pktlab private key struct should be freed with pktlab_cleanup_privatekey().

◆ pktlab_create_publickey()

struct pktlab_publickey * pktlab_create_publickey ( void )

Allocate initialized pktlab public key struct.

Returns: Pointer to an allocated initialized pktlab public key struct.

The allocated pktlab public key struct should be freed with pktlab_cleanup_publickey().

◆ pktlab_create_reader()

struct pktlab_reader * pktlab_create_reader	(	pktlab_read_t	read,
		void *	aux
	)

Get initialized pktlab reader struct.

Parameters

[in]	read	Read function to use for this reader.
[in]	aux	Auxiliary information needed by read.

Returns: An allocated and initialized pktlab reader struct.

Note to use read() in unistd.h with reader, one will need to wrap read() so that the fd is taken in via a pointer to an int variable storing the fd instead.
The returned allocated struct should be freed with pktlab_close_reader().
Normally, one would use the pktctrl module instead to read/recv pktlab messages rather than using the pktlab reader utilities.

◆ pktlab_create_result_message()

struct pktlab_message * pktlab_create_result_message ( enum pktlab_status status )

Get fields-set pktlab result message.

Parameters

[in] status Result message errid.

Returns: An allocated pktlab result message with errid set.

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

◆ pktlab_create_writer()

struct pktlab_writer * pktlab_create_writer	(	pktlab_write_t	write,
		void *	aux
	)

Get initialized pktlab writer struct.

Parameters

[in]	write	Write function to use for this writer.
[in]	aux	Auxiliary information needed by write.

Returns: An allocated and initialized pktlab writer struct.

Note to use write() in unistd.h with writer, one will need to wrap write() so that the fd is taken in via a pointer to an int variable storing the fd instead.
The returned allocated struct should be freed with pktlab_close_writer().
Normally, one would use the pktctrl module instead to write/send pktlab messages rather than using the pktlab writer utilities.

◆ pktlab_decode_certificate()

int pktlab_decode_certificate	(	const struct pktlab_certificate *	cert,
		const struct pktlab_publickey *	signkey,
		struct pktlab_cert_info **	ptr
	)

Decode pktlab certificate information from loaded pktlab certificate struct.

Parameters

[in]	cert	Pointer to a loaded pktlab certificate struct.
[in]	signkey	Pointer to a loaded pktlab public key struct for verifying certificate signature.
[out]	ptr	Pointer to return an allocated struct storing decoded certificate information.

Returns: One of the enum pktlab_decode_rst defined values representing the decoding result. Decoded certificate information struct is returned via ptr when decoding is successful.

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

◆ pktlab_decode_chlist()

int pktlab_decode_chlist	(	const void *	chlistptr,
		uint_fast32_t	chlistlen,
		struct pktlab_channel **	channels
	)

Decode a channel list.

Parameters

[in]	chlistptr	Encoded channel list to decode.
[in]	chlistlen	Length of encoded channel list.
[out]	channels	Pointer to return the allocated decoded channel linked list.

Returns

0 for success.
-1 for bad argument.
-2 for malformed chlist.
Other < 0 values for unknown errors.

The returned channels should be freed with pktlab_free_channels().

◆ pktlab_decode_dattr()

int pktlab_decode_dattr	(	const char *	dattr,
		uint_fast32_t	dattrlen,
		struct pktlab_xdescr_dattr_pair **	pairs,
		uint_fast32_t *	paircnt
	)

Decode an encoded endpoint attribute (dattr) string.

Parameters

[in]	dattr	Pointer to the encoded dattr string.
[in]	dattrlen	Encoded dattr string length.
[out]	pairs	Pointer to return an allocated array of decoded dattr name-value pair(s).
[out]	paircnt	Pointer to return the number of dattr name-value pair(s).

Returns: 0 for success, < 0 for failure.

Note when dattr is NULL, dattrlen must be 0 and vice versa.
The returned pairs should be freed with free() in stdlib.h.

◆ pktlab_decode_message()

size_t pktlab_decode_message	(	struct pktlab_message *restrict	msg,
		const void *restrict	ptr,
		size_t	len
	)

Decode pktlab message.

Parameters

[out]	msg	Pointer to a struct for returning decoded message content.
[in]	ptr	Encoded message bytes.
[in]	len	Length of encoded message bytes.

Returns: The number of bytes in ptr used for decoding. 0 if not enough bytes supplied. msg is set when > 0 bytes are used.

Note pktlab_decode_message only checks for message well-formedness as defined in the pktlab protocol documentation.
When receiving pktlab messages from a socket, rather than directly calling this function with the received bytes, it is recommended to use the pktctrl module (pktctrl_read_message()) instead.
Note the msg fields rely on the passed ptr. If the content in ptr is changed after the call to pktlab_decode_message(), the msg fields may change as well.

◆ pktlab_decode_xdescr()

int pktlab_decode_xdescr	(	const char *	xdescr,
		uint_fast32_t	xdescrlen,
		struct pktlab_xdescr_dattr_pair **	pairs,
		uint_fast32_t *	paircnt
	)

Decode an encoded experiment descriptor (xdescr) string.

Parameters

[in]	xdescr	Pointer to the encoded xdescr string.
[in]	xdescrlen	Encoded xdescr string length.
[out]	pairs	Pointer to return an allocated array of decoded xdescr name-value pair(s).
[out]	paircnt	Pointer to return the number of xdescr name-value pair(s).

Returns: 0 for success, < 0 for failure. Decoded pairs are returned via pairs and paircnt upon success.

Note when xdescr is NULL, xdescrlen must be 0 and vice versa.
The returned pairs should be freed with free() in stdlib.h.

◆ pktlab_encode_chlist()

int pktlab_encode_chlist	(	const struct pktlab_channel *	channels,
		void **	chlistptr,
		uint_fast32_t *	chlistlen
	)

Encode a channel list.

Parameters

[in]	channels	Linked list of channels to encode.
[out]	chlistptr	Pointer to return the allocated encoded channel list.
[out]	chlistlen	Length of encoded channel list returned.

Returns

0 for success.
-1 for bad argument.
-2 for bad channel in channels.
Other < 0 values for unknown errors.

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

◆ pktlab_encode_dattr()

int pktlab_encode_dattr	(	const struct pktlab_xdescr_dattr_pair *	pairs,
		uint_fast32_t	paircnt,
		char *	buf,
		uint_fast32_t	buflen,
		uint_fast32_t *	used
	)

Encode an endpoint attribute (dattr) string.

Parameters

[in]	pairs	Pointer to an array of name-value pair(s) to encode.
[in]	paircnt	Length of name-value pair array.
[out]	buf	Pointer to buffer for storing the encoded dattr string.
[in]	buflen	Size of buffer.
[out]	used	Pointer to return the length of the encoded dattr string.

Returns: 0 for success, < 0 for failure.

Note when pairs is NULL, paircnt must be 0 and vice versa.
One can estimate the buffer size the same way as described for pktlab_encode_xdescr().
The returned dattr string is NOT '\0'-terminated.

◆ pktlab_encode_message()

int pktlab_encode_message	(	const struct pktlab_message *restrict	msg,
		void *restrict	buf,
		struct iovec *restrict	iov
	)

Encode pktlab message.

Parameters

[in]	msg	Pointer to a fields-set msg struct for message encoding.
[out]	buf	Buffer of at least PKTLAB_ENCODE_BUFSZ size for msg encoding.
[out]	iov	Pointer to an array of PKTLAB_ENCODE_IOVCNT iovec elements for msg encoding.

Returns: The number of iovec elements used in iov to encode msg. < 0 if encoding failed.

Note for how to fill the msg struct, refer to the pktlab protocol documentation.
In case of successful encoding, one can use writev() in sys/uio.h to send the encoded bytes.
When sending pktlab messages via a socket, rather than directly calling this function and afterwards writev() to send the encoded bytes, it is recommended to use the pktctrl module (pktctrl_write_message()) instead.

◆ pktlab_encode_xdescr()

int pktlab_encode_xdescr	(	const struct pktlab_xdescr_dattr_pair *	pairs,
		uint_fast32_t	paircnt,
		char *	buf,
		uint_fast32_t	buflen,
		uint_fast32_t *	used
	)

Encode an experiment descriptor (xdescr) string.

Parameters

[in]	pairs	Pointer to an array of name-value pair(s) to encode.
[in]	paircnt	Length of name-value pair array.
[out]	buf	Pointer to buffer for storing the encoded xdescr string.
[in]	buflen	Size of buffer.
[out]	used	Pointer to return the length of the encoded xdescr string.

Returns: 0 for success, < 0 for failure.

Note when pairs is NULL, paircnt must be 0 and vice versa.
One can estimate the buffer size needed by summing up the name length and value length of all pairs, with an additional overhead of two characters per pair. I.e. with two pairs {name:"foo",value:"bar"} and {name:"hello",value:"world"}, the length needed is 3+3+2=8 for the first pair and 5+5+2=12 for the second pair.
One would therefore need a buffer size of at least 20 characters for encoding.
The returned xdescr string is NOT '\0'-terminated.

◆ pktlab_flush_writer()

int pktlab_flush_writer ( struct pktlab_writer * w )

Flush pktlab writer internal buffer.

Parameters

[in,out] w Initialized pktlab writer struct to be flushed.

Returns

If success, return the number of bytes flushed out of writer buffer (can be 0).
< 0 for write errors. Check errno for more information.

Note it is possible for pktlab_flush_writer() to only flush a portion of the internally buffered bytes. To ensure all internally buffered bytes are flushed, one should use pktlab_flush_writer() in conjunction with pktlab_writer_unsent() to check whether after a flush there are no internally buffered bytes left.
w should be closed afterwards if pktlab_flush_writer() failed with an error.

◆ pktlab_free_channels()

void pktlab_free_channels ( struct pktlab_channel * channels )

Free an allocated channel linked list.

Parameters

[in,out] channels Allocated channel linked list to free.

◆ pktlab_get8()

static uint_fast8_t pktlab_get8 ( const void * ptr )

inlinestatic

Get 8-bit unsigned integer from byte array.

Parameters

[in] ptr Target byte array.

Returns: 8 bit unsigned integer.

Note there also exist similar functions (pktlab_getN[b|l|n]) that gets N-bit unsigned integer from byte array (N being either 16, 24, 32 or 64). The b/l/n suffix specifies the function treats the byte array as in big endian/little endian/network byte order, respectively.

◆ pktlab_get_agent_key()

int pktlab_get_agent_key	(	const struct pktlab_certificate *	agent_cert,
		uint8_t *	agent_pubkey
	)

Get pktlab agent certificate subject (signee) public key.

Parameters

[in]	agent_cert	Pointer to a loaded pktlab agent certificate struct.
[out]	agent_pubkey	Pointer to buffer for storing raw subject (signee) public key. The buffer size must be at least PKTLAB_PUBLICKEY_LEN bytes large.

Returns: 0 if success. < 0 if failed.

◆ pktlab_get_cert_der()

int pktlab_get_cert_der	(	const struct pktlab_certificate *	cert,
		void **	der,
		uint_fast32_t *	derlen
	)

Get DER-encoded pktlab certificate bytes from loaded pktlab certificate struct.

Parameters

[in]	cert	Pointer to a loaded pktlab certificate struct.
[out]	der	Pointer to return pointer to an allocated array storing DER-encoded pktlab certificate bytes.
[out]	derlen	Pointer to return DER-encoded pktlab certificate byte array length.

Returns: 0 if success. < 0 if failed.

This function is useful when setting pktlab_message struct fields for xcert messages.
The returned der should be freed with free() in stdlib.h.

◆ pktlab_get_key_identifier()

int pktlab_get_key_identifier	(	const struct pktlab_publickey *	k,
		void *	buf,
		uint_fast32_t	buflen
	)

Get key identifier for a loaded pktlab public key struct.

Parameters

[in]	k	Pointer to a loaded pktlab public key struct.
[out]	buf	Pointer to buffer for storing computed key identifier.
[in]	buflen	Size of buffer, should be at least PKTLAB_KEYID_LEN large.

Returns: 0 if success. < 0 if failed.

◆ pktlab_get_privatekey_bytes()

int pktlab_get_privatekey_bytes	(	const struct pktlab_privatekey *	k,
		void *	buf,
		uint_fast32_t	buflen
	)

Get raw private key byte array from loaded pktlab private key struct.

Parameters

[in]	k	Pointer to a loaded pktlab private key struct.
[out]	buf	Pointer to buffer for storing raw private key bytes.
[in]	buflen	Size of buffer, should be at least PKTLAB_PRIVATEKEY_LEN large.

Returns: 0 if success. < 0 if failed.

◆ pktlab_get_publickey_bytes()

int pktlab_get_publickey_bytes	(	const struct pktlab_publickey *	k,
		void *	buf,
		uint_fast32_t	buflen
	)

Get raw public key byte array from loaded pktlab public key struct.

Parameters

[in]	k	Pointer to a loaded pktlab public key struct.
[out]	buf	Pointer to buffer for storing raw public key bytes.
[in]	buflen	Size of buffer, should be at least PKTLAB_PUBLICKEY_LEN large.

Returns: 0 if success. < 0 if failed.

◆ pktlab_get_publickey_from_privatekey()

struct pktlab_publickey * pktlab_get_publickey_from_privatekey ( const struct pktlab_privatekey * k )

Get loaded pktlab public key struct from loaded pktlab private key struct.

Parameters

[in] k Pointer to a loaded pktlab private key struct.

Returns: Pointer to an allocated loaded pktlab public key struct if success. Otherwise NULL.

◆ pktlab_getbit8()

static bool pktlab_getbit8	(	uint_fast8_t	bits,
		uint_fast8_t	pos
	)

inlinestatic

Get bit from unsigned integer at bit position.

Parameters

[in]	bits	Target unsigned interger to get bit from.
[in]	pos	Target bit position (0-indexed).

Returns: Bit.

Note there also exist similar functions (pktlab_getbitN) that get bit from larger unsigned integer (N being either 16, 32, or 64).
Getting bit for pos >= N will result in false.

◆ pktlab_hton16()

static uint_fast16_t pktlab_hton16 ( uint_fast16_t x )

inlinestatic

Convert 16-bit unsigned integer from host byte order to network byte order.

Parameters

[in] x Target value to be converted.

Returns: Converted value.

Note there also exist similar functions (pktlab_htonN and pktlab_ntohN) that convert unsigned integer from host byte order to network byte order and vice versa (N being either 16, 32, or 64).

◆ pktlab_load_cert_der()

int pktlab_load_cert_der	(	const uint8_t *	der,
		uint_fast32_t	derlen,
		struct pktlab_certificate *	cert
	)

Load pktlab certificate struct via DER-encode pktlab certificate byte array.

Parameters

[in]	der	Pointer to the DER-encode pktlab certificate byte array.
[in]	derlen	DER-encode pktlab certificate byte array length.
[in,out]	cert	Pointer to an initialized pktlab certificate struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab certificate struct, see pktlab_create_cert().
Note cert remains initialized if pktlab_load_cert_der() failed;
pktlab_load_cert_der() should NOT be called on an already loaded pktlab certificate struct.

◆ pktlab_load_cert_pem()

int pktlab_load_cert_pem	(	const char *	pem,
		uint_fast32_t	pemlen,
		struct pktlab_certificate *	cert
	)

Load pktlab certificate struct via PEM-encoded pktlab certificate char array.

Parameters

[in]	pem	Pointer to the PEM-encoded pktlab certificate char array.
[in]	pemlen	PEM-encoded pktlab certificate char array length.
[in,out]	cert	Pointer to an initialized pktlab certificate struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab certificate struct, see pktlab_create_cert().
Note cert remains initialized if pktlab_load_cert_pem() failed;
pktlab_load_cert_pem() should NOT be called on an already loaded pktlab certificate struct.
The underlying content being PEM-encoded should be a DER-encoded pktlab certificate.

◆ pktlab_load_privatekey_der()

int pktlab_load_privatekey_der	(	const uint8_t *	der,
		uint_fast32_t	derlen,
		const char *	passphrase,
		struct pktlab_privatekey *	k
	)

Load pktlab private key struct via raw PKCS8 byte array.

Parameters

[in]	der	Pointer to the raw PKCS8 byte array.
[in]	derlen	Raw PKCS8 byte array length.
[in]	passphrase	Pointer to '\0'-terminated passphrase string if the loaded private key is encrypted. For unencrypted private key one should pass in NULL.
[in,out]	k	Pointer to an initialized pktlab private key struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab private key struct, see pktlab_create_privatekey().
Note k remains initialized if pktlab_load_privatekey_der() failed;
pktlab_load_privatekey_der() should NOT be called on an already loaded pktlab private key struct.
The raw PKCS8 byte array should be an Ed25519 private key in DER-encoded PKCS8 format.

◆ pktlab_load_privatekey_pem()

int pktlab_load_privatekey_pem	(	const char *	pem,
		uint_fast32_t	pemlen,
		const char *	passphrase,
		struct pktlab_privatekey *	k
	)

Load pktlab private key struct via PEM-encoded private key char array.

Parameters

[in]	pem	Pointer to PEM-encoded private key char array.
[in]	pemlen	PEM-encoded private key char array length.
[in]	passphrase	Pointer to '\0'-terminated passphrase string if the loaded private key is encrypted. For unencrypted private key one should pass in NULL.
[in,out]	k	Pointer to an initialized pktlab private key struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab private key struct, see pktlab_create_privatekey().
Note k remains initialized if pktlab_load_privatekey_pem() failed;
pktlab_load_privatekey_pem() should NOT be called on an already loaded pktlab private key struct.
The underlying content being PEM-encoded should be an Ed25519 private key in DER-encoded PKCS8 format.

◆ pktlab_load_privatekey_raw()

int pktlab_load_privatekey_raw	(	const uint8_t *	bytes,
		uint_fast32_t	len,
		struct pktlab_privatekey *	k
	)

Load pktlab private key struct via raw private key byte array.

Parameters

[in]	bytes	Pointer to the raw private key byte array.
[in]	len	Raw private key byte array length.
[in,out]	k	Pointer to an initialized pktlab private key struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab private key struct, see pktlab_create_privatekey().
Note k remains initialized if pktlab_load_privatekey_raw() failed;
pktlab_load_privatekey_raw() should NOT be called on an already loaded pktlab private key struct.
Normally, len should be equal to PKTLAB_PRIVATEKEY_LEN.

◆ pktlab_load_publickey_der()

int pktlab_load_publickey_der	(	const uint8_t *	der,
		uint_fast32_t	derlen,
		struct pktlab_publickey *	k
	)

Load pktlab public key struct via raw SubjectPublicKeyInfo byte array.

Parameters

[in]	der	Raw SubjectPublicKeyInfo byte array.
[in]	derlen	Raw SubjectPublicKeyInfo byte array length.
[in,out]	k	Pointer to an initialized pktlab public key struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab public key struct, see pktlab_create_publickey().
Note k remains initialized if pktlab_load_publickey_der() failed;
pktlab_load_publickey_der() should NOT be called on an already loaded pktlab public key struct.
The raw SubjectPublicKeyInfo byte array should be an Ed25519 public key in DER-encoded SubjectPublicKeyInfo format.

◆ pktlab_load_publickey_pem()

int pktlab_load_publickey_pem	(	const char *	pem,
		uint_fast32_t	pemlen,
		struct pktlab_publickey *	k
	)

Load pktlab public key struct via PEM-encoded public key char array.

Parameters

[in]	pem	PEM-encoded public key char array.
[in]	pemlen	PEM-encoded public key char array length.
[in,out]	k	Pointer to an initialized pktlab public key struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab public key struct, see pktlab_create_publickey().
Note k remains initialized if pktlab_load_publickey_pem() failed;
pktlab_load_publickey_pem() should NOT be called on an already loaded pktlab public key struct.
The underlying content being PEM-encoded should be an Ed25519 public key in DER-encoded SubjectPublicKeyInfo format.

◆ pktlab_load_publickey_raw()

int pktlab_load_publickey_raw	(	const uint8_t *	bytes,
		uint_fast32_t	len,
		struct pktlab_publickey *	k
	)

Load pktlab public key struct via raw public key byte array.

Parameters

[in]	bytes	Raw public key byte array.
[in]	len	Raw public key byte array length.
[in,out]	k	Pointer to an initialized pktlab public key struct.

Returns: 0 if success. < 0 if failed.

To obtain an initialized pktlab public key struct, see pktlab_create_publickey().
Note k remains initialized if pktlab_load_publickey_raw() failed;
pktlab_load_publickey_raw() should NOT be called on an already loaded pktlab public key struct.
Normally, len should be equal to PKTLAB_PUBLICKEY_LEN.

◆ pktlab_parse_controller_exp_cert_chain()

int pktlab_parse_controller_exp_cert_chain	(	struct pktlab_certificate **	cert_ls,
		uint_fast32_t	certnum,
		const uint8_t *	controller_key,
		struct pktlab_publickey *	trusted_eop_key,
		uint8_t **	ftdigests,
		uint_fast32_t *	ftcnt,
		uint8_t **	mtdigests,
		uint_fast32_t *	mtcnt,
		char ***	priorities,
		uint_fast32_t *	pcnt,
		uint8_t *	subable_channel
	)

Parse pktlab controller experiment privilege certificate chain for subscribable channel and experiment privilege information.

Parameters

[in]	cert_ls	A potential controller experiment privilege chain (in the form of an array of pointers to loaded pktlab certificate structs consisting) that should be parsed.
[in]	certnum	The number of loaded pktlab certificate struct pointers in cert_ls.
[in]	controller_key	Raw pktlab public key bytes for checking if the certificate chain leaf entity is some expected key. Should point to an array of at least PKTLAB_PUBLICKEY_LEN bytes long.
[in]	trusted_eop_key	A loaded pktlab public key struct for checking if the certificate chain root entity is some expected key.
[out]	ftdigests	Pointer to return a list of filter digests contained in cert_ls.
[out]	ftcnt	Pointer to return the number of filter digests in ftdigests.
[out]	mtdigests	Pointer to return a list of monitor digests contained in cert_ls.
[out]	mtcnt	Pointer to return the number of monitor digests in mtdigests.
[out]	priorities	Pointer to return a list of priority strings contained in cert_ls.
[out]	pcnt	Pointer to return the number of priority strings in priorities.
[out]	subable_channel	Pointer to return a private channel ID allowed to be subscribed based on cert_ls.

Returns: One of the enum pktlab_parse_cert_chain_rst defined values representing the parsing result. Digests, priority strings, and channel information returned when parsing successful.

It is allowed to pass in NULL for controller_key/trusted_eop_key. If controller_key/trusted_eop_key is NULL, the corresponding leaf/root entity check is not conducted.
It is allowed to pass in NULL for ftdigests & ftcnt / mtdigests & mtcnt / priorities & pcnt (Note if one field is NULL, their counterpart must be NULL as well. E.g. if ftdigests is NULL, ftcnt must be NULL and vice versa). If a field is NULL, no value is returned for the field.
Note the first certificate in cert_ls is expected to be a pubcmd certificate (the others need not be in order). See PPKS documentation for more information on the expected format for a controller experiment privilege chain.

◆ pktlab_parse_endpoint_rep_cert_chain()

int pktlab_parse_endpoint_rep_cert_chain	(	struct pktlab_certificate **	cert_ls,
		uint_fast32_t	certnum,
		const uint8_t *	endpoint_key,
		struct pktlab_publickey *	root_eop_key,
		uint8_t **	subable_channels,
		uint_fast32_t *	channelnum
	)

Parse pktlab endpoint representation privilege certificate chain for subscribable channel information.

Parameters

[in]	cert_ls	A potential endpoint representation privilege chain (in the form of an array of pointers to loaded pktlab certificate structs consisting) that should be parsed.
[in]	certnum	The number of loaded pktlab certificate struct pointers in cert_ls.
[in]	endpoint_key	Raw pktlab public key bytes for checking if the certificate chain leaf entity is some expected key. Should point to an array of at least PKTLAB_PUBLICKEY_LEN bytes long.
[in]	root_eop_key	A loaded pktlab public key struct for checking if the certificate chain root entity is some expected key.
[out]	subable_channels	Pointer to return a list of private channel IDs allowed to be subscribed based on cert_ls.
[out]	channelnum	Pointer to return the number of channel IDs in subable_channels.

Returns: One of the enum pktlab_parse_cert_chain_rst defined values representing the parsing result. subable_channels & channelnum returned when parsing successful.

subable_channels is returned with all channel IDs back-to-back concatenated. Note the channel IDs returned are all PKTLAB_CHANNELID_LEN_MAX bytes long.
It is allowed to pass in NULL for endpoint_key/root_eop_key. If endpoint_key/root_eop_key is NULL, the corresponding leaf/root entity check is not conducted.
Note the first certificate in cert_ls is expected to be a subcmd certificate (the others need not be in order). See PPKS documentation for more information on the expected format for an endpoint representation privilege chain.

◆ pktlab_parse_uri()

int pktlab_parse_uri	(	struct pktlab_uri *restrict	uri_info,
		const void *restrict	ptr,
		uint_fast32_t	len
	)

Decode a pktlab URI.

Parameters

[out]	uri_info	Pointer to a struct for storing the decoded result.
[in]	ptr	pktlab URI to decode.
[in]	len	Length of pktlab URI.

Returns

0 for success.
-1 for bad argument.
-2 for malformed URI.
Other < 0 values for unknown errors.

Note the uri_info is set only when either the decoding is successful, or the URI is malformed. When the decoding is successful, type is set to the decoded URI type with the decoded information being set in the uri struct. Otherwise, the malformed struct is set with the type set to MALFORMED_URI_TYPE.
Note the uri_info fields rely on the passed ptr. If the content in ptr is changed after the call to pktlab_parse_uri(), the uri_info fields may change as well.
The expected URI format: "pktlab://HOST[:PORT]/exp|broker/".

◆ pktlab_read_message()

int pktlab_read_message	(	struct pktlab_reader *restrict	r,
		struct pktlab_message **restrict	msgptr
	)

pktlab reader read message.

Parameters

[in,out]	r	Initialized pktlab reader struct.
[out]	msgptr	Pointer to return an allocated msg that was read.

Returns

When msgptr is not NULL:
1. 1 for successful read with decoded read msg returned via msgptr. If EOF is encountered, a NULL is returned via msgptr.
2. 0 for try again later.
3. < 0 for read errors. Check errno for more information.
When msgptr is NULL:
1. 1 for there exists new msg available for reading.
2. 0 for not enough data for a new msg.
3. < 0 for reader is in error state.

To obtain an initialized pktlab reader struct, see pktlab_create_reader().
Note whenever < 0 is returned, r should not be called with msgptr being non-NULL afterwards.

◆ pktlab_reader_readaux()

void * pktlab_reader_readaux ( const struct pktlab_reader * r )

Get pktlab reader struct aux information.

Parameters

[in] r Initialized pktlab reader struct to get aux from.

Returns: Reader aux (passed in during pktlab_create_reader()).

◆ pktlab_set8()

static void pktlab_set8	(	void *	ptr,
		uint_fast8_t	val
	)

inlinestatic

Set 8-bit unsigned integer to byte array.

Parameters

[in]	ptr	Target byte array.
[in]	val	Target set value.

Note there also exist similar functions (pktlab_setN[b|l|n]) that sets N-bit unsigned integer to byte array (N being either 16, 24, 32 or 64). The b/l/n suffix specifies the function treats the byte array as in big endian/little endian/network byte order, respectively.

◆ pktlab_setbit8()

static uint_fast8_t pktlab_setbit8	(	uint_fast8_t	bits,
		uint_fast8_t	pos
	)

inlinestatic

Set bit in unsigned integer at bit position.

Parameters

[in]	bits	Target unsigned interger to set bit.
[in]	pos	Target bit position (0-indexed).

Returns: Set result.

Note there also exist similar functions (pktlab_setbitN) that set bit to larger unsigned integers (N being either 16, 32, or 64).
Setting bit for pos >= N will be ignored with unchanged bits value returned.

◆ pktlab_sktstate_name()

const char * pktlab_sktstate_name ( enum pktlab_socket_state state )

Get text description of pktlab endpoint skt state.

Parameters

[in] state pktlab endpoint skt state.

Returns: Pointer to the text description string for pktlab endpoint skt state.

◆ pktlab_time_now()

pktlab_time_t pktlab_time_now ( void )

Get current pktlab time.

Returns: Current pktlab time.

◆ pktlab_time_sec()

static pktlab_time_t pktlab_time_sec ( uint_fast32_t sec )

inlinestatic

Convert seconds to pktlab ticks.

Parameters

[in] sec The number of seconds to convert.

Returns: Converted result in pktlab ticks.

◆ pktlab_time_to_timeval()

static void pktlab_time_to_timeval	(	pktlab_time_t	t,
		struct timeval *	tv
	)

inlinestatic

Convert time period in pktlab ticks to struct timeval.

Parameters

[in]	t	The number of pktlab ticks to convert.
[out]	tv	Pointer to a timeval struct to store the converted result.

◆ pktlab_time_to_unix_time()

static uint_fast32_t pktlab_time_to_unix_time ( pktlab_time_t t )

inlinestatic

Convert a pktlab time to Unix time (in second precision).

Parameters

[in] t The pktlab time to convert.

Returns: The converted Unix time.

◆ pktlab_timeval_to_time()

static pktlab_time_t pktlab_timeval_to_time ( const struct timeval * tv )

inlinestatic

Convert time period in struct timeval to pktlab ticks.

Parameters

[in] tv Pointer to time period in struct timeval to convert.

Returns: Converted result in pktlab ticks.

◆ pktlab_tm_to_time()

pktlab_time_t pktlab_tm_to_time ( const struct tm * tm )

Convert time in struct tm to pktlab time.

Parameters

[in] tm Pointer to time in struct tm to convert.

Returns: The converted pktlab time.

◆ pktlab_verify_cert_chain()

int pktlab_verify_cert_chain	(	int	auth_mode,
		struct pktlab_certificate **	cert_ls,
		struct pktlab_publickey **	root_ls,
		struct pktlab_certificate ***	verified_cert_ls,
		uint_fast32_t	certnum,
		uint_fast32_t	rootnum,
		uint_fast32_t *	verified_certnum,
		uint_fast32_t *	used_root_indx
	)

Verify pktlab certificate chain.

Parameters

[in]	auth_mode	Verification mode to use when verifying certificate chain. Must be one of enum pktlab_auth_mode values.
[in]	cert_ls	Array of pointers to loaded pktlab certificate structs that should be verified.
[in]	root_ls	Array of pointers to loaded pktlab public key structs that could serve as the certificate chain root.
[out]	verified_cert_ls	Pointer to return the verified certificate chain (in the form of an allocated array of pointers to loaded pktlab certificate structs).
[in]	certnum	The number of loaded pktlab certificate struct pointers in cert_ls.
[in]	rootnum	The number of loaded pktlab public key struct pointers in root_ls.
[out]	verified_certnum	Pointer to return the verified certificate chain length.
[out]	used_root_indx	Pointer to return the verified certificate chain root (in the form of indx to root_ls).

Returns: One of the enum pktlab_verify_rst defined values representing verification result. Verified certificate chain information (verified_cert_ls/verified_certnum/used_root_indx) returned only when verification successful.

The returned verified_cert_ls pointer should be freed with free() in stdlib.h. Note the pointers to loaded pktlab certificate structs in verified_cert_ls are the same ones as in cert_ls (i.e. if one frees all certificate struct in cert_ls, the certificate structs in verified_cert_ls are freed as well).
It is allowed to pass in NULL for cert_ls/root_ls/verified_cert_ls/verified_certnum/used_root_indx. If cert_ls/root_ls is NULL, the corresponding certnum/rootnum must be 0 and vice versa. If verified_cert_ls/verified_certnum/used_root_indx is NULL, no value is returned and no freeing is needed.

◆ pktlab_verify_certificate_signature()

int pktlab_verify_certificate_signature	(	const struct pktlab_certificate *	cert,
		const struct pktlab_publickey *	signkey
	)

Verify the pktlab certificate signature.

Parameters

[in]	cert	Pointer to a loaded pktlab certificate struct.
[in]	signkey	Pointer to a loaded pktlab public key struct for verifying pktlab certificate signature.

Returns: 0 if verification success. < 0 if verification failed.

Note invalid input argument is considered verification failure as well.

◆ pktlab_write_message()

int pktlab_write_message	(	struct pktlab_writer *restrict	w,
		const struct pktlab_message *restrict	msg
	)

pktlab writer write message.

Parameters

[in,out]	w	Initialized pktlab writer struct.
[in]	msg	Pointer to an initialized msg struct.

Returns

1 for successful encoding and buffering of msg (some message bytes have been sent).
0 for try again later (message bytes are not buffered).
< 0 for write errors. Check errno for more information.

To obtain an initialized pktlab writer struct, see pktlab_create_writer().
Note even though the function signature is similar to pktlab_read_message(), msg must NOT be NULL.
pktlab_write_message() always first tries to flush any buffered bytes within the writer before working on sending the new message bytes. It is therefore fine to perform a consecutive call of pktlab_write_message() on a series of messages, while only stopping when pktlab_write_message() returns <= 0.
Note in case there isn't any other message to be sent, to flush the internal buffered unsent bytes and ensure that all message bytes are sent, one can use a combination of pktlab_flush_writer() and pktlab_writer_unsent() to make sure buffered bytes are flushed.
w should be closed afterwards if pktlab_write_message() failed with an error.

◆ pktlab_writer_unsent()

size_t pktlab_writer_unsent ( const struct pktlab_writer * w )

Get writer internal buffered content length.

Parameters

[in] w Initialized pktlab writer struct.

Returns: The number of buffered bytes in w.

pktlab_writer_unsent() is often used in conjunction with pktlab_flush_writer() to flush out all writer-internally buffered bytes. See pktlab_flush_writer() for more information.

◆ pktlab_writer_writeaux()

void * pktlab_writer_writeaux ( const struct pktlab_writer * w )

Get pktlab writer struct aux information.

Parameters

[in] w pktlab writer struct to get aux from.

Returns: Writer aux (passed in during pktlab_create_writer()).

◆ pktlab_xdescr_dattr_match()

bool pktlab_xdescr_dattr_match	(	const char *	xdescr,
		uint_fast32_t	xdescrlen,
		const char *	dattr,
		uint_fast32_t	dattrlen
	)

Match an experiment descriptor (xdescr) string to an endpoint attribute (dattr) string.

Parameters

[in]	xdescr	xdescr string as the matching pattern.
[in]	xdescrlen	Length of xdescr string.
[in]	dattr	dattr string as the matching target.
[in]	dattrlen	Length of dattr string.

Returns: When both xdescr and dattr are well-formed (can be decoded), true for a match between the two, false otherwise. If either is malformed, false is returned.

This function is used by the broker/rendezvous server to match between experiment publication and subscription and decide whether an experiment notification should be sent to an endpoint. A notification is sent iff when there is a match.
Note when xdescr is NULL, xdescrlen must be 0 and vice versa. The same applies to dattr and dattrlen.
Whether there is a match between (the well-formed) xdescr and dattr is decided based on the following:
1. If dattr is empty (0-length/no pairs), it is a match.
2. Otherwise, for all pairs in dattr, look for pairs in xdescr with the same name.
3. If there is no such pair in xdescr, it is considered a match for this dattr pair.
4. Else, if among all pairs in xdescr that have the same name, there exist at least one pair that has a value string matching the dattr pair value string (after wildcard matching), it is a match for this dattr pair. If no such pair exists, it is a no match for this dattr pair.
5. The overall matching result is the logical AND of per-dattr-pair matching results.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PKTLAB_FILTER_DIGEST_LEN

◆ PKTLAB_IP4_PROTO

◆ PKTLAB_IP6_PROTO

◆ PKTLAB_KEYID_LEN

◆ PKTLAB_MONITOR_DIGEST_LEN

◆ PKTLAB_NCTL_TCP_FIN

◆ PKTLAB_PRIVATEKEY_LEN

◆ PKTLAB_PUBLICKEY_LEN

◆ PKTLAB_RAW_PROTO

◆ PKTLAB_SIGNATURE_LEN

◆ PKTLAB_TCP_PROTO

◆ PKTLAB_UDP_PROTO

Typedef Documentation

◆ pktlab_read_t

◆ pktlab_time_t

◆ pktlab_write_t

Enumeration Type Documentation

◆ pktlab_auth_mode

◆ pktlab_decode_rst

◆ pktlab_filter_type

◆ pktlab_message_type

◆ pktlab_parse_cert_chain_rst

◆ pktlab_status

◆ pktlab_uri_type

◆ pktlab_verify_rst

Function Documentation

◆ pktlab_cert_type_name()

◆ pktlab_cert_type_name_to_id()

◆ pktlab_cleanup_cert()

◆ pktlab_cleanup_privatekey()

◆ pktlab_cleanup_publickey()

◆ pktlab_close_reader()

◆ pktlab_close_writer()

◆ pktlab_clrbit8()

◆ pktlab_create_cert()

◆ pktlab_create_privatekey()

◆ pktlab_create_publickey()

◆ pktlab_create_reader()

◆ pktlab_create_result_message()

◆ pktlab_create_writer()

◆ pktlab_decode_certificate()

◆ pktlab_decode_chlist()

◆ pktlab_decode_dattr()

◆ pktlab_decode_message()

◆ pktlab_decode_xdescr()

◆ pktlab_encode_chlist()

◆ pktlab_encode_dattr()

◆ pktlab_encode_message()

◆ pktlab_encode_xdescr()

◆ pktlab_flush_writer()

◆ pktlab_free_channels()

◆ pktlab_get8()

◆ pktlab_get_agent_key()

◆ pktlab_get_cert_der()

◆ pktlab_get_key_identifier()

◆ pktlab_get_privatekey_bytes()

◆ pktlab_get_publickey_bytes()

◆ pktlab_get_publickey_from_privatekey()

◆ pktlab_getbit8()

◆ pktlab_hton16()

◆ pktlab_load_cert_der()

◆ pktlab_load_cert_pem()

◆ pktlab_load_privatekey_der()

◆ pktlab_load_privatekey_pem()

◆ pktlab_load_privatekey_raw()

◆ pktlab_load_publickey_der()

◆ pktlab_load_publickey_pem()

◆ pktlab_load_publickey_raw()

◆ pktlab_parse_controller_exp_cert_chain()

◆ pktlab_parse_endpoint_rep_cert_chain()

◆ pktlab_parse_uri()

◆ pktlab_read_message()

◆ pktlab_reader_readaux()