1 /*
2 * Copyright © 2017-2024 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28 /*!
29 * @header
30 * Common types shared across the Image4 trust evaluation API.
31 */
32 #ifndef __IMAGE4_API_TYPES_H
33 #define __IMAGE4_API_TYPES_H
34
35 #include <image4/image4.h>
36 #include <stdint.h>
37 #include <stddef.h>
38
39 __BEGIN_DECLS
40 OS_ASSUME_NONNULL_BEGIN
41 OS_ASSUME_PTR_ABI_SINGLE_BEGIN
42
43 #pragma mark Definitions
44 /*!
45 * @const IMAGE4_DIGEST_MAX_LEN
46 * The maximum size of a digest.
47 */
48 #define IMAGE4_DIGEST_MAX_LEN (64u)
49
50 /*!
51 * @const IMAGE4_NONCE_MAX_LEN
52 * The maximum size of a nonce.
53 */
54 #define IMAGE4_NONCE_MAX_LEN (16u)
55
56 #pragma mark Supporting Types
57 /*!
58 * @typedef image4_struct_version_t
59 * The version of a structure in the API.
60 */
61 typedef uint16_t image4_struct_version_t;
62
63 /*!
64 * @typedef image4_coprocessor_handle_t
65 * A handle which specifies a particular execution environment within a
66 * coprocessor.
67 */
68 typedef uint64_t image4_coprocessor_handle_t;
69
70 /*!
71 * @const IMAGE4_COPROCESSOR_HANDLE_NULL
72 * An coprocessor handle which is invalid for all coprocessors. This constant is
73 * suitable for initialization purposes only.
74 */
75 #define IMAGE4_COPROCESSOR_HANDLE_NULL ((image4_coprocessor_handle_t)0xffff)
76
77 /*!
78 * @typedef image4_secure_boot_t
79 * An enumeration of secure boot levels.
80 *
81 * @const IMAGE4_SECURE_BOOT_FULL
82 * Secure Boot will only accept a live, personalized manifest.
83 *
84 * @const IMAGE4_SECURE_BOOT_REDUCED
85 * Secure Boot will only accept a globally-signed manifest whose lifetime is not
86 * entangled with the individual silicon instance. The manifest's lifetime may
87 * be statically constrained in other ways, but the device cannot unilaterally
88 * host the manifest without a software change.
89 *
90 * @const IMAGE4_SECURE_BOOT_LEAST
91 * Secure Boot will accept any Apple-signed manifest, and the manifest will not
92 * be meaningfully enforced.
93 *
94 * @const IMAGE4_SECURE_BOOT_NONE
95 * Secure Boot does not meaningfully exist.
96 */
97 OS_CLOSED_ENUM(image4_secure_boot, uint64_t,
98 IMAGE4_SECURE_BOOT_FULL,
99 IMAGE4_SECURE_BOOT_REDUCED,
100 IMAGE4_SECURE_BOOT_LEAST,
101 IMAGE4_SECURE_BOOT_NONE,
102 _IMAGE4_SECURE_BOOT_CNT,
103 );
104
105 /*!
106 * @function image4_secure_boot_check
107 * Checks the secure boot level to ensure that it represents a valid, known
108 * secure boot configuration.
109 *
110 * @param sb
111 * The secure boot level.
112 *
113 * @result
114 * If the {@link sb} is a valid secure boot level, zero is returned. Otherwise,
115 * a non-zero value is returned.
116 */
117 OS_ALWAYS_INLINE OS_WARN_RESULT
118 static inline int
image4_secure_boot_check(image4_secure_boot_t sb)119 image4_secure_boot_check(image4_secure_boot_t sb)
120 {
121 if (sb > _IMAGE4_SECURE_BOOT_CNT) {
122 __builtin_trap();
123 }
124 if (sb == _IMAGE4_SECURE_BOOT_CNT) {
125 return 1;
126 }
127 return 0;
128 }
129
130 #pragma mark API Objects
131 /*!
132 * @typedef image4_coprocessor_t
133 * An opaque structure representing a coprocessor.
134 */
135 typedef struct _image4_coprocessor image4_coprocessor_t;
136
137 /*!
138 * @typedef image4_environment_t
139 * An opaque structure representing an Image4 trust evaluation environment.
140 */
141 typedef struct _image4_environment image4_environment_t;
142
143 /*!
144 * @typedef image4_identifier_t
145 * An opaque structure representing an Image4 identifier.
146 */
147 typedef struct _image4_identifier image4_identifier_t;
148
149 /*!
150 * @typedef image4_trust_evaluation_t
151 * An opaque structure representing an Image4 trust evaluation.
152 */
153 typedef struct _image4_trust_evaluation image4_trust_evaluation_t;
154
155 /*!
156 * @typedef image4_trust_t
157 * An opaque structure representing an Image4 trust object which performs
158 * evaluations.
159 */
160 typedef struct _image4_trust image4_trust_t;
161
162 OS_ASSUME_PTR_ABI_SINGLE_END
163 OS_ASSUME_NONNULL_END
164 __END_DECLS
165
166 #endif // __IMAGE4_API_TYPES_H
167