uapi/linux/fsverity.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 /*
0003  * fs-verity user API
0004  *
0005  * These ioctls can be used on filesystems that support fs-verity.  See the
0006  * "User API" section of Documentation/filesystems/fsverity.rst.
0007  *
0008  * Copyright 2019 Google LLC
0009  */
0010 #ifndef _UAPI_LINUX_FSVERITY_H
0011 #define _UAPI_LINUX_FSVERITY_H
0012
0013 #include <linux/ioctl.h>
0014 #include <linux/types.h>
0015
0016 #define FS_VERITY_HASH_ALG_SHA256   1
0017 #define FS_VERITY_HASH_ALG_SHA512   2
0018
0019 struct fsverity_enable_arg {
0020     __u32 version;
0021     __u32 hash_algorithm;
0022     __u32 block_size;
0023     __u32 salt_size;
0024     __u64 salt_ptr;
0025     __u32 sig_size;
0026     __u32 __reserved1;
0027     __u64 sig_ptr;
0028     __u64 __reserved2[11];
0029 };
0030
0031 struct fsverity_digest {
0032     __u16 digest_algorithm;
0033     __u16 digest_size; /* input/output */
0034     __u8 digest[];
0035 };
0036
0037 /*
0038  * Struct containing a file's Merkle tree properties.  The fs-verity file digest
0039  * is the hash of this struct.  A userspace program needs this struct only if it
0040  * needs to compute fs-verity file digests itself, e.g. in order to sign files.
0041  * It isn't needed just to enable fs-verity on a file.
0042  *
0043  * Note: when computing the file digest, 'sig_size' and 'signature' must be left
0044  * zero and empty, respectively.  These fields are present only because some
0045  * filesystems reuse this struct as part of their on-disk format.
0046  */
0047 struct fsverity_descriptor {
0048     __u8 version;       /* must be 1 */
0049     __u8 hash_algorithm;    /* Merkle tree hash algorithm */
0050     __u8 log_blocksize; /* log2 of size of data and tree blocks */
0051     __u8 salt_size;     /* size of salt in bytes; 0 if none */
0052 #ifdef __KERNEL__
0053     __le32 sig_size;
0054 #else
0055     __le32 __reserved_0x04; /* must be 0 */
0056 #endif
0057     __le64 data_size;   /* size of file the Merkle tree is built over */
0058     __u8 root_hash[64]; /* Merkle tree root hash */
0059     __u8 salt[32];      /* salt prepended to each hashed block */
0060     __u8 __reserved[144];   /* must be 0's */
0061 #ifdef __KERNEL__
0062     __u8 signature[];
0063 #endif
0064 };
0065
0066 /*
0067  * Format in which fs-verity file digests are signed in built-in signatures.
0068  * This is the same as 'struct fsverity_digest', except here some magic bytes
0069  * are prepended to provide some context about what is being signed in case the
0070  * same key is used for non-fsverity purposes, and here the fields have fixed
0071  * endianness.
0072  *
0073  * This struct is specific to the built-in signature verification support, which
0074  * is optional.  fs-verity users may also verify signatures in userspace, in
0075  * which case userspace is responsible for deciding on what bytes are signed.
0076  * This struct may still be used, but it doesn't have to be.  For example,
0077  * userspace could instead use a string like "sha256:$digest_as_hex_string".
0078  */
0079 struct fsverity_formatted_digest {
0080     char magic[8];          /* must be "FSVerity" */
0081     __le16 digest_algorithm;
0082     __le16 digest_size;
0083     __u8 digest[];
0084 };
0085
0086 #define FS_VERITY_METADATA_TYPE_MERKLE_TREE 1
0087 #define FS_VERITY_METADATA_TYPE_DESCRIPTOR  2
0088 #define FS_VERITY_METADATA_TYPE_SIGNATURE   3
0089
0090 struct fsverity_read_metadata_arg {
0091     __u64 metadata_type;
0092     __u64 offset;
0093     __u64 length;
0094     __u64 buf_ptr;
0095     __u64 __reserved;
0096 };
0097
0098 #define FS_IOC_ENABLE_VERITY    _IOW('f', 133, struct fsverity_enable_arg)
0099 #define FS_IOC_MEASURE_VERITY   _IOWR('f', 134, struct fsverity_digest)
0100 #define FS_IOC_READ_VERITY_METADATA \
0101     _IOWR('f', 135, struct fsverity_read_metadata_arg)
0102
0103 #endif /* _UAPI_LINUX_FSVERITY_H */