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 * Add a trust cache module directly to the runtime. This function is used to add modules which
54 * don't need to be separately authenticated. Currently, the only trust cache types which can be
55 * used with this function are static and engineering trust caches.
56 *
57 * If the system supports read-only segments, and the runtime is allocated within the read-only
58 * segment, then this function needs to be called before the segment is enforced to be read-only.
59 * For more information, please look at <TrustCache/Types.h>.
60 */
61 TCReturn_t
62 trustCacheLoadModule(TrustCacheRuntime_t *runtime,
63 const TCType_t type,
64 TrustCache_t *trustCache,
65 const uintptr_t dataAddr,
66 const size_t dataSize);
67
68 /**
69 * Load a trust cache onto the system. This function validates the trust cache for a proper
70 * signature and adds it to the runtime.
71 *
72 * Both the payload and the manifest must be provided and they will be validated as image4
73 * objects.
74 */
75 TCReturn_t
76 trustCacheLoad(TrustCacheRuntime_t *runtime,
77 TCType_t type,
78 TrustCache_t *trustCache,
79 const uintptr_t payloadAddr,
80 const size_t payloadSize,
81 const uintptr_t manifestAddr,
82 const size_t manifestSize);
83
84 /**
85 * Query a trust cache for a particular CDHash. The returned token can then be used to
86 * query further attributes from the matched entry.
87 */
88 TCReturn_t
89 trustCacheQuery(const TrustCacheRuntime_t *runtime,
90 TCQueryType_t queryType,
91 const uint8_t CDHash[kTCEntryHashSize],
92 TrustCacheQueryToken_t *queryToken);
93
94 /**
95 * Get the capabilities of a trust cache. This function can be used to query which fields a given
96 * trust cache supports.
97 *
98 * The fields which are supported are based on the version of the trust cache module.
99 */
100 TCReturn_t
101 trustCacheGetCapabilities(const TrustCache_t *trustCache,
102 TCCapabilities_t *capabilities);
103
104 /**
105 * Acquire the trust cache type for a query token.
106 */
107 TCReturn_t
108 trustCacheQueryGetTCType(const TrustCacheQueryToken_t *queryToken,
109 TCType_t *typeRet);
110
111 /**
112 * Acquire the capabilities of the trust cache through a query token.
113 */
114 TCReturn_t
115 trustCacheQueryGetCapabilities(const TrustCacheQueryToken_t *queryToken,
116 TCCapabilities_t *capabilities);
117
118 /**
119 * Acquire the hash type for the CDHash through a query token.
120 */
121 TCReturn_t
122 trustCacheQueryGetHashType(const TrustCacheQueryToken_t *queryToken,
123 uint8_t *hashTypeRet);
124
125 /**
126 * Acquire the flags for a trust cache entry through a query token.
127 */
128 TCReturn_t
129 trustCacheQueryGetFlags(const TrustCacheQueryToken_t *queryToken,
130 uint64_t *flagsRet);
131
132 /**
133 * Acquire the constraint category for a trust cache entry through a query token.
134 */
135 TCReturn_t
136 trustCacheQueryGetConstraintCategory(const TrustCacheQueryToken_t *queryToken,
137 uint8_t *constraintCategoryRet);
138
139 __END_DECLS
140 #endif /* libTrustCache_API_h */
141