1 /* 2 * Advanced Exchange Access (AXA) protocol definitions 3 * 4 * This file is used outside the AXA programs. 5 * 6 * Copyright (c) 2014-2018 by Farsight Security, Inc. 7 * 8 * Licensed under the Apache License, Version 2.0 (the "License"); 9 * you may not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 21 #ifndef AXA_PROTOCOL_H 22 #define AXA_PROTOCOL_H 23 24 /** 25 * \defgroup axa_protocol axa_protocol 26 * 27 * `axa_protocol` contains the AXA protocol data types and macros. 28 * 29 * This protocol uses network byte order to accommodate SRA clients 30 * on a modest variety of 32-bit and 64-bit *BSD and Linux systems. 31 * 32 * It might need adjustment to accommodate clients on ARM and other 33 * platforms other than amd64 and x86. 34 * 35 * These protocols should not allow the client ask for the server to run 36 * any program or do anything else that might change any permanent state on 37 * the server other than logging and accounting. 38 * 39 * A client should only be able to set its only filter criteria and 40 * receive packets and messages matching those criteria. Other than 41 * inevitable side channels such as system load, one client must 42 * not be able to affect any other client. A client must treat the 43 * packets and messages it receives as pure data and not commands. 44 * 45 * @{ 46 */ 47 48 #include <sys/types.h> 49 #include <sys/poll.h> 50 #include <netinet/in.h> 51 52 #include <axa/socket.h> 53 #include <axa/bits.h> 54 55 /** 56 * Pack AXA structures in messages to make them the same for all platforms 57 * regardless of their word alignment restrictions. 58 */ 59 #define _PK __attribute__ ((__packed__)) 60 61 /** Send an AXA_P_OP_NOP after this many seconds of silence */ 62 #define AXA_KEEPALIVE_SECS 30 63 /** Send an AXA_P_OP_NOP after this many milliseconds of silence */ 64 #define AXA_KEEPALIVE_MS (AXA_KEEPALIVE_SECS*1000) 65 66 67 /** 68 * A tag is a 16-bit identifier used to uniquely "tag" specific events during 69 * the lifetime of an AXA session. To refer to these events, the client or 70 * server will use the tag. Some AXA messages do not require tags, in that 71 * case the tag field should be 0. Required tags must be unique during the 72 * lifetime of the corresponding client request. Some client requests such as 73 * a "watch" can last indefinitely and will elicit many server responses all 74 * with the same tag. 75 * 76 * Tags are opaque to the SRA server except for AXA_TAG_NONE and 77 * that the server sorts or orders them like integers. 78 */ 79 typedef uint16_t axa_tag_t; 80 81 #define AXA_TAG_NONE 0 /**< no tag */ 82 #define AXA_TAG_MIN 1 /**< minimum tag */ 83 #define AXA_TAG_MAX ((axa_tag_t)-1) /**< maximum tag */ 84 85 /** 86 * Convert tag from protocol to host byte order. 87 * 88 * \param[in] t tag 89 * 90 * \return host byte ordered tag 91 */ 92 #define AXA_P2H_TAG(t) AXA_P2H16(t) 93 94 /** 95 * Convert tag from host to protocol byte order. 96 * 97 * \param[in] t tag 98 * 99 * \return protocol byte ordered tag 100 */ 101 #define AXA_H2P_TAG(t) AXA_H2P16(t) 102 103 /** define old versions for eventual "#ifdef AXA_P_VERSx" */ 104 typedef uint8_t axa_p_pvers_t; 105 /** protocol versions */ 106 #define AXA_P_PVERS1 1 107 #define AXA_P_PVERS2 2 108 /** current protocol version */ 109 #define AXA_P_PVERS AXA_P_PVERS2 110 /** minimum understood protocol version */ 111 #define AXA_P_PVERS_MIN AXA_P_PVERS1 112 /** maximum understood protocol version */ 113 #define AXA_P_PVERS_MAX AXA_P_PVERS2 114 115 /** a number of messages or seconds */ 116 typedef uint64_t axa_cnt_t; 117 118 119 /** 120 * Choose a generally little endian protocol. 121 * This must not affect some values such as UDP port numbers and 122 * IPv4 addresses which must be big endian except when they are 123 * manipulated as numbers. 124 * Hence, AXA_H2Pxx() stands for "AXA Host to Protocol..." 125 */ 126 #if 1 /**< 0=switch to big endian protocol for testing */ 127 /** 128 * AXA host to protocol 16-bit 129 * 130 * \param x value to convert 131 * 132 * \return protocol byte ordered 16-bit value 133 */ 134 #define AXA_H2P16(x) htole16(x) 135 /** 136 * AXA host to protocol 32-bit 137 * 138 * \param x value to convert 139 * 140 * \return protocol byte ordered 32-bit value 141 */ 142 #define AXA_H2P32(x) htole32(x) 143 /** 144 * AXA host to protocol 64-bit 145 * 146 * \param x value to convert 147 * 148 * \return protocol byte ordered 64-bit value 149 */ 150 #define AXA_H2P64(x) htole64(x) 151 /** 152 * AXA protocol to host 16-bit 153 * 154 * \param x value to convert 155 * 156 * \return host byte ordered 16-bit value 157 */ 158 #define AXA_P2H16(x) le16toh(x) 159 /** 160 * AXA protocol to host 32-bit 161 * 162 * \param x value to convert 163 * 164 * \return host byte ordered 32-bit value 165 */ 166 #define AXA_P2H32(x) le32toh(x) 167 /** 168 * AXA protocol to host 64-bit 169 * 170 * \param x value to convert 171 * 172 * \return host byte ordered 64-bit value 173 */ 174 #define AXA_P2H64(x) le64toh(x) 175 #else 176 /**< @cond */ 177 #define AXA_H2P16(x) htobe16(x) 178 #define AXA_H2P32(x) htobe32(x) 179 #define AXA_H2P64(x) htobe64(x) 180 #define AXA_P2H16(x) be16toh(x) 181 #define AXA_P2H32(x) be32toh(x) 182 #define AXA_P2H64(x) be64toh(x) 183 /**< @endcond */ 184 #endif 185 186 /** room for more than two full sized UDP packets */ 187 #define AXA_P_MAX_BODY_LEN (64*1024*3) 188 189 /** 190 * Clients must authenticate themselves to the AXA server within this 191 * many seconds after connect(). 192 */ 193 #define AXA_AUTH_DELAY 30 194 195 /** 196 * AXA protocol header. 197 * 198 * This header starts all messages in either direction. At 8 bytes, it is 199 * alignment friendly. 200 */ 201 typedef struct _PK { 202 uint32_t len; /**< total length including header */ 203 /** 204 * A tag is a 16-bit identifier used to uniquely "tag" specific events 205 * during the lifetime of an AXA session. To refer to these events, 206 * the client or server will use the tag. Some AXA messages do not 207 * use tags. In those cases, the tag field should be 0. Required 208 * tags must be unique during the lifetime of the corresponding client 209 * request. Some requests such as a "watch" last indefinitely and 210 * can elicit many server responses all with the same tag. 211 */ 212 axa_tag_t tag; 213 axa_p_pvers_t pvers; /**< protocol version */ 214 uint8_t op; /**< op code */ 215 } axa_p_hdr_t; 216 217 /** 218 * AXA protocol opcodes 219 * Use a single address space of opcodes in both directions. 220 */ 221 typedef enum { 222 AXA_P_OP_NOP =0, /**< no data */ 223 224 /** from SRA or RAD server to client */ 225 AXA_P_OP_HELLO =1, /**< axa_p_hello_t */ 226 AXA_P_OP_OK =2, /**< axa_p_result_t */ 227 AXA_P_OP_ERROR =3, /**< axa_p_result_t */ 228 AXA_P_OP_MISSED =4, /**< axa_p_missed_t */ 229 AXA_P_OP_WHIT =5, /**< axa_p_whit_t */ 230 AXA_P_OP_WLIST =6, /**< axa_p_wlist_t */ 231 AXA_P_OP_AHIT =7, /**< axa_p_ahit_t */ 232 AXA_P_OP_ALIST =8, /**< axa_p_alist_t */ 233 AXA_P_OP_CLIST =9, /**< axa_p_clist_t */ 234 AXA_P_OP_MISSED_RAD =10, /**< axa_p_missed_rad_t */ 235 AXA_P_OP_MGMT_GETRSP=11, /**< deprecated */ 236 _AXA_P_OP_KILL_RSP =12, /**< _axa_p_kill_t */ 237 _AXA_P_OP_STATS_RSP =13, /**< _axa_p_stats_t */ 238 239 /** from client to SRA or RAD server */ 240 AXA_P_OP_USER =129, /**< axa_p_user_t */ 241 AXA_P_OP_JOIN =130, /**< no data */ 242 AXA_P_OP_PAUSE =131, /**< no data */ 243 AXA_P_OP_GO =132, /**< no data */ 244 AXA_P_OP_WATCH =133, /**< axa_p_watch_t */ 245 AXA_P_OP_WGET =134, /**< no data */ 246 AXA_P_OP_ANOM =135, /**< axa_p_anom_t */ 247 AXA_P_OP_AGET =136, /**< no data */ 248 AXA_P_OP_STOP =137, /**< no data */ 249 AXA_P_OP_ALL_STOP =138, /**< no data */ 250 AXA_P_OP_CHANNEL =139, /**< axa_p_channel_t */ 251 AXA_P_OP_CGET =140, /**< no data */ 252 AXA_P_OP_OPT =141, /**< axa_p_opt_t */ 253 AXA_P_OP_ACCT =142, /**< no data */ 254 255 AXA_P_OP_RADU =143, /**< no data */ 256 AXA_P_OP_MGMT_GET =144, /**< deprecated */ 257 _AXA_P_OP_KILL_REQ =145, /**< _axa_p_kill_t */ 258 _AXA_P_OP_STATS_REQ =146, /**< _axa_p_stats_req_t */ 259 } axa_p_op_t; 260 261 /** 262 * The AXA client ID is assigned by AXA server and echoed by the client 263 * to the server to bundle TCP connections. 264 */ 265 typedef uint64_t axa_p_clnt_id_t; 266 267 /** 268 * The AXA HELLO protocol is a bidirectional handshaking process initiated 269 * by the server, once a client has authenticated. 270 * 271 * server -> client 272 * After successful authentication, the server will send to the client a 273 * HELLO message via an axa_p_hello_t header announcing the protocol versions 274 * that the server understands, a version string, and a unique ID that can be 275 * later used by clients via AXA_P_OP_JOIN messages to flag connections that 276 * are part of a bundle. Because AXA_P_OP_HELLO is sent before the client has 277 * said anything and so declared its protocol version, AXA_P_OP_HELLO must 278 * remain the same in all versions of the AXA protocol. 279 * 280 * client -> server 281 * After receiving the server's HELLO, the client will respond with its 282 * part of the handshake. It will populate the same axa_p_hello_t header 283 * announcing the protocol versions it speaks and a detailed JSON blob 284 * containing information about the client including the following: 285 * 286 * - hostname of client system 287 * - client system information as per the uname() function 288 * - client program of origin (sratool, sratunnel, etc) 289 * - libaxa version 290 * - libnmsg version 291 * - libwdns version 292 * - libyajl version 293 * - openssl version 294 * - libprotobuf version 295 * - AXA protocol version in current use 296 * 297 * The ID field of the axa_p_hello_t header is unused in this direction. It 298 * is expected the server will log this information for subsequent issue 299 * debugging or data mining. 300 * 301 */ 302 typedef struct _PK { 303 axa_p_clnt_id_t id; /**< client ID for bundled TCP */ 304 axa_p_pvers_t pvers_min; /**< min protocol version accepted */ 305 axa_p_pvers_t pvers_max; /**< max protocol version accepted */ 306 char str[512]; /**< data about server/client */ 307 } axa_p_hello_t; 308 309 /** AXA protocol join */ 310 typedef struct _PK { 311 axa_p_clnt_id_t id; /**< client ID originally from server */ 312 } axa_p_join_t; 313 314 /** AXA protocol result */ 315 typedef struct _PK { 316 uint8_t orig_op; /**< original axa_p_op_t */ 317 /** 318 * Human readable string containing an error, success, or other 319 * about the recent operation in .op with the tag the header of 320 * this message. It is variable length string up to 512 bytes the 321 * including terminating null. 322 */ 323 char str[512]; 324 } axa_p_result_t; 325 326 /** AXA protocol SRA missed data */ 327 typedef struct _PK { 328 /** 329 * The number of packets (SIE messages or raw IP packets) lost in 330 * the network between the source and the SRA server or dropped by 331 * the SRA server because it was too busy. 332 */ 333 axa_cnt_t missed; 334 axa_cnt_t dropped; /**< by SRA client-server congestion */ 335 axa_cnt_t rlimit; /**< dropped by rate limiting */ 336 axa_cnt_t filtered; /**< total considered */ 337 uint32_t last_report; /**< UNIX epoch of previous report */ 338 } axa_p_missed_t; 339 340 /** AXA protocol RAD missed data */ 341 typedef struct _PK { 342 axa_cnt_t sra_missed; /**< missed by all SRA servers */ 343 axa_cnt_t sra_dropped; /**< for SRA client-server congestion */ 344 axa_cnt_t sra_rlimit; /**< discarded to SRA rate limit */ 345 axa_cnt_t sra_filtered; /**< considered by SRA servers */ 346 axa_cnt_t dropped; /**< for RAD client-server congestion */ 347 axa_cnt_t rlimit; /**< discarded to RAD rate limit */ 348 axa_cnt_t filtered; /**< considered by RAD modules */ 349 uint32_t last_report; /**< UNIX epoch of previous report */ 350 } axa_p_missed_rad_t; 351 352 /** AXA protocol user name */ 353 typedef struct _PK { 354 /** ASCII, variable length, null terminated user name */ 355 char name[64]; 356 } axa_p_user_t; 357 358 /** 359 * Null terminated ASCII string naming an SIE channel in configuration files, 360 * sratool commands, and sratunnel args. 361 */ 362 typedef struct { 363 char c[16]; /**< channel string */ 364 } axa_p_ch_buf_t; 365 366 /** SIE channel name prefix in configuration files, commands, and args */ 367 #define AXA_OP_CH_PREFIX "ch" 368 369 /** a binary SIE channel number in the AXA protocol */ 370 typedef uint16_t axa_p_ch_t; 371 372 /** "all SIE channels" in configuration files, commands, and args */ 373 #define AXA_OP_CH_ALL ((axa_p_ch_t)-1) 374 /** "all SIE channels" in AXA protocol messages and some axalib functions */ 375 #define AXA_OP_CH_ALLSTR "all" 376 377 /** maximum channel number */ 378 #define AXA_OP_CH_MAX 4095 379 380 /** 381 * Convert binary channel number from protocol to host byte order 382 * 383 * \param[in] ch channel 384 * 385 * \return host byte ordered SIE channel number 386 */ 387 #define AXA_P2H_CH(ch) AXA_P2H16(ch) 388 389 /** 390 * Convert channel number from host to protocol byte order 391 * 392 * \param[in] ch channel 393 * 394 * \return protocol byte ordered SIE channel number 395 */ 396 #define AXA_H2P_CH(ch) AXA_H2P16(ch) 397 398 399 /** type of AXA watch "hit" being reported to the client */ 400 typedef enum { 401 AXA_P_WHIT_NMSG =0, /**< NMSG or SIE message */ 402 AXA_P_WHIT_IP =1, /**< IP */ 403 } axa_p_whit_enum_t; 404 405 /** AXA protocol header before all watch hits */ 406 typedef struct _PK { 407 axa_p_ch_t ch; /**< channel number */ 408 uint8_t type; /**< axa_p_whit_enum_t */ 409 uint8_t pad; /**< to 0 mod 4 */ 410 } axa_p_whit_hdr_t; 411 412 /** NMSG (SIE) field or value index or a special flag */ 413 typedef uint16_t axa_nmsg_idx_t; 414 /** values >= than this are not NMSG indices but flags */ 415 #define AXA_NMSG_IDX_RSVD ((axa_nmsg_idx_t)-16) 416 /** no NMSG index */ 417 #define AXA_NMSG_IDX_NONE (AXA_NMSG_IDX_RSVD+1) 418 /** the SIE packet made no sense */ 419 #define AXA_NMSG_IDX_ERROR (AXA_NMSG_IDX_RSVD+2) 420 /** the AXA message is a dark channel packet */ 421 #define AXA_NMSG_IDX_DARK (AXA_NMSG_IDX_RSVD+3) 422 423 /** 424 * Convert #axa_nmsg_idx_t index from protocol to host byte order 425 * 426 * \param[in] idx index 427 * 428 * \return host byte ordered index, vendor number, etc. 429 */ 430 #define AXA_P2H_IDX(idx) AXA_P2H16(idx) 431 432 /** 433 * Convert #axa_nmsg_idx_t index from host to protocol byte order 434 * 435 * \param[in] idx index 436 * 437 * \return protocol byte ordered index 438 */ 439 #define AXA_H2P_IDX(idx) AXA_H2P16(idx) 440 441 /** AXA protocol watch hit header before an NMSG message */ 442 typedef struct _PK { 443 axa_p_whit_hdr_t hdr; /**< header for all watch hits */ 444 axa_nmsg_idx_t field_idx; /**< triggering field index */ 445 axa_nmsg_idx_t val_idx; /**< which value of field */ 446 axa_nmsg_idx_t vid; /**< NMSG vendor ID */ 447 axa_nmsg_idx_t type; /**< NMSG type */ 448 /** timestamp when the NMSG message was reported. */ 449 struct _PK { 450 uint32_t tv_sec; /**< seconds */ 451 uint32_t tv_nsec; /**< nanoseconds */ 452 } ts; /**< timestamp */ 453 } axa_p_whit_nmsg_hdr_t; 454 455 /** AXA protocol watch hit header before an IP packet */ 456 typedef struct _PK { 457 axa_p_whit_hdr_t hdr; /**< header for all watch hits */ 458 /** timestamp when the packet was captured */ 459 struct _PK { 460 uint32_t tv_sec; /**< seconds */ 461 uint32_t tv_usec; /**< microseconds */ 462 } tv; /**< timestamp */ 463 uint32_t ip_len; /**< packet length on the wire */ 464 } axa_p_whit_ip_hdr_t; 465 466 /** AXA protocol watch hit before an NMSG message */ 467 typedef struct _PK { 468 axa_p_whit_nmsg_hdr_t hdr; /**< watch hit NMSG header */ 469 #define AXA_P_WHIT_NMSG_MAX (3*(2<<16)) /**< some NMSGs have >1 DNS packet */ 470 uint8_t b[0]; /**< start of SIE message */ 471 } axa_p_whit_nmsg_t; 472 473 /** AXA protocol watch hit before an IP packet */ 474 typedef struct _PK { 475 axa_p_whit_ip_hdr_t hdr; /**< watch hit IP header */ 476 # define AXA_P_WHIT_IP_MAX (2<<16) /**< IPv6 can be bigger */ 477 uint8_t b[0]; /**< start of IP packet */ 478 } axa_p_whit_ip_t; 479 480 /** generic AXA protocol watch hit */ 481 typedef union { 482 axa_p_whit_hdr_t hdr; /**< top level watch hit header */ 483 axa_p_whit_nmsg_t nmsg; /**< an NMSG message */ 484 axa_p_whit_ip_t ip; /**< an IP packet */ 485 } axa_p_whit_t; 486 487 /** Smallest watch hit */ 488 #define AXA_WHIT_MIN_LEN min(sizeof(axa_p_whit_ip_t)+1, \ 489 sizeof(axa_p_whit_nmsg_t)+1) 490 /** Largest watch hit */ 491 #define AXA_WHIT_MAX_LEN max(sizeof(axa_p_whit_ip_t)+AXA_P_WHIT_IP_MAX, \ 492 sizeof(axa_p_whit_nmsg_t)+AXA_P_WHIT_NMSG_MAX) 493 494 495 /** AXA protocol watch type */ 496 typedef enum { 497 AXA_P_WATCH_IPV4 =1, /**< watch IPv4 */ 498 AXA_P_WATCH_IPV6 =2, /**< watch IPv6 */ 499 AXA_P_WATCH_DNS =3, /**< watch DNS */ 500 AXA_P_WATCH_CH =4, /**< watch channel */ 501 AXA_P_WATCH_ERRORS =5 /**< watch errors */ 502 } axa_p_watch_type_t; 503 504 /** AXA protocol watch pattern */ 505 typedef union { 506 struct in_addr addr; /**< IPv4 address */ 507 struct in6_addr addr6; /**< IPv6 address */ 508 # define AXA_P_DOMAIN_LEN 255 /**< max len of domain names */ 509 uint8_t dns[AXA_P_DOMAIN_LEN]; /**< DNS wire format */ 510 axa_p_ch_t ch; /**< channel */ 511 } axa_p_watch_pat_t; 512 513 /** AXA protocol watch */ 514 typedef struct _PK { 515 uint8_t type; /**< axa_p_watch_type_t */ 516 uint8_t prefix; /**< IP address only */ 517 uint8_t flags; /**< flags */ 518 #define AXA_P_WATCH_FG_WILD 0x01 /**< DNS wild card */ 519 #define AXA_P_WATCH_FG_SHARED 0x02 /**< DNS domain or RR is not private */ 520 #define AXA_P_WATCH_STR_SHARED "shared" /**< shared string */ 521 uint8_t pad; /**< to 0 mod 4 */ 522 axa_p_watch_pat_t pat; /**< watch pattern */ 523 } axa_p_watch_t; 524 525 /** AXA protocol watch list */ 526 typedef struct _PK { 527 axa_tag_t cur_tag; /**< current tag of watch */ 528 uint8_t pad[2]; /**< to 0 mod 4 */ 529 axa_p_watch_t w; /**< one of the listed watches */ 530 } axa_p_wlist_t; 531 532 /**< @cond */ 533 #define AXA_OP_AN_PREFIX "an;" 534 /**< @endcond */ 535 536 /** AXA protocol anomaly module name */ 537 typedef struct _PK { /**< anomaly module name */ 538 char c[32]; /**< wastefully null terminated */ 539 } axa_p_an_t; 540 541 #define AXA_PARMS_MAX 8192 /**< max size of RAD module parms */ 542 /** AXA protocol anomaly module specified by RAD client */ 543 typedef struct _PK { 544 axa_p_an_t an; /**< anomaly module name */ 545 char parms[AXA_PARMS_MAX]; /**< parms, null terminated */ 546 } axa_p_anom_t; 547 548 /** AXA protocol anomaly module hit */ 549 typedef struct _PK { 550 axa_p_an_t an; /**< module that detected the anomaly */ 551 axa_p_whit_t whit; /**< anomalous SIE message or packet */ 552 } axa_p_ahit_t; 553 554 /** AXA protocol anomaly list */ 555 typedef struct _PK { 556 axa_tag_t cur_tag; /**< current tag of watch */ 557 uint8_t pad[2]; /**< to 0 mod 4 */ 558 axa_p_anom_t anom; /**< a listed anomaly module */ 559 } axa_p_alist_t; 560 561 /** AXA protocol channel enable/disable */ 562 typedef struct _PK { 563 axa_p_ch_t ch; /**< channel number */ 564 uint8_t on; /**< boolean, 1 for on, 0 for off */ 565 } axa_p_channel_t; 566 567 /** AXA protocol channel specification */ 568 typedef struct _PK { 569 /** 570 * Human readable string specifying the channel. It often looks 571 * like an IP address or network interface name or SIE channel alias. 572 */ 573 char c[1024]; 574 } axa_p_chspec_t; 575 576 /** AXA protocol channel list */ 577 typedef struct _PK { 578 axa_p_ch_t ch; /**< channel (binary) */ 579 uint8_t on; /** < !=0 if on */ 580 axa_p_chspec_t spec; /**< channel (human readable) */ 581 } axa_p_clist_t; 582 583 /** Request server's current trace value */ 584 #define AXA_P_OPT_TRACE_REQ ((uint32_t)-1) 585 586 /** maximum rlimit */ 587 #define AXA_RLIMIT_MAX (1000*1000*1000) 588 /** Turn off a rate limit. */ 589 #define AXA_RLIMIT_OFF (AXA_RLIMIT_MAX+1) 590 /** A rate limit value that doesn't apply or is not being set */ 591 #define AXA_RLIMIT_NA ((axa_cnt_t)-1) 592 593 /** AXA protocol rlimit */ 594 typedef struct _PK { 595 /** 596 * When in an option AXA_P_OP_OPT message sent by the client, 597 * request the server to send no more than this many AXA AXA_P_OP_WHIT 598 * or AXA_P_OP_AHIT messages per second. Use AXA_RLIMIT_OFF to 599 * request no limit. AXA_RLIMIT_NA to not change th 600 */ 601 axa_cnt_t max_pkts_per_sec; 602 /** 603 * This is the current value of the server's rate limit counter. 604 * The counter is incremented each time a relevant AXA message 605 * is considered for sending to the client. If the new value is 606 * greater than the rate limit, the message dropped. The counter 607 * is reset every second. 608 */ 609 axa_cnt_t cur_pkts_per_sec; 610 axa_cnt_t unused1; /**< reserved */ 611 axa_cnt_t unused2; /**< reserved */ 612 /** 613 * The minimum number of seconds between reports of rate limiting. 614 * It is a rate limit on rate limit reports. 615 */ 616 axa_cnt_t report_secs; 617 } axa_p_rlimit_t; 618 619 /** Request the output sampling ratio */ 620 #define AXA_P_OPT_SAMPLE_REQ 0 621 /** Request the output sampling ratio */ 622 #define AXA_P_OPT_SAMPLE_SCALE 10000 623 /** maximum scaled output sampling ratio */ 624 #define AXA_P_OPT_SAMPLE_MAX (AXA_P_OPT_SAMPLE_SCALE*100) 625 626 /** Request the TCP buffer size ratio */ 627 #define AXA_P_OPT_SNDBUF_REQ 0 628 /** TCP buffer minimum window size */ 629 #define AXA_P_OPT_SNDBUF_MIN 1024 630 631 /** AXA protocol options type */ 632 typedef enum { 633 AXA_P_OPT_TRACE =0, /**< server tracing level */ 634 AXA_P_OPT_RLIMIT =1, /**< server rate limiting */ 635 AXA_P_OPT_SAMPLE =2, /**< sample an output stream. */ 636 AXA_P_OPT_SNDBUF =3, /**< set TCP buffer or window size */ 637 } axa_p_opt_type_t; 638 639 /** AXA protocol options */ 640 typedef struct _PK { 641 uint8_t type; /**< option type */ 642 uint8_t pad[7]; /**< to 0 mod 8 for axa_p_rlimit_t */ 643 /** option union */ 644 union axa_p_opt_u { 645 uint32_t trace; /**< AXA_P_OPT_TRACE: tracing level */ 646 axa_p_rlimit_t rlimit; /**< AXA_P_OPT_RLIMIT rate limits */ 647 uint32_t sample; /**< AXA_P_OPT_SAMPLE percent*1000 */ 648 uint32_t bufsize; /**< AXA_P_OPT_SNDBUF bytes */ 649 } u; /**< holds actual option */ 650 } axa_p_opt_t; 651 652 /**< @cond */ 653 654 /** 655 * ** Begin AXA stats interface. ** 656 * 657 * 'stats' is a request/response protocol that provides a way for AXA servers 658 * (both SRA and RAD) to report a current state of affairs to interested 659 * clients. 660 * 661 * It introduces two new private opcodes: 662 * - _AXA_P_OP_STATS_REQ (client to server) 663 * - _AXA_P_OP_STATS_RSP (server to client). 664 * 665 * Both request and response headers are versioned and typed. This allows for 666 * protocol extensibility in both directions. 667 * 668 * The process is initiated by a client that asks a server for stats by building 669 * an AXA header with the _AXA_P_OP_STATS_REQ opcode and an stats request 670 * header (_axa_p_stats_req_t) and sending this to the server, which may in turn 671 * respond with an _AXA_P_OP_STATS_RSP opcode, stats response 672 * header (_axa_p_stats_rsp_t) and one or more response objects. 673 * 674 * An _axa_p_stats_req_t header will contain the type of request: 675 * - AXA_P_STATS_M_M_SUM (summary): ask for system/server stats only 676 * - AXA_P_STATS_M_M_ALL (all): ask for system/server stats and all user stats 677 * - AXA_P_STATS_M_M_U (username): ask for system/server stats and stats on 678 * username 679 * - AXA_P_STATS_M_M_SN (serial number): ask for system/server stats and stats 680 * on sn 681 * 682 * Depending on the type, the username or sn field will be populated in the 683 * request. 684 * 685 * An _axa_p_stats_rsp_t header will contain a result code: 686 * - AXA_P_STATS_R_SUCCESS (success): op was successful; proceed w/ processing 687 * - AXA_P_STATS_R_FAIL_NF (failure): user or sn was not found 688 * - AXA_P_STATS_R_FAIL_UNK (failure): unknown failure 689 * 690 * IF the result code is AXA_P_STATS_R_SUCCESS, the server's response can be 691 * one or more response objects and the sys_objs_cnt and user_objs_cnt fields 692 * should be checked. After the stats response, a valid response will always 693 * begin with one _AXA_P_STATS_TYPE_SYS (system) object, or if the response is 694 * broken into multiple messages (termed "flights") because of length 695 * restrictions, subsequent messages will leave this field empty. If the 696 * number of in-flight user objects would exceed _AXA_STATS_MAX_USER_OBJS, 697 * multiple _AXA_P_OP_STATS_RSP opcodes (each containing a specified number of 698 * user objects) will be returned to the client until all have been sent. 699 * 700 * System and user objects contain both general stats applicable to both SRA 701 * and RAD servers as well as SRA/RAD specific areas in a union named "srvr". 702 * 703 * When in RAD mode, user objects may be followed by up to 704 * _AXA_STATS_MAX_USER_RAD_AN_OBJS trailing RAD user anomaly objects (each of 705 * which will carry information about a single module instance a user has 706 * loaded). 707 * 708 * Consider the following example use cases: 709 * 710 * Use Case 1: End user wants only system/server stats, not interested in user 711 * activity. 712 * 713 * client -> server 714 * [axa_p_hdr_t:_AXA_P_OP_STATS_REQ] 715 * [_axa_p_stats_req_t:AXA_P_STATS_M_M_SUM] 716 * 717 * server -> client (server returns only system/server stats object) 718 * [axa_p_hdr_t:_AXA_P_OP_STATS_RSP] 719 * [_axa_p_stats_rsp_t:sys_objs_cnt:1,user_objs_cnt:0] 720 * [_axa_p_stats_sys_t:server_type:_AXA_STATS_SRVR_TYPE_SRA] 721 * 722 * Use Case 2: End user wants information on all of a single user's sessions 723 * (in this case, user has three active sessions). 724 * 725 * client -> server (client asks for stats by username) 726 * [axa_p_hdr_t:_AXA_P_OP_STATS_REQ] 727 * [_axa_p_stats_req_t:AXA_P_STATS_M_M_U] 728 * 729 * server -> client (server returns system/server stats object and three 730 * user objects) 731 * [axa_p_hdr_t:_AXA_P_OP_STATS_RSP] 732 * [_axa_p_stats_rsp_t:sys_objs_cnt:1,user_objs_cnt:3] 733 * [_axa_p_stats_sys_t:server_type:_AXA_STATS_SRVR_TYPE_SRA] 734 * [_axa_p_stats_user_t] 735 * [_axa_p_stats_user_t] 736 * [_axa_p_stats_user_t] 737 * 738 * Use Case 3: End user asks for stats on all users (user count exceeds 739 * _AXA_STATS_MAX_USER_OBJS). 740 * 741 * client -> server 742 * [axa_p_hdr_t:_AXA_P_OP_STATS_REQ] 743 * [_axa_p_stats_req_t:AXA_P_STATS_M_M_ALL] 744 * 745 * server -> client (server returns system/server stats object and one user 746 * object for each logged in client; this number exceeds 747 * _AXA_STATS_MAX_USER_OBJS so user objects are sent via 748 * multiple _AXA_P_OP_STATS_RSP "packets"; note no 749 * system/server object is sent after the first one) 750 * [axa_p_hdr_t:_AXA_P_OP_STATS_RSP] 751 * [_axa_p_stats_rsp_t:sys_objs_cnt:1,user_objs_cnt:_AXA_STATS_MAX_USER_OBJS] 752 * [_axa_p_stats_sys_t:server_type:_AXA_STATS_SRVR_TYPE_SRA] 753 * [_axa_p_stats_user_t] 754 * [_axa_p_stats_user_t] 755 * [_axa_p_stats_user_t] 756 * [...] 757 * [_axa_p_stats_user_t] 758 * ... 759 * [axa_p_hdr_t:_AXA_P_OP_STATS_RSP] 760 * [_axa_p_stats_rsp_t:sys_objs_cnt:0,user_objs_cnt:10] 761 * [_axa_p_stats_user_t] 762 * [...] 763 * [_axa_p_stats_user_t] 764 * 765 * Use Case 4: RAD end user asks for stats on all users. 766 * 767 * client -> server 768 * [axa_p_hdr_t:_AXA_P_OP_STATS_REQ] 769 * [_axa_p_stats_req_t:AXA_P_STATS_M_M_ALL] 770 * 771 * server -> client (server returns system/server stats object and one user 772 * object for each logged in client; this number exceeds 773 * _AXA_STATS_MAX_USER_OBJS so writes are broken up as 774 * above. Users who have loaded RAD modules will have one 775 * trailing RAD anomaly object per loaded module, up to 776 * _AXA_STATS_MAX_USER_RAD_AN_OBJS) 777 * [axa_p_hdr_t:_AXA_P_OP_STATS_RSP] 778 * [_axa_p_stats_rsp_t:sys_objs_cnt:1,user_objs_cnt:_AXA_STATS_MAX_USER_OBJS] 779 * [_axa_p_stats_sys_t:server_type:_AXA_STATS_SRVR_TYPE_RAD,srvr.rad.an_obj_cnt:18] 780 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:1] 781 * [_axa_p_stats_user_rad_an_t] 782 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:0] 783 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:2] 784 * [_axa_p_stats_user_rad_an_t] 785 * [_axa_p_stats_user_rad_an_t] 786 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:0] 787 * ... 788 * [axa_p_hdr_t:_AXA_P_OP_STATS_RSP] 789 * [_axa_p_stats_rsp_t:sys_objs_cnt:0,user_objs_cnt:10] 790 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:4] 791 * [_axa_p_stats_user_rad_an_t] 792 * [_axa_p_stats_user_rad_an_t] 793 * [_axa_p_stats_user_rad_an_t] 794 * [_axa_p_stats_user_rad_an_t] 795 * [...] 796 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:0] 797 * [_axa_p_stats_user_t:srvr.rad.an_obj_cnt:1] 798 * [_axa_p_stats_user_rad_an_t] 799 * 800 * The functionality exposed here is for admin users only and is not intended 801 * to be part of the public API. 802 * 803 * If a non-privileged user requests stats, the server should return an error 804 * via output_error() and reference the original opcode. 805 * 806 * This replaces the deprecated "MGMT" opcode/command/protocol. 807 * 808 * IF any user requests the MGMT opcode, the server should return an error 809 * via output_error() and inform the user of its deprecation. 810 */ 811 #define _AXA_STATS_VERSION_ONE 1 812 #define _AXA_STATS_VERSION _AXA_STATS_VERSION_ONE 813 814 /* AXA statistics request object types. */ 815 typedef enum { 816 AXA_P_STATS_M_M_SUM =1, /* summary only */ 817 AXA_P_STATS_M_M_ALL =2, /* summary + all users */ 818 AXA_P_STATS_M_M_SN =3, /* summary + usr by sn */ 819 AXA_P_STATS_M_M_U =4, /* summary + usr by name */ 820 } _axa_p_stats_req_type_t; 821 822 /* AXA statistics request header. */ 823 typedef struct _PK { 824 uint8_t version; /* _AXA_STATS_VERSION */ 825 uint8_t type; /* _axa_p_stats_req_type_t */ 826 axa_p_user_t user; /* optional user name */ 827 uint32_t sn; /* optional serial num */ 828 } _axa_p_stats_req_t; 829 830 /* AXA statistics response codes. */ 831 typedef enum { 832 AXA_P_STATS_R_SUCCESS =1, /* successful operation */ 833 AXA_P_STATS_R_FAIL_NF =2, /* failed: sn/user not found */ 834 AXA_P_STATS_R_FAIL_UNK =3, /* failed: unknown reason */ 835 } _axa_p_stats_rsp_code_t; 836 837 /* AXA statistics response header. */ 838 typedef struct _PK { 839 uint8_t version; /* _AXA_STATS_VERSION */ 840 uint8_t sys_objs_cnt; /* _axa_p_stats_sys_t count */ 841 uint16_t user_objs_cnt; /* _axa_p_stats_user_t count */ 842 uint8_t result; /* result code */ 843 } _axa_p_stats_rsp_t; 844 845 /* AXA statistics watches object. */ 846 typedef struct _PK { 847 uint32_t ipv4_cnt; /* number of IPv4 watches */ 848 uint32_t ipv6_cnt; /* number of IPv6 watches */ 849 uint32_t dns_cnt; /* number of DNS watches */ 850 uint32_t ch_cnt; /* number of ch watches */ 851 uint32_t err_cnt; /* number of err watches */ 852 } _axa_p_stats_watches_t; 853 854 /* AXA statistics SRA server specific stats object. */ 855 typedef struct _PK { 856 _axa_p_stats_watches_t watches; /* watch count */ 857 axa_ch_mask_t ch_mask; /* channels open */ 858 } _axa_p_stats_srvr_sra_t; 859 860 /* AXA statistics RAD server specific stats object. */ 861 typedef struct _PK { 862 uint16_t an_cnt; /* total anomaly count */ 863 } _axa_p_stats_srvr_rad_t; 864 865 /* AXA statistics response object types. */ 866 typedef enum { 867 _AXA_P_STATS_TYPE_SYS =1, /* system/server object */ 868 _AXA_P_STATS_TYPE_USER =2, /* user object */ 869 } _axa_p_stats_rsp_type_t; 870 871 /* AXA statistics SRA specific user stats object. */ 872 typedef struct _PK { 873 _axa_p_stats_watches_t watches; /* watches user has loaded */ 874 axa_ch_mask_t ch_mask; /* channels user has open */ 875 uint8_t flags; /* control flags (unused) */ 876 } _axa_p_stats_user_sra_t; 877 878 /* AXA statistics RAD specific user stats object. */ 879 typedef int32_t runits_t; /* RAD Units */ 880 typedef struct _PK { 881 #define _AXA_STATS_MAX_USER_RAD_AN_OBJS 100 /* max number of an objs */ 882 uint8_t an_obj_cnt; /* number of anomaly objects 883 * in flight */ 884 uint8_t an_obj_cnt_total;/* total number of anomaly 885 * objects user has loaded */ 886 uint8_t flags; /* control flags */ 887 } _axa_p_stats_user_rad_t; 888 889 /** 890 * AXA statistics system/server object. 891 * 892 * This is a first class citizen and can be sent to a client. It must be 893 * prefaced by a _axa_p_stats_rsp_t header. It must choose a server type and 894 * populate the appropriate union values. 895 */ 896 typedef struct _PK { 897 uint8_t type; /* _AXA_P_STATS_TYPE_SYS */ 898 #define _AXA_STATS_SRVR_TYPE_SRA 1 /* implementation should set */ 899 #define _AXA_STATS_SRVR_TYPE_RAD 2 /* one or the other not both */ 900 uint8_t server_type; /* server type */ 901 uint32_t load[3]; /* load avg */ 902 uint32_t cpu_usage; /* cpu usage */ 903 uint32_t uptime; /* system uptime */ 904 uint32_t starttime; /* process start time */ 905 uint32_t fd_sockets; /* number of socket FDs */ 906 uint32_t fd_pipes; /* number of pipe FDs */ 907 uint32_t fd_anon_inodes; /* number of anon_inode FDs */ 908 uint32_t fd_other; /* number of other FDs */ 909 uint64_t vmsize; /* total program size */ 910 uint64_t vmrss; /* resident set size */ 911 uint64_t rchar; /* bytes read via read() */ 912 uint64_t wchar; /* bytes written via write() */ 913 uint32_t thread_cnt; /* number of server threads */ 914 uint16_t user_cnt; /* number of connected users */ 915 union _axa_p_stats_sys_srvr { 916 _axa_p_stats_srvr_sra_t sra; /* sra server specific stats */ 917 _axa_p_stats_srvr_rad_t rad; /* rad server specific stats */ 918 } srvr; 919 } _axa_p_stats_sys_t; 920 921 /** 922 * AXA statistics user object. 923 * 924 * This is a first class citizen and one or more can be sent to a client. 925 * It/they must be prefaced by a _axa_p_stats_rsp_t header and sometimes a 926 * _axa_p_stats_sys_t object. Multiple user objects can be sent consecutively 927 * as dictated by the user_obj_cnt in the _axa_p_stats_rsp_t header. 928 * 929 * This holds SRA or RAD specific data for a single user. It must set a 930 * server_type and populate the appropriate union values. 931 */ 932 #define _AXA_STATS_MAX_USER_OBJS 50 /* max in-flight user objs */ 933 typedef struct _PK { 934 uint8_t type; /* AXA_P_STATS_TYPE_USER */ 935 uint8_t server_type; /* server type (as above) */ 936 axa_p_user_t user; /* user name */ 937 uint8_t is_admin; /* 1 == is an admin */ 938 uint8_t io_type; /* transport type */ 939 #define AXA_AF_INET 0 /* IPv4 */ 940 #define AXA_AF_INET6 1 /* IPv6 */ 941 #define AXA_AF_UNKNOWN 2 /* unknown */ 942 uint8_t addr_type; /* address type */ 943 uint8_t pad[6]; /*< to 0 mod 8 */ 944 union _axa_p_stats_ip { 945 uint8_t ipv6[16]; /* ipv6 address */ 946 uint32_t ipv4; /* ipv4 address */ 947 } ip; 948 uint32_t sn; /* server-side serial num */ 949 struct timeval connected_since;/* logged in since */ 950 axa_cnt_t ratelimit; /* positive if user is rl'd */ 951 axa_cnt_t sample; /* "" if user is sampling */ 952 struct timeval last_cnt_update;/* last time cnts updated */ 953 axa_cnt_t filtered; /* total packets filtered */ 954 axa_cnt_t missed; /* lost before filtering */ 955 axa_cnt_t collected; /* captured by filters */ 956 axa_cnt_t sent; /* sent to client */ 957 axa_cnt_t rlimit; /* lost to rate limiting */ 958 axa_cnt_t congested; /* lost to server->client */ 959 union _axa_p_stats_srvr { 960 _axa_p_stats_user_sra_t sra; /* sra specific stats */ 961 _axa_p_stats_user_rad_t rad; /* rad specific stats */ 962 } srvr; 963 } _axa_p_stats_user_t; 964 965 /** 966 * AXA statistics RAD anomaly object. 967 * 968 * This is a first class citizen and one or more can be sent to a client. 969 * It/they must be originally prefaced by a _axa_p_stats_user_t object 970 * (with a server_type set to _AXA_STATS_SRVR_TYPE_RAD). Multiple anomaly 971 * objects can be sent consecutively as dictated by the an_obj_cnt in the 972 * _axa_p_stats_user_t --> _axa_p_stats_user_rad_t header. 973 */ 974 typedef struct _PK { 975 char name[32]; /* anomaly common name */ 976 char opt[128]; /* options, if list is too long 977 * "..." will be appended to 978 * the truncated string */ 979 runits_t ru_original; /* runits original balance */ 980 runits_t ru_current; /* runits current balance */ 981 runits_t ru_cost; /* runits cost this instance */ 982 axa_ch_mask_t ch_mask; /* channels */ 983 } _axa_p_stats_user_rad_an_t; 984 985 /* ** End AXA stats interface. **/ 986 987 /* AXA kill response codes */ 988 typedef enum { 989 AXA_P_KILL_R_SUCCESS =1, /* successful operation */ 990 AXA_P_KILL_R_FAIL_NF =2, /* failed: sn/user not found */ 991 AXA_P_KILL_R_FAIL_UNK =3, /* failed: unknown reason */ 992 } _axa_p_kill_rsp_t; 993 994 /* AXA kill modes */ 995 typedef enum { 996 AXA_P_KILL_M_SN =1, /* kill by serial number */ 997 AXA_P_KILL_M_U =2, /* kill by user name */ 998 } _axa_p_kill_mode_t; 999 1000 /* AXA kill response */ 1001 typedef struct _PK { 1002 _axa_p_kill_mode_t mode; /* mode of kill request */ 1003 axa_p_user_t user; /* user name */ 1004 uint32_t sn; /* server-side serial num */ 1005 _axa_p_kill_rsp_t result; /* result code */ 1006 } _axa_p_kill_t; 1007 /**< @endcond */ 1008 1009 /** AXA protocol body */ 1010 typedef union { 1011 axa_p_hello_t hello; /**< hello to client */ 1012 axa_p_result_t result; /**< result of client request */ 1013 axa_p_missed_t missed; /**< report missed data by SRA */ 1014 axa_p_whit_t whit; /**< watch hit */ 1015 axa_p_wlist_t wlist; /**< list an watch */ 1016 axa_p_ahit_t ahit; /**< anomaly hit */ 1017 axa_p_alist_t alist; /**< list an anomaly */ 1018 axa_p_clist_t clist; /**< channel list */ 1019 axa_p_missed_rad_t missed_rad; /**< report missed data by RAD */ 1020 1021 axa_p_user_t user; /**< tell server which user */ 1022 axa_p_join_t join; /**< bundle TCP */ 1023 axa_p_watch_t watch; /**< ask for a watch on the server */ 1024 axa_p_anom_t anom; /**< ask anomaly detection */ 1025 axa_p_channel_t channel; /**< enable or disable a channel */ 1026 axa_p_opt_t opt; /**< options */ 1027 _axa_p_stats_req_t stats_req; /**< statistics request */ 1028 _axa_p_stats_rsp_t stats_rsp; /**< statistics response */ 1029 _axa_p_kill_t kill; /**< kill (both directions) */ 1030 1031 uint8_t b[1]; /**< ... */ 1032 } axa_p_body_t; 1033 1034 /**< @cond */ 1035 /* Handshake from the program run by sshd, axaproxy, to srad or radd. */ 1036 typedef struct { /**< not packed because it is local */ 1037 char magic[16]; 1038 # define AXA_PROXY_SSH_MAGIC "PROXY_SSH_0" 1039 axa_socku_t su; 1040 char peer[INET6_ADDRSTRLEN]; 1041 axa_p_user_t user; 1042 } axa_proxy_ssh_t; 1043 /**< @endcond */ 1044 1045 /**@}*/ 1046 1047 #undef _PK 1048 #endif /* AXA_PROTOCOL_H */ 1049