1.\"-
2.\" Copyright (c) 2005-2006 Robert N. M. Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
| 1.\"-
2.\" Copyright (c) 2005-2006 Robert N. M. Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
|
26.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_control.3#8 $
| 26.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_control.3#9 $
|
27.\"
28.Dd April 19, 2005
29.Dt AU_CONTROL 3
30.Os
31.Sh NAME
32.Nm setac ,
33.Nm endac ,
34.Nm getacdir ,
35.Nm getacmin ,
36.Nm getacfilesz ,
37.Nm getacflg ,
38.Nm getacna ,
39.Nm getacpol ,
40.Nm au_poltostr ,
41.Nm au_strtopol
42.Nd "look up information from the audit_control database"
43.Sh LIBRARY
44.Lb libbsm
45.Sh SYNOPSIS
46.In bsm/libbsm.h
47.Ft void
48.Fn setac void
49.Ft void
50.Fn endac void
51.Ft int
52.Fn getacdir "char *name" "int len"
53.Ft int
54.Fn getacmin "int *min_val"
55.Ft int
56.Fn getacfilesz "size_t *size_val"
57.Ft int
58.Fn getacflg "char *auditstr" "int len"
59.Ft int
60.Fn getacna "char *auditstr" "int len"
61.Ft int
62.Fn getacpol "char *auditstr" "size_t len"
63.Ft ssize_t
64.Fn au_poltostr "long policy" "size_t maxsize" "char *buf"
65.Ft int
66.Fn au_strtopol "const char *polstr" "long *policy"
67.Sh DESCRIPTION
68These interfaces may be used to look up information from the
69.Xr audit_control 5
70database, which contains various audit-related administrative parameters.
71.Pp
72The
73.Fn setac
74function
75resets the database iterator to the beginning of the database; see the
76.Sx BUGS
77section for more information.
78.Pp
79The
| 27.\"
28.Dd April 19, 2005
29.Dt AU_CONTROL 3
30.Os
31.Sh NAME
32.Nm setac ,
33.Nm endac ,
34.Nm getacdir ,
35.Nm getacmin ,
36.Nm getacfilesz ,
37.Nm getacflg ,
38.Nm getacna ,
39.Nm getacpol ,
40.Nm au_poltostr ,
41.Nm au_strtopol
42.Nd "look up information from the audit_control database"
43.Sh LIBRARY
44.Lb libbsm
45.Sh SYNOPSIS
46.In bsm/libbsm.h
47.Ft void
48.Fn setac void
49.Ft void
50.Fn endac void
51.Ft int
52.Fn getacdir "char *name" "int len"
53.Ft int
54.Fn getacmin "int *min_val"
55.Ft int
56.Fn getacfilesz "size_t *size_val"
57.Ft int
58.Fn getacflg "char *auditstr" "int len"
59.Ft int
60.Fn getacna "char *auditstr" "int len"
61.Ft int
62.Fn getacpol "char *auditstr" "size_t len"
63.Ft ssize_t
64.Fn au_poltostr "long policy" "size_t maxsize" "char *buf"
65.Ft int
66.Fn au_strtopol "const char *polstr" "long *policy"
67.Sh DESCRIPTION
68These interfaces may be used to look up information from the
69.Xr audit_control 5
70database, which contains various audit-related administrative parameters.
71.Pp
72The
73.Fn setac
74function
75resets the database iterator to the beginning of the database; see the
76.Sx BUGS
77section for more information.
78.Pp
79The
|
80.Fn sendac
| 80.Fn endac
|
81function
82closes the
83.Xr audit_control 5
84database.
85.Pp
86The
87.Fn getacdir
88function
89returns the name of the directory where log data is stored via the passed
90character buffer
91.Fa name
92of length
93.Fa len .
94.Pp
95The
96.Fn getacmin
97function
98returns the minimum free disk space for the audit log target file system via
99the passed
100.Fa min_val
101variable.
102.Pp
103The
104.Fn getacfilesz
105function
106returns the audit trail rotation size in the passed
107.Vt size_t
108buffer
109.Fa size_val .
110.Pp
111The
112.Fn getacflg
113function
114returns the audit system flags via the the passed character buffer
115.Fa auditstr
116of length
117.Fa len .
118.Pp
119The
120.Fn getacna
121function
122returns the non-attributable flags via the passed character buffer
123.Fa auditstr
124of length
125.Fa len .
126.Pp
127The
128.Fn getacpol
129function
130returns the audit policy flags via the passed character buffer
131.Fa auditstr
132of length
133.Fa len .
134.Pp
135The
136.Fn au_poltostr
137function
138converts a numeric audit policy mask,
139.Fa policy ,
140to a string in the passed character buffer
141.Fa buf
142of lenth
143.Fa maxsize .
144.Pp
145The
146.Fn au_strtopol
147function
148converts an audit policy flags string,
149.Fa polstr ,
150to a numeric audit policy mask returned via
151.Fa policy .
152.Sh RETURN VALULES
153The
154.Fn getacdir ,
155.Fn getacmin ,
156.Fn getacflg ,
157.Fn getacna ,
158.Fn getacpol ,
159and
160.Fn au_strtopol
161functions
162return 0 on success, or a negative value on failure, along with error
163information in
164.Va errno .
165.Pp
166The
167.Fn au_poltostr
168function
169returns a string length of 0 or more on success, or a negative value on
170if there is a failure.
171.Pp
172Functions that return a string value will return a failure if there is
173insufficient room in the passed character buffer for the full string.
174.Sh SEE ALSO
175.Xr libbsm 3 ,
176.Xr audit_control 5
177.Sh HISTORY
178The OpenBSM implementation was created by McAfee Research, the security
179division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
180It was subsequently adopted by the TrustedBSD Project as the foundation for
181the OpenBSM distribution.
182.Sh AUTHORS
183.An -nosplit
184This software was created by
185.An Robert Watson ,
186.An Wayne Salamon ,
187and
188.An Suresh Krishnaswamy
189for McAfee Research, the security research division of McAfee,
190Inc., under contract to Apple Computer, Inc.
191.Pp
192The Basic Security Module (BSM) interface to audit records and audit event
193stream format were defined by Sun Microsystems.
194.Sh BUGS
195These routines cannot currently distinguish between an entry not being found
196and an error accessing the database.
197The implementation should be changed to return an error via
198.Va errno
199when
200.Dv NULL
201is returned.
202.Sh BUGS
203There is no reason for the
204.Fn setac
205interface to be exposed as part of the public API, as it is called implicitly
206by other access functions and iteration is not supported.
207.Pp
208These interfaces inconsistently return various negative values depending on
209the failure mode, and do not always set
210.Va errno
211on failure.
| 81function
82closes the
83.Xr audit_control 5
84database.
85.Pp
86The
87.Fn getacdir
88function
89returns the name of the directory where log data is stored via the passed
90character buffer
91.Fa name
92of length
93.Fa len .
94.Pp
95The
96.Fn getacmin
97function
98returns the minimum free disk space for the audit log target file system via
99the passed
100.Fa min_val
101variable.
102.Pp
103The
104.Fn getacfilesz
105function
106returns the audit trail rotation size in the passed
107.Vt size_t
108buffer
109.Fa size_val .
110.Pp
111The
112.Fn getacflg
113function
114returns the audit system flags via the the passed character buffer
115.Fa auditstr
116of length
117.Fa len .
118.Pp
119The
120.Fn getacna
121function
122returns the non-attributable flags via the passed character buffer
123.Fa auditstr
124of length
125.Fa len .
126.Pp
127The
128.Fn getacpol
129function
130returns the audit policy flags via the passed character buffer
131.Fa auditstr
132of length
133.Fa len .
134.Pp
135The
136.Fn au_poltostr
137function
138converts a numeric audit policy mask,
139.Fa policy ,
140to a string in the passed character buffer
141.Fa buf
142of lenth
143.Fa maxsize .
144.Pp
145The
146.Fn au_strtopol
147function
148converts an audit policy flags string,
149.Fa polstr ,
150to a numeric audit policy mask returned via
151.Fa policy .
152.Sh RETURN VALULES
153The
154.Fn getacdir ,
155.Fn getacmin ,
156.Fn getacflg ,
157.Fn getacna ,
158.Fn getacpol ,
159and
160.Fn au_strtopol
161functions
162return 0 on success, or a negative value on failure, along with error
163information in
164.Va errno .
165.Pp
166The
167.Fn au_poltostr
168function
169returns a string length of 0 or more on success, or a negative value on
170if there is a failure.
171.Pp
172Functions that return a string value will return a failure if there is
173insufficient room in the passed character buffer for the full string.
174.Sh SEE ALSO
175.Xr libbsm 3 ,
176.Xr audit_control 5
177.Sh HISTORY
178The OpenBSM implementation was created by McAfee Research, the security
179division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
180It was subsequently adopted by the TrustedBSD Project as the foundation for
181the OpenBSM distribution.
182.Sh AUTHORS
183.An -nosplit
184This software was created by
185.An Robert Watson ,
186.An Wayne Salamon ,
187and
188.An Suresh Krishnaswamy
189for McAfee Research, the security research division of McAfee,
190Inc., under contract to Apple Computer, Inc.
191.Pp
192The Basic Security Module (BSM) interface to audit records and audit event
193stream format were defined by Sun Microsystems.
194.Sh BUGS
195These routines cannot currently distinguish between an entry not being found
196and an error accessing the database.
197The implementation should be changed to return an error via
198.Va errno
199when
200.Dv NULL
201is returned.
202.Sh BUGS
203There is no reason for the
204.Fn setac
205interface to be exposed as part of the public API, as it is called implicitly
206by other access functions and iteration is not supported.
207.Pp
208These interfaces inconsistently return various negative values depending on
209the failure mode, and do not always set
210.Va errno
211on failure.
|