Debian Codegraph @

include/libfsverity.h

raw
1 /* SPDX-License-Identifier: MIT */
2 /*
3 * libfsverity API
4 *
5 * Copyright 2018 Google LLC
6 * Copyright (C) 2020 Facebook
7 *
8 * Use of this source code is governed by an MIT-style
9 * license that can be found in the LICENSE file or at
10 * https://opensource.org/licenses/MIT.
11 */
12
13 #ifndef LIBFSVERITY_H
14 #define LIBFSVERITY_H
15
16 #include <errno.h>
17 #include <stddef.h>
18 #include <stdint.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 #define FSVERITY_UTILS_MAJOR_VERSION 1
25 #define FSVERITY_UTILS_MINOR_VERSION 6
26
27 #define FS_VERITY_HASH_ALG_SHA256 1
28 #define FS_VERITY_HASH_ALG_SHA512 2
29
30 /**
31 * struct libfsverity_merkle_tree_params - properties of a file's Merkle tree
32 *
33 * Zero this, then fill in at least @version and @file_size.
34 */
35 struct libfsverity_merkle_tree_params {
36
37 /** @version: must be 1 */
38 uint32_t version;
39
40 /**
41 * @hash_algorithm: one of FS_VERITY_HASH_ALG_*, or 0 to use the default
42 * of FS_VERITY_HASH_ALG_SHA256
43 */
44 uint32_t hash_algorithm;
45
46 /** @file_size: the file size in bytes */
47 uint64_t file_size;
48
49 /**
50 * @block_size: the Merkle tree block size in bytes, or 0 to use the
51 * default of 4096 bytes
52 */
53 uint32_t block_size;
54
55 /** @salt_size: the salt size in bytes, or 0 if unsalted */
56 uint32_t salt_size;
57
58 /** @salt: pointer to the salt, or NULL if unsalted */
59 const uint8_t *salt;
60
61 /** @reserved1: must be 0 */
62 uint64_t reserved1[8];
63
64 /**
65 * @metadata_callbacks: if non-NULL, this gives a set of callback
66 * functions to which libfsverity_compute_digest() will pass the Merkle
67 * tree blocks and fs-verity descriptor after they are computed.
68 * Normally this isn't useful, but this can be needed in rare cases
69 * where the metadata needs to be consumed by something other than one
70 * of the native Linux kernel implementations of fs-verity.
71 */
72 const struct libfsverity_metadata_callbacks *metadata_callbacks;
73
74 /** @reserved2: must be 0 */
75 uintptr_t reserved2[7];
76 };
77
78 struct libfsverity_digest {
79 uint16_t digest_algorithm; /* one of FS_VERITY_HASH_ALG_* */
80 uint16_t digest_size; /* digest size in bytes */
81 uint8_t digest[]; /* the actual digest */
82 };
83
84 /**
85 * struct libfsverity_signature_params - certificate and private key information
86 *
87 * Zero this, then set @certfile. Then, to specify the private key by key file,
88 * set @keyfile. Alternatively, to specify the private key by PKCS#11 token,
89 * set @pkcs11_engine, @pkcs11_module, and optionally @pkcs11_keyid.
90 *
91 * Support for PKCS#11 tokens is unavailable when libfsverity was linked to
92 * BoringSSL rather than OpenSSL.
93 */
94 struct libfsverity_signature_params {
95
96 /** @keyfile: the path to the key file in PEM format, when applicable */
97 const char *keyfile;
98
99 /** @certfile: the path to the certificate file in PEM format */
100 const char *certfile;
101
102 /** @reserved1: must be 0 */
103 uint64_t reserved1[8];
104
105 /**
106 * @pkcs11_engine: the path to the PKCS#11 engine .so file, when
107 * applicable
108 */
109 const char *pkcs11_engine;
110
111 /**
112 * @pkcs11_module: the path to the PKCS#11 module .so file, when
113 * applicable
114 */
115 const char *pkcs11_module;
116
117 /** @pkcs11_keyid: the PKCS#11 key identifier, when applicable */
118 const char *pkcs11_keyid;
119
120 /** @reserved2: must be 0 */
121 uintptr_t reserved2[5];
122 };
123
124 struct libfsverity_metadata_callbacks {
125
126 /** @ctx: context passed to the below callbacks (opaque to library) */
127 void *ctx;
128
129 /**
130 * @merkle_tree_size: if non-NULL, called with the total size of the
131 * Merkle tree in bytes, prior to any call to @merkle_tree_block. Must
132 * return 0 on success, or a negative errno value on failure.
133 */
134 int (*merkle_tree_size)(void *ctx, uint64_t size);
135
136 /**
137 * @merkle_tree_block: if non-NULL, called with each block of the
138 * Merkle tree after it is computed. The offset is the offset in bytes
139 * to the block within the Merkle tree, using the Merkle tree layout
140 * used by FS_IOC_READ_VERITY_METADATA. The offsets won't necessarily
141 * be in increasing order. Must return 0 on success, or a negative
142 * errno value on failure.
143 */
144 int (*merkle_tree_block)(void *ctx, const void *block, size_t size,
145 uint64_t offset);
146
147 /**
148 * @descriptor: if non-NULL, called with the fs-verity descriptor after
149 * it is computed. Must return 0 on success, or a negative errno value
150 * on failure.
151 */
152 int (*descriptor)(void *ctx, const void *descriptor, size_t size);
153 };
154
155 /*
156 * libfsverity_read_fn_t - callback that incrementally provides a file's data
157 * @fd: the user-provided "file descriptor" (opaque to library)
158 * @buf: buffer into which to read the next chunk of the file's data
159 * @count: number of bytes to read in this chunk
160 *
161 * Must return 0 on success (all 'count' bytes read), or a negative errno value
162 * on failure.
163 */
164 typedef int (*libfsverity_read_fn_t)(void *fd, void *buf, size_t count);
165
166 /**
167 * libfsverity_compute_digest() - Compute digest of a file
168 * A fs-verity file digest is the hash of a file's fsverity_descriptor.
169 * Not to be confused with a traditional file digest computed over the
170 * entire file, or with the bare fsverity_descriptor::root_hash.
171 * @fd: context that will be passed to @read_fn
172 * @read_fn: a function that will read the data of the file
173 * @params: Pointer to the Merkle tree parameters
174 * @digest_ret: Pointer to pointer for computed digest.
175 *
176 * Returns:
177 * * 0 for success, -EINVAL for invalid input arguments, -ENOMEM if libfsverity
178 * failed to allocate memory, or an error returned by @read_fn or by one of
179 * the @params->metadata_callbacks.
180 * * digest_ret returns a pointer to the digest on success. The digest object
181 * is allocated by libfsverity and must be freed by the caller using free().
182 */
183 int
184 libfsverity_compute_digest(void *fd, libfsverity_read_fn_t read_fn,
185 const struct libfsverity_merkle_tree_params *params,
186 struct libfsverity_digest **digest_ret);
187
188 /**
189 * libfsverity_sign_digest() - Sign a file for built-in signature verification
190 * Sign a file digest in a way that is compatible with the Linux
191 * kernel's fs-verity built-in signature verification support. The
192 * resulting signature will be a PKCS#7 message in DER format. Note
193 * that this is not the only way to do signatures with fs-verity. For
194 * more details, refer to the fsverity-utils README and to
195 * Documentation/filesystems/fsverity.rst in the kernel source tree.
196 * @digest: pointer to previously computed digest
197 * @sig_params: pointer to the certificate and private key information
198 * @sig_ret: Pointer to pointer for signed digest
199 * @sig_size_ret: Pointer to size of signed return digest
200 *
201 * Return:
202 * * 0 for success, -EINVAL for invalid input arguments or if the cryptographic
203 * operations to sign the digest failed, -EBADMSG if the key and/or
204 * certificate file is invalid, or another negative errno value.
205 * * sig_ret returns a pointer to the signed digest on success. This object
206 * is allocated by libfsverity and must be freed by the caller using free().
207 * * sig_size_ret returns the size (in bytes) of the signed digest on success.
208 */
209 int
210 libfsverity_sign_digest(const struct libfsverity_digest *digest,
211 const struct libfsverity_signature_params *sig_params,
212 uint8_t **sig_ret, size_t *sig_size_ret);
213
214 /**
215 * libfsverity_enable() - Enable fs-verity on a file
216 * @fd: read-only file descriptor to the file
217 * @params: pointer to the Merkle tree parameters
218 *
219 * This is a simple wrapper around the FS_IOC_ENABLE_VERITY ioctl.
220 *
221 * Return: 0 on success, -EINVAL for invalid arguments, or a negative errno
222 * value from the FS_IOC_ENABLE_VERITY ioctl. See
223 * Documentation/filesystems/fsverity.rst in the kernel source tree for
224 * the possible error codes from FS_IOC_ENABLE_VERITY.
225 */
226 int
227 libfsverity_enable(int fd, const struct libfsverity_merkle_tree_params *params);
228
229 /**
230 * libfsverity_enable_with_sig() - Enable fs-verity on a file, with a signature
231 * @fd: read-only file descriptor to the file
232 * @params: pointer to the Merkle tree parameters
233 * @sig: pointer to the file's signature
234 * @sig_size: size of the file's signature in bytes
235 *
236 * Like libfsverity_enable(), but allows specifying a built-in signature (i.e. a
237 * singature created with libfsverity_sign_digest()) to associate with the file.
238 * This is only needed if the in-kernel signature verification support is being
239 * used; it is not needed if signatures are being verified in userspace.
240 *
241 * If @sig is NULL and @sig_size is 0, this is the same as libfsverity_enable().
242 *
243 * Return: See libfsverity_enable().
244 */
245 int
246 libfsverity_enable_with_sig(int fd,
247 const struct libfsverity_merkle_tree_params *params,
248 const uint8_t *sig, size_t sig_size);
249
250 /**
251 * libfsverity_find_hash_alg_by_name() - Find hash algorithm by name
252 * @name: Pointer to name of hash algorithm
253 *
254 * Return: The hash algorithm number, or zero if not found.
255 */
256 uint32_t libfsverity_find_hash_alg_by_name(const char *name);
257
258 /**
259 * libfsverity_get_digest_size() - Get size of digest for a given algorithm
260 * @alg_num: Number of hash algorithm
261 *
262 * Return: size of digest in bytes, or -1 if algorithm is unknown.
263 */
264 int libfsverity_get_digest_size(uint32_t alg_num);
265
266 /**
267 * libfsverity_get_hash_name() - Get name of hash algorithm by number
268 * @alg_num: Number of hash algorithm
269 *
270 * Return: The name of the hash algorithm, or NULL if algorithm is unknown.
271 */
272 const char *libfsverity_get_hash_name(uint32_t alg_num);
273
274 /**
275 * libfsverity_set_error_callback() - Set callback to handle error messages
276 * @cb: the callback function.
277 *
278 * If a callback is already set, it is replaced. @cb may be NULL in order to
279 * remove the existing callback.
280 */
281 void libfsverity_set_error_callback(void (*cb)(const char *msg));
282
283 #ifdef __cplusplus
284 }
285 #endif
286
287 #endif /* LIBFSVERITY_H */