1502 Remove conversion cruft from manpages

[unleashed.git] / usr / src / man / man5 / audit_remote.5

'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH AUDIT_REMOTE 5 "Sep 8, 2009"
.SH NAME
audit_remote \- send Solaris audit logs to a remote server
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/security/audit_remote.so\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBaudit_remote\fR plugin module for Solaris audit,
\fB/usr/lib/security/audit_remote.so\fR, sends binary audit records
(\fBaudit.log\fR(4)) to audit servers specified in \fBaudit_control\fR(4).
.sp
.LP
The \fBaudit_remote\fR plugin is loaded by \fBauditd\fR(1M) if
\fBaudit_control\fR contains a \fBplugin:\fR specification of
\fBname=audit_remote.so\fR.
.SS "Object Attributes"
.sp
.LP
The following attributes specify the configuration of \fBaudit_remote\fR
plugin:
.sp
.ne 2
.na
\fB\fBp_hosts\fR\fR
.ad
.sp .6
.RS 4n
.sp
.in +2
.nf
\fIhost1\fR[:[\fIport1\fR][:\fImech1\fR]][,\fIhost2\fR[:[\fIport2\fR][:\fImech2\fR]],... \e
    \fIhostn\fR[:[\fIportn\fR][:\fImechn\fR]]]
.fi
.in -2
.sp

A list of audit hosts/servers. Audit records are sent to the first available
host. If a host is unreachable or a timeout occurs while sending data, the next
host in the list is tried. If connection to all hosts fails, the list is tried
again from the beginning.
.sp
The \fIhost\fR part of a \fBp_hosts\fR entry can be in any form acceptable to
\fBgetipnodebyname\fR(3SOCKET).
.sp
The \fIport\fR part of a \fBp_hosts\fR entry is the port on host that is
contacted to initiate an audit server connection. If not specified, the port
number is that assigned to the \fBsolaris-audit\fR service. See
\fBgetservbyname\fR(3XNET).
.sp
The \fBmech\fR part of a \fBp_host\fR entry is the GSS-API mechanism name
(\fBmech\fR(4)). If not specified, the local host's default mechanism is used.
The recommended mechanism is \fBkerberos_v5\fR.
.RE

.sp
.ne 2
.na
\fB\fBp_retries\fR\fR
.ad
.sp .6
.RS 4n
The number of retries for connecting to and sending data to a server.
.sp
The default value is \fB3\fR.
.RE

.sp
.ne 2
.na
\fB\fBp_timeout\fR\fR
.ad
.sp .6
.RS 4n
The number of seconds in which a connection/sending data timeouts.
.sp
The default value is \fB5\fR seconds.
.RE

.sp
.ne 2
.na
\fB\fBqsize\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of outstanding audit records to keep.
.sp
The default is the value of the kernel queue control high water mark. See
\fBauditconfig\fR(1M).
.RE

.SS "GSS SESSION"
.sp
.LP
The \fBaudit_remote plugin\fR is a TCP client that authenticates configured
audit servers using the GSS-API (\fBlibgss\fR(3LIB)). Binary Solaris Audit
records are sent with integrity and confidentiality protection as per-message
tokens generated by \fBgss_wrap\fR(3GSS).
.sp
.LP
The plugin initiates a TCP connection to an audit server (\fIhost:port:mech\fR)
and establishes a GSS security context (with \fBgss_init_sec_context\fR(3GSS)),
with appropriate security mechanism (\fBmech\fR(4)).
.sp
.LP
If no port is specified, the service name \fBsolaris-audit\fR is looked up to
obtain a TCP port number. If no mechanism is specified, the \fBGSS_C_NO_OID\fR
is used as a \fBmech_type\fR parameter of \fBgss_init_sec_context\fR(3GSS), and
causes the underlying \fBGSS-API\fR to use the local default mechanism.
.sp
.LP
\fBgss_init_sec_context\fR(3GSS) uses \fBGSS_C_NO_CREDENTIAL\fR as the
initiator credential handle and a target name of the form
\fBaudit@<ost_fqdn>\fR. The server is expected to use
\fBgss_accept_sec_context\fR(3GSS) to complete the context establishment.
.sp
.LP
Once the security context is established, the client (\fBaudit_remote\fR
plugin) calls \fBgss_wrap\fR(3GSS) to achieve the confidentiality of the
transferred payload - the audit records. The server is expected to use
\fBgss_unwrap\fR(3GSS) to unwrap the received data and \fBgss_get_mic\fR(3GSS)
to obtain the MIC (Message Integrity Code) to be later sent back to the plugin
as a message retrieval acknowledgment.
.sp
.LP
For example, if the \fBkerberos_v5\fR mechanism is configured as \fBGSS_API\fR
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
\fBaudit/<host_fqdn>@<REALM>\fR 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 \fBaudit/<host_fqdn>@<REALM>\fR principal
stored in the \fBkeytab\fR file (\fBkrb5.conf\fR(4)) to be able to decrypt the
session keys.
.sp
.LP
The \fBaudit_remote\fR plugin initiates a connection to first server in the
\fBp_hosts\fR list. If the connection fails or audit record sends are not
responded to in \fBp_timeout\fR seconds, after \fBp_retries\fR 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.
\fBaudit_warn\fR(1M) is executed at every unsuccessful attempt to connect to
the server or send timeout with the plugin option plugin \fBaudit_remote.so
retry <count> <error>.<error>\fR is connection \fB<host:port> <the network
error>\fR\&. An \fBEPROTO\fR network error indicates that the client plugin did
not get a successful protocol version handshake.
.SS "PROTOCOL DESCRIPTION"
.sp
.LP
All protocol messages are preceded by the 4 octets of the size of the data to
follow. This size is in network byte order.
.sp
.LP
The protocol begins with version negotiation followed by a \fBGSS-API\fR
security context token exchange. On error the connection is closed (and any
output token optionally sent).
.sp
.LP
The version negotiation takes place in the clear with the plugin sending an
octet array of the comma (\fB,\fR) separated list of versions supported. The
current version number is the characters \fB01\fR. The receiver is expected to
respond with the version that they accept (in the current case that is the
characters \fB01\fR). A mismatch is considered an error and the connection is
closed.
.sp
.LP
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.
.sp
.in +2
.nf
<plugin version characters> || <server accepted version characters>"
||" represents concatenation
.fi
.in -2

