TPM2-Plugin/lib/include/files.h

   1 //**********************************************************************;
   2 // Copyright (c) 2017, Intel Corporation
   3 // All rights reserved.
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions are met:
   7 //
   8 // 1. Redistributions of source code must retain the above copyright notice,
   9 // this list of conditions and the following disclaimer.
  10 //
  11 // 2. Redistributions in binary form must reproduce the above copyright notice,
  12 // this list of conditions and the following disclaimer in the documentation
  13 // and/or other materials provided with the distribution.
  14 //
  15 // 3. Neither the name of Intel Corporation nor the names of its contributors
  16 // may be used to endorse or promote products derived from this software without
  17 // specific prior written permission.
  18 //
  19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  20 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  23 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  29 // THE POSSIBILITY OF SUCH DAMAGE.
  30 //**********************************************************************;
  31 #ifndef FILES_H
  32 #define FILES_H
  33
  34 #include <stdbool.h>
  35 #include <stdio.h>
  36
  37 #include <tss2/tss2_sys.h>
  38
  39 /**
  40  * Reads a series of bytes from a file as a byte array. This is similar to files_read_bytes(),
  41  * but opens and closes the FILE for the caller. Size is both an input and output value where
  42  * the size value is the max buffer size on call and the returned size is how much was read.
  43  *
  44  * This interface could be cleaned up in a later revision.
  45  * @param path
  46  *  The path to the file to open.
  47  * @param buf
  48  *  The buffer to read the data into
  49  * @param size
  50  *  The max size of the buffer on call, and the size of the data read on return.
  51  * @return
  52  *  True on success, false otherwise.
  53  */
  54 bool files_load_bytes_from_path(const char *path, UINT8 *buf, UINT16 *size);
  55
  56 /**
  57  * Loads data from a file path or stdin enforcing an upper bound on size.
  58  * @param path
  59  *  The path to load data from, NULL means stdin.
  60  * @param size
  61  *  The maximum size.
  62  * @param buf
  63  *  The buffer to write the data into.
  64  * @return
  65  *  True on success or false otherwise.
  66  */
  67 bool files_load_bytes_from_file_or_stdin(const char *path, UINT16 *size, BYTE *buf);
  68
  69 /**
  70  * Similar to files_write_bytes(), in that it writes an array of bytes to disk,
  71  * but this routine opens and closes the file on the callers behalf.
  72  * @param path
  73  *  The path to the file to write the data to.
  74  * @param buf
  75  *  The buffer of data to write
  76  * @param size
  77  *  The size of the data to write in bytes.
  78  * @return
  79  *  True on success, false otherwise.
  80  */
  81 bool files_save_bytes_to_file(const char *path, UINT8 *buf, UINT16 size);
  82
  83 /**
  84  * Saves the TPM context for an object handle to disk by calling Tss2_Sys_ContextSave() and serializing the
  85  * resulting TPMS_CONTEXT structure to disk.
  86  * @param sapi_context
  87  *  The system api context
  88  * @param handle
  89  *  The object handle for the object to save.
  90  * @param path
  91  *  The output path of the file.
  92  *
  93  * @return
  94  *  True on success, False on error.
  95  */
  96 bool files_save_tpm_context_to_path(TSS2_SYS_CONTEXT *sapi_context, TPM2_HANDLE handle, const char *path);
  97
  98 /**
  99  * Like files_save_tpm_context_to_path() but saves a tpm session to a FILE stream.
 100  * @param sapi_context
 101  *  The system api context
 102  * @param handle
 103  *  The object handle for the object to save.
 104  * @param stream
 105  *  The FILE stream to save too.
 106  * @return
 107  *  True on success, False on error.
 108  */
 109 bool files_save_tpm_context_to_file(TSS2_SYS_CONTEXT *sapi_context, TPM2_HANDLE handle,
 110         FILE *stream);
 111
 112 /**
 113  * Loads a TPM object context from disk.
 114  * @param sapi_context
 115  *  The system API context
 116  * @param handle
 117  *  The object handle that was saved.
 118  * @param path
 119  *  The path to the input file.
 120  * @return
 121  *  True on Success, false on error.
 122  */
 123 bool files_load_tpm_context_from_path(TSS2_SYS_CONTEXT *sapi_context, TPM2_HANDLE *handle, const char *path);
 124
 125 /**
 126  * Like files_load_tpm_context_from_path() but loads the context from a FILE stream.
 127  * @param sapi_context
 128  *  The system API context
 129  * @param handle
 130  *  The object handle that was saved.
 131  * @param stream
 132  *  The FILE stream to read from.
 133  * @return
 134  *  True on success, False on error.
 135  */
 136 bool files_load_tpm_context_from_file(TSS2_SYS_CONTEXT *sapi_context,
 137         TPM2_HANDLE *handle, FILE *stream);
 138
 139 /**
 140  * Serializes a TPM2B_PUBLIC to the file path provided.
 141  * @param public
 142  *  The TPM2B_PUBLIC to save to disk.
 143  * @param path
 144  *  The path to save to.
 145  * @return
 146  *  true on success, false on error.
 147  */
 148 bool files_save_public(TPM2B_PUBLIC *public, const char *path);
 149
 150 /**
 151  * Loads a TPM2B_PUBLIC from disk that was saved with files_save_pubkey()
 152  * @param path
 153  *  The path to load from.
 154  * @param public
 155  *  The TPM2B_PUBLIC to load.
 156  * @return
 157  *  true on success, false on error.
 158  */
 159 bool files_load_public(const char *path, TPM2B_PUBLIC *public);
 160
 161 /**
 162  * Serializes a TPMT_SIGNATURE to the file path provided.
 163  * @param signature
 164  *  The TPMT_SIGNATURE to save to disk.
 165  * @param path
 166  *  The path to save to.
 167  * @return
 168  *  true on success, false on error.
 169  */
 170 bool files_save_signature(TPMT_SIGNATURE *signature, const char *path);
 171
 172 /**
 173  * Loads a TPMT_SIGNATURE from disk that was saved with files_save_signature()
 174  * @param path
 175  *  The path to load from.
 176  * @param signature
 177  *  The TPMT_SIGNATURE to load.
 178  * @return
 179  *  true on success, false on error.
 180  */
 181 bool files_load_signature(const char *path, TPMT_SIGNATURE *signature);
 182
 183 /**
 184  * Serializes a TPMT_TK_VERIFIED to the file path provided.
 185  * @param signature
 186  *  The TPMT_SIGNATURE to save to disk.
 187  * @param path
 188  *  The path to save to.
 189  * @return
 190  *  true on success, false on error.
 191  */
 192 bool files_save_ticket(TPMT_TK_VERIFIED *ticket, const char *path);
 193
 194 /**
 195  * Loads a TPMT_TK_VERIFIED from disk that was saved with files_save_ticket()
 196  * @param path
 197  *  The path to load from.
 198  * @param signature
 199  *  The TPMT_TK_VERIFIED to load.
 200  * @return
 201  *  true on success, false on error.
 202  */
 203 bool files_load_ticket(const char *path, TPMT_TK_VERIFIED *ticket);
 204
 205 /**
 206  * Loads a TPM2B_SENSITIVE from disk.
 207  * @param path
 208  *  The path to load from.
 209  * @param signature
 210  *  The TPM2B_SENSITIVE to load.
 211  * @return
 212  *  true on success, false on error.
 213  */
 214 bool files_load_sensitive(const char *path, TPM2B_SENSITIVE *sensitive);
 215
 216 /**
 217  * Serializes a TPM2B_SENSITIVE to the file path provided.
 218  * @param sensitive
 219  *  The TPM2B_SENSITIVE to save to disk.
 220  * @param path
 221  *  The path to save to.
 222  * @return
 223  *  true on success, false on error.
 224  */
 225 bool files_save_sensitive(TPM2B_SENSITIVE *sensitive, const char *path);
 226 /**
 227  * Serializes a TPMT_TK_HASHCHECK to the file path provided.
 228  * @param validation
 229  *  The TPMT_TK_HASHCHECK to save to disk.
 230  * @param path
 231  *  The path to save to.
 232  * @return
 233  *  true on success, false on error.
 234  */
 235 bool files_save_validation(TPMT_TK_HASHCHECK *validation, const char *path);
 236
 237 /**
 238  * Loads a TPMT_TK_HASHCHECK from disk.
 239  * @param path
 240  *  The path to load from.
 241  * @param validation
 242  *  The TPMT_TK_HASHCHECK to load.
 243  * @return
 244  *  true on success, false on error.
 245  */
 246 bool files_load_validation(const char *path, TPMT_TK_HASHCHECK *validation);
 247
 248 /**
 249  * Serializes a TPM2B_PRIVATE to the file path provided.
 250  * @param private
 251  *  The TPM2B_PRIVATE to save to disk.
 252  * @param path
 253  *  The path to save to.
 254  * @return
 255  *  true on success, false on error.
 256  */
 257 bool files_save_private(TPM2B_PRIVATE *private, const char *path);
 258
 259 /**
 260  * Loads a TPM2B_PRIVATE from disk.
 261  * @param private
 262  *  The path to load from.
 263  * @param validation
 264  *  The TPM2B_PRIVATE to load.
 265  * @return
 266  *  true on success, false on error.
 267  */
 268 bool files_load_private(const char *path, TPM2B_PRIVATE *private);
 269
 270 /**
 271  * Checks a file for existence.
 272  * @param path
 273  *  The file to check for existence.
 274  * @return
 275  * true if a file exists with read permissions, false if it doesn't exist or an error occurs.
 276  *
 277  */
 278 bool files_does_file_exist(const char *path);
 279
 280 /**
 281  * Retrieves a files size given a file path.
 282  * @param path
 283  *  The path of the file to retreive the size of.
 284  * @param file_size
 285  *  A pointer to an unsigned long to return the file size. The
 286  *  pointed to value is valid only on a true return.
 287  *
 288  * @return
 289  *  True for success or False for error.
 290  */
 291 bool files_get_file_size_path(const char *path, unsigned long *file_size);
 292
 293 /**
 294  * Similar to files_get_file_size_path(), but uses an already opened FILE object.
 295  * @param fp
 296  *  The file pointer to query the size of.
 297  * @param file_size
 298  *  Output of the file size.
 299  * @param path
 300  *  An optional path used for error reporting, a NULL path disables error logging.
 301  * @return
 302  *  True on success, False otherwise.
 303  */
 304 bool files_get_file_size(FILE *fp, unsigned long *file_size, const char *path);
 305
 306 /**
 307  * Writes a TPM2.0 header to a file.
 308  * @param f
 309  *  The file to write to.
 310  * @param version
 311  *  The version number of the format of the file.
 312  * @return
 313  *  True on success, false on error.
 314  */
 315 bool files_write_header(FILE *f, UINT32 version);
 316
 317 /**
 318  * Reads a TPM2.0 header from a file.
 319  * @param f
 320  *  The file to read.
 321  * @param version
 322  *  The version that was found.
 323  * @return
 324  *  True on Success, False on error.
 325  */
 326 bool files_read_header(FILE *f, UINT32 *version);
 327
 328 /**
 329  * Writes a 16 bit value to the file in big endian, converting
 330  * if needed.
 331  * @param out
 332  *  The file to write.
 333  * @param data
 334  *  The 16 bit value to write.
 335  * @return
 336  *  True on success, False on error.
 337  */
 338 bool files_write_16(FILE *out, UINT16 data);
 339
 340 /**
 341  * Same as files_write_16 but for 32 bit values.
 342  */
 343 bool files_write_32(FILE *out, UINT32 data);
 344
 345 /**
 346  * Same as files_write_16 but for 64 bit values.
 347  */
 348 bool files_write_64(FILE *out, UINT64 data);
 349
 350 /**
 351  * Writes a byte array out to a file.
 352  * @param out
 353  *  The file to write to.
 354  * @param data
 355  *  The data to write.
 356  * @param size
 357  *  The size of the data to write in bytes.
 358  * @return
 359  *  True on success, False otherwise.
 360  */
 361 bool files_write_bytes(FILE *out, UINT8 data[], size_t size);
 362
 363 /**
 364  * Reads a 16 bit value from a file converting from big endian to host
 365  * endianess.
 366  * @param out
 367  *  The file to read from.
 368  * @param data
 369  *  The data that is read, valid on a true return.
 370  * @return
 371  *  True on success, False on error.
 372  */
 373 bool files_read_16(FILE *out, UINT16 *data);
 374
 375 /**
 376  * Same as files_read_16 but for 32 bit values.
 377  */
 378 bool files_read_32(FILE *out, UINT32 *data);
 379
 380 /**
 381  * Same as files_read_16 but for 64 bit values.
 382  */
 383 bool files_read_64(FILE *out, UINT64 *data);
 384
 385 /**
 386  * Reads len bytes from a file.
 387  * @param out
 388  *  The file to read from.
 389  * @param data
 390  *  The buffer to read into, only valid on a True return.
 391  * @param size
 392  *  The number of bytes to read.
 393  * @return
 394  *  True on success, False otherwise.
 395  */
 396 bool files_read_bytes(FILE *out, UINT8 data[], size_t size);
 397
 398 #endif /* FILES_H */