1#ifndef libTrustCache_API_h
2#define libTrustCache_API_h
3
4#include <sys/cdefs.h>
5__BEGIN_DECLS
6
7#include <stdint.h>
8#include <stdbool.h>
9#include <img4/firmware.h>
10#include <TrustCache/RawTypes.h>
11#include <TrustCache/Types.h>
12#include <TrustCache/TypesConfig.h>
13#include <TrustCache/Return.h>
14
15/**
16 * NOTE: This library does not enforce any concurrency by itself. To be safe in a multi-threaded
17 * environment, the caller must manually enforce concurrency on the runtime data structure as
18 * otherwise the library is susceptible to memory corruption from race conditions.
19 */
20
21/**
22 * Initialize a runtime to the default values.
23 *
24 * If the system supports read-only segments, and the runtime is allocated within the read-only
25 * segment, then this function needs to be called before the segment is enforced to be read-only.
26 * For more information, please look at <TrustCache/Types.h>.
27 */
28static inline void
29trustCacheInitializeRuntime(TrustCacheRuntime_t *runtime,
30 TrustCacheMutableRuntime_t *mutableRT,
31 bool allowSecondStaticTC,
32 bool allowEngineeringTC,
33 bool allowLegacyTC,
34 const img4_runtime_t *image4RT)
35{
36 /* Zero out everything */
37 memset(s: runtime, c: 0, n: sizeof(*runtime));
38 memset(s: mutableRT, c: 0, n: sizeof(*mutableRT));
39
40 /* Set the mutable runtime pointer */
41 runtime->mutableRT = mutableRT;
42
43 /* Setup trust cache type permissions */
44 runtime->allowSecondStaticTC = allowSecondStaticTC;
45 runtime->allowEngineeringTC = allowEngineeringTC;
46 runtime->allowLegacyTC = allowLegacyTC;
47
48 /* Set the image4 runtime */
49 runtime->image4RT = image4RT;
50}
51
52/**
53 * Construct a trust cache object from some module bytes. The module is validated for
54 * correctness before being returned.
55 */
56TCReturn_t
57trustCacheConstructInvalid(TrustCache_t *trustCache,
58 const uint8_t *moduleAddr,
59 size_t moduleSize);
60
61/**
62 * Check the runtime for a trust cache which matches a particular UUID. Since we do
63 * not allow trust caches with duplocate UUIDs, there can only ever be a single trust
64 * cache with a particular UUID within the runtime.
65 */
66TCReturn_t
67trustCacheCheckRuntimeForUUID(const TrustCacheRuntime_t *runtime,
68 const uint8_t checkUUID[kUUIDSize],
69 const TrustCache_t **trustCacheRet);
70
71/**
72 * Add a trust cache module directly to the runtime. This function is used to add modules which
73 * don't need to be separately authenticated. Currently, the only trust cache types which can be
74 * used with this function are static and engineering trust caches.
75 *
76 * If the system supports read-only segments, and the runtime is allocated within the read-only
77 * segment, then this function needs to be called before the segment is enforced to be read-only.
78 * For more information, please look at <TrustCache/Types.h>.
79 */
80TCReturn_t
81trustCacheLoadModule(TrustCacheRuntime_t *runtime,
82 const TCType_t type,
83 TrustCache_t *trustCache,
84 const uintptr_t dataAddr,
85 const size_t dataSize);
86
87/**
88 * Load a trust cache onto the system. This function validates the trust cache for a proper
89 * signature and adds it to the runtime.
90 *
91 * Both the payload and the manifest must be provided and they will be validated as image4
92 * objects.
93 */
94TCReturn_t
95trustCacheLoad(TrustCacheRuntime_t *runtime,
96 TCType_t type,
97 TrustCache_t *trustCache,
98 const uintptr_t payloadAddr,
99 const size_t payloadSize,
100 const uintptr_t manifestAddr,
101 const size_t manifestSize);
102
103/**
104 * Extract an image4 artifact from an image4 file or an image4 payload and extract the
105 * trust cache module embedded within it. The module is validated for correctness
106 * before being returned, however the image4 signature is not verified.
107 *
108 * The returned trust cache object is marked with an invalid type.
109 */
110TCReturn_t
111trustCacheExtractModule(TrustCache_t *trustCache,
112 const uint8_t *dataAddr,
113 size_t dataSize);
114
115/**
116 * Query a trust cache for a particular CDHash. The returned token can then be used to
117 * query further attributes from the matched entry.
118 */
119TCReturn_t
120trustCacheQuery(const TrustCacheRuntime_t *runtime,
121 TCQueryType_t queryType,
122 const uint8_t CDHash[kTCEntryHashSize],
123 TrustCacheQueryToken_t *queryToken);
124
125/**
126 * Get the module bytes backng a trust cache object. The environment may have chosen
127 * to allocate the module bytes within read-only memory, so the bytes returned may
128 * not be mutable.
129 */
130TCReturn_t
131trustCacheGetModule(const TrustCache_t *trustCache,
132 const uint8_t **moduleAddrRet,
133 size_t *moduleSizeRet);
134
135/**
136 * Get the UUID of the trust cache module represented by the wrapped trust cache object.
137 */
138TCReturn_t
139trustCacheGetUUID(const TrustCache_t *trustCache,
140 uint8_t returnUUID[kUUIDSize]);
141
142/**
143 * Get the capabilities of a trust cache. This function can be used to query which fields a given
144 * trust cache supports.
145 *
146 * The fields which are supported are based on the version of the trust cache module.
147 */
148TCReturn_t
149trustCacheGetCapabilities(const TrustCache_t *trustCache,
150 TCCapabilities_t *capabilities);
151
152/**
153 * Acquire the trust cache type for a query token.
154 */
155TCReturn_t
156trustCacheQueryGetTCType(const TrustCacheQueryToken_t *queryToken,
157 TCType_t *typeRet);
158
159/**
160 * Acquire the capabilities of the trust cache through a query token.
161 */
162TCReturn_t
163trustCacheQueryGetCapabilities(const TrustCacheQueryToken_t *queryToken,
164 TCCapabilities_t *capabilities);
165
166/**
167 * Acquire the hash type for the CDHash through a query token.
168 */
169TCReturn_t
170trustCacheQueryGetHashType(const TrustCacheQueryToken_t *queryToken,
171 uint8_t *hashTypeRet);
172
173/**
174 * Acquire the flags for a trust cache entry through a query token.
175 */
176TCReturn_t
177trustCacheQueryGetFlags(const TrustCacheQueryToken_t *queryToken,
178 uint64_t *flagsRet);
179
180/**
181 * Acquire the constraint category for a trust cache entry through a query token.
182 */
183TCReturn_t
184trustCacheQueryGetConstraintCategory(const TrustCacheQueryToken_t *queryToken,
185 uint8_t *constraintCategoryRet);
186
187__END_DECLS
188#endif /* libTrustCache_API_h */
189