Linux-FSCrypt Archive on lore.kernel.org
 help / color / Atom feed
From: Eric Biggers <ebiggers@kernel.org>
To: Jes Sorensen <jes.sorensen@gmail.com>
Cc: linux-fscrypt@vger.kernel.org, kernel-team@fb.com,
	Jes Sorensen <jsorensen@fb.com>
Subject: Re: [PATCH 9/9] Document API of libfsverity
Date: Sat, 21 Mar 2020 22:54:08 -0700
Message-ID: <20200322055408.GJ111151@sol.localdomain> (raw)
In-Reply-To: <20200312214758.343212-10-Jes.Sorensen@gmail.com>

On Thu, Mar 12, 2020 at 05:47:58PM -0400, Jes Sorensen wrote:
> From: Jes Sorensen <jsorensen@fb.com>
> 
> Signed-off-by: Jes Sorensen <jsorensen@fb.com>
> ---
>  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

  reply index

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-12 21:47 [PATCH v3 0/9] Split fsverity-utils into a shared library Jes Sorensen
2020-03-12 21:47 ` [PATCH 1/9] Build basic shared library framework Jes Sorensen
2020-03-22  5:23   ` Eric Biggers
2020-03-22  5:33   ` Eric Biggers
2020-03-12 21:47 ` [PATCH 2/9] Change compute_file_measurement() to take a file descriptor as argument Jes Sorensen
2020-03-12 21:47 ` [PATCH 3/9] Move fsverity_descriptor definition to libfsverity.h Jes Sorensen
2020-03-22  4:57   ` Eric Biggers
2020-03-12 21:47 ` [PATCH 4/9] Move hash algorithm code to shared library Jes Sorensen
2020-03-22  5:38   ` Eric Biggers
2020-03-12 21:47 ` [PATCH 5/9] Create libfsverity_compute_digest() and adapt cmd_sign to use it Jes Sorensen
2020-03-22  5:40   ` Eric Biggers
2020-03-12 21:47 ` [PATCH 6/9] Introduce libfsverity_sign_digest() Jes Sorensen
2020-03-12 21:47 ` [PATCH 7/9] Validate input arguments to libfsverity_compute_digest() Jes Sorensen
2020-03-12 21:47 ` [PATCH 8/9] Validate input parameters for libfsverity_sign_digest() Jes Sorensen
2020-03-22  5:27   ` Eric Biggers
2020-03-12 21:47 ` [PATCH 9/9] Document API of libfsverity Jes Sorensen
2020-03-22  5:54   ` Eric Biggers [this message]
2020-03-22  5:05 ` [PATCH v3 0/9] Split fsverity-utils into a shared library Eric Biggers

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200322055408.GJ111151@sol.localdomain \
    --to=ebiggers@kernel.org \
    --cc=jes.sorensen@gmail.com \
    --cc=jsorensen@fb.com \
    --cc=kernel-team@fb.com \
    --cc=linux-fscrypt@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-FSCrypt Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-fscrypt/0 linux-fscrypt/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-fscrypt linux-fscrypt/ https://lore.kernel.org/linux-fscrypt \
		linux-fscrypt@vger.kernel.org
	public-inbox-index linux-fscrypt

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-fscrypt


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git