1 //**********************************************************************;
2 // Copyright (c) 2017, Intel Corporation
3 // All rights reserved.
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are met:
8 // 1. Redistributions of source code must retain the above copyright notice,
9 // this list of conditions and the following disclaimer.
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.
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.
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_
36 #include <tss2/tss2_sys.h>
39 * Iterator callback routine for iterating over known algorithm name and value
44 * The associated "nice-name".
46 * A user supplied data pointer.
48 * True to stop iterating, false to keep iterating.
50 typedef bool (*tpm2_alg_util_alg_iteraror)(TPM2_ALG_ID id, const char *name, void *userdata);
53 * Iterate over the algorithm name-value pairs calling the iterator callback for each pair.
55 * The iterator callback function.
57 * A pointer to user supplied data, this is passed to the iterator for each call.
59 void tpm2_alg_util_for_each_alg(tpm2_alg_util_alg_iteraror iterator, void *userdata);
62 * Convert a "nice-name" string to an algorithm id.
64 * The "nice-name" to convert.
66 * TPM2_ALG_ERROR on error, or a valid algorithm identifier.
68 TPM2_ALG_ID tpm2_alg_util_strtoalg(const char *name);
71 * Convert an id to a nice-name.
77 const char *tpm2_alg_util_algtostr(TPM2_ALG_ID id);
80 * Converts either a string from algrotithm number or algorithm nice-name to
83 * The string to convert from an algorithm number or nice name.
85 * TPM2_ALG_ERROR on error or the algorithm id.
87 TPM2_ALG_ID tpm2_alg_util_from_optarg(char *optarg);
90 * Detects if an algorithm is considered a hashing algorithm.
92 * The algorithm id to check.
94 * True if it is a hash algorithm, False otherwise.
96 bool tpm2_alg_util_is_hash_alg(TPM2_ALG_ID id);
99 * Contains the information from parsing an argv style vector of strings for
100 * pcr digest language specifications.
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;
109 * Parses an argv array that contains a digest specification at each location
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.
119 * - The hex hash value,
121 * This all distills to a string that looks like this:
122 * <pcr index>:<hash alg id>=<hash value>
125 * "4:sha=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"
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.
133 * At most 5 hash extensions per PCR entry are supported. This
134 * is to keep the parser simple.
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.
140 * The argv of digest specifications to parse.
142 * The number of digest specifications to parse.
144 * An array of tpm2_pcr_digest_spec big enough to hold len items.
146 * True if parsing was successful, False otherwise.
148 * This function logs errors via LOG_ERR.
150 bool pcr_parse_digest_list(char **argv, int len,
151 tpm2_pcr_digest_spec *digest_spec);
154 * Retrieves the size of a hash in bytes for a given hash
155 * algorithm or 0 if unknown/not found.
157 * The HASH algorithm identifier.
159 * 0 on failure or the size of the hash bytes.
161 UINT16 tpm2_alg_util_get_hash_size(TPMI_ALG_HASH id);
164 * Extracts the plain signature data without any headers
166 * Communicates errors via LOG_ERR.
169 * Will receive the number of bytes stored in buffer.
170 * @signature The actual signature struct to extract the plain signature from.
172 * Returns a buffer filled with the extracted signature or NULL on error.
173 * Needs to be free()'d by the caller.
175 UINT8* tpm2_extract_plain_signature(UINT16 *size, TPMT_SIGNATURE *signature);
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
183 * Handle to key used in signing operation
185 * Hash algoritm for message
187 * Signature scheme output
190 * False otherwise, and scheme is left unmodified
192 bool get_signature_scheme(TSS2_SYS_CONTEXT *sapi_context,
193 TPMI_DH_OBJECT keyHandle, TPMI_ALG_HASH halg,
194 TPMT_SIG_SCHEME *scheme);
196 #endif /* LIB_TPM2_ALG_UTIL_H_ */