EXTERNAL_HEADERS/img4/payload.h

   1 /*!
   2  * @header
   3  * Image4 payload interfaces. These interfaces provide a lightweight type for
   4  * working with an Image4 payload that is described by a separate manifest (e.g.
   5  * a .im4p file whose contents are described by an object in a manifest from a
   6  * .im4m file).
   7  *
   8  * No direct access is provided to the raw payload bytes encapsulated by the
   9  * Image4 payload by design. The intent is that in order to access the raw
  10  * bytes, the payload object must be validated against a manifest object using
  11  * the {@link img4_get_trusted_external_payload} interface.
  12  */
  13 #ifndef __IMG4_PAYLOAD_H
  14 #define __IMG4_PAYLOAD_H
  15
  16 #ifndef __IMG4_INDIRECT
  17 #error "Please #include <img4/img4.h> instead of this file directly"
  18 #endif // __IMG4_INDIRECT
  19
  20 #if IMG4_TAPI
  21 #include "tapi.h"
  22 #endif
  23
  24 /*!
  25  * @typedef img4_payload_flags_t
  26  * Flags modifying the behavior of an Image4 payload object.
  27  *
  28  * @const I4PLF_INIT
  29  * No flags set. This value is suitable for initialization purposes.
  30  *
  31  * @const I4PLF_UNWRAPPED
  32  * Indicates that the payload bytes are not wrapped in an Image4 payload object
  33  * (.im4p file). If this flag is given, the payload tag is ignored.
  34  *
  35  * This should be used in scenarios such as x86 SecureBoot, which use Image4 to
  36  * describe portable executable files which must be fed directly to the firmware
  37  * and cannot tolerate being wrapped in an intermediary format.
  38  */
  39 OS_CLOSED_OPTIONS(img4_payload_flags, uint64_t,
  40         I4PLF_INIT = 0,
  41         I4PLF_UNWRAPPED = (1 << 0),
  42 );
  43
  44 /*!
  45  * @function img4_payload_init
  46  * Initializes an Image4 payload object.
  47  *
  48  * @param i4p
  49  * A pointer to the payload object to initialize.
  50  *
  51  * @param tag
  52  * The expected tag for the payload.
  53  *
  54  * @param flags
  55  * Flags modifying the behavior of the payload object.
  56  *
  57  * @param bytes
  58  * The buffer containing the Image4 payload.
  59  *
  60  * @param len
  61  * The length of the buffer.
  62  *
  63  * @param destructor
  64  * A pointer to a routine to dispose of the buffer. May be NULL if the buffer
  65  * does not require explicit disposal (e.g. the buffer is stack memory).
  66  *
  67  * @result
  68  * Upon success, zero is returned. Otherwise, one of the following error codes:
  69  *
  70  *     [EILSEQ]     The data is not valid Image4 data
  71  *     [EFTYPE]     The data does not contain an Image4 payload
  72  *     [ENOENT]     The bytes do not contain a payload for the specified tag
  73  */
  74 #if !XNU_KERNEL_PRIVATE
  75 IMG4_API_AVAILABLE_20180112
  76 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL4
  77 errno_t
  78 img4_payload_init(img4_payload_t *i4p, img4_tag_t tag,
  79                 img4_payload_flags_t flags, const uint8_t *bytes, size_t len,
  80                 img4_destructor_t destructor);
  81 #else
  82 #define img4_payload_init(...) img4if->i4if_payload_init(__VA_ARGS__)
  83 #endif
  84
  85 /*!
  86  * @function img4_payload_init_with_vnode_4xnu
  87  * Initializes an Image4 payload object from a vnode.
  88  *
  89  * @param i4p
  90  * A pointer to the payload object to initialize.
  91  *
  92  * @param tag
  93  * The expected tag for the payload.
  94  *
  95  * @param vn
  96  * The vnode from which to initialize the payload.
  97  *
  98  * @param flags
  99  * Flags modifying the behavior of the payload object.
 100  *
 101  * @result
 102  * Upon success, zero is returned. Otherwise, one of the following error codes:
 103  *
 104  *     [ENOENT]     The vnode is either dead or in the process of being
 105  *                  recycled
 106  *     [EIO]        Reading from the vnode stalled repeatedly beyond the
 107  *                  implementation's tolerance
 108  *
 109  * Additionally, the implementation may return any error that vnode_ref() may
 110  * return.
 111  *
 112  * @discussion
 113  * Verification of a vnode is performed by reading in chunks of data, updating
 114  * an ongoing hash operation with that data, and then discarding it. Therefore,
 115  * payload objects created in this manner can only guarantee their validity at
 116  * the time the check was performed since the vnode's contents are not kept in
 117  * memory and may be tampered with after validation has been performed.
 118  *
 119  * Additionally, this operation requires the payload to be unwrapped, as it does
 120  * not parse or recognize any Image4 payload wrapper. Payloads created with this
 121  * interface are therefore implicitly created with the {@link I4PLF_UNWRAPPED}
 122  * flag.
 123  */
 124
 125 #if KERNEL
 126 #if !XNU_KERNEL_PRIVATE
 127 IMG4_API_AVAILABLE_20180112
 128 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
 129 errno_t
 130 img4_payload_init_with_vnode_4xnu(img4_payload_t *i4p, img4_tag_t tag,
 131                 vnode_t vn, img4_payload_flags_t flags);
 132 #else
 133 #define img4_payload_init_with_vnode_4xnu(...) \
 134                 (img4if->i4if_v2.payload_init_with_vnode_4xnu(__VA_ARGS__))
 135 #endif // !XNU_KERNEL_PRIVATE
 136 #endif // KERNEL
 137
 138 /*!
 139  * @function img4_payload_init_with_fd_4MSM
 140  * Initializes an Image4 payload object from a file descriptor.
 141  *
 142  * @param i4p
 143  * A pointer to the payload object to initialize.
 144  *
 145  * @param tag
 146  * The expected tag for the payload.
 147  *
 148  * @param fd
 149  * The file descriptor from which to initialize the payload.
 150  *
 151  * @param flags
 152  * Flags modifying the behavior of the payload object.
 153  *
 154  * @result
 155  * Upon success, zero is returned. Otherwise, the implementation may return any
 156  * errno that is set by the dup(2) system call.
 157  *
 158  * @discussion
 159  * This interface is a userspace equivalent to
 160  * {@link img4_payload_init_with_vnode_4xnu}, and all the same caveats apply.
 161  */
 162
 163 #if !KERNEL
 164 IMG4_API_AVAILABLE_20180112
 165 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 166 errno_t
 167 img4_payload_init_with_fd_4MSM(img4_payload_t *i4p, img4_tag_t tag,
 168                 int fd, img4_payload_flags_t flags);
 169 #endif // KERNEL
 170
 171 /*!
 172  * @function img4_payload_destroy
 173  * Disposes of the resources associated with the payload object.
 174  *
 175  * @param i4p
 176  * The payload object of which to dispose.
 177  *
 178  * @discussion
 179  * This routine does not deallocate the storage for the payload object itself,
 180  * only the associated resources. This routine will cause the destructor given
 181  * in {@link img4_payload_init} to be called, if any.
 182  */
 183 #if !XNU_KERNEL_PRIVATE
 184 IMG4_API_AVAILABLE_20180112
 185 OS_EXPORT OS_NONNULL1
 186 void
 187 img4_payload_destroy(img4_payload_t *i4p);
 188 #else
 189 #define img4_payload_destroy(...) img4if->i4if_payload_destroy(__VA_ARGS__)
 190 #endif
 191
 192 #endif // __IMG4_PAYLOAD_H