libpktlab - The PacketLab Utility Library
Classes | Macros | Typedefs | Enumerations | Functions
pktlab.h File Reference

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_namevalue_pair
 Structure for encoding/decoding experiment descriptor (xdescr)/endpoint attribute (dattr) in xpub and xsub messages. More...
 
struct  pktlab_aux_field
 Structure of auxiliary field in pktlab_cert_detail. More...
 
struct  pktlab_channel
 Structure for encoding/decoding channel lists in xpub and xsub messages. More...
 
struct  pktlab_ebpf_instr
 Structure for encoding/decoding pktlab eBPF programs in cdata & ncap msg. Represents one eBPF instruction. 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_valid_dest
 Structure for storing pktlab valid destination information. More...
 
struct  pktlab_burst_rate
 Structure for storing pktlab burst rate information. More...
 
struct  pktlab_decoded_certificate
 Structure for storing decoded pktlab certificate information. More...
 
struct  pktlab_cert_detail
 Structure for storing pktlab certificate detail information, including cert_info and cert_limit. 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_PROXY_SETUP_PORT_STR   "20557"
 Default proxy setup 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_NAMEVALUE_PAIR_SEP   '='
 
#define PKTLAB_NAMEVALUE_PAIR_END   ';'
 
#define PKTLAB_NAMEVALUE_NAMELEN_MIN   0x1
 
#define PKTLAB_NAMEVALUE_NAMELEN_MAX   0x20
 
#define PKTLAB_NAMEVALUE_VALUELEN_MIN   0x1
 Minimum xdescr/dattr pair value length.
 
#define PKTLAB_NAMEVALUE_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_EBPF_INSTR_LEN   sizeof(struct pktlab_ebpf_instr)
 pktlab eBPF program unencoded instruction size in bytes.
 
#define PKTLAB_ENC_EBPF_INSTR_LEN   8
 pktlab eBPF program encoded instruction length in bytes.
 
#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_LEN*0x100)
 
#define PKTLAB_VMEMADDR_SYSPARAM_IP6LS_FL   (sizeof(uint8_t)*PKTLAB_IPV6_ADDR_LEN*0x100)
 
#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_LEN*0x10)
 
#define PKTLAB_VMEMADDR_SYSPARAM_IP6DNSLS_FL   (sizeof(uint8_t)*PKTLAB_IPV6_ADDR_LEN*0x10)
 
#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_NOTIFMASK_NBLOCK   (0x1 << 5)
 
#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_CDATA_HINT_FILTER   "filter"
 Defined cdata hint value - filter program.
 
#define PKTLAB_CDATA_HINT_MONITOR   "monitor"
 Defined cdata hint value - monitor program.
 
#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_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_INFO   "1.2.3.1"
 
#define PKTLAB_EXT_CERT_LIMIT   "1.2.3.3"
 
#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_prog_type { PKTLAB_EBPF = 0x0, PKTLAB_WASM = 0x1 }
 pktlab defined program 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_NBLOCK_MESSAGE = 0x64, 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_ECTLMONREJ = 0x12,
  PKTLAB_ECTLMONUKN = 0x13, PKTLAB_ECRTBADHDAT = 0x20, PKTLAB_ECRTNOHDAT = 0x21, PKTLAB_ECRTBADFRM = 0x22,
  PKTLAB_ECRTNOSPACE = 0x23, PKTLAB_ECRTBADHINT = 0x24, 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_ESKTPKTDENY = 0x39,
  PKTLAB_ESKTOPNDENY = 0x3A, PKTLAB_ETCPNOPORT = 0x40, PKTLAB_EPKTNOTSENT = 0x41, PKTLAB_EUDPNOPORT = 0x42,
  PKTLAB_EPKTTRUNC = 0x43, PKTLAB_ENORES = 0x44, PKTLAB_EMEMBADADR = 0x48, PKTLAB_EPUBBADCHL = 0x50,
  PKTLAB_EPUBBADCHN = 0x51, PKTLAB_EPUBBADADDR = 0x52, PKTLAB_EPUBBADPR = 0x53, PKTLAB_EPUBBADXD = 0x54,
  PKTLAB_ESUBBADCHL = 0x60, PKTLAB_ESUBBADCHN = 0x61, PKTLAB_ESUBBADDA = 0x62, 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_del_type { PKTLAB_DEL_TYPE_EXPPRIV = 0x1, PKTLAB_DEL_TYPE_REPPRIV = 0x2, PKTLAB_DEL_TYPE_NOT_PRSENT = 0x0 }
 
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_INFO = 14, PKTLAB_DECODE_BAD_CERT_LIMIT = 15,
  PKTLAB_DECODE_BAD_PRIORITY = 16, PKTLAB_DECODE_BAD_MONITOR_DIGESTS = 17, PKTLAB_DECODE_BAD_DEL_TYPE = 18, PKTLAB_DECODE_BAD_AUX_INFO = 19,
  PKTLAB_DECODE_BAD_CERT_DESC = 20, PKTLAB_DECODE_BAD_VALID_DEST = 21, PKTLAB_DECODE_BAD_SRC_IP_SPOOFING = 22, PKTLAB_DECODE_BAD_MAX_BURST_RATE = 23,
  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 pktlab_time_t pktlab_timespec_to_time (const struct timespec *tp)
 Convert time period in struct timespec 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 void pktlab_time_to_timespec (pktlab_time_t t, struct timespec *tp)
 Convert time period in pktlab ticks to struct timespec. 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_namevalue_pair **pairs, uint_fast32_t *paircnt)
 Decode an encoded experiment descriptor (xdescr) string. More...
 
