xref: /freebsd/sys/security/audit/audit_private.h (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
1 /*-
2  * Copyright (c) 1999-2009 Apple Inc.
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  * 3.  Neither the name of Apple Inc. ("Apple") nor the names of
14  *     its contributors may be used to endorse or promote products derived
15  *     from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR
21  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
25  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
26  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27  * POSSIBILITY OF SUCH DAMAGE.
28  *
29  * $FreeBSD$
30  */
31 
32 /*
33  * This include file contains function prototypes and type definitions used
34  * within the audit implementation.
35  */
36 
37 #ifndef _SECURITY_AUDIT_PRIVATE_H_
38 #define	_SECURITY_AUDIT_PRIVATE_H_
39 
40 #ifndef _KERNEL
41 #error "no user-serviceable parts inside"
42 #endif
43 
44 #include <sys/ipc.h>
45 #include <sys/socket.h>
46 #include <sys/ucred.h>
47 
48 #ifdef MALLOC_DECLARE
49 MALLOC_DECLARE(M_AUDITBSM);
50 MALLOC_DECLARE(M_AUDITDATA);
51 MALLOC_DECLARE(M_AUDITPATH);
52 MALLOC_DECLARE(M_AUDITTEXT);
53 #endif
54 
55 /*
56  * Audit control variables that are usually set/read via system calls and
57  * used to control various aspects of auditing.
58  */
59 extern struct au_qctrl		audit_qctrl;
60 extern struct audit_fstat	audit_fstat;
61 extern struct au_mask		audit_nae_mask;
62 extern int			audit_panic_on_write_fail;
63 extern int			audit_fail_stop;
64 extern int			audit_argv;
65 extern int			audit_arge;
66 
67 /*
68  * Success/failure conditions for the conversion of a kernel audit record to
69  * BSM format.
70  */
71 #define	BSM_SUCCESS	0
72 #define	BSM_FAILURE	1
73 #define	BSM_NOAUDIT	2
74 
75 /*
76  * Defines for the kernel audit record k_ar_commit field.  Flags are set to
77  * indicate what sort of record it is, and which preselection mechanism
78  * selected it.
79  */
80 #define	AR_COMMIT_KERNEL	0x00000001U
81 #define	AR_COMMIT_USER		0x00000010U
82 
83 #define	AR_PRESELECT_TRAIL	0x00001000U
84 #define	AR_PRESELECT_PIPE	0x00002000U
85 
86 #define	AR_PRESELECT_USER_TRAIL	0x00004000U
87 #define	AR_PRESELECT_USER_PIPE	0x00008000U
88 
89 /*
90  * Audit data is generated as a stream of struct audit_record structures,
91  * linked by struct kaudit_record, and contain storage for possible audit so
92  * that it will not need to be allocated during the processing of a system
93  * call, both improving efficiency and avoiding sleeping at untimely moments.
94  * This structure is converted to BSM format before being written to disk.
95  */
96 struct vnode_au_info {
97 	mode_t	vn_mode;
98 	uid_t	vn_uid;
99 	gid_t	vn_gid;
100 	dev_t	vn_dev;
101 	long	vn_fsid;
102 	long	vn_fileid;
103 	long	vn_gen;
104 };
105 
106 struct groupset {
107 	gid_t	gidset[NGROUPS];
108 	u_int	gidset_size;
109 };
110 
111 struct socket_au_info {
112 	int		so_domain;
113 	int		so_type;
114 	int		so_protocol;
115 	in_addr_t	so_raddr;	/* Remote address if INET socket. */
116 	in_addr_t	so_laddr;	/* Local address if INET socket. */
117 	u_short		so_rport;	/* Remote port. */
118 	u_short		so_lport;	/* Local port. */
119 };
120 
121 union auditon_udata {
122 	char			*au_path;
123 	long			au_cond;
124 	long			au_flags;
125 	long			au_policy;
126 	int			au_trigger;
127 	au_evclass_map_t	au_evclass;
128 	au_mask_t		au_mask;
129 	auditinfo_t		au_auinfo;
130 	auditpinfo_t		au_aupinfo;
131 	auditpinfo_addr_t	au_aupinfo_addr;
132 	au_qctrl_t		au_qctrl;
133 	au_stat_t		au_stat;
134 	au_fstat_t		au_fstat;
135 	auditinfo_addr_t	au_kau_info;
136 };
137 
138 struct posix_ipc_perm {
139 	uid_t	pipc_uid;
140 	gid_t	pipc_gid;
141 	mode_t	pipc_mode;
142 };
143 
144 struct audit_record {
145 	/* Audit record header. */
146 	u_int32_t		ar_magic;
147 	int			ar_event;
148 	int			ar_retval; /* value returned to the process */
149 	int			ar_errno;  /* return status of system call */
150 	struct timespec		ar_starttime;
151 	struct timespec		ar_endtime;
152 	u_int64_t		ar_valid_arg;  /* Bitmask of valid arguments */
153 
154 	/* Audit subject information. */
155 	struct xucred		ar_subj_cred;
156 	uid_t			ar_subj_ruid;
157 	gid_t			ar_subj_rgid;
158 	gid_t			ar_subj_egid;
159 	uid_t			ar_subj_auid; /* Audit user ID */
160 	pid_t			ar_subj_asid; /* Audit session ID */
161 	pid_t			ar_subj_pid;
162 	struct au_tid		ar_subj_term;
163 	struct au_tid_addr	ar_subj_term_addr;
164 	struct au_mask		ar_subj_amask;
165 
166 	/* Operation arguments. */
167 	uid_t			ar_arg_euid;
168 	uid_t			ar_arg_ruid;
169 	uid_t			ar_arg_suid;
170 	gid_t			ar_arg_egid;
171 	gid_t			ar_arg_rgid;
172 	gid_t			ar_arg_sgid;
173 	pid_t			ar_arg_pid;
174 	pid_t			ar_arg_asid;
175 	struct au_tid		ar_arg_termid;
176 	struct au_tid_addr	ar_arg_termid_addr;
177 	uid_t			ar_arg_uid;
178 	uid_t			ar_arg_auid;
179 	gid_t			ar_arg_gid;
180 	struct groupset		ar_arg_groups;
181 	int			ar_arg_fd;
182 	int			ar_arg_fflags;
183 	mode_t			ar_arg_mode;
184 	int			ar_arg_dev;
185 	long			ar_arg_value;
186 	void *			ar_arg_addr;
187 	int			ar_arg_len;
188 	int			ar_arg_mask;
189 	u_int			ar_arg_signum;
190 	char			ar_arg_login[MAXLOGNAME];
191 	int			ar_arg_ctlname[CTL_MAXNAME];
192 	struct socket_au_info	ar_arg_sockinfo;
193 	char			*ar_arg_upath1;
194 	char			*ar_arg_upath2;
195 	char			*ar_arg_text;
196 	struct au_mask		ar_arg_amask;
197 	struct vnode_au_info	ar_arg_vnode1;
198 	struct vnode_au_info	ar_arg_vnode2;
199 	int			ar_arg_cmd;
200 	int			ar_arg_svipc_cmd;
201 	struct ipc_perm		ar_arg_svipc_perm;
202 	int			ar_arg_svipc_id;
203 	void *			ar_arg_svipc_addr;
204 	struct posix_ipc_perm	ar_arg_pipc_perm;
205 	union auditon_udata	ar_arg_auditon;
206 	char			*ar_arg_argv;
207 	int			ar_arg_argc;
208 	char			*ar_arg_envv;
209 	int			ar_arg_envc;
210 	int			ar_arg_exitstatus;
211 	int			ar_arg_exitretval;
212 	struct sockaddr_storage ar_arg_sockaddr;
213 };
214 
215 /*
216  * Arguments in the audit record are initially not defined; flags are set to
217  * indicate if they are present so they can be included in the audit log
218  * stream only if defined.
219  */
220 #define	ARG_IS_VALID(kar, arg)	((kar)->k_ar.ar_valid_arg & (arg))
221 #define	ARG_SET_VALID(kar, arg) do {					\
222 	(kar)->k_ar.ar_valid_arg |= (arg);				\
223 } while (0)
224 
225 /*
226  * In-kernel version of audit record; the basic record plus queue meta-data.
227  * This record can also have a pointer set to some opaque data that will be
228  * passed through to the audit writing mechanism.
229  */
230 struct kaudit_record {
231 	struct audit_record		 k_ar;
232 	u_int32_t			 k_ar_commit;
233 	void				*k_udata;	/* User data. */
234 	u_int				 k_ulen;	/* User data length. */
235 	struct uthread			*k_uthread;	/* Audited thread. */
236 	TAILQ_ENTRY(kaudit_record)	 k_q;
237 };
238 TAILQ_HEAD(kaudit_queue, kaudit_record);
239 
240 /*
241  * Functions to manage the allocation, release, and commit of kernel audit
242  * records.
243  */
244 void			 audit_abort(struct kaudit_record *ar);
245 void			 audit_commit(struct kaudit_record *ar, int error,
246 			    int retval);
247 struct kaudit_record	*audit_new(int event, struct thread *td);
248 
249 /*
250  * Functions relating to the conversion of internal kernel audit records to
251  * the BSM file format.
252  */
253 struct au_record;
254 int	 kaudit_to_bsm(struct kaudit_record *kar, struct au_record **pau);
255 int	 bsm_rec_verify(void *rec);
256 
257 /*
258  * Kernel versions of the libbsm audit record functions.
259  */
260 void	 kau_free(struct au_record *rec);
261 void	 kau_init(void);
262 
263 /*
264  * Return values for pre-selection and post-selection decisions.
265  */
266 #define	AU_PRS_SUCCESS	1
267 #define	AU_PRS_FAILURE	2
268 #define	AU_PRS_BOTH	(AU_PRS_SUCCESS|AU_PRS_FAILURE)
269 
270 /*
271  * Data structures relating to the kernel audit queue.  Ideally, these might
272  * be abstracted so that only accessor methods are exposed.
273  */
274 extern struct mtx		audit_mtx;
275 extern struct cv		audit_watermark_cv;
276 extern struct cv		audit_worker_cv;
277 extern struct kaudit_queue	audit_q;
278 extern size_t			audit_q_len;
279 extern size_t			audit_pre_q_len;
280 extern int			audit_in_failure;
281 
282 /*
283  * Flags to use on audit files when opening and closing.
284  */
285 #define	AUDIT_OPEN_FLAGS	(FWRITE | O_APPEND)
286 #define	AUDIT_CLOSE_FLAGS	(FWRITE | O_APPEND)
287 
288 #include <sys/fcntl.h>
289 #include <sys/kernel.h>
290 #include <sys/malloc.h>
291 
292 /*
293  * Some of the BSM tokenizer functions take different parameters in the
294  * kernel implementations in order to save the copying of large kernel data
295  * structures.  The prototypes of these functions are declared here.
296  */
297 token_t		*kau_to_socket(struct socket_au_info *soi);
298 
299 /*
300  * audit_klib prototypes
301  */
302 int		 au_preselect(au_event_t event, au_class_t class,
303 		    au_mask_t *mask_p, int sorf);
304 void		 au_evclassmap_init(void);
305 void		 au_evclassmap_insert(au_event_t event, au_class_t class);
306 au_class_t	 au_event_class(au_event_t event);
307 au_event_t	 audit_ctlname_to_sysctlevent(int name[], uint64_t valid_arg);
308 au_event_t	 audit_flags_and_error_to_openevent(int oflags, int error);
309 au_event_t	 audit_msgctl_to_event(int cmd);
310 au_event_t	 audit_semctl_to_event(int cmr);
311 void		 audit_canon_path(struct thread *td, char *path, char *cpath);
312 au_event_t	 auditon_command_event(int cmd);
313 
314 /*
315  * Audit trigger events notify user space of kernel audit conditions
316  * asynchronously.
317  */
318 void		 audit_trigger_init(void);
319 int		 audit_send_trigger(unsigned int trigger);
320 
321 /*
322  * Accessor functions to manage global audit state.
323  */
324 void	 audit_set_kinfo(struct auditinfo_addr *);
325 void	 audit_get_kinfo(struct auditinfo_addr *);
326 
327 /*
328  * General audit related functions.
329  */
330 struct kaudit_record	*currecord(void);
331 void			 audit_free(struct kaudit_record *ar);
332 void			 audit_shutdown(void *arg, int howto);
333 void			 audit_rotate_vnode(struct ucred *cred,
334 			    struct vnode *vp);
335 void			 audit_worker_init(void);
336 
337 /*
338  * Audit pipe functions.
339  */
340 int	 audit_pipe_preselect(au_id_t auid, au_event_t event,
341 	    au_class_t class, int sorf, int trail_select);
342 void	 audit_pipe_submit(au_id_t auid, au_event_t event, au_class_t class,
343 	    int sorf, int trail_select, void *record, u_int record_len);
344 void	 audit_pipe_submit_user(void *record, u_int record_len);
345 
346 #endif /* ! _SECURITY_AUDIT_PRIVATE_H_ */
347