/usr/lib/security/audit_remote.so

host1[:[port1][:mech1]][,host2[:[port2][:mech2]],... \e
 hostn[:[portn][:mechn]]]

The plugin initiates a TCP connection to an audit server (host:port:mech) and establishes a GSS security context (with gss_init_sec_context(3GSS)), with appropriate security mechanism (mech(5)).

If no port is specified, the service name solaris-audit is looked up to obtain a TCP port number. If no mechanism is specified, the GSS_C_NO_OID is used as a mech_type parameter of gss_init_sec_context(3GSS), and causes the underlying GSS-API to use the local default mechanism.

gss_init_sec_context(3GSS) uses GSS_C_NO_CREDENTIAL as the initiator credential handle and a target name of the form audit@<ost_fqdn>. The server is expected to use gss_accept_sec_context(3GSS) to complete the context establishment.

Once the security context is established, the client (audit_remote plugin) calls gss_wrap(3GSS) to achieve the confidentiality of the transferred payload - the audit records. The server is expected to use gss_unwrap(3GSS) to unwrap the received data and gss_get_mic(3GSS) to obtain the MIC (Message Integrity Code) to be later sent back to the plugin as a message retrieval acknowledgment.

For example, if the kerberos_v5 mechanism is configured as GSS_API mechanism on the client and both sides agree on using this mechanism, the client side has to be eligible to non-interactively gain session keys for the audit/<host_fqdn>@<REALM> principal from the Kerberos KDC/TGS. At the same time the identity running the audit server application has to have the long term keys associated with the audit/<host_fqdn>@<REALM> principal stored in the keytab file (krb5.conf(5)) to be able to decrypt the session keys.

The audit_remote plugin initiates a connection to first server in the p_hosts list. If the connection fails or audit record sends are not responded to in p_timeout seconds, after p_retries attempts the plugin tries to connect to the next server. If the connection to the last server fails, the plugin retries to connect to the first host in the list. audit_warn(8) is executed at every unsuccessful attempt to connect to the server or send timeout with the plugin option plugin audit_remote.so retry <count> <error>.<error> is connection <host:port> <the network error>. An EPROTO network error indicates that the client plugin did not get a successful protocol version handshake.

The protocol begins with version negotiation followed by a GSS-API security context token exchange. On error the connection is closed (and any output token optionally sent).

The version negotiation takes place in the clear with the plugin sending an octet array of the comma (,) separated list of versions supported. The current version number is the characters 01. The receiver is expected to respond with the version that they accept (in the current case that is the characters 01). A mismatch is considered an error and the connection is closed.

The version octet array sent by the plugin and the version characters accepted by the receiver are concatenated together to make up the application data field of the channel bindings of the GSS security context establishment.

<plugin version characters> || <server accepted version characters>"
||" represents concatenation

Subsequent tokens contain a 64 bit sequence number in network byte order and a single audit record (audit.log(5)); the client uses confidentiality protection. wrap (64 bit sequence number || audit record)

The server acknowledges the receipt (and is then responsible for any data loss) with the received 64 bit sequence number and a MIC token of the unwrapped 64 bit sequence number and audit record. MIC verification on the client side acknowledges the audit record can be freed and not saved for possible retransmission.

64 bit sequence number || mic (64 bit sequence number || audit record)

Secure remote audit client/server communication flow:

1) Client <--> Server - TCP handshake

2) Client <--> Server - protocol version negotiation:
 a) Client --> Server - send data size - uint32_t value (2)
 b) Client --> Server - send clear text message of the versions
 supported comma separated, e.g.,
 "01,02,03" for versions 1 and 2 and 3.
 The only version supported at present is
 "01"
 c) Client <-- Server - send data size - uint32_t value (2)
 d) Client <-- Server - send clear text version selected
 ("01")
 :no version match; close connection; try next host

3) Security context initiation:
 a) Client - Construct channel bindings application data value
 (4 octets "0101")
 b) Client --> Server - send token (data) size - uint32_t value
 c) Client --> Server - GSS-API per-context token
 d) Client <-- Server - send token (data) size
 e) Client <-- Server - GSS-API per-context token
 :repeat a-e until security context is initialized; if unsuccessful,
 close connection; try next host

4) Client - transmit thread, when audit record to be sent:
 a) Client --> Server - send data size
 b) Client --> Server - GSS-API per-message token
 wrap (sequence number || audit record)
 :repeat a-b while less than max (qsize) outstanding records

 5) Client - receive thread:
 a) Client <-- Server - receive data size - uint32_t value
 b) Client <-- Server - receive sequence number - uint64_t value
 c) Client <-- Server - receive MIC
 d) Client - MIC verification - OK
 e) Client - remove particular audit record
 pointed by the sequence number from the
 retransmit buffer
 :repeat a-e, on error close connection; try next host;
 retransmit unacknowledged audit records

6) Server - receive thread:
 a) Client --> Server - receive data size
 b) Client --> Server - GSS-API receive, uwrap, store
 per-message token

7) Server - transmit thread:
 a) Server - MIC generation - message integrity code
 mic (sequence number || audit record)
 b) Client <-- Server - send data size
 c) Client < -- Server - send sequence number
 d) Client <-- Server - send MIC

The following commands cause audit_remote.so to be activated and set the p_retries and p_timeout attributes. Note that using auditconfig(8) only allows one attribute to be set at a time.

# auditconfig -setplugin audit_remote active p_retries=2
# auditconfig -setplugin audit_remote active p_timeout=90

Example 2 Activating audit_remote.so and Specifying the Remote Audit Servers

The following command causes audit_remote.so to be activated and specifies the remote audit servers to where the audit records are sent. The kerberos_v5 security mechanism is defined to be used when communicating with the servers.

# auditconfig -setplugin audit_remote active \e
p_hosts=eggplant.eng.example.com::kerberos_v5,\e
purple.ebay.example.com:4592:kerberos_v5

Example 3 Using the Configuration of Usage Default Security Mechanism

The following example shows the configuration of usage of default security mechanism. It also shows use of default port on one of the configured servers:

# auditconfig -setplugin audit_remote active \e
p_hosts=jedger.eng.example.com,\e
jbadams.ebay.example.com:4592

The plugin configuration parameters are Committed. The client/server protocol (version "01") is Contracted Project Private. See audit.log(5) for the audit record format and content stability.

The solaris-audit service port assigned by IANA is 16162.