int pktlab_encode_xdescr (const struct pktlab_namevalue_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_namevalue_pair **pairs, uint_fast32_t *paircnt)
 Decode an encoded endpoint attribute (dattr) string. More...
 
int pktlab_encode_dattr (const struct pktlab_namevalue_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_encode_program (enum pktlab_prog_type type, const void *prog, uint_fast32_t proglen, void **buf, uint_fast32_t *buflen)
 Encode pktlab program. More...
 
int pktlab_decode_program (const void *buf, uint_fast32_t buflen, enum pktlab_prog_type *type, void **prog, uint_fast32_t *proglen)
 Decode pktlab program. More...
 
int pktlab_get_program_digest (const void *data, uint_fast32_t datalen, uint8_t *digest)
 Compute encoded pktlab program digest. More...
 
int pktlab_load_program (const char *data, uint_fast32_t datalen, enum pktlab_prog_type type, void **prog, uint_fast32_t *proglen, uint_fast32_t *errlineno)
 Load pktlab program from file content. 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_message * pktlab_create_monrej_result_message (uint16_t monindx, uint16_t monerrid)
 Get fields-set pktlab result message with status PKTLAB_ECTLMONREJ. More...
 
struct pktlab_message * pktlab_create_monukn_result_message (uint16_t monindx)
 Get fields-set pktlab result message with status PKTLAB_ECTLMONUKN. 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_decoded_certificate **decoded_cert)
 Decode pktlab certificate information from loaded pktlab certificate struct. More...
 
int pktlab_decode_cert_detail (const struct pktlab_certificate *cert, const struct pktlab_publickey *signkey, struct pktlab_cert_detail **ptr)
 Decode pktlab certificate detail information from loaded pktlab certificate struct. More...
 
int pktlab_decoded_cert_get_cert_type (const struct pktlab_decoded_certificate *decoded_cert, enum pktlab_cert_type *cert_type)
 Get pktlab certificate type from decoded pktlab certificate information. 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...
 
int pktlab_cleanup_detail_ls (struct pktlab_cert_detail *head)
 Free the chain of allocated pktlab certificate detail structs. 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, struct pktlab_cert_detail **cert_details, 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_INFO 

Bad pktlab certificate information.

PKTLAB_DECODE_BAD_CERT_LIMIT 

Bad pktlab certificate limit.

PKTLAB_DECODE_BAD_PRIORITY 

Bad pktlab priority string.

PKTLAB_DECODE_BAD_MONITOR_DIGESTS 

Bad pktlab monitor digests.

PKTLAB_DECODE_BAD_DEL_TYPE 

Bad pktlab delegation type.

PKTLAB_DECODE_BAD_AUX_INFO 

Bad pktlab auxiliary information.

PKTLAB_DECODE_BAD_CERT_DESC 

Bad pktlab certificate description.

PKTLAB_DECODE_BAD_VALID_DEST 

Bad pktlab valid destination.

PKTLAB_DECODE_BAD_SRC_IP_SPOOFING 

Bad pktlab source IP spoofing.

PKTLAB_DECODE_BAD_MAX_BURST_RATE 

Bad pktlab maximum burst rate.

PKTLAB_DECODE_UNKNOWN_FAULT 

