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").field(&format!("0x{self:08X}")).finish()
65 }
66}
67
68impl fmt::LowerHex for audit_token_t {
69 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70 for v in self.val {
71 fmt::LowerHex::fmt(&v, f)?;
72 }
73
74 Ok(())
75 }
76}
77
78impl fmt::UpperHex for audit_token_t {
79 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
80 for v in self.val {
81 fmt::UpperHex::fmt(&v, f)?;
82 }
83
84 Ok(())
85 }
86}
87
88#[repr(C)]
89#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
90pub struct attrlist {
91 /// number of attr. bit sets in list (should be 5)
92 pub bitmapcount: c_ushort,
93 /// (to maintain 4-byte alignment)
94 _reserved: u16,
95 /// common attribute group
96 pub commonattr: attrgroup_t,
97 /// Volume attribute group
98 pub volattr: attrgroup_t,
99 /// directory attribute group
100 pub dirattr: attrgroup_t,
101 /// file attribute group
102 pub fileattr: attrgroup_t,
103 /// fork attribute group
104 pub forkattr: attrgroup_t,
105}
106
107#[link(name = "bsm", kind = "dylib")]
108extern "C" {
109 /// Extract information from an [`audit_token_t`], used to identify Mach tasks and senders
110 /// of Mach messages as subjects to the audit system. `audit_tokent_to_au32()` is the only
111 /// method that should be used to parse an `audit_token_t`, since its internal representation
112 /// may change over time. A pointer parameter may be `NULL` if that information is not needed.
113 /// `audit_token_to_au32()` has been deprecated because the terminal ID information is no
114 /// longer saved in this token. The last parameter is actually the process ID version. The
115 /// API calls [`audit_token_to_auid()`], [`audit_token_to_euid()`], [`audit_token_to_ruid()`],
116 /// [`audit_token_to_rgid()`], [`audit_token_to_pid()`], [`audit_token_to_asid()`], and/or
117 /// [`audit_token_to_pidversion()`] should be used instead.
118 ///
119 /// Note: **this function has been deprecated by Apple in an unknown version**.
120 ///
121 /// - `atoken`: the audit token containing the desired information
122 /// - `auidp`: Pointer to a `uid_t`; on return will be set to the task or sender's audit user ID
123 /// - `euidp`: Pointer to a `uid_t`; on return will be set to the task or sender's effective
124 /// user ID
125 /// - `egidp`: Pointer to a `gid_t`; on return will be set to the task or sender's effective
126 /// group ID
127 /// - `ruidp`: Pointer to a `uid_t`; on return will be set to the task or sender's real user ID
128 /// - `rgidp`: Pointer to a `gid_t`; on return will be set to the task or sender's real group ID
129 /// - `pidp`: Pointer to a `pid_t`; on return will be set to the task or sender's process ID
130 /// - `asidp`: Pointer to an `au_asid_t`; on return will be set to the task or sender's audit
131 /// session ID
132 /// - `tidp`: Pointer to an `au_tid_t`; on return will be set to the process ID version and NOT
133 /// THE SENDER'S TERMINAL ID.
134 ///
135 /// IMPORTANT: In Apple's `bsm-8`, these are marked `__APPLE_API_PRIVATE`.
136 pub fn audit_token_to_au32(
137 atoken: audit_token_t,
138 auidp: *mut uid_t,
139 euidp: *mut uid_t,
140 egidp: *mut gid_t,
141 ruidp: *mut uid_t,
142 rgidp: *mut gid_t,
143 pidp: *mut pid_t,
144 asidp: *mut au_asid_t,
145 tidp: *mut au_tid_t,
146 );
147
148 /// Extract the audit user ID from an `audit_token_t`, used to identify Mach tasks and
149 /// senders of Mach messages as subjects of the audit system.
150 ///
151 /// - `atoken`: The Mach audit token.
152 /// - Returns: The audit user ID extracted from the Mach audit token.
153 pub fn audit_token_to_auid(atoken: audit_token_t) -> uid_t;
154
155 /// Extract the effective user ID from an `audit_token_t`, used to identify Mach tasks and
156 /// senders of Mach messages as subjects of the audit system.
157 ///
158 /// - `atoken`: The Mach audit token.
159 /// - Returns: The effective user ID extracted from the Mach audit token.
160 pub fn audit_token_to_euid(atoken: audit_token_t) -> uid_t;
161
162 /// Extract the effective group ID from an `audit_token_t`, used to identify Mach tasks and
163 /// senders of Mach messages as subjects of the audit system.
164 ///
165 /// - `atoken`: The Mach audit token.
166 /// - Returns: The effective group ID extracted from the Mach audit token.
167 pub fn audit_token_to_egid(atoken: audit_token_t) -> gid_t;
168
169 /// Extract the real user ID from an `audit_token_t`, used to identify Mach tasks and
170 /// senders of Mach messages as subjects of the audit system.
171 ///
172 /// - `atoken`: The Mach audit token.
173 /// - Returns: The real user ID extracted from the Mach audit token.
174 pub fn audit_token_to_ruid(atoken: audit_token_t) -> uid_t;
175
176 /// Extract the real group ID from an `audit_token_t`, used to identify Mach tasks and
177 /// senders of Mach messages as subjects of the audit system.
178 ///
179 /// - `atoken`: The Mach audit token.
180 /// - Returns: The real group ID extracted from the Mach audit token.
181 pub fn audit_token_to_rgid(atoken: audit_token_t) -> gid_t;
182
183 /// Extract the process ID from an `audit_token_t`, used to identify Mach tasks and senders
184 /// of Mach messages as subjects of the audit system.
185 ///
186 /// - `atoken`: The Mach audit token.
187 /// - Returns: The process ID extracted from the Mach audit token.
188 pub fn audit_token_to_pid(atoken: audit_token_t) -> pid_t;
189
190 /// Extract the audit session ID from an `audit_token_t`, used to identify Mach tasks and
191 /// senders of Mach messages as subjects of the audit system.
192 ///
193 /// - `atoken`: The Mach audit token.
194 /// - Returns: The audit session ID extracted from the Mach audit token.
195 pub fn audit_token_to_asid(atoken: audit_token_t) -> au_asid_t;
196
197 /// Extract the process ID version from an `audit_token_t`, used to identify Mach tasks and
198 /// senders of Mach messages as subjects of the audit system.
199 ///
200 /// - `atoken`: The Mach audit token.
201 /// - Returns: The process ID version extracted from the Mach audit token.
202 pub fn audit_token_to_pidversion(atoken: audit_token_t) -> c_int;
203}