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  * Length 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          * Get Platform and OS Info
 165          *
 166          * @return                                      Platform and OS info
 167          */
 168         char* (*get_platform_info)(pts_t *this);
 169
 170         /**
 171          * Set Platform and OS Info
 172          *
 173          * @param info                          Platform and OS info
 174          */
 175         void (*set_platform_info)(pts_t *this, char *info);
 176
 177         /**
 178          * Get TPM 1.2 Version Info
 179          *
 180          * @param info                          chunk containing a TPM_CAP_VERSION_INFO struct
 181          * @return                                      TRUE if TPM Version Info available
 182          */
 183         bool (*get_tpm_version_info)(pts_t *this, chunk_t *info);
 184
 185         /**
 186          * Set TPM 1.2 Version Info
 187          *
 188          * @param info                          chunk containing a TPM_CAP_VERSION_INFO struct
 189          */
 190         void (*set_tpm_version_info)(pts_t *this, chunk_t info);
 191
 192         /**
 193          * Get the length of the TPM PCR registers
 194          *
 195          * @return                                      Length of PCR registers in bytes, 0 if undefined
 196          */
 197         size_t (*get_pcr_len)(pts_t *this);
 198
 199         /**
 200          * Get Attestation Identity Certificate or Public Key
 201          *
 202          * @return                                      AIK Certificate or Public Key
 203          */
 204         certificate_t* (*get_aik)(pts_t *this);
 205
 206         /**
 207          * Set Attestation Identity Certificate or Public Key
 208          *
 209          * @param aik                           AIK Certificate or Public Key
 210          */
 211         void (*set_aik)(pts_t *this, certificate_t *aik);
 212
 213         /**
 214          * Get SHA-1 Attestation Identity Public Key Info ID
 215          *
 216          * @param keyid                         AIK ID
 217          * @return                                      TRUE if AIK ID exists
 218          */
 219         bool (*get_aik_keyid)(pts_t *this, chunk_t *keyid);
 220
 221         /**
 222          * Check whether path is valid file/directory on filesystem
 223          *
 224          * @param path                          Absolute path
 225          * @param error_code            Output variable for PTS error code
 226          * @return                                      TRUE if path is valid or file/directory
 227          *                                                      doesn't exist or path is invalid
 228          *                                              FALSE if local error occurred within stat function
 229          */
 230         bool (*is_path_valid)(pts_t *this, char *path, pts_error_code_t *error_code);
 231
 232         /**
 233          * Obtain file metadata
 234          *
 235          * @param pathname                      Absolute pathname of file/directory
 236          * @param is_dir                        TRUE if directory contents are requested
 237          * @return                                      PTS File Metadata or NULL if FAILED
 238          */
 239         pts_file_meta_t* (*get_metadata)(pts_t *this, char *pathname, bool is_dir);
 240
 241         /**
 242          * Reads given PCR value and returns it
 243          * Expects owner secret to be WELL_KNOWN_SECRET
 244          *
 245          * @param pcr_num                       Number of PCR to read
 246          * @param pcr_value                     Chunk to save pcr read output
 247          * @return                                      NULL in case of TSS error, PCR value otherwise
 248          */
 249         bool (*read_pcr)(pts_t *this, u_int32_t pcr_num, chunk_t *pcr_value);
 250
 251         /**
 252          * Extends given PCR with given value
 253          * Expects owner secret to be WELL_KNOWN_SECRET
 254          *
 255          * @param pcr_num                       Number of PCR to extend
 256          * @param input                         Value to extend
 257          * @param output                        Chunk to save PCR value after extension
 258          * @return                                      FALSE in case of TSS error, TRUE otherwise
 259          */
 260         bool (*extend_pcr)(pts_t *this, u_int32_t pcr_num, chunk_t input,
 261                                            chunk_t *output);
 262
 263         /**
 264          * Quote over PCR's
 265          * Expects owner and SRK secret to be WELL_KNOWN_SECRET and no password set for AIK
 266          *
 267          * @param use_quote2            Version of the Quote function to be used
 268          * @param pcr_comp                      Chunk to save PCR composite structure
 269          * @param quote_sig                     Chunk to save quote operation output
 270          *                                                      without external data (anti-replay protection)
 271          * @return                                      FALSE in case of TSS error, TRUE otherwise
 272          */
 273          bool (*quote_tpm)(pts_t *this, bool use_quote2, chunk_t *pcr_comp,
 274                                                                                                          chunk_t *quote_sig);
 275
 276          /**
 277          * Mark an extended PCR as selected
 278          *
 279          * @param pcr                           Number of the extended PCR
 280          * @return                                      TRUE if PCR number is valid
 281          */
 282          bool (*select_pcr)(pts_t *this, u_int32_t pcr);
 283
 284          /**
 285          * Add an extended PCR with its corresponding value
 286          *
 287          * @param pcr                           Number of the extended PCR
 288          * @param pcr_before            PCR value before extension
 289          * @param pcr_after                     PCR value after extension
 290          * @return                                      TRUE if PCR number and register length is valid
 291          */
 292         bool (*add_pcr)(pts_t *this, u_int32_t pcr, chunk_t pcr_before,
 293                                                                                                 chunk_t pcr_after);
 294
 295          /**
 296          * Constructs and returns TPM Quote Info structure expected from IMC
 297          *
 298          * @param use_quote2            Version of the TPM_QUOTE_INFO to be constructed
 299          * @param use_ver_info          Version info is concatenated to TPM_QUOTE_INFO2
 300          * @param comp_hash_algo        Composite Hash Algorithm
 301          * @param pcr_comp                      Output variable to store PCR Composite
 302          * @param quote_info            Output variable to store TPM Quote Info
 303          * @return                                      FALSE in case of any error, TRUE otherwise
 304          */
 305          bool (*get_quote_info)(pts_t *this, bool use_quote2, bool ver_info_included,
 306                                                         pts_meas_algorithms_t comp_hash_algo,
 307                                                         chunk_t *pcr_comp, chunk_t *quote_info);
 308
 309          /**
 310          * Constructs and returns PCR Quote Digest structure expected from IMC
 311          *
 312          * @param data                          Calculated TPM Quote Digest
 313          * @param signature                     TPM Quote Signature received from IMC
 314          * @return                                      FALSE if signature is not verified
 315          */
 316          bool (*verify_quote_signature)(pts_t *this, chunk_t data, chunk_t signature);
 317
 318         /**
 319          * Destroys a pts_t object.
 320          */
 321         void (*destroy)(pts_t *this);
 322
 323 };
 324
 325 /**
 326  * Creates an pts_t object
 327  *
 328  * @param is_imc                        TRUE if running on an IMC
 329  */
 330 pts_t* pts_create(bool is_imc);
 331
 332 #endif /** PTS_H_ @}*/