Unknwon error during decoding.

◆ 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_prog_type

enum pktlab_prog_type

pktlab defined program types.

Enumerator
PKTLAB_EBPF 

Extended BPF

PKTLAB_WASM 

WebAssembly

◆ 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_typepktlab 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]namePointer 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]certPointer to an allocated pktlab certificate struct to free.
Returns
0 if success. < 0 if failed.

◆ pktlab_cleanup_detail_ls()

int pktlab_cleanup_detail_ls ( struct pktlab_cert_detail *  head)

Free the chain of allocated pktlab certificate detail structs.

Parameters
[in,out]headPointer to the head of the chain of allocated pktlab certificate detail structs to free.
Returns
0 if success. < 0 if failed.

◆ pktlab_cleanup_privatekey()

int pktlab_cleanup_privatekey ( struct pktlab_privatekey *  k)

Free an allocated pktlab private key struct.

Parameters
[in,out]kPointer to an allocated pktlab private key struct to free.
Returns
0 if success. < 0 if failed.

◆ pktlab_cleanup_publickey()

int pktlab_cleanup_publickey ( struct pktlab_publickey *  k)

Free an allocated pktlab public key struct.

Parameters
[in,out]kAllocated pktlab public key struct to free.
Returns
0 if success. < 0 if failed.

◆ pktlab_close_reader()

void pktlab_close_reader ( struct pktlab_reader *  r)

Close and free pktlab reader struct.

Parameters
[in,out]rAllocated pktlab reader struct to free.

◆ pktlab_close_writer()

void pktlab_close_writer ( struct pktlab_writer *  w)

Close and free pktlab writer struct.

Parameters
[in,out]wAllocated pktlab writer struct to free.

◆ 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]bitsTarget unsigned interger to clear bit.
[in]posTarget 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.

◆ pktlab_create_monrej_result_message()

struct pktlab_message* pktlab_create_monrej_result_message ( uint16_t  monindx,
uint16_t  monerrid 
)

Get fields-set pktlab result message with status PKTLAB_ECTLMONREJ.

Parameters
[in]statusResult message errid.
[in]monindxThe index of the monitor that the result message is for.
[in]monerridThe errid of the monitor that the result message is for.
Returns
An allocated pktlab result message with errid set.
  • The returned message pointer should be freed with free() in stdlib.h.

◆ pktlab_create_monukn_result_message()

struct pktlab_message* pktlab_create_monukn_result_message ( uint16_t  monindx)

Get fields-set pktlab result message with status PKTLAB_ECTLMONUKN.

Parameters
[in]statusResult message errid.
[in]monindxThe index of the monitor that the result message is for.
Returns
An allocated pktlab result message with errid set.
  • The returned message pointer should be freed with free() in stdlib.h.

◆ 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.

◆ 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.

◆ pktlab_create_reader()

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

Get initialized pktlab reader struct.

Parameters
[in]readRead function to use for this reader.
[in]auxAuxiliary 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]statusResult 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]writeWrite function to use for this writer.
[in]auxAuxiliary 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_cert_detail()

int pktlab_decode_cert_detail ( const struct pktlab_certificate *  cert,
const struct pktlab_publickey *  signkey,
struct pktlab_cert_detail **  ptr 
)

Decode pktlab certificate detail information from loaded pktlab certificate struct.

Parameters
[in]certPointer to a loaded pktlab certificate struct.
[in]signkeyPointer to a loaded pktlab public key struct for verifying certificate signature.
[out]ptrPointer to return an allocated struct storing decoded certificate detail 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.
  • If signkey is NULL, the function still attempts to decode the certificate, but does not check if the certificate signature is valid w.r.t. signkey.
  • The returned ptr should be freed with free() in stdlib.h.
  • As pktlab_cert_detail struct is a linked list and there is only one cert, this function will only return a single node with the next pointer set to NULL.

◆ pktlab_decode_certificate()

int pktlab_decode_certificate ( const struct pktlab_certificate *  cert,
const struct pktlab_publickey *  signkey,
struct pktlab_decoded_certificate **  decoded_cert 
)

Decode pktlab certificate information from loaded pktlab certificate struct.

Parameters
[in]certPointer to a loaded pktlab certificate struct.
[in]signkeyPointer to a loaded pktlab public key struct for verifying certificate signature.
[out]ptrPointer 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.
  • If signkey is NULL, the function still attempts to decode the certificate, but does not check if the certificate signature is valid w.r.t. signkey.
  • 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]chlistptrEncoded channel list to decode.
