Commit bde49334 authored by Eric Biggers's avatar Eric Biggers
Browse files

fs-verity: move structs needed for file signing to UAPI header 



Although it isn't used directly by the ioctls,
"struct fsverity_descriptor" is required by userspace programs that need
to compute fs-verity file digests in a standalone way.  Therefore
it's also needed to sign files in a standalone way.

Similarly, "struct fsverity_formatted_digest" (previously called
"struct fsverity_signed_digest" which was misleading) is also needed to
sign files if the built-in signature verification is being used.

Therefore, move these structs to the UAPI header.

While doing this, try to make it clear that the signature-related fields
in fsverity_descriptor aren't used in the file digest computation.

Acked-by: default avatarLuca Boccassi <luca.boccassi@microsoft.com>
Link: https://lore.kernel.org/r/20201113211918.71883-5-ebiggers@kernel.org


Signed-off-by: default avatarEric Biggers <ebiggers@google.com>
parent ed45e201

Documentation/filesystems/fsverity.rst

+1 −5
Original line number Diff line number Diff line
@@ -334,17 +334,13 @@ root hash as well as other fields such as the file size:: 
            __u8 hash_algorithm;    /* Merkle tree hash algorithm */

            __u8 log_blocksize;     /* log2 of size of data and tree blocks */

            __u8 salt_size;         /* size of salt in bytes; 0 if none */

            __le32 sig_size;        /* must be 0 */

            __le32 __reserved_0x04; /* must be 0 */

            __le64 data_size;       /* size of file the Merkle tree is built over */

            __u8 root_hash[64];     /* Merkle tree root hash */

            __u8 salt[32];          /* salt prepended to each hashed block */

            __u8 __reserved[144];   /* must be 0's */

    };



Note that the ``sig_size`` field must be set to 0 for the purpose of

computing the file measurement, even if a signature was provided (or

will be provided) to `FS_IOC_ENABLE_VERITY`_.



Built-in signature verification

===============================

fs/verity/fsverity_private.h

+0 −37
Original line number Diff line number Diff line
@@ -77,49 +77,12 @@ struct fsverity_info { 
	const struct inode *inode;

};



/*

 * Merkle tree properties.  The fs-verity file digest is the hash of this

 * structure excluding the signature and with the sig_size field set to 0.

 */

struct fsverity_descriptor {

	__u8 version;		/* must be 1 */

	__u8 hash_algorithm;	/* Merkle tree hash algorithm */

	__u8 log_blocksize;	/* log2 of size of data and tree blocks */

	__u8 salt_size;		/* size of salt in bytes; 0 if none */

	__le32 sig_size;	/* size of signature in bytes; 0 if none */

	__le64 data_size;	/* size of file the Merkle tree is built over */

	__u8 root_hash[64];	/* Merkle tree root hash */

	__u8 salt[32];		/* salt prepended to each hashed block */

	__u8 __reserved[144];	/* must be 0's */

	__u8 signature[];	/* optional PKCS#7 signature */

};



/* Arbitrary limit to bound the kmalloc() size.  Can be changed. */

#define FS_VERITY_MAX_DESCRIPTOR_SIZE	16384



#define FS_VERITY_MAX_SIGNATURE_SIZE	(FS_VERITY_MAX_DESCRIPTOR_SIZE - \

					 sizeof(struct fsverity_descriptor))



/*

 * Format in which fs-verity file digests are signed in built-in signatures.

 * This is the same as 'struct fsverity_digest', except here some magic bytes

 * are prepended to provide some context about what is being signed in case the

 * same key is used for non-fsverity purposes, and here the fields have fixed

 * endianness.

 *

 * This struct is specific to the built-in signature verification support, which

 * is optional.  fs-verity users may also verify signatures in userspace, in

 * which case userspace is responsible for deciding on what bytes are signed.

 * This struct may still be used, but it doesn't have to be.  For example,

 * userspace could instead use a string like "sha256:$digest_as_hex_string".

 */

struct fsverity_formatted_digest {

	char magic[8];			/* must be "FSVerity" */

	__le16 digest_algorithm;

	__le16 digest_size;

	__u8 digest[];

};



/* hash_algs.c */



extern struct fsverity_hash_alg fsverity_hash_algs[];

include/uapi/linux/fsverity.h

+49 −0
Original line number Diff line number Diff line
@@ -34,6 +34,55 @@ struct fsverity_digest { 
	__u8 digest[];

};



/*

 * Struct containing a file's Merkle tree properties.  The fs-verity file digest

 * is the hash of this struct.  A userspace program needs this struct only if it

 * needs to compute fs-verity file digests itself, e.g. in order to sign files.

 * It isn't needed just to enable fs-verity on a file.

 *

 * Note: when computing the file digest, 'sig_size' and 'signature' must be left

 * zero and empty, respectively.  These fields are present only because some

 * filesystems reuse this struct as part of their on-disk format.

 */

struct fsverity_descriptor {

	__u8 version;		/* must be 1 */

	__u8 hash_algorithm;	/* Merkle tree hash algorithm */

	__u8 log_blocksize;	/* log2 of size of data and tree blocks */

	__u8 salt_size;		/* size of salt in bytes; 0 if none */

#ifdef __KERNEL__

	__le32 sig_size;

#else

	__le32 __reserved_0x04;	/* must be 0 */

#endif

	__le64 data_size;	/* size of file the Merkle tree is built over */

	__u8 root_hash[64];	/* Merkle tree root hash */

	__u8 salt[32];		/* salt prepended to each hashed block */

	__u8 __reserved[144];	/* must be 0's */

#ifdef __KERNEL__

	__u8 signature[];

#endif

};



/*

 * Format in which fs-verity file digests are signed in built-in signatures.

 * This is the same as 'struct fsverity_digest', except here some magic bytes

 * are prepended to provide some context about what is being signed in case the

 * same key is used for non-fsverity purposes, and here the fields have fixed

 * endianness.

 *

 * This struct is specific to the built-in signature verification support, which

 * is optional.  fs-verity users may also verify signatures in userspace, in

 * which case userspace is responsible for deciding on what bytes are signed.

 * This struct may still be used, but it doesn't have to be.  For example,

 * userspace could instead use a string like "sha256:$digest_as_hex_string".

 */

struct fsverity_formatted_digest {

	char magic[8];			/* must be "FSVerity" */

	__le16 digest_algorithm;

	__le16 digest_size;

	__u8 digest[];

};



#define FS_IOC_ENABLE_VERITY	_IOW('f', 133, struct fsverity_enable_arg)

#define FS_IOC_MEASURE_VERITY	_IOWR('f', 134, struct fsverity_digest)

CRA Git | Maintained and supported by SUSTech CRA and CCSE