endpoint_sec_sys/additional.rs
1//! Types and definitions used in Endpoint Security but not declared in the ES headers
2//!
3//! The types here are not available in the [`libc`] crate either and only one of them is available
4//! in the [`mach2`](https://docs.rs/mach2) crate.
5
6use core::fmt;
7use std::os::raw::c_int;
8pub use std::os::raw::{c_uint, c_ushort};
9
10use libc::{dev_t, gid_t, pid_t, uid_t};
11pub use mach2::vm_types::user_addr_t;
12
13pub type user_size_t = u64;
14
15pub type attrgroup_t = u32;
16
17pub type au_asid_t = pid_t;
18
19/// Pointer to opaque type for Endpoint Security ACL.
20///
21/// The ACL provided cannot be directly used by functions within the `<sys/acl.h>` header. These
22/// functions can mutate the struct passed into them, which is not compatible with the immutable
23/// nature of `es_message_t`. Additionally, because this field is minimally constructed, you
24/// must not use `acl_dup(3)` to get a mutable copy, as this can lead to out of bounds memory
25/// access. To obtain a `acl_t` struct that is able to be used with all functions within `<sys/
26/// acl.h>`, please use a combination of `acl_copy_ext(3)` followed by `acl_copy_int(3)`.
27#[cfg(feature = "macos_10_15_1")]
28pub type acl_t = *mut _acl;
29
30/// Never use directly, use [`acl_t`] instead
31#[repr(C)]
32#[cfg(feature = "macos_10_15_1")]
33pub struct _acl {
34 _unused: [u8; 0],
35}
36
37#[repr(C)]
38#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
39pub struct au_tid_t {
40 pub port: dev_t,
41 pub machine: u32,
42}
43
44/// The audit token is an opaque token which identifies Mach tasks and senders of Mach messages
45/// as subjects to the BSM audit system. Only the appropriate BSM library routines should
46/// be used to interpret the contents of the audit token as the representation of the subject
47/// identity within the token may change over time.
48///
49/// Starting with macOS 11, almost all audit functions have been deprecated (see the system
50/// header `bsm/libbsm.h`), do not use them if your program target more recent versions of
51/// macOS.
52#[repr(C)]
53#[derive(Default, Copy, Clone, PartialEq, Eq, Hash)]
54pub struct audit_token_t {
55 /// Value of the token
56 ///
57 /// This is considered an opaque value, do not rely on its format
58 pub val: [c_uint; 8],
59}
60
61// Make the debug representation an hex string to make it shorter and clearer when debugging
62impl fmt::Debug for audit_token_t {
63 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
64 f.debug_tuple("audit_token_t")
65 .field(&format!("0x{:08X}", self))
66 .finish()
67 }
68}
69
70impl fmt::LowerHex for audit_token_t {
71 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
72 for v in self.val {
73 fmt::LowerHex::fmt(&v, f)?;
74 }
75
76 Ok(())
77 }
78}
79
80impl fmt::UpperHex for audit_token_t {
81 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
82 for v in self.val {
83 fmt::UpperHex::fmt(&v, f)?;
84 }
85
86 Ok(())
87 }
88}
89
90#[repr(C)]
91#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
92pub struct attrlist {
93 /// number of attr. bit sets in list (should be 5)
94 pub bitmapcount: c_ushort,
95 /// (to maintain 4-byte alignment)
96 _reserved: u16,
97 /// common attribute group
98 pub commonattr: attrgroup_t,
99 /// Volume attribute group
100 pub volattr: attrgroup_t,
101 /// directory attribute group
102 pub dirattr: attrgroup_t,
103 /// file attribute group
104 pub fileattr: attrgroup_t,
105 /// fork attribute group
106 pub forkattr: attrgroup_t,
107}
108
109#[link(name = "bsm", kind = "dylib")]
110extern "C" {
111 /// Extract information from an [`audit_token_t`], used to identify Mach tasks and senders
112 /// of Mach messages as subjects to the audit system. `audit_tokent_to_au32()` is the only
113 /// method that should be used to parse an `audit_token_t`, since its internal representation
114 /// may change over time. A pointer parameter may be `NULL` if that information is not needed.
115 /// `audit_token_to_au32()` has been deprecated because the terminal ID information is no
116 /// longer saved in this token. The last parameter is actually the process ID version. The
117 /// API calls [`audit_token_to_auid()`], [`audit_token_to_euid()`], [`audit_token_to_ruid()`],
118 /// [`audit_token_to_rgid()`], [`audit_token_to_pid()`], [`audit_token_to_asid()`], and/or
119 /// [`audit_token_to_pidversion()`] should be used instead.
120 ///
121 /// Note: **this function has been deprecated by Apple in an unknown version**.
122 ///
123 /// - `atoken`: the audit token containing the desired information
124 /// - `auidp`: Pointer to a `uid_t`; on return will be set to the task or sender's audit user ID
125 /// - `euidp`: Pointer to a `uid_t`; on return will be set to the task or sender's effective
126 /// user ID
127 /// - `egidp`: Pointer to a `gid_t`; on return will be set to the task or sender's effective
128 /// group ID
129 /// - `ruidp`: Pointer to a `uid_t`; on return will be set to the task or sender's real user ID
130 /// - `rgidp`: Pointer to a `gid_t`; on return will be set to the task or sender's real group ID
131 /// - `pidp`: Pointer to a `pid_t`; on return will be set to the task or sender's process ID
132 /// - `asidp`: Pointer to an `au_asid_t`; on return will be set to the task or sender's audit
133 /// session ID
134 /// - `tidp`: Pointer to an `au_tid_t`; on return will be set to the process ID version and NOT
135 /// THE SENDER'S TERMINAL ID.
136 ///
137 /// IMPORTANT: In Apple's `bsm-8`, these are marked `__APPLE_API_PRIVATE`.
138 pub fn audit_token_to_au32(
139 atoken: audit_token_t,
140 auidp: *mut uid_t,
141 euidp: *mut uid_t,
142 egidp: *mut gid_t,
143 ruidp: *mut uid_t,
144 rgidp: *mut gid_t,
145 pidp: *mut pid_t,
146 asidp: *mut au_asid_t,
147 tidp: *mut au_tid_t,
148 );
149
150 /// Extract the audit user ID from an `audit_token_t`, used to identify Mach tasks and
151 /// senders of Mach messages as subjects of the audit system.
152 ///
153 /// - `atoken`: The Mach audit token.
154 /// - Returns: The audit user ID extracted from the Mach audit token.
155 pub fn audit_token_to_auid(atoken: audit_token_t) -> uid_t;
156
157 /// Extract the effective user ID from an `audit_token_t`, used to identify Mach tasks and
158 /// senders of Mach messages as subjects of the audit system.
159 ///
160 /// - `atoken`: The Mach audit token.
161 /// - Returns: The effective user ID extracted from the Mach audit token.
162 pub fn audit_token_to_euid(atoken: audit_token_t) -> uid_t;
163
164 /// Extract the effective group ID from an `audit_token_t`, used to identify Mach tasks and
165 /// senders of Mach messages as subjects of the audit system.
166 ///
167 /// - `atoken`: The Mach audit token.
168 /// - Returns: The effective group ID extracted from the Mach audit token.
169 pub fn audit_token_to_egid(atoken: audit_token_t) -> gid_t;
170
171 /// Extract the real user ID from an `audit_token_t`, used to identify Mach tasks and
172 /// senders of Mach messages as subjects of the audit system.
173 ///
174 /// - `atoken`: The Mach audit token.
175 /// - Returns: The real user ID extracted from the Mach audit token.
176 pub fn audit_token_to_ruid(atoken: audit_token_t) -> uid_t;
177
178 /// Extract the real group ID from an `audit_token_t`, used to identify Mach tasks and
179 /// senders of Mach messages as subjects of the audit system.
180 ///
181 /// - `atoken`: The Mach audit token.
182 /// - Returns: The real group ID extracted from the Mach audit token.
183 pub fn audit_token_to_rgid(atoken: audit_token_t) -> gid_t;
184
185 /// Extract the process ID from an `audit_token_t`, used to identify Mach tasks and senders
186 /// of Mach messages as subjects of the audit system.
187 ///
188 /// - `atoken`: The Mach audit token.
189 /// - Returns: The process ID extracted from the Mach audit token.
190 pub fn audit_token_to_pid(atoken: audit_token_t) -> pid_t;
191
192 /// Extract the audit session ID from an `audit_token_t`, used to identify Mach tasks and
193 /// senders of Mach messages as subjects of the audit system.
194 ///
195 /// - `atoken`: The Mach audit token.
196 /// - Returns: The audit session ID extracted from the Mach audit token.
197 pub fn audit_token_to_asid(atoken: audit_token_t) -> au_asid_t;
198
199 /// Extract the process ID version from an `audit_token_t`, used to identify Mach tasks and
200 /// senders of Mach messages as subjects of the audit system.
201 ///
202 /// - `atoken`: The Mach audit token.
203 /// - Returns: The process ID version extracted from the Mach audit token.
204 pub fn audit_token_to_pidversion(atoken: audit_token_t) -> c_int;
205}