[in]chlistlenLength of encoded channel list.
[out]channelsPointer to return the allocated decoded channel linked list.
Returns
  1. 0 for success.
  2. -1 for bad argument.
  3. -2 for malformed chlist.
  4. Other < 0 values for unknown errors.

◆ pktlab_decode_dattr()

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

Decode an encoded endpoint attribute (dattr) string.

Parameters
[in]dattrPointer to the encoded dattr string.
[in]dattrlenEncoded dattr string length.
[out]pairsPointer to return an allocated array of decoded dattr name-value pair(s).
[out]paircntPointer 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]msgPointer to a struct for returning decoded message content.
[in]ptrEncoded message bytes.
[in]lenLength 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_program()

int pktlab_decode_program ( const void *  buf,
uint_fast32_t  buflen,
enum pktlab_prog_type *  type,
void **  prog,
uint_fast32_t *  proglen 
)

Decode pktlab program.

Parameters
[in]bufPointer to encoded program bytes.
[in]buflenLength of encoded program in bytes.
[out]typePointer to return decoded program type.
[out]progPointer to return allocated decoded pktlab program bytes.
[out]proglenPointer to return decoded pktlab program length in bytes.
Returns
0 for success, < 0 for failure.
  • Note prog and proglen are set only when the decoding is successful.
  • The returned prog should be freed with free() in stdlib.h.

◆ pktlab_decode_xdescr()

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

Decode an encoded experiment descriptor (xdescr) string.

Parameters
[in]xdescrPointer to the encoded xdescr string.
[in]xdescrlenEncoded xdescr string length.
[out]pairsPointer to return an allocated array of decoded xdescr name-value pair(s).
[out]paircntPointer 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_decoded_cert_get_cert_type()

int pktlab_decoded_cert_get_cert_type ( const struct pktlab_decoded_certificate *  decoded_cert,
enum pktlab_cert_type *  cert_type 
)

Get pktlab certificate type from decoded pktlab certificate information.

Parameters
[in]certPointer to a loaded pktlab certificate struct.
[out]cert_typePointer to return pktlab certificate type value.
Returns
0 if success. < 0 if failed.

◆ pktlab_encode_chlist()

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

Encode a channel list.

Parameters
[in]channelsLinked list of channels to encode.
[out]chlistptrPointer to return the allocated encoded channel list.
[out]chlistlenLength of encoded channel list returned.
Returns
  1. 0 for success.
  2. -1 for bad argument.
  3. -2 for bad channel in channels.
  4. 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_namevalue_pair *  pairs,
uint_fast32_t  paircnt,
char *  buf,
uint_fast32_t  buflen,
uint_fast32_t *  used 
)

Encode an endpoint attribute (dattr) string.

Parameters
[in]pairsPointer to an array of name-value pair(s) to encode.
[in]paircntLength of name-value pair array.
[out]bufPointer to buffer for storing the encoded dattr string.
[in]buflenSize of buffer.
[out]usedPointer 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]msgPointer to a fields-set msg struct for message encoding.
[out]bufBuffer of at least PKTLAB_ENCODE_BUFSZ size for msg encoding.
[out]iovPointer 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_program()

int pktlab_encode_program ( enum pktlab_prog_type  type,
const void *  prog,
uint_fast32_t  proglen,
void **  buf,
uint_fast32_t *  buflen 
)

Encode pktlab program.

Parameters
[in]typeProgram type to be encoded.
[in]progPointer to the pktlab program bytes.
[in]proglenLength of pktlab program in bytes.
[out]bufPointer to return allocated encoded program bytes.
[out]buflenPointer to return length of encoded program bytes.
Returns
0 for success, < 0 for failure.
  • The returned buf should be freed with free() in stdlib.h.

◆ pktlab_encode_xdescr()

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

Encode an experiment descriptor (xdescr) string.

Parameters
[in]pairsPointer to an array of name-value pair(s) to encode.
[in]paircntLength of name-value pair array.
[out]bufPointer to buffer for storing the encoded xdescr string.
[in]buflenSize of buffer.
[out]usedPointer 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]wInitialized pktlab writer struct to be flushed.
Returns
  1. If success, return the number of bytes flushed out of writer buffer (can be 0).
  2. < 0 for write errors. Check errno for more information.

◆ pktlab_free_channels()