.sp
.LP
Subsequent tokens contain a 64 bit sequence number in network byte order and a
single audit record (\fBaudit.log\fR(4)); the client uses confidentiality
protection. wrap (64 bit sequence number || audit record)
.sp
.LP
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.
.sp
.in +2
.nf
64 bit sequence number || mic (64 bit sequence number || audit record)
.fi
.in -2

.sp
.LP
Secure remote audit client/server communication flow:
.sp
.in +2
.nf
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
.fi
.in -2

.SH EXAMPLES
.LP
\fBExample 1 \fRLoading \fBaudit_remote.so\fR and Specifying the Remote Audit
Servers
.sp
.LP
The following directives cause \fBaudit_remote.so\fR to be loaded and specify
the remote audit servers to where the audit records are sent. The
\fBkerberos_v5\fR security mechanism is defined to be used when communicating
with the servers.

.sp
.in +2
.nf
plugin: name=audit_remote.so;\e
p_timeout=90;p_retries=2;\e
p_hosts=eggplant.eng.sun.com::kerberos_v5,\e
purple.ebay.sun.com:4592:kerberos_v5
.fi
.in -2

.LP
\fBExample 2 \fRUsing the Configuration of Usage Default Security Mechanism
.sp
.LP
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:

.sp
.in +2
.nf
plugin: name=audit_remote.so;\e
p_timeout=10;p_retries=2;\e
p_hosts=jedger.eng.sun.com,\e
jbadams.ebay.sun.com:4592
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
MT Level        MT-Safe
_
Interface Stability     See below.
.TE

.sp
.LP
The plugin configuration parameters are Committed. The client/server protocol
(version \fB"01"\fR) is Contracted Project Private. See \fBaudit.log\fR(4) for
the audit record format and content stability.
.SH SEE ALSO
.sp
.LP
\fBauditd\fR(1M), \fBauditconfig\fR(1M), \fBaudit_warn\fR(1M),
\fBgetipnodebyname\fR(3SOCKET), \fBgetservbyname\fR(3XNET),
\fBgss_accept_sec_context\fR(3GSS), \fBgss_get_mic\fR(3GSS),
\fBgss_init_sec_context\fR(3GSS), \fBgss_wrap\fR(3GSS), \fBgss_unwrap\fR(3GSS),
\fBlibgss\fR(3LIB), \fBlibsocket\fR(3LIB), \fBaudit_control\fR(4),
\fBaudit.log\fR(4), \fBkrb5.conf\fR(4), \fBmech\fR(4), \fBattributes\fR(5),
\fBkerberos\fR(5), \fBtcp\fR(7P)
.SH NOTES
.sp
.LP
\fBaudit_remote\fR authenticates itself to the remote audit service by way of
GSS-API (\fBlibgss\fR(3LIB)). Default gss credentials are used as provided by
the \fBgss\fR implementation mechanism, such as Kerberos.
.sp
.LP
The \fBsolaris-audit\fR service port assigned by IANA is \fB16162\fR.