1/*
2 * Copyright (c) 2018 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/*!
30 * @header
31 * Interfaces to register the AppleImage4 interface with xnu-proper to avoid a
32 * build-time layering inversion.
33 */
34#ifndef __IMG4_INTERFACE_H
35#define __IMG4_INTERFACE_H
36
37#include <os/base.h>
38#include <sys/cdefs.h>
39
40/*
41 * We rely on img4.h's logic for either including sys/types.h or declaring
42 * errno_t ourselves.
43 */
44#include <img4/img4.h>
45
46/*!
47 * @const IMG4_INTERFACE_VERSION
48 * The version of the interface supported by the implementation. As new
49 * functions are added to the interface, this value will be incremented so that
50 * it can be tested at build-time and not require rev-locked submissions of xnu
51 * and AppleImage4.
52 */
53#define IMG4_INTERFACE_VERSION (1u)
54
55/*!
56 * @typedef img4_init_t
57 * A type describing the img4_init() function.
58 */
59typedef errno_t (*img4_init_t)(
60 img4_t *i4,
61 img4_flags_t flags,
62 const uint8_t *bytes,
63 size_t len,
64 img4_destructor_t destructor
65);
66
67/*!
68 * @typedef img4_init_t
69 * A type describing the img4_set_custom_tag_handler() function.
70 */
71typedef void (*img4_set_custom_tag_handler_t)(
72 img4_t *i4,
73 const img4_custom_tag_t *tags,
74 size_t tags_cnt
75);
76
77/*!
78 * @typedef img4_init_t
79 * A type describing the img4_get_trusted_payload() function.
80 */
81typedef errno_t (*img4_get_trusted_payload_t)(
82 img4_t *i4,
83 img4_tag_t tag,
84 const img4_environment_t *env,
85 void *ctx,
86 const uint8_t **bytes,
87 size_t *len
88);
89
90/*!
91 * @typedef img4_init_t
92 * A type describing the img4_get_trusted_external_payload() function.
93 */
94typedef errno_t (*img4_get_trusted_external_payload_t)(
95 img4_t *img4,
96 img4_payload_t *payload,
97 const img4_environment_t *env,
98 void *ctx,
99 const uint8_t **bytes,
100 size_t *len
101);
102
103/*!
104 * @typedef img4_init_t
105 * A type describing the img4_get_entitlement_bool() function.
106 */
107typedef bool (*img4_get_entitlement_bool_t)(
108 img4_t *i4,
109 img4_tag_t entitlement
110);
111
112/*!
113 * @typedef img4_init_t
114 * A type describing the img4_get_object_entitlement_bool() function.
115 */
116typedef bool (*img4_get_object_entitlement_bool_t)(
117 img4_t *i4,
118 img4_tag_t object,
119 img4_tag_t entitlement
120);
121
122/*!
123 * @typedef img4_init_t
124 * A type describing the img4_destroy() function.
125 */
126typedef void (*img4_destroy_t)(
127 img4_t *i4
128);
129
130/*!
131 * @typedef img4_interface_t
132 * A structure describing the interface to the AppleImage4 kext.
133 *
134 * @property i4if_version
135 * The version of the structure supported by the implementation.
136 *
137 * @property i4if_init
138 * A pointer to the img4_init function.
139 *
140 * @property i4if_set_custom_tag_handler
141 * A pointer to the img4_set_custom_tag_handler function.
142 *
143 * @property i4if_get_trusted_payload
144 * A pointer to the img4_get_trusted_payload function.
145 *
146 * @property i4if_get_trusted_external_payload
147 * A pointer to the img4_get_trusted_external_payload function.
148 *
149 * @property i4if_get_entitlement_bool
150 * A pointer to the img4_get_entitlement_bool function.
151 *
152 * @property i4if_get_object_entitlement_bool
153 * A pointer to the img4_get_object_entitlement_bool function.
154 *
155 * @property i4if_destroy
156 * A pointer to the img4_destroy function.
157 *
158 * @property i4if_v1
159 * All members added in version 1 of the structure.
160 *
161 * @property environment_platform
162 * The IMG4_ENVIRONMENT_PLATFORM global.
163 */
164typedef struct _img4_interface {
165 const uint32_t i4if_version;
166 const img4_init_t i4if_init;
167 const img4_set_custom_tag_handler_t i4if_set_custom_tag_handler;
168 const img4_get_trusted_payload_t i4if_get_trusted_payload;
169 const img4_get_trusted_external_payload_t i4if_get_trusted_external_payload;
170 const img4_get_entitlement_bool_t i4if_get_entitlement_bool;
171 const img4_get_object_entitlement_bool_t i4if_get_object_entitlement_bool;
172 const img4_destroy_t i4if_destroy;
173 struct {
174 const img4_environment_t *environment_platform;
175 } i4if_v1;
176 void *__reserved[23];
177} img4_interface_t;
178
179__BEGIN_DECLS;
180
181/*!
182 * @const img4if
183 * The AppleImage4 interface that was registered.
184 */
185extern const img4_interface_t *img4if;
186
187/*!
188 * @function img4_interface_register
189 * Registers the AppleImage4 kext interface with xnu.
190 *
191 * @param i4
192 * The interface to register.
193 *
194 * @discussion
195 * This routine may only be called once and must be called before late-const has
196 * been applied to kernel memory.
197 */
198OS_EXPORT OS_NONNULL1
199void
200img4_interface_register(const img4_interface_t *i4);
201
202__END_DECLS;
203
204#endif // __IMG4_INTERFACE_H
205