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