refactored PCR functionality
[strongswan.git] / src / libpts / pts / pts.h
1 /*
2 * Copyright (C) 2011 Sansar Choinyambuu
3 * HSR Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup pts pts
18 * @{ @ingroup pts
19 */
20
21 #ifndef PTS_H_
22 #define PTS_H_
23
24 typedef struct pts_t pts_t;
25
26 #include "pts_error.h"
27 #include "pts_proto_caps.h"
28 #include "pts_meas_algo.h"
29 #include "pts_file_meas.h"
30 #include "pts_file_meta.h"
31 #include "pts_dh_group.h"
32 #include "pts_func_comp_evid_req.h"
33 #include "components/pts_comp_func_name.h"
34 #include "components/tcg/tcg_comp_func_name.h"
35 #include "components/ita/ita_comp_func_name.h"
36 #include "components/ita/ita_comp_tboot.h"
37 #include "components/ita/ita_comp_tgrub.h"
38
39 #include <library.h>
40 #include <utils/linked_list.h>
41
42 /**
43 * UTF-8 encoding of the character used to delimiter the filename
44 */
45 #define SOLIDUS_UTF 0x2F
46 #define REVERSE_SOLIDUS_UTF 0x5C
47
48 /**
49 * PCR indices used for measurements of various functional components
50 */
51 #define PCR_BIOS 0
52 #define PCR_PLATFORM_EXT 1
53 #define PCR_MOTHERBOARD 1
54 #define PCR_OPTION_ROMS 2
55 #define PCR_IPL 4
56
57 #define PCR_TBOOT_POLICY 17
58 #define PCR_TBOOT_MLE 18
59
60 #define PCR_TGRUB_MBR_STAGE1 4
61 #define PCR_TGRUB_STAGE2_PART1 8
62 #define PCR_TGRUB_STAGE2_PART2 9
63 #define PCR_TGRUB_CMD_LINE_ARGS 12
64 #define PCR_TGRUB_CHECKFILE 13
65 #define PCR_TGRUB_LOADED_FILES 14
66
67 #define PCR_DEBUG 16
68
69 /**
70 * Number of sequences for functional components
71 */
72 #define TBOOT_SEQUENCE_COUNT 2
73 #define TGRUB_SEQUENCE_COUNT 6
74
75 /**
76 * Length of the generated nonce used for calculation of shared secret
77 */
78 #define ASSESSMENT_SECRET_LEN 20
79
80 /**
81 * Maximum number of PCR's of TPM, TPM Spec 1.2
82 */
83 #define PCR_MAX_NUM 24
84
85 /**
86 * Number of bytes that can be saved in a PCR of TPM, TPM Spec 1.2
87 */
88 #define PCR_LEN 20
89
90 /**
91 * Lenght of the TPM_QUOTE_INFO structure, TPM Spec 1.2
92 */
93 #define TPM_QUOTE_INFO_LEN 48
94
95 /**
96 * Hashing algorithm used by tboot and trustedGRUB
97 */
98 #define TRUSTED_HASH_ALGO PTS_MEAS_ALGO_SHA1
99
100 /**
101 * Class implementing the TCG Platform Trust Service (PTS)
102 *
103 */
104 struct pts_t {
105
106 /**
107 * Get PTS Protocol Capabilities
108 *
109 * @return Protocol capabilities flags
110 */
111 pts_proto_caps_flag_t (*get_proto_caps)(pts_t *this);
112
113 /**
114 * Set PTS Protocol Capabilities
115 *
116 * @param flags Protocol capabilities flags
117 */
118 void (*set_proto_caps)(pts_t *this, pts_proto_caps_flag_t flags);
119
120 /**
121 * Get PTS Measurement Algorithm
122 *
123 * @return PTS measurement algorithm
124 */
125 pts_meas_algorithms_t (*get_meas_algorithm)(pts_t *this);
126
127 /**
128 * Set PTS Measurement Algorithm
129 *
130 * @param algorithm PTS measurement algorithm
131 */
132 void (*set_meas_algorithm)(pts_t *this, pts_meas_algorithms_t algorithm);
133
134 /**
135 * Get DH Hash Algorithm
136 *
137 * @return DH hash algorithm
138 */
139 pts_meas_algorithms_t (*get_dh_hash_algorithm)(pts_t *this);
140
141 /**
142 * Set DH Hash Algorithm
143 *
144 * @param algorithm DH hash algorithm
145 */
146 void (*set_dh_hash_algorithm)(pts_t *this, pts_meas_algorithms_t algorithm);
147
148 /**
149 * Create PTS Diffie-Hellman object and nonce
150 *
151 * @param group PTS DH group
152 * @param nonce_len Nonce length
153 * @return TRUE if creation was successful
154 *
155 */
156 bool (*create_dh_nonce)(pts_t *this, pts_dh_group_t group, int nonce_len);
157
158 /**
159 * Get my Diffie-Hellman public value
160 *
161 * @param value My public DH value
162 * @param nonce My DH nonce
163 */
164 void (*get_my_public_value)(pts_t *this, chunk_t *value, chunk_t *nonce);
165
166 /**
167 * Set peer Diffie.Hellman public value
168 *
169 * @param value Peer public DH value
170 * @param nonce Peer DH nonce
171 */
172 void (*set_peer_public_value) (pts_t *this, chunk_t value, chunk_t nonce);
173
174 /**
175 * Calculates assessment secret to be used for TPM Quote as ExternalData
176 *
177 * @return TRUE unless both DH public values
178 * and nonces are set
179 */
180 bool (*calculate_secret) (pts_t *this);
181
182 /**
183 * Set PTS Diffie Hellman Object
184 *
185 * @param dh D-H object
186 */
187 bool (*create_dh_nonce)(pts_t *this, pts_dh_group_t group, int nonce_len);
188
189 /**
190 * Get my Diffie-Hellman public value
191 *
192 * @param value My public DH value
193 * @param nonce My DH nonce
194 */
195 void (*get_my_public_value)(pts_t *this, chunk_t *value, chunk_t *nonce);
196
197 /**
198 * Set peer Diffie.Hellman public value
199 *
200 * @param value Peer public DH value
201 * @param nonce Peer DH nonce
202 */
203 void (*set_peer_public_value) (pts_t *this, chunk_t value, chunk_t nonce);
204
205 /**
206 * Calculates secret assessment value to be used for TPM Quote as ExternalData
207 *
208 * @return TRUE unless both DH public values
209 * and nonces are set
210 */
211 bool (*calculate_secret) (pts_t *this);
212
213 /**
214 * Get Platform and OS Info
215 *
216 * @return Platform and OS info
217 */
218 char* (*get_platform_info)(pts_t *this);
219
220 /**
221 * Set Platform and OS Info
222 *
223 * @param info Platform and OS info
224 */
225 void (*set_platform_info)(pts_t *this, char *info);
226
227 /**
228 * Get TPM 1.2 Version Info
229 *
230 * @param info chunk containing a TPM_CAP_VERSION_INFO struct
231 * @return TRUE if TPM Version Info available
232 */
233 bool (*get_tpm_version_info)(pts_t *this, chunk_t *info);
234
235 /**
236 * Set TPM 1.2 Version Info
237 *
238 * @param info chunk containing a TPM_CAP_VERSION_INFO struct
239 */
240 void (*set_tpm_version_info)(pts_t *this, chunk_t info);
241
242 /**
243 * Get Attestation Identity Certificate or Public Key
244 *
245 * @return AIK Certificate or Public Key
246 */
247 certificate_t* (*get_aik)(pts_t *this);
248
249 /**
250 * Set Attestation Identity Certificate or Public Key
251 *
252 * @param aik AIK Certificate or Public Key
253 */
254 void (*set_aik)(pts_t *this, certificate_t *aik);
255
256 /**
257 * Check whether path is valid file/directory on filesystem
258 *
259 * @param path Absolute path
260 * @param error_code Output variable for PTS error code
261 * @return TRUE if path is valid or file/directory
262 * doesn't exist or path is invalid
263 * FALSE if local error occured within stat function
264 */
265 bool (*is_path_valid)(pts_t *this, char *path, pts_error_code_t *error_code);
266
267 /**
268 * Compute a hash over a file
269 *
270 * @param hasher Hasher to be used
271 * @param pathname Absolute path of a file
272 * @param hash Buffer to keep hash output
273 * @return TRUE if path is valid and hashing succeeded
274 */
275 bool (*hash_file)(pts_t *this, hasher_t *hasher, char *pathname, u_char *hash);
276
277 /**
278 * Do PTS File Measurements
279 *
280 * @param request_id ID of PTS File Measurement Request
281 * @param pathname Absolute pathname of file to be measured
282 * @param is_directory TRUE if directory contents are measured
283 * @return PTS File Measurements of NULL if FAILED
284 */
285 pts_file_meas_t* (*do_measurements)(pts_t *this, u_int16_t request_id,
286 char *pathname, bool is_directory);
287
288 /**
289 * Obtain file metadata
290 *
291 * @param pathname Absolute pathname of file/directory
292 * @param is_directory TRUE if directory contents are requested
293 * @return PTS File Metadata or NULL if FAILED
294 */
295 pts_file_meta_t* (*get_metadata)(pts_t *this, char *pathname,
296 bool is_directory);
297
298 /**
299 * Reads given PCR value and returns it
300 * Expects owner secret to be WELL_KNOWN_SECRET
301 *
302 * @param pcr_num Number of PCR to read
303 * @param pcr_value Chunk to save pcr read output
304 * @return NULL in case of TSS error, PCR value otherwise
305 */
306 bool (*read_pcr)(pts_t *this, u_int32_t pcr_num, chunk_t *pcr_value);
307
308 /**
309 * Extends given PCR with given value
310 * Expects owner secret to be WELL_KNOWN_SECRET
311 *
312 * @param pcr_num Number of PCR to extend
313 * @param input Value to extend
314 * @param output Chunk to save PCR value after extension
315 * @return FALSE in case of TSS error, TRUE otherwise
316 */
317 bool (*extend_pcr)(pts_t *this, u_int32_t pcr_num, chunk_t input,
318 chunk_t *output);
319
320 /**
321 * Quote over PCR's
322 * Expects owner and SRK secret to be WELL_KNOWN_SECRET and no password set for AIK
323 *
324 * @param use_quote2 Version of the Quote funtion to be used
325 * @param pcr_composite Chunk to save pcr composite structure
326 * @param quote_signature Chunk to save quote operation output
327 * without external data (anti-replay protection)
328 * @return FALSE in case of TSS error, TRUE otherwise
329 */
330 bool (*quote_tpm)(pts_t *this, bool use_quote2, chunk_t *pcr_composite,
331 chunk_t *quote_signature);
332
333 /**
334 * Mark an extended PCR as selected
335 *
336 * @param pcr Number of the extended PCR
337 * @return TRUE if PCR number is valid
338 */
339 bool (*select_pcr)(pts_t *this, u_int32_t pcr);
340
341 /**
342 * Add an extended PCR with its corresponding value
343 *
344 * @param pcr Number of the extended PCR
345 * @param pcr_before PCR value before extension
346 * @param pcr_after PCR value after extension
347 * @return TRUE if PCR number and register length is valid
348 */
349 bool (*add_pcr)(pts_t *this, u_int32_t pcr, chunk_t pcr_before,
350 chunk_t pcr_after);
351
352 /**
353 * Constructs and returns TPM Quote Info structure expected from IMC
354 *
355 * @param use_quote2 Version of the TPM_QUOTE_INFO to be constructed
356 * @param ver_info_included Version info is concatenated to TPM_QUOTE_INFO2
357 * @param pcr_composite Output variable to store PCR Composite
358 * @param quote_info Output variable to store TPM Quote Info
359 * @return FALSE in case of any error, TRUE otherwise
360 */
361 bool (*get_quote_info)(pts_t *this, bool use_quote2, bool ver_info_included,
362 pts_meas_algorithms_t composite_algo,
363 chunk_t *pcr_composite, chunk_t *quote_info);
364
365 /**
366 * Constructs and returns PCR Quote Digest structure expected from IMC
367 *
368 * @param data Calculated TPM Quote Digest
369 * @param signature TPM Quote Signature received from IMC
370 * @return FALSE in case signature is not verified, TRUE otherwise
371 */
372 bool (*verify_quote_signature)(pts_t *this, chunk_t data, chunk_t signature);
373
374 /**
375 * Reads given PCR value and returns it
376 * Expects owner secret to be WELL_KNOWN_SECRET
377 *
378 * @param pcr_num Number of PCR to read
379 * @param pcr_value Chunk to save pcr read output
380 * @return NULL in case of TSS error, PCR value otherwise
381 */
382 bool (*read_pcr)(pts_t *this, u_int32_t pcr_num, chunk_t *pcr_value);
383
384 /**
385 * Extends given PCR with given value
386 * Expects owner secret to be WELL_KNOWN_SECRET
387 *
388 * @param pcr_num Number of PCR to extend
389 * @param input Value to extend
390 * @param output Chunk to save PCR value after extension
391 * @return FALSE in case of TSS error, TRUE otherwise
392 */
393 bool (*extend_pcr)(pts_t *this, u_int32_t pcr_num, chunk_t input,
394 chunk_t *output);
395
396 /**
397 * Quote over PCR's
398 * Expects owner and SRK secret to be WELL_KNOWN_SECRET and no password set for AIK
399 *
400 * @param pcrs Array of PCR's to make quotation over
401 * @param num_of_pcrs Number of elements in pcrs array
402 * @param pcr_composite Chunk to save pcr composite structure
403 * @param quote_signature Chunk to save quote operation output
404 * without external data (anti-replay protection)
405 * @return FALSE in case of TSS error, TRUE otherwise
406 */
407 bool (*quote_tpm)(pts_t *this, u_int32_t *pcrs, u_int32_t num_of_pcrs,
408 chunk_t *pcr_composite, chunk_t *quote_signature);
409
410 /**
411 * Add extended PCR with its corresponding value
412 *
413 * @return FALSE in case of any error or non-match, TRUE otherwise
414 */
415 void (*add_pcr_entry)(pts_t *this, pcr_entry_t *entry);
416
417 /**
418 * Constructs and returns TPM Quote Info structure expected from IMC
419 *
420 * @param pcr_composite Output variable to store PCR Composite
421 * @param quote_info Output variable to store TPM Quote Info
422 * @return FALSE in case of any error, TRUE otherwise
423 */
424 bool (*get_quote_info)(pts_t *this, chunk_t *pcr_composite,
425 chunk_t *quote_info);
426
427 /**
428 * Constructs and returns PCR Quote Digest structure expected from IMC
429 *
430 * @param data Calculated TPM Quote Digest
431 * @param signature TPM Quote Signature received from IMC
432 * @return FALSE in case signature is not verified, TRUE otherwise
433 */
434 bool (*verify_quote_signature)(pts_t *this, chunk_t data, chunk_t signature);
435
436 /**
437 * Destroys a pts_t object.
438 */
439 void (*destroy)(pts_t *this);
440
441 };
442
443 /**
444 * Creates an pts_t object
445 *
446 * @param is_imc TRUE if running on an IMC
447 */
448 pts_t* pts_create(bool is_imc);
449
450 #endif /** PTS_H_ @}*/
451