libkern/libkern/img4/interface.h

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