blob: 23567b8e3523365ee0266f1df123f46d809108ae [file] [log] [blame]
Harrison Mutai88d6ec82025-08-12 14:32:58 +00001/*
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 */
25const struct event_log_algorithm *
26event_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 */
50size_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 */
75size_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 */