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 |
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(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 | */ |
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 | (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 | |