libkern/libkern/img4/interface.h

   1 /*
   2  * Copyright (c) 2019 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. So when building the kernel, include img4.h from our
  43  * external headers. Avoid this inclusion if we're building AppleImage4, which
  44  * will have included its own internal version of the header.
  45  */
  46 #if MACH_KERNEL_PRIVATE || !_DARWIN_BUILDING_PROJECT_APPLEIMAGE4
  47 #include <img4/img4.h>
  48 #endif
  49
  50 /*!
  51  * @const IMG4_INTERFACE_VERSION
  52  * The version of the interface supported by the implementation. As new
  53  * functions are added to the interface, this value will be incremented so that
  54  * it can be tested at build-time and not require rev-locked submissions of xnu
  55  * and AppleImage4.
  56  */
  57 #define IMG4_INTERFACE_VERSION (3u)
  58
  59 /*!
  60  * @typedef img4_init_t
  61  * A type describing a pointer to the {@link img4_init} function.
  62  */
  63 typedef errno_t (*const img4_init_t)(
  64         img4_t *i4,
  65         img4_flags_t flags,
  66         const uint8_t *bytes,
  67         size_t len,
  68         img4_destructor_t destructor
  69         );
  70
  71 /*!
  72  * @typedef img4_get_trusted_payload_t
  73  * A type describing a pointer to the {@link img4_get_trusted_payload} function.
  74  */
  75 typedef errno_t (*const img4_get_trusted_payload_t)(
  76         img4_t *i4,
  77         img4_tag_t tag,
  78         const img4_environment_t *env,
  79         const uint8_t **bytes,
  80         size_t *len
  81         );
  82
  83 /*!
  84  * @typedef img4_get_trusted_external_payload_t
  85  * A type describing a pointer to the {@link img4_get_trusted_external_payload}
  86  * function.
  87  */
  88 typedef errno_t (*const img4_get_trusted_external_payload_t)(
  89         img4_t *img4,
  90         img4_payload_t *payload,
  91         const img4_environment_t *env,
  92         const uint8_t **bytes,
  93         size_t *len
  94         );
  95
  96 /*!
  97  * @typedef img4_set_nonce_t
  98  * A type describing a pointer to the {@link img4_set_nonce} function.
  99  */
 100 typedef void (*const img4_set_nonce_t)(img4_t *i4,
 101     const void *bytes,
 102     size_t len
 103     );
 104
 105 /*!
 106  * @typedef img4_destroy_t
 107  * A type describing the {@link img4_destroy} function.
 108  */
 109 typedef void (*const img4_destroy_t)(
 110         img4_t *i4
 111         );
 112
 113 /*!
 114  * @typedef img4_payload_init_t
 115  * A type describing the {@link img4_payload_init} function.
 116  */
 117 typedef errno_t (*const img4_payload_init_t)(
 118         img4_payload_t *i4p,
 119         img4_tag_t tag,
 120         img4_payload_flags_t flags,
 121         const uint8_t *bytes,
 122         size_t len,
 123         img4_destructor_t destructor
 124         );
 125
 126 /*!
 127  * @typedef img4_payload_destroy_t
 128  * A type describing the {@link img4_payload_destroy} function.
 129  */
 130 typedef void (*const img4_payload_destroy_t)(
 131         img4_payload_t *i4
 132         );
 133
 134 /*!
 135  * @typedef img4_payload_destroy_t
 136  * A type describing the {@link img4_set_nonce_domain} function.
 137  */
 138 typedef void (*const img4_set_nonce_domain_t)(
 139         img4_t *i4,
 140         const img4_nonce_domain_t *nd
 141         );
 142
 143 /*!
 144  * @typedef img4_nonce_domain_copy_nonce_t
 145  * A type describing the {@link img4_nonce_domain_copy_nonce} function.
 146  */
 147 typedef errno_t (*const img4_nonce_domain_copy_nonce_t)(
 148         const img4_nonce_domain_t *nd,
 149         img4_nonce_t *n
 150         );
 151
 152 /*!
 153  * @typedef img4_nonce_domain_roll_nonce_t
 154  * A type describing the {@link img4_nonce_domain_roll_nonce} function.
 155  */
 156 typedef errno_t (*const img4_nonce_domain_roll_nonce_t)(
 157         const img4_nonce_domain_t *nd
 158         );
 159
 160 /*!
 161  * @typedef img4_payload_init_with_vnode_4xnu_t
 162  * A type describing the {@link img4_payload_init_with_vnode_4xnu} function.
 163  */
 164 typedef errno_t (*img4_payload_init_with_vnode_4xnu_t)(
 165         img4_payload_t *i4p,
 166         img4_tag_t tag,
 167         vnode_t vn,
 168         img4_payload_flags_t flags
 169         );
 170
 171 /*!
 172  * @typedef img4_interface_t
 173  * A structure describing the interface to the AppleImage4 kext.
 174  *
 175  * @field i4if_version
 176  * The version of the structure supported by the implementation.
 177  *
 178  * @field i4if_init
 179  * A pointer to the {@link img4_init} function.
 180  *
 181  * @field i4if_get_trusted_payload
 182  * A pointer to the {@link img4_get_trusted_payload} function.
 183  *
 184  * @field i4if_get_trusted_external_payload
 185  * A pointer to the {@link img4_get_trusted_external_payload} function.
 186  *
 187  * @field i4if_destroy
 188  * A pointer to the {@link img4_destroy} function.
 189  *
 190  * @field i4if_payload_init
 191  * A pointer to the {@link img4_payload_init} function.
 192  *
 193  * @field i4if_destroy
 194  * A pointer to the {@link img4_payload_destroy} function.
 195  *
 196  * @field i4if_environment_platform
 197  * The {@link IMG4_ENVIRONMENT_PLATFORM} global.
 198  *
 199  * @field i4if_environment_reserved
 200  * Reserved for use by the implementation.
 201  *
 202  * @field i4if_environment_trust_cache
 203  * The {@link IMG4_ENVIRONMENT_TRUST_CACHE} global.
 204  *
 205  * @field i4if_v1
 206  * All fields added in version 1 of the structure.
 207  *
 208  * @field i4if_v1.set_nonce_domain
 209  * A pointer to the @{link img4_set_nonce_domain} function.
 210  *
 211  * @field i4if_v1.nonce_domain_copy_nonce
 212  * A pointer to the {@link img4_nonce_domain_copy_nonce} function.
 213  *
 214  * @field i4if_v1.nonce_domain_roll_nonce
 215  * A pointer to the {@link img4_nonce_domain_roll_nonce} function.
 216  *
 217  * @field i4if_v1.nonce_domain_trust_cache
 218  * The {@link IMG4_NONCE_DOMAIN_TRUST_CACHE} global.
 219  *
 220  * @field i4if_v2
 221  * All fields added in version 2 of the structure.
 222  *
 223  * @field i4if_v2.payload_init_with_vnode_4xnu
 224  * A pointer to the {@link img4_payload_init_with_vnode_4xnu} function.
 225  *
 226  * @field i4if_v3
 227  * All fields added in version 3 of the structure.
 228  *
 229  * @field i4if_v3.nonce_domain_pdi
 230  * The {@link IMG4_NONCE_DOMAIN_PDI} global.
 231  *
 232  * @field i4if_v3.nonce_domain_cryptex
 233  * The {@link IMG4_NONCE_DOMAIN_CRYPTEX} global.
 234  */
 235
 236 typedef struct _img4_interface {
 237         const uint32_t i4if_version;
 238         img4_init_t i4if_init;
 239         img4_set_nonce_t i4if_set_nonce;
 240         img4_get_trusted_payload_t i4if_get_trusted_payload;
 241         img4_get_trusted_external_payload_t i4if_get_trusted_external_payload;
 242         img4_destroy_t i4if_destroy;
 243         img4_payload_init_t i4if_payload_init;
 244         img4_payload_destroy_t i4if_payload_destroy;
 245         const img4_environment_t *i4if_environment_platform;
 246         const img4_environment_t *i4if_environment_reserved;
 247         const img4_environment_t *i4if_environment_trust_cache;
 248         struct {
 249                 img4_set_nonce_domain_t set_nonce_domain;
 250                 img4_nonce_domain_copy_nonce_t nonce_domain_copy_nonce;
 251                 img4_nonce_domain_roll_nonce_t nonce_domain_roll_nonce;
 252                 const img4_nonce_domain_t *nonce_domain_trust_cache;
 253         } i4if_v1;
 254         struct {
 255                 img4_payload_init_with_vnode_4xnu_t payload_init_with_vnode_4xnu;
 256         } i4if_v2;
 257         struct {
 258                 const img4_nonce_domain_t *nonce_domain_pdi;
 259                 const img4_nonce_domain_t *nonce_domain_cryptex;
 260         } i4if_v3;
 261         void *__reserved[15];
 262 } img4_interface_t;
 263
 264 __BEGIN_DECLS
 265
 266 /*!
 267  * @const img4if
 268  * The AppleImage4 interface that was registered.
 269  */
 270 extern const img4_interface_t *img4if;
 271
 272 /*!
 273  * @function img4_interface_register
 274  * Registers the AppleImage4 kext interface for use within the kernel proper.
 275  *
 276  * @param i4
 277  * The interface to register.
 278  *
 279  * @discussion
 280  * This routine may only be called once and must be called before late-const has
 281  * been applied to kernel memory.
 282  */
 283 OS_EXPORT OS_NONNULL1
 284 void
 285 img4_interface_register(const img4_interface_t *i4);
 286
 287 __END_DECLS
 288
 289 #endif // __IMG4_INTERFACE_H