[9/9] Document API of libfsverity

Commit Message

Jes Sorensen March 12, 2020, 9:47 p.m. UTC

From: Jes Sorensen <[e-mail]>

Signed-off-by: Jes Sorensen <[e-mail]>
---
 libfsverity.h | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

Comments

Eric Biggers March 22, 2020, 5:54 a.m. UTC | #1

On Thu, Mar 12, 2020 at 05:47:58PM -0400, Jes Sorensen wrote:
> From: Jes Sorensen <[e-mail]>
> 
> Signed-off-by: Jes Sorensen <[e-mail]>
> ---
>  libfsverity.h | 45 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 45 insertions(+)
> 
> diff --git a/libfsverity.h b/libfsverity.h
> index a2abdb3..f6c4b13 100644
> --- a/libfsverity.h
> +++ b/libfsverity.h
> @@ -64,18 +64,63 @@ struct fsverity_hash_alg {
>  	struct hash_ctx *(*create_ctx)(const struct fsverity_hash_alg *alg);
>  };
>  
> +/*
> + * libfsverity_compute_digest - Compute digest of a file
> + * @fd: open file descriptor of file to compute digest for
> + * @params: struct libfsverity_merkle_tree_params specifying hash algorithm,
> + *	    block size, version, and optional salt parameters.
> + *	    reserved parameters must be zero.
> + * @digest_ret: Pointer to pointer for computed digest
> + *
> + * Returns:
> + * * 0 for success, -EINVAL for invalid input arguments, -ENOMEM if failed
> + *   to allocate memory, -EBADF if fd is invalid, and -EAGAIN if root hash
> + *   fails to compute.
> + * * digest_ret returns a pointer to the digest on success.
> + */
>  int
>  libfsverity_compute_digest(int fd,
>  			   const struct libfsverity_merkle_tree_params *params,
>  			   struct libfsverity_digest **digest_ret);

Can you add a brief explanation here that clarifies that the "digest of a file"
in this context means fs-verity's Merkle tree-based hash (what the kernel calls
the "file measurement"), not a standard file hash?  These could easily be
confused, especially by people not as familiar with fs-verity.

Also, it's important to also mention that the digest needs to be free()d.

>  
> +/*
> + * libfsverity_sign_digest - Sign previously computed digest of a file
> + * @digest: pointer to previously computed digest
> + * @sig_params: struct libfsverity_signature_params providing filenames of
> + *          the keyfile and certificate file. Reserved parameters must be zero.
> + * @sig_ret: Pointer to pointer for signed digest
> + * @sig_size_ret: Pointer to size of signed return digest
> + *
> + * Returns:
> + * * 0 for success, -EINVAL for invalid input arguments, -EAGAIN if key or
> + *   certificate files fail to read, or if signing the digest fails.
> + * * sig_ret returns a pointer to the signed digest on success.
> + * * sig_size_ret returns the size of the signed digest on success.
> + */
>  int
>  libfsverity_sign_digest(const struct libfsverity_digest *digest,
>  			const struct libfsverity_signature_params *sig_params,
>  			uint8_t **sig_ret, size_t *sig_size_ret);

Can you add some more details here?  What is the signature for, what type of
signature is it, what format do the key file and certificate file need to be in,
what crypto algorithms do they need to use, etc.?

(I know, I need to add a man page for the 'fsverity' program that explains this
too.  There's some explanation in the README but not enough.)

Also, it's important to mention that the signature needs to be free()d.

> +/*
> + * libfsverity_find_hash_alg_by_name - Find hash algorithm by name
> + * @name: Pointer to name of hash algorithm
> + *
> + * Returns:
> + * struct fsverity_hash_alg success
> + * NULL on error
> + */

We should be more specific and write "NULL if not found", since "not found" is
the only type of error that makes sense for this.

>  const struct fsverity_hash_alg *
>  libfsverity_find_hash_alg_by_name(const char *name);
> +
> +/*
> + * libfsverity_find_hash_alg_by_num - Find hash algorithm by number
> + * @name: Number of hash algorithm
> + *
> + * Returns:
> + * struct fsverity_hash_alg success
> + * NULL on error
> + */
>  const struct fsverity_hash_alg *
>  libfsverity_find_hash_alg_by_num(unsigned int num);

Likewise.

- Eric

Patch

diff --git a/libfsverity.h b/libfsverity.h
index a2abdb3..f6c4b13 100644
--- a/libfsverity.h
+++ b/libfsverity.h
@@ -64,18 +64,63 @@  struct fsverity_hash_alg {
 	struct hash_ctx *(*create_ctx)(const struct fsverity_hash_alg *alg);
 };
 
+/*
+ * libfsverity_compute_digest - Compute digest of a file
+ * @fd: open file descriptor of file to compute digest for
+ * @params: struct libfsverity_merkle_tree_params specifying hash algorithm,
+ *	    block size, version, and optional salt parameters.
+ *	    reserved parameters must be zero.
+ * @digest_ret: Pointer to pointer for computed digest
+ *
+ * Returns:
+ * * 0 for success, -EINVAL for invalid input arguments, -ENOMEM if failed
+ *   to allocate memory, -EBADF if fd is invalid, and -EAGAIN if root hash
+ *   fails to compute.
+ * * digest_ret returns a pointer to the digest on success.
+ */
 int
 libfsverity_compute_digest(int fd,
 			   const struct libfsverity_merkle_tree_params *params,
 			   struct libfsverity_digest **digest_ret);
 
+/*
+ * libfsverity_sign_digest - Sign previously computed digest of a file
+ * @digest: pointer to previously computed digest
+ * @sig_params: struct libfsverity_signature_params providing filenames of
+ *          the keyfile and certificate file. Reserved parameters must be zero.
+ * @sig_ret: Pointer to pointer for signed digest
+ * @sig_size_ret: Pointer to size of signed return digest
+ *
+ * Returns:
+ * * 0 for success, -EINVAL for invalid input arguments, -EAGAIN if key or
+ *   certificate files fail to read, or if signing the digest fails.
+ * * sig_ret returns a pointer to the signed digest on success.
+ * * sig_size_ret returns the size of the signed digest on success.
+ */
 int
 libfsverity_sign_digest(const struct libfsverity_digest *digest,
 			const struct libfsverity_signature_params *sig_params,
 			uint8_t **sig_ret, size_t *sig_size_ret);
 
+/*
+ * libfsverity_find_hash_alg_by_name - Find hash algorithm by name
+ * @name: Pointer to name of hash algorithm
+ *
+ * Returns:
+ * struct fsverity_hash_alg success
+ * NULL on error
+ */
 const struct fsverity_hash_alg *
 libfsverity_find_hash_alg_by_name(const char *name);
+
+/*
+ * libfsverity_find_hash_alg_by_num - Find hash algorithm by number
+ * @name: Number of hash algorithm
+ *
+ * Returns:
+ * struct fsverity_hash_alg success
+ * NULL on error
+ */
 const struct fsverity_hash_alg *
 libfsverity_find_hash_alg_by_num(unsigned int num);