TPM2-Plugin/lib/include/tpm2_alg_util.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 LIB_TPM2_ALG_UTIL_H_
  32 #define LIB_TPM2_ALG_UTIL_H_
  33
  34 #include <stdbool.h>
  35
  36 #include <tss2/tss2_sys.h>
  37
  38 /**
  39  * Iterator callback routine for iterating over known algorithm name and value
  40  * pairs.
  41  * @param id
  42  *  The algorithm id.
  43  * @param name
  44  *  The associated "nice-name".
  45  * @param userdata
  46  *  A user supplied data pointer.
  47  * @return
  48  *  True to stop iterating, false to keep iterating.
  49  */
  50 typedef bool (*tpm2_alg_util_alg_iteraror)(TPM2_ALG_ID id, const char *name, void *userdata);
  51
  52 /**
  53  * Iterate over the algorithm name-value pairs calling the iterator callback for each pair.
  54  * @param iterator
  55  *  The iterator callback function.
  56  * @param userdata
  57  *  A pointer to user supplied data, this is passed to the iterator for each call.
  58  */
  59 void tpm2_alg_util_for_each_alg(tpm2_alg_util_alg_iteraror iterator, void *userdata);
  60
  61 /**
  62  * Convert a "nice-name" string to an algorithm id.
  63  * @param name
  64  *  The "nice-name" to convert.
  65  * @return
  66  *  TPM2_ALG_ERROR on error, or a valid algorithm identifier.
  67  */
  68 TPM2_ALG_ID tpm2_alg_util_strtoalg(const char *name);
  69
  70 /**
  71  * Convert an id to a nice-name.
  72  * @param id
  73  *  The id to convert.
  74  * @return
  75  *  The nice-name.
  76  */
  77 const char *tpm2_alg_util_algtostr(TPM2_ALG_ID id);
  78
  79 /**
  80  * Converts either a string from algrotithm number or algorithm nice-name to
  81  * an algorithm id.
  82  * @param optarg
  83  *  The string to convert from an algorithm number or nice name.
  84  * @return
  85  *  TPM2_ALG_ERROR on error or the algorithm id.
  86  */
  87 TPM2_ALG_ID tpm2_alg_util_from_optarg(char *optarg);
  88
  89 /**
  90  * Detects if an algorithm is considered a hashing algorithm.
  91  * @param id
  92  *  The algorithm id to check.
  93  * @return
  94  *  True if it is a hash algorithm, False otherwise.
  95  */
  96 bool tpm2_alg_util_is_hash_alg(TPM2_ALG_ID id);
  97
  98 /**
  99  * Contains the information from parsing an argv style vector of strings for
 100  * pcr digest language specifications.
 101  */
 102 typedef struct tpm2_pcr_digest_spec tpm2_pcr_digest_spec;
 103 struct tpm2_pcr_digest_spec {
 104     TPML_DIGEST_VALUES digests;
 105     TPMI_DH_PCR pcr_index;
 106 };
 107
 108 /**
 109  * Parses an argv array that contains a digest specification at each location
 110  * within argv.
 111  *
 112  * The digest specification is as follows:
 113  *   - A pcr identifier as understood by strtoul with 0 as the base.
 114  *   - A colon followed by the algorithm hash specification.
 115  *   - The algorithm hash specification is as follows:
 116  *       - The algorithm friendly name or raw numerical as understood by
 117  *         strtoul with a base of 0.
 118  *       - An equals sign
 119  *       - The hex hash value,
 120  *
 121  *   This all distills to a string that looks like this:
 122  *   <pcr index>:<hash alg id>=<hash value>
 123  *
 124  *   Example:
 125  *   "4:sha=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"
 126  *
 127  *   Note:
 128  *   Multiple specifications of PCR and hash are OK. Multiple hashes
 129  *   cause the pcr to be extended with both hashes. Multiple same PCR
 130  *   values cause the PCR to be extended multiple times. Extension
 131  *   is done in order from left to right as specified.
 132  *
 133  *   At most 5 hash extensions per PCR entry are supported. This
 134  *   is to keep the parser simple.
 135  *
 136  * @param sapi_context
 137  *  The system API context for hashing files with the tpm. This can
 138  *  be NULL if the argument vector doesn't have a file spec for the hash.
 139  * @param argv
 140  *  The argv of digest specifications to parse.
 141  * @param len
 142  *  The number of digest specifications to parse.
 143  * @param digests
 144  *  An array of tpm2_pcr_digest_spec big enough to hold len items.
 145  * @return
 146  *  True if parsing was successful, False otherwise.
 147  *  @note
 148  *  This function logs errors via LOG_ERR.
 149  */
 150 bool pcr_parse_digest_list(char **argv, int len,
 151         tpm2_pcr_digest_spec *digest_spec);
 152
 153 /**
 154  * Retrieves the size of a hash in bytes for a given hash
 155  * algorithm or 0 if unknown/not found.
 156  * @param id
 157  *  The HASH algorithm identifier.
 158  * @return
 159  *  0 on failure or the size of the hash bytes.
 160  */
 161 UINT16 tpm2_alg_util_get_hash_size(TPMI_ALG_HASH id);
 162
 163 /**
 164  * Extracts the plain signature data without any headers
 165  *
 166  * Communicates errors via LOG_ERR.
 167  *
 168  * @param size
 169  *  Will receive the number of bytes stored in buffer.
 170  * @signature The actual signature struct to extract the plain signature from.
 171  * @return
 172  *  Returns a buffer filled with the extracted signature or NULL on error.
 173  *  Needs to be free()'d by the caller.
 174  */
 175 UINT8* tpm2_extract_plain_signature(UINT16 *size, TPMT_SIGNATURE *signature);
 176
 177 /**
 178  * Retrieves an approproate signature scheme (scheme) signable by
 179  * specified key (keyHandle) and hash algorithm (halg).
 180  * @param sapi_context
 181  *  System API context for tpm
 182  * @param keyHandle
 183  *  Handle to key used in signing operation
 184  * @param halg
 185  *  Hash algoritm for message
 186  * @param scheme
 187  *  Signature scheme output
 188  * @return
 189  *  True if successful
 190  *  False otherwise, and scheme is left unmodified
 191  */
 192 bool get_signature_scheme(TSS2_SYS_CONTEXT *sapi_context,
 193         TPMI_DH_OBJECT keyHandle, TPMI_ALG_HASH halg,
 194         TPMT_SIG_SCHEME *scheme);
 195
 196 #endif /* LIB_TPM2_ALG_UTIL_H_ */