Harrison Mutai | 88d6ec8 | 2025-08-12 14:32:58 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright (c) 2025, Arm Limited. All rights reserved. |
| 3 | * |
| 4 | * SPDX-License-Identifier: BSD-3-Clause |
| 5 | */ |
| 6 | |
| 7 | #ifndef DIGEST_H |
| 8 | #define DIGEST_H |
| 9 | |
| 10 | #include <stddef.h> |
| 11 | #include <stdint.h> |
| 12 | |
| 13 | #include "event_log.h" |
| 14 | |
| 15 | /** |
| 16 | * @brief Lookup algorithm metadata by numeric identifier. |
| 17 | * |
| 18 | * Translates a TPM/TCG-style algorithm ID into a description structure |
| 19 | * containing name, digest length, and other properties. |
| 20 | * |
| 21 | * @param[in] algo_id Numeric algorithm identifier (e.g. TPM2_ALG_SHA256). |
| 22 | * |
| 23 | * @return Pointer to a constant algorithm descriptor, or NULL if not found. |
| 24 | */ |
| 25 | const struct event_log_algorithm * |
| 26 | event_log_algorithm_lookup(uint16_t algorithm_id); |
| 27 | |
| 28 | /** |
| 29 | * @brief Append a C-string to a growing buffer with running position. |
| 30 | * |
| 31 | * Appends as many characters from @p s as fit, ensuring NUL-termination if any |
| 32 | * bytes were copied. Advances @p *pos by the full length of @p s regardless of |
| 33 | * truncation, enabling “would-have-written” accounting at the call site. |
| 34 | * |
| 35 | * @param[in,out] dst Destination buffer. |
| 36 | * @param[in] cap Total capacity of @p dst (bytes, incl. space for NUL). |
| 37 | * @param[in,out] pos In: current logical length; Out: increased by strlen(@p s). |
| 38 | * @param[in] s NUL-terminated string to append. |
| 39 | * |
| 40 | * @return strlen(@p s). |
| 41 | * |
| 42 | * @note Intended usage pattern: |
| 43 | * @code |
| 44 | * size_t pos = 0; buf[0] = '\0'; |
| 45 | * append_str(buf, cap, &pos, "prefix: "); |
| 46 | * append_str(buf, cap, &pos, value); |
| 47 | * bool truncated = (pos >= cap); |
| 48 | * @endcode |
| 49 | */ |
| 50 | size_t event_log_append_str(char *dst, size_t cap, size_t *pos, const char *s); |
| 51 | |
| 52 | /** |
| 53 | * @brief Convert bytes to lower-hex with spaces (e.g., "aa ff …"). |
| 54 | * |
| 55 | * Writes at most @p dst_len bytes including the terminating NUL (if @p dst_len > 0). |
| 56 | * Always returns the number of characters that would have been written |
| 57 | * (excluding the NUL), so you can detect truncation by checking |
| 58 | * `return_value >= dst_len`. |
| 59 | * |
| 60 | * @param[out] dst Destination buffer for ASCII hex; may be NULL only if @p dst_len == 0. |
| 61 | * @param[in] dst_len Capacity of @p dst in bytes (including room for NUL). |
| 62 | * @param[in] nbytes Number of input bytes to render. |
| 63 | * @param[in] digest Pointer to @p nbytes of data; not modified. |
| 64 | * |
| 65 | * @return Characters that would have been written (excluding the terminating NUL). |
| 66 | * |
| 67 | * Example: |
| 68 | * @code |
| 69 | * // For 3 bytes, required size is 3*3 - 1 + 1 (for NUL) = 9 |
| 70 | * char buf[9]; |
| 71 | * size_t need = write_hex_spaced(buf, sizeof buf, 3, in); |
| 72 | * bool truncated = (need >= sizeof buf); |
| 73 | * @endcode |
| 74 | */ |
| 75 | size_t event_log_write_hex_spaced(char *dst, size_t dst_len, size_t nbytes, |
| 76 | const uint8_t *digest); |
| 77 | |
| 78 | #endif /* DIGEST_H */ |