axa
1.2.1
Farsight Security Advanced Exchange Access (AXA)
|
axa_wire
is an interface for wire protocol data types and function declarations.
Data Structures | |
struct | axa_io |
AXA I/O context. More... | |
Macros | |
#define | AXA_TAG_STRLEN 10 |
maximum human readable tag string length More... | |
#define | AXA_P_OP_STRLEN 20 |
maximum buffer size for text representations of AXA opcodes More... | |
#define | AXA_P_STRLEN |
Maximum buffer or string length from axa_p_to_str() More... | |
#define | AXA_IO_TYPE_UNIX_STR "unix" |
AXA I/O type prefix: UNIX domain socket unix:/path/to/socket. More... | |
#define | AXA_IO_TYPE_TCP_STR "tcp" |
AXA I/O type prefix: TCP connection tcp:hostname,port. More... | |
#define | AXA_IO_TYPE_SSH_STR "ssh" |
AXA I/O type prefix: ssh connection ssh:[user@]host. More... | |
#define | AXA_IO_TYPE_TLS_STR "tls" |
AXA I/O type prefix: tls connection tls:certfile,keyfile[,certdir]@host[,port]. More... | |
#define | AXA_IO_OPENED(io) ((io)->i_fd >= 0) |
Check than an AXA I/O context is open. More... | |
#define | AXA_IO_CONNECTED(io) (AXA_IO_OPENED(io) && (io)->connected) |
check that an AXA I/O context is open and connected More... | |
Typedefs | |
typedef struct axa_io | axa_io_t |
AXA I/O context. More... | |
Enumerations | |
enum | axa_p_direction_t |
AXA protocol data direction, to or from SRA or RAD server. More... | |
enum | axa_io_type_t |
AXA I/O context types. More... | |
enum | axa_io_result_t |
I/O result codes. More... | |
Functions | |
bool | axa_parse_watch (axa_emsg_t *emsg, axa_p_watch_t *watch, size_t *watch_len, const char *arg) |
Parse an AXA watch definition. More... | |
bool | axa_parse_rad_watch (axa_emsg_t *emsg, axa_p_watch_t *watch, size_t *watch_len, const char *arg) |
Parse a RAD watch definition. More... | |
bool | axa_parse_anom (axa_emsg_t *emsg, axa_p_anom_t *anom, size_t *anom_len, const char *arg) |
Parse an AXA anomaly detection module definition. More... | |
char * | axa_watch_to_str (char *buf, size_t buf_len, const axa_p_watch_t *watch, size_t watch_len) |
Convert a watch to its string equivalent. More... | |
const char * | axa_tag_to_str (char *buf, size_t buf_len, axa_tag_t tag) |
Convert AXA tag to its string equivalent. More... | |
const char * | axa_op_to_str (char *buf, size_t buf_len, axa_p_op_t op) |
Convert AXA opcode to its string equivalent. More... | |
const char * | axa_tag_op_to_str (char *buf, size_t buf_len, axa_tag_t tag, axa_p_op_t op) |
Convert AXA tag and opcode to their string equivalents separated by ' '. More... | |
bool | axa_ipdg_parse (const uint8_t *pkt_data, size_t caplen, axa_p_ch_t ch, axa_socku_t *dst, axa_socku_t *src, char *cmt, size_t cmt_len) |
Parse a raw IP datagram. More... | |
char * | axa_p_to_str (char *buf, size_t buf_len, bool print_op, const axa_p_hdr_t *hdr, const axa_p_body_t *cmd) |
Convert AXA protocol message to a string representation. More... | |
size_t | axa_make_hdr (axa_emsg_t *emsg, axa_p_hdr_t *hdr, axa_p_pvers_t pvers, axa_tag_t tag, axa_p_op_t op, size_t b1_len, size_t b2_len, axa_p_direction_t dir) |
Populate an AXA header including converting to wire byte order. More... | |
bool | axa_ck_body (axa_emsg_t *emsg, axa_p_op_t op, const axa_p_body_t *body, size_t body_len) |
Sanity check the body of an AXA message. More... | |
void | axa_io_init (axa_io_t *io) |
Initialize an AXA I/O structure with default values. More... | |
void | axa_recv_flush (axa_io_t *io) |
Flush and free the received AXA protocol message (if any) in an I/O context from a previous use of axa_recv_buf() or axa_input(). More... | |
void | axa_io_close (axa_io_t *io) |
Close the connection and flush and release buffers. More... | |
axa_io_result_t | axa_recv_buf (axa_emsg_t *emsg, axa_io_t *io) |
Receive some of an AXA request or response into a fixed header buffer and a dynamic body buffer. More... | |
axa_io_result_t | axa_send (axa_emsg_t *emsg, axa_io_t *io, axa_tag_t tag, axa_p_op_t op, axa_p_hdr_t *hdr, const void *b1, size_t b1_len, const void *b2, size_t b2_len) |
Send an AXA request or response to the client or the server. More... | |
axa_io_result_t | axa_send_flush (axa_emsg_t *emsg, axa_io_t *io) |
Flush the pending output buffer. More... | |
void | axa_send_save (axa_io_t *io, size_t done, const axa_p_hdr_t *hdr, const void *b1, size_t b1_len, const void *b2, size_t b2_len) |
Save un-transmitted data. More... | |
axa_io_result_t | axa_io_wait (axa_emsg_t *emsg, axa_io_t *io, time_t wait_ms, bool keepalive, bool tun) |
Wait for some input activity. More... | |
axa_io_result_t | axa_input (axa_emsg_t *emsg, axa_io_t *io, time_t wait_ms) |
Wait for and read an AXA message from the server into the client context. More... | |
const char * | axa_io_tunerr (axa_io_t *io) |
Get error or debugging messages from the tunnel (e.g. More... | |
bool | axa_tls_certs_dir (axa_emsg_t *emsg, const char *dir) |
Get or set TLS certificates directory. More... | |
const char * | axa_tls_cipher_list (axa_emsg_t *emsg, const char *list) |
Get or set TLS certificate list. More... | |
bool | axa_tls_init (axa_emsg_t *emsg, bool srvr, bool threaded) |
Initialize the AXA TLS code including creating a SSL_CTX. More... | |
void | axa_io_cleanup (void) |
Clean up AXA I/O functions including freeing TLS data. More... | |
#define AXA_TAG_STRLEN 10 |
maximum human readable tag string length
#define AXA_P_OP_STRLEN 20 |
maximum buffer size for text representations of AXA opcodes
#define AXA_P_STRLEN |
Maximum buffer or string length from axa_p_to_str()
#define AXA_IO_TYPE_UNIX_STR "unix" |
AXA I/O type prefix: UNIX domain socket unix:/path/to/socket.
#define AXA_IO_TYPE_TCP_STR "tcp" |
AXA I/O type prefix: TCP connection tcp:hostname,port.
#define AXA_IO_TYPE_SSH_STR "ssh" |
AXA I/O type prefix: ssh connection ssh:[user@]host.
#define AXA_IO_TYPE_TLS_STR "tls" |
AXA I/O type prefix: tls connection tls:certfile,keyfile[,certdir]@host[,port].
#define AXA_IO_OPENED | ( | io | ) | ((io)->i_fd >= 0) |
Check than an AXA I/O context is open.
[in] | io | address of an I/O context |
#define AXA_IO_CONNECTED | ( | io | ) | (AXA_IO_OPENED(io) && (io)->connected) |
check that an AXA I/O context is open and connected
[in] | io | address of an I/O context |
enum axa_p_direction_t |
enum axa_io_type_t |
enum axa_io_result_t |
I/O result codes.
Enumerator | |
---|---|
AXA_IO_ERR |
print emsg |
AXA_IO_OK |
operation finished |
AXA_IO_BUSY |
incomplete; poll() & try again |
AXA_IO_TUNERR |
get text via axa_io_tunerr() |
AXA_IO_KEEPALIVE |
need to send keepalive NOP |
bool axa_parse_watch | ( | axa_emsg_t * | emsg, |
axa_p_watch_t * | watch, | ||
size_t * | watch_len, | ||
const char * | arg | ||
) |
Parse an AXA watch definition.
If there is a problem, the function will return false and emsg->c will contain a relevant error message – except when the watch makes no sense. In that case, emsg->c[0] == '\0'.
[out] | emsg | the reason if something went wrong |
[out] | watch | parsed result |
[out] | watch_len | sizeof(*watch) - sizeof(watch->pat); |
[in] | arg | user specified string to watch for, must be NULL terminated |
true | success |
false | error; check emsg |
bool axa_parse_rad_watch | ( | axa_emsg_t * | emsg, |
axa_p_watch_t * | watch, | ||
size_t * | watch_len, | ||
const char * | arg | ||
) |
Parse a RAD watch definition.
If there is a problem, the function will return false and emsg->c will contain a relevant error message – except when the watch is unrecognized. In that case, emsg->c[0] == '\0'.
[out] | emsg | if something goes wrong, this will contain the reason |
[out] | watch | parsed result |
[out] | watch_len | sizeof(*watch) - sizeof(watch->pat); |
[in] | arg | user specified string to watch for, must be NULL terminated |
true | success |
false | error, check emsg |
bool axa_parse_anom | ( | axa_emsg_t * | emsg, |
axa_p_anom_t * | anom, | ||
size_t * | anom_len, | ||
const char * | arg | ||
) |
Parse an AXA anomaly detection module definition.
If there is a problem, the function will return false and emsg->c will contain a relevant error message – except when the watch is unrecognized. In that case, emsg->c[0] == '\0'.
[out] | emsg | if something goes wrong, this will contain the reason |
[out] | anom | parsed result |
[out] | anom_len | sizeof(*watch) - sizeof(watch->pat); |
[in] | arg | user specified string to watch for, must be NULL terminated |
true | success |
false | error, check emsg |
char* axa_watch_to_str | ( | char * | buf, |
size_t | buf_len, | ||
const axa_p_watch_t * | watch, | ||
size_t | watch_len | ||
) |
Convert a watch to its string equivalent.
[out] | buf | will hold the watch string |
[in] | buf_len | length of buf |
[in] | watch | the watch to convert |
[in] | watch_len | size of the watch parameter |
const char* axa_tag_to_str | ( | char * | buf, |
size_t | buf_len, | ||
axa_tag_t | tag | ||
) |
Convert AXA tag to its string equivalent.
If the tag is AXA_TAG_NONE, buf will contain "*".
[out] | buf | will hold the tag string |
[in] | buf_len | length of buf (should be AXA_TAG_STRLEN) |
[in] | tag | the AXA tag value |
const char* axa_op_to_str | ( | char * | buf, |
size_t | buf_len, | ||
axa_p_op_t | op | ||
) |
Convert AXA opcode to its string equivalent.
If the opcode is unknown to AXA, the buffer will contain the string "unknown op n".
[out] | buf | will hold the opcode string |
[in] | buf_len | length of buf (should be AXA_P_OP_STRLEN) |
[in] | op | the opcode to look up |
const char* axa_tag_op_to_str | ( | char * | buf, |
size_t | buf_len, | ||
axa_tag_t | tag, | ||
axa_p_op_t | op | ||
) |
Convert AXA tag and opcode to their string equivalents separated by ' '.
[out] | buf | for the result |
[in] | buf_len | length of buf (should be AXA_P_OP_STRLEN) |
[in] | tag | the tag to convert |
[in] | op | the opcode to convert |
bool axa_ipdg_parse | ( | const uint8_t * | pkt_data, |
size_t | caplen, | ||
axa_p_ch_t | ch, | ||
axa_socku_t * | dst, | ||
axa_socku_t * | src, | ||
char * | cmt, | ||
size_t | cmt_len | ||
) |
Parse a raw IP datagram.
[in] | pkt_data | IP datagram |
[in] | caplen | captured length of the packet |
[in] | ch | host byte order SIE channel on which it arrived |
[out] | dst | buffer for destination address and port number |
[out] | src | buffer for destination address and port number |
[out] | cmt | buffer for error messages, optional protocol name,or other optional comments; always '\0' terminated |
[in] | cmt_len | length of cmt; 80 is good |
true | found something to decode into the src and dst buffers |
false | only the cmt buffer is set |
char* axa_p_to_str | ( | char * | buf, |
size_t | buf_len, | ||
bool | print_op, | ||
const axa_p_hdr_t * | hdr, | ||
const axa_p_body_t * | cmd | ||
) |
Convert AXA protocol message to a string representation.
Return NULL if the protocol message is invalid.
[out] | buf | will hold the message string |
[in] | buf_len | length of buf (should be AXA_P_STRLEN) |
[in] | print_op | if true, prepend the tag and opcode to string |
[in] | hdr | protocol header |
[in] | cmd | AXA command to parse into a string |
size_t axa_make_hdr | ( | axa_emsg_t * | emsg, |
axa_p_hdr_t * | hdr, | ||
axa_p_pvers_t | pvers, | ||
axa_tag_t | tag, | ||
axa_p_op_t | op, | ||
size_t | b1_len, | ||
size_t | b2_len, | ||
axa_p_direction_t | dir | ||
) |
Populate an AXA header including converting to wire byte order.
[out] | emsg | the reason if the return value is 0 |
[out] | hdr | AXA protocol header (will be filled in) |
[in] | pvers | protocol version |
[in] | tag | AXA tag |
[in] | op | AXA opcode |
[in] | b1_len | length of first message body (if any) |
[in] | b2_len | length of second message body (if any) |
[in] | dir | the direction of the flow (to/from SRA to to/from RAD) |
bool axa_ck_body | ( | axa_emsg_t * | emsg, |
axa_p_op_t | op, | ||
const axa_p_body_t * | body, | ||
size_t | body_len | ||
) |
Sanity check the body of an AXA message.
Depending on the opcode, function checks such things as NULL termination on strings, sane channel numbers, legal options, watch semantics, etc.
[out] | emsg | if something goes wrong, this will contain the reason |
[in] | op | opcode |
[in] | body | message body |
[in] | body_len | message body length |
true | message is legal |
false | something's wrong, check emsg |
void axa_io_init | ( | axa_io_t * | io | ) |
Initialize an AXA I/O structure with default values.
When re-initializing, all buffers must have been freed and file descriptors closed.
[in] | io | address of a io context |
void axa_recv_flush | ( | axa_io_t * | io | ) |
Flush and free the received AXA protocol message (if any) in an I/O context from a previous use of axa_recv_buf() or axa_input().
[in] | io | address of an I/O context |
void axa_io_close | ( | axa_io_t * | io | ) |
Close the connection and flush and release buffers.
[in] | io | address of an I/O structure |
axa_io_result_t axa_recv_buf | ( | axa_emsg_t * | emsg, |
axa_io_t * | io | ||
) |
Receive some of an AXA request or response into a fixed header buffer and a dynamic body buffer.
This function can stall until a byte is read, so call axa_io_wait() first or axa_input() instead. axa_recv_flush() must be called to discard the AXA message before another use of this function.
[out] | emsg | if something goes wrong, this will contain the reason |
[in] | io | AXA IO context |
AXA_IO_OK | message in io->recv_hdr, recv_body, and recv_len |
AXA_IO_BUSY | try again after axa_io_wait() |
AXA_IO_ERR | fatal error or EOF |
axa_io_result_t axa_send | ( | axa_emsg_t * | emsg, |
axa_io_t * | io, | ||
axa_tag_t | tag, | ||
axa_p_op_t | op, | ||
axa_p_hdr_t * | hdr, | ||
const void * | b1, | ||
size_t | b1_len, | ||
const void * | b2, | ||
size_t | b2_len | ||
) |
Send an AXA request or response to the client or the server.
The message is in 1, 2, or 3 parts. hdr always points to the AXA protocol header to build b1 and b1_len specify an optional second part b2 and b2_len specify the optional third part. The second part must be present if the third part is.
[out] | emsg | an error message for a result of AXA_IO_ERR |
[in] | io | AXA I/O context |
[in] | tag | AXA tag |
[in] | op | AXA opcode |
[out] | hdr | AXA protocol header to be built or NULL |
[in] | b1 | NULL or first part of AXA message after header |
[in] | b1_len | length of b1 |
[in] | b2 | NULL or second part of the message |
[in] | b2_len | length of b2 |
AXA_IO_OK | finished or output saved |
AXA_IO_BUSY | nothing sent; axa_io_wait() and try again |
AXA_IO_ERR | fatal error |
axa_io_result_t axa_send_flush | ( | axa_emsg_t * | emsg, |
axa_io_t * | io | ||
) |
Flush the pending output buffer.
[out] | emsg | contains an error message for return values other than AXA_IO_OK |
[in] | io | AXA I/O context |
AXA_IO_OK | finished |
AXA_IO_BUSY | incomplete; io->{i,o}_events ready for axa_io_wait() |
AXA_IO_ERR | fatal error |
void axa_send_save | ( | axa_io_t * | io, |
size_t | done, | ||
const axa_p_hdr_t * | hdr, | ||
const void * | b1, | ||
size_t | b1_len, | ||
const void * | b2, | ||
size_t | b2_len | ||
) |
Save un-transmitted data.
[in] | io | AXA I/O context |
[in] | done | bytes already handled |
[out] | hdr | AXA protocol header |
[in] | b1 | NULL or first part of AXA message after header |
[in] | b1_len | length of b1 |
[in] | b2 | NULL or second part of the message |
[in] | b2_len | length of b2 |
axa_io_result_t axa_io_wait | ( | axa_emsg_t * | emsg, |
axa_io_t * | io, | ||
time_t | wait_ms, | ||
bool | keepalive, | ||
bool | tun | ||
) |
Wait for some input activity.
[out] | emsg | if something goes wrong, this will contain the reason |
[in] | io | address of the AXA I/O context |
[in] | wait_ms | wait no longer than this many milliseconds |
[in] | keepalive | true to wake up to send a keep-alive |
[in] | tun | true to pay attention if possible to tunnel messages |
one | of axa_io_result_t |
axa_io_result_t axa_input | ( | axa_emsg_t * | emsg, |
axa_io_t * | io, | ||
time_t | wait_ms | ||
) |
Wait for and read an AXA message from the server into the client context.
axa_recv_flush() must be called to discard the AXA message in the client context before another use of this function.
[out] | emsg | if something goes wrong, this will contain the reason |
[in] | io | address of the AXA I/O context |
[in] | wait_ms | milliseconds to wait |
one | of axa_io_result_t |
const char* axa_io_tunerr | ( | axa_io_t * | io | ) |
Get error or debugging messages from the tunnel (e.g.
ssh).
[in] | io | address of the AXA I/O context |
NULL | or pointer to '\0' terminated text |
bool axa_tls_certs_dir | ( | axa_emsg_t * | emsg, |
const char * | dir | ||
) |
Get or set TLS certificates directory.
[out] | emsg | the reason if something went wrong |
[in] | dir | directory containing TLS certificate key files or NULL |
true | success |
false | error; check emsg |
const char* axa_tls_cipher_list | ( | axa_emsg_t * | emsg, |
const char * | list | ||
) |
Get or set TLS certificate list.
[out] | emsg | the reason if something went wrong |
[in] | list | OpenSSL format cipher list or NULL |
NULL | implies an error; check emsg |
new | value if not NULL |
bool axa_tls_init | ( | axa_emsg_t * | emsg, |
bool | srvr, | ||
bool | threaded | ||
) |
Initialize the AXA TLS code including creating a SSL_CTX.
[out] | emsg | the reason if something went wrong |
[in] | srvr | true if running as a server. |
[in] | threaded | true if using pthreads. |
true | success |
false | error; check emsg |
void axa_io_cleanup | ( | void | ) |
Clean up AXA I/O functions including freeing TLS data.