contrib/openbsm/man/audit.log.5

   1 .\"-
   2 .\" Copyright (c) 2005-2006 Robert N. M. Watson
   3 .\" Copyright (c) 2008 Apple Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $P4: //depot/projects/trustedbsd/openbsm/man/audit.log.5#26 $
  28 .\"
  29 .Dd November 5, 2006
  30 .Dt AUDIT.LOG 5
  31 .Os
  32 .Sh NAME
  33 .Nm audit
  34 .Nd "Basic Security Module (BSM) file format"
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 file format is based on Sun's Basic Security Module (BSM) file format, a
  39 token-based record stream to represent system audit data.
  40 This file format is both flexible and extensible, able to describe a broad
  41 range of data types, and easily extended to describe new data types in a
  42 moderately backward and forward compatible way.
  43 .Pp
  44 BSM token streams typically begin and end with a
  45 .Dq file
  46 token, which provides time stamp and file name information for the stream;
  47 when processing a BSM token stream from a stream as opposed to a single file
  48 source, file tokens may be seen at any point between ordinary records
  49 identifying when particular parts of the stream begin and end.
  50 All other tokens will appear in the context of a complete BSM audit record,
  51 which begins with a
  52 .Dq header
  53 token, and ends with a
  54 .Dq trailer
  55 token, which describe the audit record.
  56 Between these two tokens will appear a variety of data tokens, such as
  57 process information, file path names, IPC object information, MAC labels,
  58 socket information, and so on.
  59 .Pp
  60 The BSM file format defines specific token orders for each record event type;
  61 however, some variation may occur depending on the operating system in use,
  62 what system options, such as mandatory access control, are present.
  63 .Pp
  64 This manual page documents the common token types and their binary format, and
  65 is intended for reference purposes only.
  66 It is recommended that application programmers use the
  67 .Xr libbsm 3
  68 interface to read and write tokens, rather than parsing or constructing
  69 records by hand.
  70 .Ss File Token
  71 The
  72 .Dq file
  73 token is used at the beginning and end of an audit log file to indicate
  74 when the audit log begins and ends.
  75 It includes a pathname so that, if concatenated together, original file
  76 boundaries are still observable, and gaps in the audit log can be identified.
  77 A
  78 .Dq file
  79 token can be created using
  80 .Xr au_to_file 3 .
  81 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
  82 .It Sy "Field   Bytes   Description"
  83 .It "Token ID   1 byte  Token ID"
  84 .It "Seconds    4 bytes File time stamp"
  85 .It "Microseconds       4 bytes File time stamp"
  86 .It "File name length   2 bytes File name of audit trail"
  87 .It "File pathname      N bytes + 1 NUL File name of audit trail"
  88 .El
  89 .Ss Header Token
  90 The
  91 .Dq header
  92 token is used to mark the beginning of a complete audit record, and includes
  93 the length of the total record in bytes, a version number for the record
  94 layout, the event type and subtype, and the time at which the event occurred.
  95 A 32-bit
  96 .Dq header
  97 token can be created using
  98 .Xr au_to_header32 3 ;
  99 a 64-bit
 100 .Dq header
 101 token can be created using
 102 .Xr au_to_header64 3 .
 103 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 104 .It Sy "Field   Bytes   Description"
 105 .It "Token ID   1 byte  Token ID"
 106 .It "Record Byte Count  4 bytes Number of bytes in record"
 107 .It "Version Number     2 bytes Record version number"
 108 .It "Event Type 2 bytes Event type"
 109 .It "Event Modifier     2 bytes Event sub-type"
 110 .It "Seconds    4/8 bytes       Record time stamp (32/64-bits)"
 111 .It "Nanoseconds        4/8 bytes       Record time stamp (32/64-bits)"
 112 .El
 113 .Ss Expanded Header Token
 114 The
 115 .Dq expanded header
 116 token is an expanded version of the
 117 .Dq header
 118 token, with the addition of a machine IPv4 or IPv6 address.
 119 A 32-bit extended
 120 .Dq header
 121 token can be created using
 122 .Xr au_to_header32_ex 3 ;
 123 a 64-bit extended
 124 .Dq header
 125 token can be created using
 126 .Xr au_to_header64_ex 3 .
 127 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 128 .It Sy "Field   Bytes   Description"
 129 .It "Token ID   1 byte  Token ID"
 130 .It "Record Byte Count  4 bytes Number of bytes in record"
 131 .It "Version Number     2 bytes Record version number"
 132 .It "Event Type 2 bytes Event type"
 133 .It "Event Modifier     2 bytes Event sub-type"
 134 .It "Address Type/Length        1 byte  Host address type and length"
 135 .It "Machine Address    4/16 bytes      IPv4 or IPv6 address"
 136 .It "Seconds    4/8 bytes       Record time stamp (32/64-bits)"
 137 .It "Nanoseconds        4/8 bytes       Record time stamp (32/64-bits)"
 138 .El
 139 .Ss Trailer Token
 140 The
 141 .Dq trailer
 142 terminates a BSM audit record, and contains a magic number,
 143 .Dv AUT_TRAILER_MAGIC
 144 and length that can be used to validate that the record was read properly.
 145 A
 146 .Dq trailer
 147 token can be created using
 148 .Xr au_to_trailer 3 .
 149 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 150 .It Sy "Field   Bytes   Description"
 151 .It "Token ID   1 byte  Token ID"
 152 .It "Trailer Magic      2 bytes Trailer magic number"
 153 .It "Record Byte Count  4 bytes Number of bytes in record"
 154 .El
 155 .Ss Arbitrary Data Token
 156 The
 157 .Dq arbitrary data
 158 token contains a byte stream of opaque (untyped) data.
 159 The size of the data is calculated as the size of each unit of data
 160 multiplied by the number of units of data.
 161 A
 162 .Dq How to print
 163 field is present to specify how to print the data, but interpretation of
 164 that field is not currently defined.
 165 An
 166 .Dq arbitrary data
 167 token can be created using
 168 .Xr au_to_data 3 .
 169 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 170 .It Sy "Field   Bytes   Description"
 171 .It "Token ID   1 byte  Token ID"
 172 .It "How to Print       1 byte  User-defined printing information"
 173 .It "Basic Unit 1 byte  Size of a unit in bytes"
 174 .It "Unit Count 1 byte  Number of units of data present"
 175 .It "Data Items Variable        User data"
 176 .El
 177 .Ss in_addr Token
 178 The
 179 .Dq in_addr
 180 token holds a network byte order IPv4 address.
 181 An
 182 .Dq in_addr
 183 token can be created using
 184 .Xr au_to_in_addr 3
 185 for an IPv4 address.
 186 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 187 .It Sy "Field   Bytes   Description"
 188 .It "Token ID   1 byte  Token ID"
 189 .It "IP Address 4 bytes IPv4 address"
 190 .El
 191 .Ss Expanded in_addr Token
 192 The
 193 .Dq in_addr_ex
 194 token holds a network byte order IPv4 or IPv6 address.
 195 An
 196 .Dq in_addr_ex
 197 token can be created using
 198 .Xr au_to_in_addr_ex 3
 199 for an IPv6 address.
 200 .Pp
 201 See the
 202 .Sx BUGS
 203 section for information on the storage of this token.
 204 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 205 .It Sy "Field   Bytes   Description"
 206 .It "Token ID   1 byte  Token ID"
 207 .It "IP Address Type    1 byte  Type of address"
 208 .It "IP Address 4/16 bytes      IPv4 or IPv6 address"
 209 .El
 210 .Ss ip Token
 211 The
 212 .Dq ip
 213 token contains an IP packet header in network byte order.
 214 An
 215 .Dq ip
 216 token can be created using
 217 .Xr au_to_ip 3 .
 218 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 219 .It Sy "Field   Bytes   Description"
 220 .It "Token ID   1 byte  Token ID"
 221 .It "Version and IHL    1 byte  Version and IP header length"
 222 .It "Type of Service    1 byte  IP TOS field"
 223 .It "Length     2 bytes IP packet length in network byte order"
 224 .It "ID 2 bytes IP header ID for reassembly"
 225 .It "Offset     2 bytes IP fragment offset and flags, network byte order"
 226 .It "TTL        1 byte  IP Time-to-Live"
 227 .It "Protocol   1 byte  IP protocol number"
 228 .It "Checksum   2 bytes IP header checksum, network byte order"
 229 .It "Source Address     4 bytes IPv4 source address"
 230 .It "Destination Address        4 bytes IPv4 destination address"
 231 .El
 232 .Ss iport Token
 233 The
 234 .Dq iport
 235 token stores an IP port number in network byte order.
 236 An
 237 .Dq iport
 238 token can be created using
 239 .Xr au_to_iport 3 .
 240 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 241 .It Sy "Field   Bytes   Description"
 242 .It "Token ID   1 byte  Token ID"
 243 .It "Port Number        2 bytes Port number in network byte order"
 244 .El
 245 .Ss Path Token
 246 The
 247 .Dq path
 248 token contains a pathname.
 249 A
 250 .Dq path
 251 token can be created using
 252 .Xr au_to_path 3 .
 253 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 254 .It Sy "Field   Bytes   Description"
 255 .It "Token ID   1 byte  Token ID"
 256 .It "Path Length        2 bytes Length of path in bytes"
 257 .It "Path       N bytes + 1 NUL Path name"
 258 .El
 259 .Ss path_attr Token
 260 The
 261 .Dq path_attr
 262 token contains a set of NUL-terminated path names.
 263 The
 264 .Xr libbsm 3
 265 API cannot currently create a
 266 .Dq path_attr
 267 token.
 268 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 269 .It Sy "Field   Bytes   Description"
 270 .It "Token ID   1 byte  Token ID"
 271 .It "Count      2 bytes Number of NUL-terminated string(s) in token"
 272 .It "Path       Variable        count NUL-terminated string(s)"
 273 .El
 274 .Ss Process Token
 275 The
 276 .Dq process
 277 token contains a description of the security properties of a process
 278 involved as the target of an auditable event, such as the destination for
 279 signal delivery.
 280 It should not be confused with the
 281 .Dq subject
 282 token, which describes the subject performing an auditable event.
 283 This includes both the traditional
 284 .Ux
 285 security properties, such as user IDs and group IDs, but also audit
 286 information such as the audit user ID and session.
 287 A
 288 .Dq process
 289 token can be created using
 290 .Xr au_to_process32 3
 291 or
 292 .Xr au_to_process64 3 .
 293 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 294 .It Sy "Field   Bytes   Description"
 295 .It "Token ID   1 byte  Token ID"
 296 .It "Audit ID   4 bytes Audit user ID"
 297 .It "Effective User ID  4 bytes Effective user ID"
 298 .It "Effective Group ID 4 bytes Effective group ID"
 299 .It "Real User ID       4 bytes Real user ID"
 300 .It "Real Group ID      4 bytes Real group ID"
 301 .It "Process ID 4 bytes Process ID"
 302 .It "Session ID 4 bytes Audit session ID"
 303 .It "Terminal Port ID   4/8 bytes       Terminal port ID (32/64-bits)"
 304 .It "Terminal Machine Address   4 bytes IP address of machine"
 305 .El
 306 .Ss Expanded Process Token
 307 The
 308 .Dq expanded process
 309 token contains the contents of the
 310 .Dq process
 311 token, with the addition of a machine address type and variable length
 312 address storage capable of containing IPv6 addresses.
 313 An
 314 .Dq expanded process
 315 token can be created using
 316 .Xr au_to_process32_ex 3
 317 or
 318 .Xr au_to_process64_ex 3 .
 319 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 320 .It Sy "Field   Bytes   Description"
 321 .It "Token ID   1 byte  Token ID"
 322 .It "Audit ID   4 bytes Audit user ID"
 323 .It "Effective User ID  4 bytes Effective user ID"
 324 .It "Effective Group ID 4 bytes Effective group ID"
 325 .It "Real User ID       4 bytes Real user ID"
 326 .It "Real Group ID      4 bytes Real group ID"
 327 .It "Process ID 4 bytes Process ID"
 328 .It "Session ID 4 bytes Audit session ID"
 329 .It "Terminal Port ID   4/8 bytes       Terminal port ID (32/64-bits)"
 330 .It "Terminal Address Type/Length       1 byte  Length of machine address"
 331 .It "Terminal Machine Address   4 bytes IPv4 or IPv6 address of machine"
 332 .El
 333 .Ss Return Token
 334 The
 335 .Dq return
 336 token contains a system call or library function return condition, including
 337 return value and error number associated with the global variable
 338 .Er errno .
 339 A
 340 .Dq return
 341 token can be created using
 342 .Xr au_to_return32 3
 343 or
 344 .Xr au_to_return64 3 .
 345 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 346 .It Sy "Field   Bytes   Description"
 347 .It "Token ID   1 byte  Token ID"
 348 .It "Error Number       1 byte  Errno value, or 0 if undefined"
 349 .It "Return Value       4/8 bytes       Return value (32/64-bits)"
 350 .El
 351 .Ss Subject Token
 352 The
 353 .Dq subject
 354 token contains information on the subject performing the operation described
 355 by an audit record, and includes similar information to that found in the
 356 .Dq process
 357 and
 358 .Dq expanded process
 359 tokens.
 360 However, those tokens are used where the process being described is the
 361 target of the operation, not the authorizing party.
 362 A
 363 .Dq subject
 364 token can be created using
 365 .Xr au_to_subject32 3
 366 and
 367 .Xr au_to_subject64 3 .
 368 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 369 .It Sy "Field   Bytes   Description"
 370 .It "Token ID   1 byte  Token ID"
 371 .It "Audit ID   4 bytes Audit user ID"
 372 .It "Effective User ID  4 bytes Effective user ID"
 373 .It "Effective Group ID 4 bytes Effective group ID"
 374 .It "Real User ID       4 bytes Real user ID"
 375 .It "Real Group ID      4 bytes Real group ID"
 376 .It "Process ID 4 bytes Process ID"
 377 .It "Session ID 4 bytes Audit session ID"
 378 .It "Terminal Port ID   4/8 bytes       Terminal port ID (32/64-bits)"
 379 .It "Terminal Machine Address   4 bytes IP address of machine"
 380 .El
 381 .Ss Expanded Subject Token
 382 The
 383 .Dq expanded subject
 384 token consists of the same elements as the
 385 .Dq subject
 386 token, with the addition of type/length and variable size machine address
 387 information in the terminal ID.
 388 An
 389 .Dq expanded subject
 390 token can be created using
 391 .Xr au_to_subject32_ex 3
 392 or
 393 .Xr au_to_subject64_ex 3 .
 394 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 395 .It Sy "Field   Bytes   Description"
 396 .It "Token ID   1 byte  Token ID"
 397 .It "Audit ID   4 bytes Audit user ID"
 398 .It "Effective User ID  4 bytes Effective user ID"
 399 .It "Effective Group ID 4 bytes Effective group ID"
 400 .It "Real User ID       4 bytes Real user ID"
 401 .It "Real Group ID      4 bytes Real group ID"
 402 .It "Process ID 4 bytes Process ID"
 403 .It "Session ID 4 bytes Audit session ID"
 404 .It "Terminal Port ID   4/8 bytes       Terminal port ID (32/64-bits)"
 405 .It "Terminal Address Type/Length       1 byte  Length of machine address"
 406 .It "Terminal Machine Address   4 bytes IPv4 or IPv6 address of machine"
 407 .El
 408 .Ss System V IPC Token
 409 The
 410 .Dq System V IPC
 411 token contains the System V IPC message handle, semaphore handle or shared
 412 memory handle.
 413 A System V IPC token may be created using
 414 +.Xr au_to_ipc 3 .
 415 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 416 .It Sy "Field   Bytes   Description"
 417 .It "Token ID   1 byte  Token ID"
 418 .It "Object ID type     1 byte  Object ID"
 419 .It "Object ID  4 bytes Object ID"
 420 .El
 421 .Ss Text Token
 422 The
 423 .Dq text
 424 token contains a single NUL-terminated text string.
 425 A
 426 .Dq text
 427 token may be created using
 428 .Xr au_to_text 3 .
 429 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 430 .It Sy "Field   Bytes   Description"
 431 .It "Token ID   1 byte  Token ID"
 432 .It "Text Length        2 bytes Length of text string including NUL"
 433 .It "Text       N bytes + 1 NUL Text string including NUL"
 434 .El
 435 .Ss Attribute Token
 436 The
 437 .Dq attribute
 438 token describes the attributes of a file associated with the audit event.
 439 As files may be identified by 0, 1, or many path names, a path name is not
 440 included with the attribute block for a file; optional
 441 .Dq path
 442 tokens may also be present in an audit record indicating which path, if any,
 443 was used to reach the object.
 444 An
 445 .Dq attribute
 446 token can be created using
 447 .Xr au_to_attr32 3
 448 or
 449 .Xr au_to_attr64 3 .
 450 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 451 .It Sy "Field   Bytes   Description"
 452 .It "Token ID   1 byte  Token ID"
 453 .It "File Access Mode   1 byte  mode_t associated with file"
 454 .It "Owner User ID      4 bytes uid_t associated with file"
 455 .It "Owner Group ID     4 bytes gid_t associated with file"
 456 .It "File System ID     4 bytes fsid_t associated with file"
 457 .It "File System Node ID        8 bytes ino_t associated with file"
 458 .It "Device     4/8 bytes       Device major/minor number (32/64-bit)"
 459 .El
 460 .Ss Groups Token
 461 The
 462 .Dq groups
 463 token contains a list of group IDs associated with the audit event.
 464 A
 465 .Dq groups
 466 token can be created using
 467 .Xr au_to_groups 3 .
 468 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 469 .It Sy "Field   Bytes   Description"
 470 .It "Token ID   1 byte  Token ID"
 471 .It "Number of Groups   2 bytes Number of groups in token"
 472 .It "Group List N * 4 bytes     List of N group IDs"
 473 .El
 474 .Ss System V IPC Permission Token
 475 The
 476 .Dq System V IPC permission
 477 token contains a System V IPC access permissions.
 478 A System V IPC permission token may be created using
 479 .Xr au_to_ipc_perm 3 .
 480 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 481 .It Sy "Field   Bytes   Description"
 482 .It "Token ID   1 byte  Token ID"
 483 .It Li "Owner user ID" Ta "4 bytes" Ta "User ID of IPC owner"
 484 .It Li "Owner group ID" Ta "4 bytes" Ta "Group ID of IPC owner"
 485 .It Li "Creator user ID" Ta "4 bytes" Ta "User ID of IPC creator"
 486 .It Li "Creator group ID" Ta "4 bytes" Ta "Group ID of IPC creator"
 487 .It Li "Access mode" Ta "4 bytes" Ta "Access mode"
 488 .It Li "Sequence number" Ta "4 bytes" Ta "Sequence number"
 489 .It Li "Key" Ta "4 bytes" Ta "IPC key"
 490 .El
 491 .Ss Arg Token
 492 The
 493 .Dq arg
 494 token contains information about arguments of the system call.
 495 Depending on the size of the desired argument value, an Arg token may be
 496 created using
 497 .Xr au_to_arg32 3
 498 or
 499 .Xr au_to_arg64 3 .
 500 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 501 .It Sy "Field   Bytes   Description"
 502 .It "Token ID   1 byte  Token ID"
 503 .It Li "Argument ID" Ta "1 byte" Ta "Argument ID"
 504 .It Li "Argument value" Ta "4/8 bytes" Ta "Argument value"
 505 .It Li "Length" Ta "2 bytes" Ta "Length of the text"
 506 .It Li "Text" Ta "N bytes + 1 nul" Ta "The string including nul"
 507 .El
 508 .Ss exec_args Token
 509 The
 510 .Dq exec_args
 511 token contains information about arguments of the exec() system call.
 512 An exec_args token may be created using
 513 .Xr au_to_exec_args 3 .
 514 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 515 .It Sy "Field   Bytes   Description"
 516 .It "Token ID   1 byte  Token ID"
 517 .It Li "Count" Ta "4 bytes" Ta "Number of arguments"
 518 .It Li "Text" Ta "* bytes" Ta "Count nul-terminated strings"
 519 .El
 520 .Ss exec_env Token
 521 The
 522 .Dq exec_env
 523 token contains current environment variables to an exec() system call.
 524 An exec_args token may be created using
 525 .Xr au_to_exec_env 3 .
 526 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 527 .It Sy "Field   Bytes   Description"
 528 .It "Token ID   1 byte  Token ID"
 529 .It Li "Count ID" Ta "4 bytes" Ta "Number of variables"
 530 .It Li "Text" Ta "* bytes" Ta "Count nul-terminated strings"
 531 .El
 532 .Ss Exit Token
 533 The
 534 .Dq exit
 535 token contains process exit/return code information.
 536 An
 537 .Dq exit
 538 token can be created using
 539 .Xr au_to_exit 3 .
 540 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 541 .It Sy "Field   Bytes   Description"
 542 .It "Token ID   1 byte  Token ID"
 543 .It "Status     4 bytes Process status on exit"
 544 .It "Return Value       4 bytes Process return value on exit"
 545 .El
 546 .Ss Socket Token
 547 The
 548 .Dq socket
 549 token contains information about UNIX domain and Internet sockets.
 550 Each token has four or eight fields.
 551 Depending on the type of socket, a socket token may be created using
 552 .Xr au_to_sock_unix 3 ,
 553 .Xr au_to_sock_inet32 3
 554 or
 555 .Xr au_to_sock_inet128 3 .
 556 .Bl -column -offset 3n ".Sy Field Name Width XX" ".Sy XX Bytes XXXX" ".Sy Description"
 557 .It Sy "Field" Ta Sy Bytes Ta Sy Description
 558 .It Li "Token ID" Ta "1 byte" Ta "Token ID"
 559 .It Li "Socket family" Ta "2 bytes" Ta "Socket family"
 560 .It Li "Local port" Ta "2 bytes" Ta "Local port"
 561 .It Li "Socket address" Ta "4 bytes" Ta "Socket address"
 562 .El
 563 .Ss Expanded Socket Token
 564 The
 565 .Dq expanded socket
 566 token contains information about IPv4 and IPv6 sockets.
 567 A
 568 .Dq expanded socket
 569 token can be created using
 570 .Xr au_to_socket_ex 3 .
 571 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 572 .It Sy "Field   Bytes   Description"
 573 .It Li "Token ID" Ta "1 byte" Ta "Token ID"
 574 .It Li "Socket domain" Ta "2 bytes" Ta "Socket domain"
 575 .It Li "Socket type" Ta "2 bytes" Ta "Socket type"
 576 .It Li "Address type" Ta "2 byte" Ta "Address type (IPv4/IPv6)"
 577 .It Li "Local port" Ta "2 bytes" Ta "Local port"
 578 .It Li "Local IP address" Ta "4/16 bytes" Ta "Local IP address"
 579 .It Li "Remote port" Ta "2 bytes" Ta "Remote port"
 580 .It Li "Remote IP address" Ta "4/16 bytes" Ta "Remote IP address"
 581 .El
 582 .Ss Seq Token
 583 The
 584 .Dq seq
 585 token contains a unique and monotonically increasing audit event sequence ID.
 586 Due to the limited range of 32 bits, serial number arithmetic and caution
 587 should be used when comparing sequence numbers.
 588 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 589 .It Sy "Field   Bytes   Description"
 590 .It "Token ID   1 byte  Token ID"
 591 .It "Sequence Number    4 bytes Audit event sequence number"
 592 .El
 593 .Ss privilege Token
 594 The
 595 .Dq privilege
 596 token ...
 597 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 598 .It Sy "Field   Bytes   Description"
 599 .It "Token ID   1 byte  Token ID"
 600 .El
 601 .Ss Use-of-auth Token
 602 The
 603 .Dq use-of-auth
 604 token ...
 605 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 606 .It Sy "Field   Bytes   Description"
 607 .It "Token ID   1 byte  Token ID"
 608 .El
 609 .Ss Command Token
 610 The
 611 .Dq command
 612 token ...
 613 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 614 .It Sy "Field   Bytes   Description"
 615 .It "Token ID   1 byte  Token ID"
 616 .El
 617 .Ss ACL Token
 618 The
 619 .Dq ACL
 620 token ...
 621 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 622 .It Sy "Field   Bytes   Description"
 623 .It "Token ID   1 byte  Token ID"
 624 .El
 625 .Ss Zonename Token
 626 The
 627 .Dq zonename
 628 token holds a NUL-terminated string with the name of the zone or jail from
 629 which the record originated.
 630 A
 631 .Dq zonename
 632 token can be created using
 633 .Xr au_to_zonename 3 .
 634 .Bl -column -offset 3n ".No Terminal Address Type/Length" ".No N bytes + 1 NUL"
 635 .It Sy "Field   Bytes   Description"
 636 .It "Token ID   1 byte  Token ID"
 637 .It "Zonename length    2 bytes Length of zonename string including NUL"
 638 .It "Zonename   N bytes + 1 NUL Zonename string including NUL"
 639 .El
 640 .Sh SEE ALSO
 641 .Xr auditreduce 1 ,
 642 .Xr praudit 1 ,
 643 .Xr libbsm 3 ,
 644 .Xr audit 4 ,
 645 .Xr auditpipe 4 ,
 646 .Xr audit 8
 647 .Sh HISTORY
 648 The OpenBSM implementation was created by McAfee Research, the security
 649 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 650 It was subsequently adopted by the TrustedBSD Project as the foundation for
 651 the OpenBSM distribution.
 652 .Sh AUTHORS
 653 The Basic Security Module (BSM) interface to audit records and audit event
 654 stream format were defined by Sun Microsystems.
 655 .Pp
 656 This manual page was written by
 657 .An Robert Watson Aq rwatson@FreeBSD.org .
 658 .Sh BUGS
 659 The
 660 .Dq How to print
 661 field in the
 662 .Dq arbitrary data
 663 token has undefined values.
 664 .Pp
 665 The
 666 .Dq in_addr
 667 and
 668 .Dq in_addr_ex
 669 token layout documented here appears to be in conflict with the
 670 .Xr libbsm 3
 671 implementation of
 672 .Xr au_to_in_addr_ex 3 .