| au_open.3 (162503) | au_open.3 (168777) |
|---|---|
| 1.\"- 2.\" Copyright (c) 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. | 1.\"- 2.\" Copyright (c) 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.\" | 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.\" | 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_open.3#5 $ | 26.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_open.3#8 $ |
| 27.\" 28.Dd March 4, 2006 29.Dt AU_OPEN 3 30.Os 31.Sh NAME 32.Nm au_close , 33.Nm au_close_buffer , 34.Nm au_close_token , 35.Nm au_open , 36.Nm au_write | 27.\" 28.Dd March 4, 2006 29.Dt AU_OPEN 3 30.Os 31.Sh NAME 32.Nm au_close , 33.Nm au_close_buffer , 34.Nm au_close_token , 35.Nm au_open , 36.Nm au_write |
| 37.Nd "Create and commit audit records" | 37.Nd "create and commit audit records" |
| 38.Sh LIBRARY 39.Lb libbsm 40.Sh SYNOPSIS | 38.Sh LIBRARY 39.Lb libbsm 40.Sh SYNOPSIS |
| 41.In libbsm.h | 41.In bsm/libbsm.h |
| 42.Ft int | 42.Ft int |
| 43.Fn au_open "void" | 43.Fn au_open void |
| 44.Ft int 45.Fn au_write "int d" "token_t *tok" 46.Ft int 47.Fn au_close "int d" "int keep" "short event" 48.Ft int 49.Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen" 50.Ft int 51.Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen" --- 16 unchanged lines hidden (view full) --- 68.Xr au_free_token 3 . 69.Pp 70The 71.Fn au_close 72function is used to commit an audit record to the system audit log, or 73abandon the record. 74In either cases, all resources associated with the record will be released. 75The | 44.Ft int 45.Fn au_write "int d" "token_t *tok" 46.Ft int 47.Fn au_close "int d" "int keep" "short event" 48.Ft int 49.Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen" 50.Ft int 51.Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen" --- 16 unchanged lines hidden (view full) --- 68.Xr au_free_token 3 . 69.Pp 70The 71.Fn au_close 72function is used to commit an audit record to the system audit log, or 73abandon the record. 74In either cases, all resources associated with the record will be released. 75The |
| 76.Va keep | 76.Fa keep |
| 77argument determines the behavior: a value of 78.Dv AU_TO_WRITE 79causes the record to be committed; a value of 80.Dv AU_TO_NO_WRITE 81causes it to be abandoned. 82When the audit record is committed, a BSM header will be inserted before 83tokens added to the record, using the event identifier passed via | 77argument determines the behavior: a value of 78.Dv AU_TO_WRITE 79causes the record to be committed; a value of 80.Dv AU_TO_NO_WRITE 81causes it to be abandoned. 82When the audit record is committed, a BSM header will be inserted before 83tokens added to the record, using the event identifier passed via |
| 84.Va event , | 84.Fa event , |
| 85and a trailer added to the end. 86Committing a record to the system audit log requires privilege. 87.Pp 88The 89.Fn au_close_buffer 90function writes the resulting record to an in-memory buffer of size | 85and a trailer added to the end. 86Committing a record to the system audit log requires privilege. 87.Pp 88The 89.Fn au_close_buffer 90function writes the resulting record to an in-memory buffer of size |
| 91.Va *buflen ; | 91.Fa *buflen ; |
| 92it will write back the filled buffer length into the same variable. 93The argument | 92it will write back the filled buffer length into the same variable. 93The argument |
| 94.Va short | 94.Fa event |
| 95is the event identifier to use in the record header. 96.Pp 97The 98.Fn au_close_token 99function generates the BSM stream output for a single token, | 95is the event identifier to use in the record header. 96.Pp 97The 98.Fn au_close_token 99function generates the BSM stream output for a single token, |
| 100.Va tok , | 100.Fa tok , |
| 101in the passed buffer | 101in the passed buffer |
| 102.Va buffer . | 102.Fa buffer . |
| 103The initial buffer size and resulting data size are passed via | 103The initial buffer size and resulting data size are passed via |
| 104.Va *buflen . | 104.Fa *buflen . 105The |
| 105.Fn au_close_token | 106.Fn au_close_token |
| 107function |
|
| 106will free the token before returning. 107.Sh RETURN VALUES 108The function 109.Fn au_open 110returns a non-negative audit record descriptor number on success, or a 111negative value on failure, along with error information in 112.Va errno . 113.Pp --- 4 unchanged lines hidden (view full) --- 118and 119.Fn au_close_token 120return 0 on success, or a negative value on failure, along with error 121information in 122.Va errno . 123.Sh SEE ALSO 124.Xr audit_submit 3 , 125.Xr libbsm 3 | 108will free the token before returning. 109.Sh RETURN VALUES 110The function 111.Fn au_open 112returns a non-negative audit record descriptor number on success, or a 113negative value on failure, along with error information in 114.Va errno . 115.Pp --- 4 unchanged lines hidden (view full) --- 120and 121.Fn au_close_token 122return 0 on success, or a negative value on failure, along with error 123information in 124.Va errno . 125.Sh SEE ALSO 126.Xr audit_submit 3 , 127.Xr libbsm 3 |
| 126.Sh AUTHORS 127This software was created by Robert Watson, Wayne Salamon, and Suresh 128Krishnaswamy for McAfee Research, the security research division of McAfee, 129Inc., under contract to Apple Computer, Inc. 130.Pp 131The Basic Security Module (BSM) interface to audit records and audit event 132stream format were defined by Sun Microsystems. | |
| 133.Sh HISTORY 134The OpenBSM implementation was created by McAfee Research, the security 135division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. 136It was subsequently adopted by the TrustedBSD Project as the foundation for 137the OpenBSM distribution. | 128.Sh HISTORY 129The OpenBSM implementation was created by McAfee Research, the security 130division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. 131It was subsequently adopted by the TrustedBSD Project as the foundation for 132the OpenBSM distribution. |
| 133.Sh AUTHORS 134.An -nosplit 135This software was created by 136.An Robert Watson , 137.An Wayne Salamon , 138and 139.An Suresh Krishnaswamy 140for McAfee Research, the security research division of McAfee, 141Inc., under contract to Apple Computer, Inc. 142.Pp 143The Basic Security Module (BSM) interface to audit records and audit event 144stream format were defined by Sun Microsystems. |
|
| 138.Sh BUGS 139Currently, 140.Fn au_open 141does not reserve kernel resources necessary to commit the record to the 142trail; on systems supporting 143.Fn au_close , 144the call will block until resources are available to commit the record. 145However, this leads to the possibility of an action being permitted without 146the record being guaranteed to go to disk. 147Ideally, 148.Fn au_open 149would reserve resources necessary to commit any submitted record, releasing 150them on 151.Fn au_close . | 145.Sh BUGS 146Currently, 147.Fn au_open 148does not reserve kernel resources necessary to commit the record to the 149trail; on systems supporting 150.Fn au_close , 151the call will block until resources are available to commit the record. 152However, this leads to the possibility of an action being permitted without 153the record being guaranteed to go to disk. 154Ideally, 155.Fn au_open 156would reserve resources necessary to commit any submitted record, releasing 157them on 158.Fn au_close . |