Line data Source code
1 1 : /*
2 : * Copyright (c) 2025, SECO Mind Srl
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_SYS_UUID_H_
8 : #define ZEPHYR_INCLUDE_SYS_UUID_H_
9 :
10 : /**
11 : * @file
12 : *
13 : * @brief Utility functions for the generation and parsing of Universal Unique Identifier.
14 : * @details This driver is compliant with RFC9562: https://datatracker.ietf.org/doc/rfc9562/
15 : */
16 :
17 : #include <zephyr/kernel.h>
18 : #include <zephyr/types.h>
19 :
20 : #ifdef __cplusplus
21 : extern "C" {
22 : #endif
23 :
24 : /**
25 : * @defgroup uuid UUID
26 : * @since 4.0
27 : * @version 0.1.0
28 : * @ingroup utilities
29 : * @{
30 : */
31 :
32 : /** @brief Number of bytes in the binary representation of a UUID. */
33 1 : #define UUID_SIZE 16U
34 :
35 : /** @brief Length of the UUID canonical string representation, including the NULL terminator. */
36 1 : #define UUID_STR_LEN 37U
37 :
38 : /** @brief Length of the UUID base64 string representation, including the NULL terminator. */
39 1 : #define UUID_BASE64_LEN 25U
40 :
41 : /**
42 : * @brief Length of the UUID base64 URL and filename safe string representation, including the
43 : * NULL terminator.
44 : */
45 1 : #define UUID_BASE64URL_LEN 23U
46 :
47 : /** @brief Binary representation of a UUID. */
48 1 : struct uuid {
49 : /** @cond INTERNAL_HIDDEN */
50 : uint8_t val[UUID_SIZE];
51 : /** @endcond */
52 : };
53 :
54 : /**
55 : * @brief Generate a UUIDv4.
56 : *
57 : * @param out The UUID where the result will be written.
58 : *
59 : * @retval 0 The UUID has been correctly generated and stored in @p out
60 : * @retval -EINVAL @p out is not acceptable
61 : */
62 1 : int uuid_generate_v4(struct uuid *out);
63 :
64 : /**
65 : * @brief Generate a UUIDv5.
66 : *
67 : * @details This function computes a deterministic UUID starting from a namespace UUID and binary
68 : * data.
69 : *
70 : * @param ns A pointer to an UUID to be used as namespace.
71 : * @param data A pointer to the data that will be hashed to produce the UUID.
72 : * @param data_size The size of the data buffer.
73 : * @param out The UUID where the result will be written.
74 : *
75 : * @retval 0 The UUID has been correctly generated and stored in @p out
76 : * @retval -EINVAL @p out is not acceptable
77 : * @retval -ENOMEM Memory allocation failed
78 : * @retval -ENOTSUP mbedTLS returned an unrecognized error
79 : */
80 1 : int uuid_generate_v5(const struct uuid *ns, const void *data, size_t data_size,
81 : struct uuid *out);
82 :
83 : /**
84 : * @brief Copy an UUID into another UUID.
85 : *
86 : * @param data Input data to copy.
87 : * @param out Destination for the copy.
88 : *
89 : * @retval 0 The UUID has been correctly copied in @p dst
90 : * @retval -EINVAL @p dst is not acceptable
91 : */
92 1 : int uuid_copy(const struct uuid *data, struct uuid *out);
93 :
94 : /**
95 : * @brief Create a uuid_t from a binary (big-endian) formatted UUID.
96 : *
97 : * @param data The buffer where the binary UUID is stored in a big-endian order.
98 : * @param out The UUID where the result will be written.
99 : *
100 : * @retval 0 The UUID has been correctly parsed and stored in @p out
101 : * @retval -EINVAL @p data or @p out are not acceptable
102 : */
103 1 : int uuid_from_buffer(const uint8_t data[UUID_SIZE], struct uuid *out);
104 :
105 : /**
106 : * @brief Parse a UUID from its canonical (RFC9562) string representation.
107 : *
108 : * @param data A pointer to the string to be parsed.
109 : * @param out The UUID where the result will be written.
110 : *
111 : * @retval 0 The UUID has been correctly parsed and stored in @p out
112 : * @retval -EINVAL @p input or @p out are not acceptable
113 : */
114 1 : int uuid_from_string(const char data[UUID_STR_LEN], struct uuid *out);
115 :
116 : /**
117 : * @brief Create a uuid_t from a binary (big-endian) formatted UUID.
118 : *
119 : * @param data The input UUID to store in the buffer.
120 : * @param out The buffer where the binary UUID is stored in a big-endian order.
121 : *
122 : * @retval 0 The UUID has been correctly parsed and stored in @p buff
123 : * @retval -EINVAL @p buff is not acceptable
124 : */
125 1 : int uuid_to_buffer(const struct uuid *data, uint8_t out[UUID_SIZE]);
126 :
127 : /**
128 : * @brief Convert a UUID to its canonical (RFC9562) string representation.
129 : *
130 : * @param data The UUID to convert to string.
131 : * @param out A pointer to a previously allocated buffer where the result will be written.
132 : *
133 : * @retval 0 The UUID has been converted and written in @p out
134 : * @retval -EINVAL @p out is not acceptable
135 : */
136 1 : int uuid_to_string(const struct uuid *data, char out[UUID_STR_LEN]);
137 :
138 : /**
139 : * @brief Convert a UUID to its base 64 (RFC 3548, RFC 4648) string representation.
140 : *
141 : * @param data The UUID to convert to string.
142 : * @param out A pointer to a previously allocated buffer where the result will be written.
143 : *
144 : * @retval 0 The UUID has been converted and written in @p out
145 : * @retval -EINVAL @p out is not acceptable
146 : */
147 1 : int uuid_to_base64(const struct uuid *data, char out[UUID_BASE64_LEN]);
148 :
149 : /**
150 : * @brief Convert a UUID to its base 64 (RFC 4648 sec. 5) URL and filename safe string
151 : * representation.
152 : *
153 : * @param data The UUID to convert to string.
154 : * @param out A pointer to a previously allocated buffer where the result will be written.
155 : *
156 : * @retval 0 The UUID has been converted and written in @p out
157 : * @retval -EINVAL @p out is not acceptable
158 : */
159 1 : int uuid_to_base64url(const struct uuid *data, char out[UUID_BASE64URL_LEN]);
160 :
161 : /**
162 : * @}
163 : */
164 :
165 : #ifdef __cplusplus
166 : }
167 : #endif
168 :
169 : #endif /* ZEPHYR_INCLUDE_SYS_UUID_H_ */
|
