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