1audit_remote(5) Standards, Environments, and Macros audit_remote(5)
2
6 audit_remote - send Solaris audit logs to a remote server
7
9 /usr/lib/security/audit_remote.so
10
13 The audit_remote plugin module for Solaris audit, /usr/lib/secu‐
14 rity/audit_remote.so, sends binary audit records (audit.log(4)) to
15 audit servers specified in audit_control(4).
16 The audit_remote plugin is loaded by auditd(1M) if audit_control con‐
19 tains a plugin: specification of name=audit_remote.so.
20 Object Attributes
22 The following attributes specify the configuration of audit_remote
23 plugin:
24 p_hosts
26 host1[:[port1][:mech1]][,host2[:[port2][:mech2]],... \
29 hostn[:[portn][:mechn]]]
30 A list of audit hosts/servers. Audit records are sent to the first
33 available host. If a host is unreachable or a timeout occurs while
34 sending data, the next host in the list is tried. If connection to
35 all hosts fails, the list is tried again from the beginning.
36 The host part of a p_hosts entry can be in any form acceptable to
38 getipnodebyname(3SOCKET).
39 The port part of a p_hosts entry is the port on host that is con‐
41 tacted to initiate an audit server connection. If not specified,
42 the port number is that assigned to the solaris-audit service. See
43 getservbyname(3XNET).
44 The mech part of a p_host entry is the GSS-API mechanism name
46 (mech(4)). If not specified, the local host's default mechanism is
47 used. The recommended mechanism is kerberos_v5.
48 p_retries
51 The number of retries for connecting to and sending data to a
53 server.
54 The default value is 3.
56 p_timeout
59 The number of seconds in which a connection/sending data timeouts.
61 The default value is 5 seconds.
63 qsize
66 The maximum number of outstanding audit records to keep.
68 The default is the value of the kernel queue control high water
70 mark. See auditconfig(1M).
71 GSS SESSION
74 The audit_remote plugin is a TCP client that authenticates configured
75 audit servers using the GSS-API (libgss(3LIB)). Binary Solaris Audit
76 records are sent with integrity and confidentiality protection as per-
77 message tokens generated by gss_wrap(3GSS).
78 The plugin initiates a TCP connection to an audit server
81 (host:port:mech) and establishes a GSS security context (with
82 gss_init_sec_context(3GSS)), with appropriate security mechanism
83 (mech(4)).
84 If no port is specified, the service name solaris-audit is looked up to
87 obtain a TCP port number. If no mechanism is specified, the
88 GSS_C_NO_OID is used as a mech_type parameter of gss_init_sec_con‐
89 text(3GSS), and causes the underlying GSS-API to use the local default
90 mechanism.
91 gss_init_sec_context(3GSS) uses GSS_C_NO_CREDENTIAL as the initiator
94 credential handle and a target name of the form audit@<ost_fqdn>. The
95 server is expected to use gss_accept_sec_context(3GSS) to complete the
96 context establishment.
97 Once the security context is established, the client (audit_remote
100 plugin) calls gss_wrap(3GSS) to achieve the confidentiality of the
101 transferred payload - the audit records. The server is expected to use
102 gss_unwrap(3GSS) to unwrap the received data and gss_get_mic(3GSS) to
103 obtain the MIC (Message Integrity Code) to be later sent back to the
104 plugin as a message retrieval acknowledgment.
105 For example, if the kerberos_v5 mechanism is configured as GSS_API
108 mechanism on the client and both sides agree on using this mechanism,
109 the client side has to be eligible to non-interactively gain session
110 keys for the audit/<host_fqdn>@<REALM> principal from the Kerberos
111 KDC/TGS. At the same time the identity running the audit server appli‐
112 cation has to have the long term keys associated with the
113 audit/<host_fqdn>@<REALM> principal stored in the keytab file
114 (krb5.conf(4)) to be able to decrypt the session keys.
115 The audit_remote plugin initiates a connection to first server in the
118 p_hosts list. If the connection fails or audit record sends are not
119 responded to in p_timeout seconds, after p_retries attempts the plugin
120 tries to connect to the next server. If the connection to the last
121 server fails, the plugin retries to connect to the first host in the
122 list. audit_warn(1M) is executed at every unsuccessful attempt to con‐
123 nect to the server or send timeout with the plugin option plugin
124 audit_remote.so retry <count> <error>.<error> is connection <host:port>
125 <the network error>. An EPROTO network error indicates that the client
126 plugin did not get a successful protocol version handshake.
127 PROTOCOL DESCRIPTION
129 All protocol messages are preceded by the 4 octets of the size of the
130 data to follow. This size is in network byte order.
131 The protocol begins with version negotiation followed by a GSS-API
134 security context token exchange. On error the connection is closed (and
135 any output token optionally sent).
136 The version negotiation takes place in the clear with the plugin send‐
139 ing an octet array of the comma (,) separated list of versions sup‐
140 ported. The current version number is the characters 01. The receiver
141 is expected to respond with the version that they accept (in the cur‐
142 rent case that is the characters 01). A mismatch is considered an error
143 and the connection is closed.
144 The version octet array sent by the plugin and the version characters
147 accepted by the receiver are concatenated together to make up the
148 application data field of the channel bindings of the GSS security con‐
149 text establishment.
150 <plugin version characters> || <server accepted version characters>"
152 ||" represents concatenation
153 Subsequent tokens contain a 64 bit sequence number in network byte
157 order and a single audit record (audit.log(4)); the client uses confi‐
158 dentiality protection. wrap (64 bit sequence number || audit record)
159 The server acknowledges the receipt (and is then responsible for any
162 data loss) with the received 64 bit sequence number and a MIC token of
163 the unwrapped 64 bit sequence number and audit record. MIC verification
164 on the client side acknowledges the audit record can be freed and not
165 saved for possible retransmission.
166 64 bit sequence number || mic (64 bit sequence number || audit record)
168 Secure remote audit client/server communication flow:
172 1) Client <--> Server - TCP handshake
174 2) Client <--> Server - protocol version negotiation:
176 a) Client --> Server - send data size - uint32_t value (2)
177 b) Client --> Server - send clear text message of the versions
178 supported comma separated, e.g.,
179 "01,02,03" for versions 1 and 2 and 3.
180 The only version supported at present is
181 "01"
182 c) Client <-- Server - send data size - uint32_t value (2)
183 d) Client <-- Server - send clear text version selected
184 ("01")
185 :no version match; close connection; try next host
186 3) Security context initiation:
188 a) Client - Construct channel bindings application data value
189 (4 octets "0101")
190 b) Client --> Server - send token (data) size - uint32_t value
191 c) Client --> Server - GSS-API per-context token
192 d) Client <-- Server - send token (data) size
193 e) Client <-- Server - GSS-API per-context token
194 :repeat a-e until security context is initialized; if unsuccessful,
195 close connection; try next host
196 4) Client - transmit thread, when audit record to be sent:
198 a) Client --> Server - send data size
199 b) Client --> Server - GSS-API per-message token
200 wrap (sequence number || audit record)
201 :repeat a-b while less than max (qsize) outstanding records
202 5) Client - receive thread:
204 a) Client <-- Server - receive data size - uint32_t value
205 b) Client <-- Server - receive sequence number - uint64_t value
206 c) Client <-- Server - receive MIC
207 d) Client - MIC verification - OK
208 e) Client - remove particular audit record
209 pointed by the sequence number from the
210 retransmit buffer
211 :repeat a-e, on error close connection; try next host;
212 retransmit unacknowledged audit records
213 6) Server - receive thread:
215 a) Client --> Server - receive data size
216 b) Client --> Server - GSS-API receive, uwrap, store
217 per-message token
218 7) Server - transmit thread:
220 a) Server - MIC generation - message integrity code
221 mic (sequence number || audit record)
222 b) Client <-- Server - send data size
223 c) Client < -- Server - send sequence number
224 d) Client <-- Server - send MIC
225
228 Example 1 Loading audit_remote.so and Specifying the Remote Audit
229 Servers
230 The following directives cause audit_remote.so to be loaded and specify
233 the remote audit servers to where the audit records are sent. The ker‐
234 beros_v5 security mechanism is defined to be used when communicating
235 with the servers.
236 plugin: name=audit_remote.so;\
239 p_timeout=90;p_retries=2;\
240 p_hosts=eggplant.eng.sun.com::kerberos_v5,\
241 purple.ebay.sun.com:4592:kerberos_v5
242 Example 2 Using the Configuration of Usage Default Security Mechanism
245 The following example shows the configuration of usage of default secu‐
248 rity mechanism. It also shows use of default port on one of the config‐
249 ured servers:
250 plugin: name=audit_remote.so;\
253 p_timeout=10;p_retries=2;\
254 p_hosts=jedger.eng.sun.com,\
255 jbadams.ebay.sun.com:4592
256
260 See attributes(5) for a description of the following attributes:
261 ┌─────────────────────────────┬─────────────────────────────┐
266 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
267 ├─────────────────────────────┼─────────────────────────────┤
268 │MT Level │MT-Safe │
269 ├─────────────────────────────┼─────────────────────────────┤
270 │Interface Stability │See below. │
271 └─────────────────────────────┴─────────────────────────────┘
272 The plugin configuration parameters are Committed. The client/server
275 protocol (version "01") is Contracted Project Private. See audit.log(4)
276 for the audit record format and content stability.
277
279 auditd(1M), auditconfig(1M), audit_warn(1M), getipnodebyname(3SOCKET),
280 getservbyname(3XNET), gss_accept_sec_context(3GSS), gss_get_mic(3GSS),
281 gss_init_sec_context(3GSS), gss_wrap(3GSS), gss_unwrap(3GSS),
282 libgss(3LIB), libsocket(3LIB), audit_control(4), audit.log(4),
283 krb5.conf(4), mech(4), attributes(5), kerberos(5), tcp(7P)
284
286 audit_remote authenticates itself to the remote audit service by way of
287 GSS-API (libgss(3LIB)). Default gss credentials are used as provided by
288 the gss implementation mechanism, such as Kerberos.
289 The solaris-audit service port assigned by IANA is 16162.
292SunOS 5.11 8 Sep 2009 audit_remote(5)