1 /*############################################################################ 2 # Copyright 2016-2017 Intel Corporation 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); 5 # you may not use this file except in compliance with the License. 6 # You may obtain a copy of the License at 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, 12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 # See the License for the specific language governing permissions and 14 # limitations under the License. 15 ############################################################################*/ 16 17 /*! 18 * \file 19 * \brief Intel(R) EPID issuer material parsing utilities. 20 */ 21 #ifndef EPID_COMMON_FILE_PARSER_H_ 22 #define EPID_COMMON_FILE_PARSER_H_ 23 24 #include <stddef.h> 25 26 #include "epid/common/errors.h" 27 #include "epid/common/types.h" 28 29 /// Parser for issuer material 30 /*! 31 \defgroup FileParser fileparser 32 Provides an API for parsing buffers formatted according to the 33 various IoT Intel(R) EPID binary file formats. 34 35 To use this module, include the header epid/common/file_parser.h. 36 37 \ingroup EpidCommon 38 @{ 39 */ 40 41 /// Recognized Intel(R) EPID versions 42 typedef enum EpidVersion { 43 kEpid1x, ///< Intel(R) EPID version 1.x 44 kEpid2x, ///< Intel(R) EPID version 2.x 45 kNumEpidVersions, ///< Maximum number of versions 46 } EpidVersion; 47 48 /// Encoding of issuer material Intel(R) EPID versions 49 extern const OctStr16 kEpidVersionCode[kNumEpidVersions]; 50 51 /// Recognized Intel(R) EPID file types 52 typedef enum EpidFileType { 53 kIssuingCaPubKeyFile, ///< IoT Issuing CA public key file 54 kGroupPubKeyFile, ///< Group Public Key Output File Format 55 kPrivRlFile, ///< Binary Private Key Revocation List 56 kSigRlFile, ///< Binary Signature Revocation List 57 kGroupRlFile, ///< Binary Group Revocation List 58 kPrivRlRequestFile, ///< Binary Private Key Revocation Request 59 kSigRlRequestFile, ///< Binary Signature Revocation Request 60 kGroupRlRequestFile, ///< Binary Group Revocation Request 61 kNumFileTypes, ///< Maximum number of file types 62 } EpidFileType; 63 64 /// Encoding of issuer material file types 65 extern const OctStr16 kEpidFileTypeCode[kNumFileTypes]; 66 67 #pragma pack(1) 68 /// Intel(R) EPID binary file header 69 typedef struct EpidFileHeader { 70 OctStr16 epid_version; ///< Intel(R) EPID Version 71 OctStr16 file_type; ///< File Type 72 } EpidFileHeader; 73 74 /// IoT CA Certificate binary format 75 typedef struct EpidCaCertificate { 76 EpidFileHeader header; ///< Intel(R) EPID binary file header 77 OctStr512 pubkey; ///< Public Key (Qx, Qy) 78 OctStr256 prime; ///< Prime of GF(p) 79 OctStr256 a; ///< Coefficient of E Curve 80 OctStr256 b; ///< Coefficient of E Curve 81 OctStr256 x; ///< X coordinate of Base point G 82 OctStr256 y; ///< Y coordinate of Base point G 83 OctStr256 r; ///< Order of base point 84 EcdsaSignature signature; ///< ECDSA Signature on SHA-256 of above values 85 } EpidCaCertificate; 86 #pragma pack() 87 88 /// Extracts Intel(R) EPID Binary Output File header information 89 /*! 90 \param[in] buf 91 Pointer to buffer containing Intel(R) EPID Binary Output File to parse. 92 93 \param[in] len 94 The size of buf in bytes. 95 96 \param[out] epid_version 97 The extracted Intel(R) EPID version or kNumEpidVersions if Intel(R) EPID 98 version is unknown. Pass NULL to not extract. 99 100 \param[out] file_type 101 The extracted Intel(R) EPID file type or kNumFileTypes if file type is 102 unknown. Pass NULL to not extract. 103 104 \returns ::EpidStatus 105 106 */ 107 EpidStatus EpidParseFileHeader(void const* buf, size_t len, 108 EpidVersion* epid_version, 109 EpidFileType* file_type); 110 111 /// Extracts group public key from buffer in issuer binary format 112 /*! 113 114 Extracts the first group public key from a buffer with format of 115 Intel(R) EPID 2.0 Group Public Key Certificate Binary File. The 116 function validates that the first public key was signed by the 117 private key corresponding to the provided CA certificate and the 118 size of the input buffer is correct. 119 120 \warning 121 It is the responsibility of the caller to authenticate the 122 EpidCaCertificate. 123 124 \param[in] buf 125 Pointer to buffer containing public key to extract. 126 127 \param[in] len 128 The size of buf in bytes. 129 130 \param[in] cert 131 The issuing CA public key certificate. 132 133 \param[out] pubkey 134 The extracted group public key. 135 136 \returns ::EpidStatus 137 138 \retval ::kEpidSigInvalid 139 Parsing failed due to data authentication failure. 140 141 \b Examples 142 143 \ref UserManual_GeneratingAnIntelEpidSignature 144 */ 145 EpidStatus EpidParseGroupPubKeyFile(void const* buf, size_t len, 146 EpidCaCertificate const* cert, 147 GroupPubKey* pubkey); 148 149 /// Extracts private key revocation list from buffer in issuer binary format 150 /*! 151 152 Extracts the private key revocation list from a buffer with format of 153 Binary Private Key Revocation List File. The function 154 validates that the revocation list was signed by the private 155 key corresponding to the provided CA certificate and the size of the 156 input buffer is correct. 157 158 To determine the required size of the revocation list output buffer, 159 provide a null pointer for the output buffer. 160 161 \warning 162 It is the responsibility of the caller to authenticate the 163 EpidCaCertificate. 164 165 \param[in] buf 166 Pointer to buffer containing the revocation list to extract. 167 168 \param[in] len 169 The size of buf in bytes. 170 171 \param[in] cert 172 The issuing CA public key certificate. 173 174 \param[out] rl 175 The extracted revocation list. If Null, rl_len is filled with 176 the required output buffer size. 177 178 \param[in,out] rl_len 179 The size of rl in bytes. 180 181 \returns ::EpidStatus 182 183 \retval ::kEpidSigInvalid 184 Parsing failed due to data authentication failure. 185 186 \b Example 187 188 \ref UserManual_VerifyingAnIntelEpidSignature 189 */ 190 EpidStatus EpidParsePrivRlFile(void const* buf, size_t len, 191 EpidCaCertificate const* cert, PrivRl* rl, 192 size_t* rl_len); 193 194 /// Extracts signature revocation list from buffer in issuer binary format 195 /*! 196 197 Extracts the signature based revocation list from a buffer with 198 format of Binary Signature Revocation List File. The function 199 validates that the revocation list was signed by the private key 200 corresponding to the provided CA certificate and the size of the 201 input buffer is correct. 202 203 To determine the required size of the revocation list output buffer, 204 provide a null pointer for the output buffer. 205 206 \warning 207 It is the responsibility of the caller to authenticate the 208 EpidCaCertificate. 209 210 \param[in] buf 211 Pointer to buffer containing the revocation list to extract. 212 213 \param[in] len 214 The size of buf in bytes. 215 216 \param[in] cert 217 The issuing CA public key certificate. 218 219 \param[out] rl 220 The extracted revocation list. If Null, rl_len is filled with 221 the required output buffer size. 222 223 \param[in,out] rl_len 224 The size of rl in bytes. 225 226 \returns ::EpidStatus 227 228 \retval ::kEpidSigInvalid 229 Parsing failed due to data authentication failure. 230 231 \b Examples 232 233 \ref UserManual_GeneratingAnIntelEpidSignature 234 */ 235 EpidStatus EpidParseSigRlFile(void const* buf, size_t len, 236 EpidCaCertificate const* cert, SigRl* rl, 237 size_t* rl_len); 238 239 /// Extracts group revocation list from buffer in issuer binary format 240 /*! 241 242 Extracts the group revocation list from a buffer with format of 243 Binary Group Certificate Revocation List File. The function 244 validates that the revocation list was signed by the private key 245 corresponding to the provided CA certificate and the size of the 246 input buffer is correct. 247 248 To determine the required size of the revocation list output buffer, 249 provide a null pointer for the output buffer. 250 251 \warning 252 It is the responsibility of the caller to authenticate the 253 EpidCaCertificate. 254 255 \param[in] buf 256 Pointer to buffer containing the revocation list to extract. 257 258 \param[in] len 259 The size of buf in bytes. 260 261 \param[in] cert 262 The issuing CA public key certificate. 263 264 \param[out] rl 265 The extracted revocation list. If Null, rl_len is filled with 266 the required output buffer size. 267 268 \param[in,out] rl_len 269 The size of rl in bytes. 270 271 \returns ::EpidStatus 272 273 \retval ::kEpidSigInvalid 274 Parsing failed due to data authentication failure. 275 276 \b Example 277 278 \ref UserManual_VerifyingAnIntelEpidSignature 279 */ 280 EpidStatus EpidParseGroupRlFile(void const* buf, size_t len, 281 EpidCaCertificate const* cert, GroupRl* rl, 282 size_t* rl_len); 283 284 /*! 285 @} 286 */ 287 288 #endif // EPID_COMMON_FILE_PARSER_H_ 289