void pktlab_free_channels ( struct pktlab_channel *  channels)

Free an allocated channel linked list.

Parameters
[in,out]channelsAllocated 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]ptrTarget 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_certPointer to a loaded pktlab agent certificate struct.
[out]agent_pubkeyPointer 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]certPointer to a loaded pktlab certificate struct.
[out]derPointer to return pointer to an allocated array storing DER-encoded pktlab certificate bytes.
[out]derlenPointer 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]kPointer to a loaded pktlab public key struct.
[out]bufPointer to buffer for storing computed key identifier.
[in]buflenSize 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]kPointer to a loaded pktlab private key struct.
[out]bufPointer to buffer for storing raw private key bytes.
[in]buflenSize of buffer, should be at least PKTLAB_PRIVATEKEY_LEN large.
Returns
0 if success. < 0 if failed.

◆ pktlab_get_program_digest()

int pktlab_get_program_digest ( const void *  data,
uint_fast32_t  datalen,
uint8_t *  digest 
)

Compute encoded pktlab program digest.

Parameters
[in]dataPointer to encoded program bytes.
[in]datalenLength of encoded program in bytes.
[out]digestPointer to return digest of encoded pktlab program. Should point to buffer of at least PKTLAB_SHA256_DIGEST_LEN large.
Returns
0 for success, < 0 for failure.

◆ 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]kPointer to a loaded pktlab public key struct.
[out]bufPointer to buffer for storing raw public key bytes.
[in]buflenSize 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]kPointer 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]bitsTarget unsigned interger to get bit from.
[in]posTarget 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]xTarget 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]derPointer to the DER-encode pktlab certificate byte array.
[in]derlenDER-encode pktlab certificate byte array length.
[in,out]certPointer to an initialized pktlab certificate struct.
Returns
0 if success. < 0 if failed.

◆ 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]pemPointer to the PEM-encoded pktlab certificate char array.
[in]pemlenPEM-encoded pktlab certificate char array length.
[in,out]certPointer 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]derPointer to the raw PKCS8 byte array.
[in]derlenRaw PKCS8 byte array length.
[in]passphrasePointer to '\0'-terminated passphrase string if the loaded private key is encrypted. For unencrypted private key one should pass in NULL.
[in,out]kPointer to an initialized pktlab private key struct.
Returns
0 if success. < 0 if failed.

◆ 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]pemPointer to PEM-encoded private key char array.
[in]pemlenPEM-encoded private key char array length.
[in]passphrasePointer to '\0'-terminated passphrase string if the loaded private key is encrypted. For unencrypted private key one should pass in NULL.
[in,out]kPointer to an initialized pktlab private key struct.
Returns
0 if success. < 0 if failed.

◆ 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]bytesPointer to the raw private key byte array.
[in]lenRaw private key byte array length.
[in,out]kPointer to an initialized pktlab private key struct.
Returns
0 if success. < 0 if failed.

◆ pktlab_load_program()

int pktlab_load_program ( const char *  data,
uint_fast32_t  datalen,
enum pktlab_prog_type  type,
void **  prog,
uint_fast32_t *  proglen,
uint_fast32_t *  errlineno 
)

Load pktlab program from file content.

Parameters
[in]dataPointer to program file content.
[in]datalenLength of program file content in bytes.
[in]typeProgram file content program type.
[out]progPointer to return allocated loaded pktlab program bytes.
[out]proglenPointer to return loaded pktlab program length in bytes.
[out]errlinenoPointer to return the line number when a parsing error occurred.
Returns
0 for success, < 0 for failure.
  • The returned prog should be freed with free() in stdlib.h.
  • For program file content, line starting with '#', empty new line (only '
    '), and carriage-return-only line ('\r
    ') are ignored.
  • For eBPF programs, each non-ignored line should consist of 5 unsigned integers in the format acceptable to strtoull.
  • If pktlab_load_program failed due to a malformed line, the errlineno (if non-NULL) is set to the line number (1 indexed). Otherwise it is set to 0.

◆ 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]derRaw SubjectPublicKeyInfo byte array.
[in]derlenRaw SubjectPublicKeyInfo byte array length.
[in,out]kPointer to an initialized pktlab public key struct.
Returns
0 if success. < 0 if failed.

◆ 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]pemPEM-encoded public key char array.
[in]pemlenPEM-encoded public key char array length.
[in,out]kPointer to an initialized pktlab public key struct.
Returns
0 if success. < 0 if failed.

