1 /*!
2 * @header
3 * Common types shared across the Image4 trust evaluation API.
4 */
5 #ifndef __IMAGE4_API_TYPES_H
6 #define __IMAGE4_API_TYPES_H
7
8 #include <image4/image4.h>
9 #include <stdint.h>
10 #include <stddef.h>
11
12 __BEGIN_DECLS
13 OS_ASSUME_NONNULL_BEGIN
14 OS_ASSUME_PTR_ABI_SINGLE_BEGIN
15
16 #pragma mark Supporting Types
17 /*!
18 * @typedef image4_struct_version_t
19 * The version of a structure in the API.
20 */
21 typedef uint16_t image4_struct_version_t;
22
23 #pragma mark Supporting Types
24 /*!
25 * @typedef image4_coprocessor_handle_t
26 * A handle which specifies a particular execution environment within a
27 * coprocessor.
28 */
29 typedef uint64_t image4_coprocessor_handle_t;
30
31 /*!
32 * @const IMAGE4_COPROCESSOR_HANDLE_NULL
33 * An coprocessor handle which is invalid for all coprocessors. This constant is
34 * suitable for initialization purposes only.
35 */
36 #define IMAGE4_COPROCESSOR_HANDLE_NULL ((image4_coprocessor_handle_t)0xffff)
37
38 /*!
39 * @typedef image4_secure_boot_t
40 * An enumeration of secure boot levels.
41 *
42 * @const IMAGE4_SECURE_BOOT_FULL
43 * Secure Boot will only accept a live, personalized manifest.
44 *
45 * @const IMAGE4_SECURE_BOOT_REDUCED
46 * Secure Boot will only accept a globally-signed manifest whose lifetime is not
47 * entangled with the individual silicon instance. The manifest's lifetime may
48 * be statically constrained in other ways, but the device cannot unilaterally
49 * host the manifest without a software change.
50 *
51 * @const IMAGE4_SECURE_BOOT_LEAST
52 * Secure Boot will accept any Apple-signed manifest, and the manifest will not
53 * be meaningfully enforced.
54 *
55 * @const IMAGE4_SECURE_BOOT_NONE
56 * Secure Boot does not meaningfully exist.
57 */
58 OS_CLOSED_ENUM(image4_secure_boot, uint64_t,
59 IMAGE4_SECURE_BOOT_FULL,
60 IMAGE4_SECURE_BOOT_REDUCED,
61 IMAGE4_SECURE_BOOT_LEAST,
62 IMAGE4_SECURE_BOOT_NONE,
63 _IMAGE4_SECURE_BOOT_CNT,
64 );
65
66 /*!
67 * @function image4_secure_boot_check
68 * Checks the secure boot level to ensure that it represents a valid, known
69 * secure boot configuration.
70 *
71 * @param sb
72 * The secure boot level.
73 *
74 * @result
75 * If the {@link sb} is a valid secure boot level, zero is returned. Otherwise,
76 * a non-zero value is returned.
77 */
78 OS_ALWAYS_INLINE OS_WARN_RESULT
79 static inline int
image4_secure_boot_check(image4_secure_boot_t sb)80 image4_secure_boot_check(image4_secure_boot_t sb)
81 {
82 if (sb > _IMAGE4_SECURE_BOOT_CNT) {
83 __builtin_trap();
84 }
85 if (sb == _IMAGE4_SECURE_BOOT_CNT) {
86 return 1;
87 }
88 return 0;
89 }
90
91 /*!
92 * @const IMAGE4_NONCE_MAX_LEN
93 * The maximum size of a boot nonce.
94 */
95 #define IMAGE4_NONCE_MAX_LEN (16u)
96
97 /*!
98 * @const IMAGE4_NONCE_DIGEST_STRUCT_VERSION
99 * The version of the {@link image4_nonce_digest_t} structure supported by the
100 * implementation.
101 */
102 #define IMAGE4_NONCE_DIGEST_STRUCT_VERSION (0u)
103
104 /*!
105 * @const IMAGE4_NONCE_DIGEST_MAX_LEN
106 * The maximum size of a nonce digest.
107 */
108 #define IMAGE4_NONCE_DIGEST_MAX_LEN (64u)
109
110 /*!
111 * @typedef image4_nonce_digest_t
112 * A structure representing a nonce digest.
113 *
114 * @field nd_version
115 * The version of the structure. Initialize to
116 * {@link IMAGE4_NONCE_DIGEST_STRUCT_VERSION}.
117 *
118 * @field nd_length
119 * The length of the digest.
120 *
121 * @field nd_bytes
122 * The digest bytes.
123 */
124 typedef struct _image4_nonce_digest {
125 image4_struct_version_t nd_version;
126 size_t nd_length;
127 uint8_t nd_bytes[IMAGE4_NONCE_DIGEST_MAX_LEN];
128 } image4_nonce_digest_t;
129
130 /*!
131 * @const IMAGE4_NONCE_DIGEST_INIT
132 * Initializer for an {@link image4_nonce_digest_t} structure.
133 */
134 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
135 #define IMAGE4_NONCE_DIGEST_INIT (image4_nonce_digest_t){ \
136 .nd_version = IMAGE4_NONCE_DIGEST_STRUCT_VERSION, \
137 .nd_length = 0, \
138 .nd_bytes = { \
139 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, \
140 }, \
141 }
142 #elif defined(__cplusplus) && __cplusplus >= 201103L
143 #define IMAGE4_NONCE_DIGEST_INIT (image4_nonce_digest_t {\
144 IMAGE4_NONCE_DIGEST_STRUCT_VERSION, \
145 0, \
146 { \
147 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, \
148 }, \
149 })
150 #elif defined(__cplusplus)
151 #define IMAGE4_NONCE_DIGEST_INIT (image4_nonce_digest_t(\
152 (image4_nonce_digest_t){ \
153 IMAGE4_NONCE_DIGEST_STRUCT_VERSION, \
154 0, \
155 { \
156 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, \
157 }, \
158 } \
159 ))
160 #else
161 #define IMAGE4_NONCE_DIGEST_INIT { \
162 IMAGE4_NONCE_DIGEST_STRUCT_VERSION, \
163 0, \
164 { \
165 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, \
166 }, \
167 }
168 #endif
169
170 #pragma mark API Objects
171 /*!
172 * @typedef image4_coprocessor_t
173 * An opaque structure representing a coprocessor.
174 */
175 typedef struct _image4_coprocessor image4_coprocessor_t;
176
177 /*!
178 * @typedef image4_environment_t
179 * An opaque structure representing an Image4 trust evaluation environment.
180 */
181 typedef struct _image4_environment image4_environment_t;
182
183 /*!
184 * @typedef image4_identifier_t
185 * An opaque structure representing an Image4 identifier.
186 */
187 typedef struct _image4_identifier image4_identifier_t;
188
189 /*!
190 * @typedef image4_trust_evaluation_t
191 * An opaque structure representing an Image4 trust evaluation.
192 */
193 typedef struct _image4_trust_evaluation image4_trust_evaluation_t;
194
195 /*!
196 * @typedef image4_trust_t
197 * An opaque structure representing an Image4 trust object which performs
198 * evaluations.
199 */
200 typedef struct _image4_trust image4_trust_t;
201
202 OS_ASSUME_PTR_ABI_SINGLE_END
203 OS_ASSUME_NONNULL_END
204 __END_DECLS
205
206 #endif // __IMAGE4_API_TYPES_H
207