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 */
28 static inline void
trustCacheInitializeRuntime(TrustCacheRuntime_t * runtime,TrustCacheMutableRuntime_t * mutableRT,bool allowSecondStaticTC,bool allowEngineeringTC,bool allowLegacyTC,const img4_runtime_t * image4RT)29 trustCacheInitializeRuntime(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(runtime, 0, sizeof(*runtime));
38 memset(mutableRT, 0, 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 */
56 TCReturn_t
57 trustCacheConstructInvalid(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 */
66 TCReturn_t
67 trustCacheCheckRuntimeForUUID(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 */
80 TCReturn_t
81 trustCacheLoadModule(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 */
94 TCReturn_t
95 trustCacheLoad(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 */
110 TCReturn_t
111 trustCacheExtractModule(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 */
119 TCReturn_t
120 trustCacheQuery(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 */
130 TCReturn_t
131 trustCacheGetModule(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 */
138 TCReturn_t
139 trustCacheGetUUID(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 */
148 TCReturn_t
149 trustCacheGetCapabilities(const TrustCache_t *trustCache,
150 TCCapabilities_t *capabilities);
151
152 /**
153 * Acquire the trust cache type for a query token.
154 */
155 TCReturn_t
156 trustCacheQueryGetTCType(const TrustCacheQueryToken_t *queryToken,
157 TCType_t *typeRet);
158
159 /**
160 * Acquire the capabilities of the trust cache through a query token.
161 */
162 TCReturn_t
163 trustCacheQueryGetCapabilities(const TrustCacheQueryToken_t *queryToken,
164 TCCapabilities_t *capabilities);
165
166 /**
167 * Acquire the hash type for the CDHash through a query token.
168 */
169 TCReturn_t
170 trustCacheQueryGetHashType(const TrustCacheQueryToken_t *queryToken,
171 uint8_t *hashTypeRet);
172
173 /**
174 * Acquire the flags for a trust cache entry through a query token.
175 */
176 TCReturn_t
177 trustCacheQueryGetFlags(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 */
183 TCReturn_t
184 trustCacheQueryGetConstraintCategory(const TrustCacheQueryToken_t *queryToken,
185 uint8_t *constraintCategoryRet);
186
187 __END_DECLS
188 #endif /* libTrustCache_API_h */
189