pktctrl.h

Go to the documentation of this file.

// pktctrl.h
// The pktctrl module for handling the pktlab control session.
//
 
#ifndef _PKTCTRL_H_
#define _PKTCTRL_H_
 
#include <pktlab.h>
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include <poll.h>
#include <sys/select.h>
 
//
// EXPORTED CONSTANTS
//
 
#define PKTCTRL_SNIKEY_LEN_MIN 1
#define PKTCTRL_SNIKEY_LEN_MAX 63 // i.e. the maximum domain name label length
 
enum pktctrl_err {
    PKTCTRL_SUCCESS          = 0,
    PKTCTRL_INVAL            = 1,
    PKTCTRL_MAP_ERR          = 2,
    PKTCTRL_KEY_NOT_FOUND    = 3,
    PKTCTRL_SSL_FAILURE      = 4,
    PKTCTRL_BAD_CERT         = 5,
    PKTCTRL_BAD_CERTKEY      = 6,
    PKTCTRL_IN_PROGRESS      = 7,
    PKTCTRL_UNKNOWN_FAULT    = 127,
};
 
//
// EXPORTED FUNCTION DECLARATIONS
//
 
struct pktctrl_obj;           // opaque
struct pktctrl_keycert_store; // opaque
 
extern struct pktctrl_obj * pktctrl_create_obj(void);
extern struct pktctrl_keycert_store * pktctrl_create_keycert_store(void);
 
extern int pktctrl_set_server_keycert (
    struct pktctrl_keycert_store * store, const char * snikey,
    struct pktlab_certificate ** cert_ls, uint_fast32_t certnum,
    struct pktlab_publickey ** root_ls, uint_fast32_t rootnum);
extern int pktctrl_get_server_keycert (
    struct pktctrl_keycert_store * store, const char * snikey,
    struct pktlab_certificate *** cert_ls, uint_fast32_t * certnum,
    struct pktlab_publickey *** root_ls, uint_fast32_t * rootnum);
extern int pktctrl_clear_server_keycert (
    struct pktctrl_keycert_store * store, const char * snikey);
 
extern int pktctrl_set_server_keycert_default (
    struct pktctrl_keycert_store * store, const char * snikey);
extern int pktctrl_clear_server_keycert_default (
    struct pktctrl_keycert_store * store);
 
extern int pktctrl_set_client_keycert (
    struct pktctrl_keycert_store * store,
    struct pktlab_certificate ** cert_ls, uint_fast32_t certnum,
    struct pktlab_publickey ** root_ls, uint_fast32_t rootnum);
extern int pktctrl_get_client_keycert (
    struct pktctrl_keycert_store * store,
    struct pktlab_certificate *** cert_ls, uint_fast32_t * certnum,
    struct pktlab_publickey *** root_ls, uint_fast32_t * rootnum);
extern int pktctrl_clear_client_keycert(struct pktctrl_keycert_store * store);
 
// normal pktctrl session setup functions
// uses TLS while incorporating pktlab access control checks
extern int pktctrl_accept (
    int fd, int auth_mode,
    struct pktlab_privatekey * serverkey,
    struct pktctrl_keycert_store * store, struct pktctrl_obj * ctrlobj,
    struct pktlab_certificate *** peer_cert_ls, uint_fast32_t * peer_cert_num);
extern int pktctrl_connect (
    int fd, int auth_mode, const char * snikey,
    struct pktlab_privatekey * clientkey,
    struct pktctrl_keycert_store * store, struct pktctrl_obj * ctrlobj,
    struct pktlab_certificate *** peer_cert_ls, uint_fast32_t * peer_cert_num);
 
// special no setup alternative
// uses bare-bone TCP connection with no access control checks conducted
extern int pktctrl_raw_session (
    int fd, struct pktctrl_obj * ctrlobj);
 
extern int pktctrl_prepare_select (
    int * nfds, fd_set * restrict rset, fd_set * restrict wset,
    bool want_read, bool want_write, struct pktctrl_obj * ctrlobj);
extern int pktctrl_process_select (
    const fd_set * restrict rset, const fd_set * restrict wset,
    struct pktctrl_obj * ctrlobj, bool * readable, bool * writable);
 
extern int pktctrl_prepare_poll (
    struct pollfd * restrict pfd,
    bool want_read, bool want_write,
    struct pktctrl_obj * ctrlobj);
extern int pktctrl_process_poll (
    const struct pollfd * restrict pfd,
    struct pktctrl_obj * ctrlobj,
    bool * readable, bool * writable);
 
extern int pktctrl_read_message (
    struct pktctrl_obj * ctrlobj,
    struct pktlab_message ** msgptr);
extern int pktctrl_write_message (
    struct pktctrl_obj * ctrlobj,
    const struct pktlab_message * msg);
extern int pktctrl_flush_write(struct pktctrl_obj * ctrlobj);
extern size_t pktctrl_write_unsent(const struct pktctrl_obj * ctrlobj);
 
// for non-buffered raw bytes reading
// should not be used after using pktctrl_read_message/pktctrl_write_message
extern ssize_t pktctrl_read (
    struct pktctrl_obj * obj,
    void * buf, size_t nbyte);
extern ssize_t pktctrl_write (
    struct pktctrl_obj * obj,
    const void * buf, size_t nbyte);
 
extern int pktctrl_close(struct pktctrl_obj * obj);
extern int pktctrl_cleanup_keycert_store(struct pktctrl_keycert_store * store);
 
extern bool pktctrl_is_established(struct pktctrl_obj * obj);
 
extern bool pktctrl_is_valid_snikey(const char * snikey);
extern int pktctrl_gen_snikey(char ** buf);
 
#endif