EXTERNAL_HEADERS/img4/environment.h

   1 /*!
   2  * @header
   3  * Image4 environments.
   4  */
   5 #ifndef __IMG4_ENVIRONMENT_H
   6 #define __IMG4_ENVIRONMENT_H
   7
   8 #ifndef __IMG4_INDIRECT
   9 #error "Please #include <img4/img4.h> instead of this file directly"
  10 #endif // __IMG4_INDIRECT
  11
  12 #if IMG4_TAPI
  13 #include "tapi.h"
  14 #endif
  15
  16 /*!
  17  * @const IMG4_IDENTITY_VERSION
  18  * The version of the {@link img4_identity_t} supported by the implementation.
  19  */
  20 #define IMG4_IDENTITY_VERSION (0u)
  21
  22 /*!
  23  * @const IMG4_ENVIRONMENT_LENGTH
  24  * The minimum length for an allocation which can accommodate an
  25  * img4_environment_t structure. This is the minimum length which must be given
  26  * to {@link img4_environment_init_identity}.
  27  */
  28 #define IMG4_ENVIRONMENT_LENGTH (160ul)
  29
  30 /*!
  31  * @const IMG4_IDENTITY_CRYPTO_SHA1
  32  * The device-tree string indicating that the identity requires SHA1.
  33  */
  34 #define IMG4_IDENTITY_CRYPTO_SHA1 "sha1"
  35
  36 /*!
  37  * @const IMG4_IDENTITY_CRYPTO_SHA2_384
  38  * The device-tree string indicating that the identity requires SHA2-384.
  39  */
  40 #define IMG4_IDENTITY_CRYPTO_SHA2_384 "sha2-384"
  41
  42 /*!
  43  * @typedef img4_environment_t
  44  * An opaque type describing an Image4 environment.
  45  */
  46 typedef struct _img4_environment img4_environment_t;
  47
  48 /*!
  49  * @typedef img4_identity_t
  50  * A structure describing a specific Image4 identity comprised of user-supplied
  51  * identifiers.
  52  *
  53  * @field i4id_version
  54  * The version of the identity structure; initialize to
  55  * {@link IMG4_IDENTITY_VERSION}
  56  *
  57  * @field i4id_algo
  58  * A string identifying the chosen crypto algorithm as represented in the device
  59  * tree. Currently valid values are:
  60  *
  61  *     - {@link IMG4_IDENTITY_CRYPTO_SHA1}
  62  *     - {@link IMG4_IDENTITY_CRYPTO_SHA2_384}
  63  *
  64  * @field i4id_cepo
  65  * The minimum certificate epoch required,
  66  *
  67  * @field i4id_bord
  68  * The board identifier.
  69  *
  70  * @field i4id_chip
  71  * The chip identifier.
  72  *
  73  * @field i4id_ecid
  74  * The unique chip identifier.
  75  *
  76  * @field i4id_sdom
  77  * The security domain.
  78  *
  79  * @field i4id_cpro
  80  * The certificate production status.
  81  *
  82  * @field i4id_csec
  83  * The certificate security mode.
  84  *
  85  * @field i4id_epro
  86  * The effective production status.
  87  *
  88  * @field i4id_esec
  89  * The effective security mode.
  90  */
  91 IMG4_API_AVAILABLE_20191001
  92 typedef struct _img4_identity {
  93         img4_struct_version_t i4id_version;
  94         char i4id_algo[12];
  95         uint32_t i4id_cepo;
  96         uint32_t i4id_bord;
  97         uint32_t i4id_chip;
  98         uint64_t i4id_ecid;
  99         uint32_t i4id_sdom;
 100         bool i4id_cpro;
 101         bool i4id_csec;
 102         bool i4id_epro;
 103         bool i4id_esec;
 104 } img4_identity_t;
 105
 106 /*!
 107  * @const IMG4_ENVIRONMENT_PLATFORM
 108  * The environment for the host that uses the default platform implementation to
 109  * resolve the environment. This is the environment against which manifests are
 110  * personalized.
 111  */
 112 #if !XNU_KERNEL_PRIVATE
 113 IMG4_API_AVAILABLE_20180112
 114 OS_EXPORT
 115 const struct _img4_environment _img4_environment_platform;
 116 #define IMG4_ENVIRONMENT_PLATFORM (&_img4_environment_platform)
 117 #else
 118 #define IMG4_ENVIRONMENT_PLATFORM (img4if->i4if_environment_platform)
 119 #endif
 120
 121
 122 /*!
 123  * @const IMG4_ENVIRONMENT_TRUST_CACHE
 124  * The software environment for globally-signed loadable trust caches. This
 125  * environment should be used as a fallback when validation against the platform
 126  * fails, and the caller is handling a loadable trust cache.
 127  */
 128 #if !XNU_KERNEL_PRIVATE
 129 IMG4_API_AVAILABLE_20181004
 130 OS_EXPORT
 131 const struct _img4_environment _img4_environment_trust_cache;
 132 #define IMG4_ENVIRONMENT_TRUST_CACHE (&_img4_environment_trust_cache)
 133 #else
 134 #define IMG4_ENVIRONMENT_TRUST_CACHE (img4if->i4if_environment_trust_cache)
 135 #endif
 136
 137 /*!
 138  * @function img4_environment_init_identity
 139  * Initializes a caller-supplied environment with custom identity information.
 140  * This may be used for performing test evaluations or evaluations against
 141  * environments not yet supported by the implementation.
 142  *
 143  * @param i4e
 144  * A pointer to the storage which will hold the custom environment.
 145  *
 146  * @param len
 147  * The length of the storage referenced by {@link i4e}. This must be at least
 148  * {@link IMG4_ENVIRONMENT_LENGTH} bytes.
 149  *
 150  * @param i4id
 151  * The identity with which to initialize the environment. The resulting
 152  * environment object will provide these identitifers to the evaluator.
 153  *
 154  * @result
 155  * Upon success, zero is returned. The implementation may also return one of the
 156  * following error codes directly:
 157  *
 158  *     [EOVERFLOW]    The length provided is insufficient to initialize an
 159  *                    environment structure
 160  *
 161  * @discussion
 162  * When the resulting environment is given to {@link img4_get_trusted_payload}
 163  * or {@link img4_get_trusted_external_payload}, the trust evaluation proceeds
 164  * as though it were creating a new chain of trust and therefore acts as though
 165  * {@link I4F_FIRST_STAGE} was given to {@link img4_init}. No prior stage of
 166  * secure boot will be consulted for evaluation, and mix-n-match will be
 167  * presumed to be permitted.
 168  */
 169 #if !XNU_KERNEL_PRIVATE
 170 IMG4_API_AVAILABLE_20191001
 171 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
 172 errno_t
 173 img4_environment_init_identity(img4_environment_t *i4e, size_t len,
 174                 const img4_identity_t *i4id);
 175 #else
 176 #define img4_environment_init_identity(...) \
 177                 (img4if->i4if_v4.environment_init_identity(__VA_ARGS__))
 178 #endif
 179
 180 #endif // __IMG4_ENVIRONMENT_H