◆ 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]bytesRaw public key byte array.
[in]lenRaw public key byte array length.
[in,out]kPointer to an initialized pktlab public key struct.
Returns
0 if success. < 0 if failed.

◆ 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,
struct pktlab_cert_detail **  cert_details,
uint8_t *  subable_channel 
)

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

Parameters
[in]cert_lsA potential controller experiment privilege chain (in the form of an array of pointers to loaded pktlab certificate structs consisting) that should be parsed.
[in]certnumThe number of loaded pktlab certificate struct pointers in cert_ls.
[in]controller_keyRaw 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_keyA loaded pktlab public key struct for checking if the certificate chain root entity is some expected key.
[out]cert_detailsHead pointer to return an allocated struct storing decoded certificate detail information.
[out]subable_channelPointer 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 cert_details. 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_lsA potential endpoint representation privilege chain (in the form of an array of pointers to loaded pktlab certificate structs consisting) that should be parsed.
[in]certnumThe number of loaded pktlab certificate struct pointers in cert_ls.
[in]endpoint_keyRaw 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_keyA loaded pktlab public key struct for checking if the certificate chain root entity is some expected key.
[out]subable_channelsPointer to return a list of private channel IDs allowed to be subscribed based on cert_ls.
[out]channelnumPointer 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_infoPointer to a struct for storing the decoded result.
[in]ptrpktlab URI to decode.
[in]lenLength of pktlab URI.
Returns
  1. 0 for success.
  2. -1 for bad argument.
  3. -2 for malformed URI.
  4. 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]rInitialized pktlab reader struct.
[out]msgptrPointer 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]rInitialized 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]ptrTarget byte array.
[in]valTarget 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]bitsTarget unsigned interger to set bit.
[in]posTarget 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]statepktlab 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]secThe number of seconds to convert.
Returns
Converted result in pktlab ticks.

◆ pktlab_time_to_timespec()

static void pktlab_time_to_timespec ( pktlab_time_t  t,
struct timespec *  tp 
)
inlinestatic

Convert time period in pktlab ticks to struct timespec.

Parameters
[in]tThe number of pktlab ticks to convert.
[out]tpPointer to a timespec struct to store the converted result.

◆ 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]tThe number of pktlab ticks to convert.
[out]tvPointer 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]tThe pktlab time to convert.
Returns
The converted Unix time.

◆ pktlab_timespec_to_time()

static pktlab_time_t pktlab_timespec_to_time ( const struct timespec *  tp)
inlinestatic

Convert time period in struct timespec to pktlab ticks.

Parameters
[in]tpPointer to time period in struct timespec to convert.
Returns
Converted result in pktlab ticks.

◆ 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]tvPointer 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]tmPointer 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_modeVerification mode to use when verifying certificate chain. Must be one of enum pktlab_auth_mode values.
[in]cert_lsArray of pointers to loaded pktlab certificate structs that should be verified.
[in]root_lsArray of pointers to loaded pktlab public key structs that could serve as the certificate chain root.
[out]verified_cert_lsPointer to return the verified certificate chain (in the form of an allocated array of pointers to loaded pktlab certificate structs).
[in]certnumThe number of loaded pktlab certificate struct pointers in cert_ls.
[in]rootnumThe number of loaded pktlab public key struct pointers in root_ls.
[out]verified_certnumPointer to return the verified certificate chain length.
[out]used_root_indxPointer 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]certPointer to a loaded pktlab certificate struct.
[in]signkeyPointer 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]wInitialized pktlab writer struct.
[in]msgPointer to an initialized msg struct.
Returns
  1. 1 for successful encoding and buffering of msg (some message bytes have been sent).
  2. 0 for try again later (message bytes are not buffered).
  3. < 0 for write errors. Check errno for more information.

◆ pktlab_writer_unsent()

size_t pktlab_writer_unsent ( const struct pktlab_writer *  w)

Get writer internal buffered content length.

Parameters
[in]wInitialized pktlab writer struct.
Returns
The number of buffered bytes in w.

◆ pktlab_writer_writeaux()

void* pktlab_writer_writeaux ( const struct pktlab_writer *  w)

Get pktlab writer struct aux information.

Parameters
[in]wpktlab 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]xdescrxdescr string as the matching pattern.
[in]xdescrlenLength of xdescr string.
[in]dattrdattr string as the matching target.
[in]dattrlenLength 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.
Generated by   doxygen 1.8.17