[PATCH 0/3] keys: Add well known IDs for fs-verity/dm-verity keys

[PATCH 0/3] keys: Add well known IDs for fs-verity/dm-verity keys

[Andrew Halaney]

This more or less follows the bpf keyring approach, allowing userspace
to easily find the keys instead of having to parse /proc/keys.

Signed-off-by: Andrew Halaney <andrew@amutable.com>
---
Andrew Halaney (3):
      keys: add KEY_SPEC_DM_VERITY_KEYRING
      keys: add KEY_SPEC_FS_VERITY_KEYRING
      Documentation: keys: document IDs added since KEY_SPEC_REQKEY_AUTH_KEY

 Documentation/security/keys/core.rst | 13 ++++++++
 drivers/md/dm-verity-verify-sig.c    |  3 ++
 fs/verity/signature.c                |  2 ++
 include/linux/key.h                  |  2 ++
 include/uapi/linux/keyctl.h          |  2 ++
 security/keys/process_keys.c         | 58 ++++++++++++++++++++++++++++++++++++
 6 files changed, 80 insertions(+)
---
base-commit: 1a1de54f7369cd2b5bac0f265910e60ad3a6b4c3
change-id: 20260914-ajhalaney-dmverity-key-identifier-4187b6233be5

Best regards,
-- 
Andrew Halaney <andrew@amutable.com>

[PATCH 1/3] keys: add KEY_SPEC_DM_VERITY_KEYRING

[Andrew Halaney]

The .dm-verity keyring is not linked into any process keyring, so
request_key() and KEYCTL_SEARCH cannot find it. Userspace has to scrape
/proc/keys for the serial to use.

That's not great, one could put in a bogus description containing
a newline to confuse userspace further. For example, thanks to AI
models, which I run as root but you could show off as any old user:

    # DESC=$'.dm-verity: 1\n0badf00d I--Q---     1 perm 082f0000     0     0 keyring   .dm-verity'
    # k=$(echo -n "1234567" | keyctl padd user "$DESC" @s)
    # keyctl setperm "$k" 0x3f010001

    # cat /proc/keys | grep dm-verity
    10402023 I------     2 perm 082f0000     0     0 keyring   .dm-verity: empty
    12e0bee6 I--Q---     1 perm 3f010001     0     0 user      .dm-verity: 1
    0badf00d I--Q---     1 perm 082f0000     0     0 keyring   .dm-verity: 7

0x0badf00d is not a keyring, it is the text inside our user's key
description. Telling the two apart needs a KEYCTL_DESCRIBE per row
which is annoying to do. i.e.:

    # keyctl rdescribe 0x10402023
    keyring;0;0;082f0000;.dm-verity
    # keyctl rdescribe 0x0badf00d
    keyctl_describe: Required key not available

Let's just give it a well known identifier, i.e.:

    # keyctl rdescribe -10
    keyring;0;0;082f0000;.dm-verity

This is exactly what
commit 264d8fd2794f ("bpf, keys: Add a bpf keyring for program signature validation")
did, and was the inspiration for this commit minus the spinlock bits
required due to dm-verity being a module.

Suggested-by: Christian Brauner (Amutable) <brauner@kernel.org>
Signed-off-by: Andrew Halaney <andrew@amutable.com>
---
 drivers/md/dm-verity-verify-sig.c |  3 +++
 include/linux/key.h               |  1 +
 include/uapi/linux/keyctl.h       |  1 +
 security/keys/process_keys.c      | 33 +++++++++++++++++++++++++++++++++
 4 files changed, 38 insertions(+)

diff --git a/drivers/md/dm-verity-verify-sig.c b/drivers/md/dm-verity-verify-sig.c
index b2b55c41e2cb..da509dcdd7e5 100644
--- a/drivers/md/dm-verity-verify-sig.c
+++ b/drivers/md/dm-verity-verify-sig.c
@@ -189,11 +189,14 @@ int __init dm_verity_verify_sig_init(void)
 	    keyring_restrict(make_key_ref(dm_verity_keyring, true), NULL, NULL))
 		panic("dm-verity can't seal keyring\n");
 
+	key_register_dm_verity_keyring(dm_verity_keyring);
+
 	return 0;
 }
 
 void dm_verity_verify_sig_exit(void)
 {
+	key_register_dm_verity_keyring(NULL);
 	key_revoke(dm_verity_keyring);
 	key_put(dm_verity_keyring);
 }
diff --git a/include/linux/key.h b/include/linux/key.h
index bd10fe45819d..ae8d3314fd93 100644
--- a/include/linux/key.h
+++ b/include/linux/key.h
@@ -441,6 +441,7 @@ extern int keyring_restrict(key_ref_t keyring, const char *type,
 			    const char *restriction);
 
 extern void key_register_bpf_keyring(struct key *keyring);
+extern void key_register_dm_verity_keyring(struct key *keyring);
 
 extern struct key *key_lookup(key_serial_t id);
 
diff --git a/include/uapi/linux/keyctl.h b/include/uapi/linux/keyctl.h
index fa85b9760391..75923941f1b3 100644
--- a/include/uapi/linux/keyctl.h
+++ b/include/uapi/linux/keyctl.h
@@ -25,6 +25,7 @@
 #define KEY_SPEC_REQKEY_AUTH_KEY	-7	/* - key ID for assumed request_key auth key */
 #define KEY_SPEC_REQUESTOR_KEYRING	-8	/* - key ID for request_key() dest keyring */
 #define KEY_SPEC_BPF_KEYRING		-9	/* - key ID for the BPF-specific keyring */
+#define KEY_SPEC_DM_VERITY_KEYRING	-10	/* - key ID for the .dm-verity keyring */
 
 /* request-key default keyrings */
 #define KEY_REQKEY_DEFL_NO_CHANGE		-1
diff --git a/security/keys/process_keys.c b/security/keys/process_keys.c
index 44358388e395..dba3df41638b 100644
--- a/security/keys/process_keys.c
+++ b/security/keys/process_keys.c
@@ -25,6 +25,10 @@ static DEFINE_MUTEX(key_session_mutex);
 /* BPF keyring reachable through KEY_SPEC_BPF_KEYRING */
 static struct key *bpf_keyring __ro_after_init;
 
+/* dm-verity keyring reachable through KEY_SPEC_DM_VERITY_KEYRING */
+static struct key *dm_verity_keyring;
+static DEFINE_SPINLOCK(dm_verity_keyring_lock);
+
 /* The root user's tracking struct */
 struct key_user root_key_user = {
 	.usage		= REFCOUNT_INIT(3),
@@ -607,6 +611,24 @@ void key_register_bpf_keyring(struct key *keyring)
 	bpf_keyring = keyring;
 }
 
+/**
+ * key_register_dm_verity_keyring - Publish the keyring for KEY_SPEC_DM_VERITY_KEYRING
+ * @keyring: The keyring to publish, or NULL to withdraw it
+ *
+ * Make @keyring reachable by userspace through the KEY_SPEC_DM_VERITY_KEYRING
+ * special key ID, so that provisioning it does not require scraping its
+ * serial out of /proc/keys first. dm-verity can be unloaded as a module
+ * and the keyring deregistered, as such serialize access with
+ * dm_verity_keyring_lock.
+ */
+void key_register_dm_verity_keyring(struct key *keyring)
+{
+	spin_lock(&dm_verity_keyring_lock);
+	dm_verity_keyring = keyring;
+	spin_unlock(&dm_verity_keyring_lock);
+}
+EXPORT_SYMBOL_GPL(key_register_dm_verity_keyring);
+
 /*
  * Look up a key ID given us by userspace with a given permissions mask to get
  * the key it refers to.
@@ -766,6 +788,17 @@ key_ref_t lookup_user_key(key_serial_t id, unsigned long lflags,
 		key_ref = make_key_ref(key, 0);
 		break;
 
+	case KEY_SPEC_DM_VERITY_KEYRING:
+		spin_lock(&dm_verity_keyring_lock);
+		key = dm_verity_keyring;
+		if (key)
+			__key_get(key);
+		spin_unlock(&dm_verity_keyring_lock);
+		if (!key)
+			goto error;
+		key_ref = make_key_ref(key, 0);
+		break;
+
 	default:
 		key_ref = ERR_PTR(-EINVAL);
 		if (id < 1)

-- 
2.55.0

[PATCH 2/3] keys: add KEY_SPEC_FS_VERITY_KEYRING

[Andrew Halaney]

Same problem as the dm-verity keyring: .fs-verity is allocated unlinked,
so the only way for userspace to name it is to scrape /proc/keys.

Suggested-by: Christian Brauner (Amutable) <brauner@kernel.org>
Signed-off-by: Andrew Halaney <andrew@amutable.com>
---
 fs/verity/signature.c        |  2 ++
 include/linux/key.h          |  1 +
 include/uapi/linux/keyctl.h  |  1 +
 security/keys/process_keys.c | 25 +++++++++++++++++++++++++
 4 files changed, 29 insertions(+)

diff --git a/fs/verity/signature.c b/fs/verity/signature.c
index 0302a4e506ec..07657e913b22 100644
--- a/fs/verity/signature.c
+++ b/fs/verity/signature.c
@@ -135,4 +135,6 @@ void __init fsverity_init_signature(void)
 			      KEY_ALLOC_NOT_IN_QUOTA, NULL, NULL);
 	if (IS_ERR(fsverity_keyring))
 		panic("failed to allocate \".fs-verity\" keyring");
+
+	key_register_fs_verity_keyring(fsverity_keyring);
 }
diff --git a/include/linux/key.h b/include/linux/key.h
index ae8d3314fd93..dd386c56278c 100644
--- a/include/linux/key.h
+++ b/include/linux/key.h
@@ -442,6 +442,7 @@ extern int keyring_restrict(key_ref_t keyring, const char *type,
 
 extern void key_register_bpf_keyring(struct key *keyring);
 extern void key_register_dm_verity_keyring(struct key *keyring);
+extern void key_register_fs_verity_keyring(struct key *keyring);
 
 extern struct key *key_lookup(key_serial_t id);
 
diff --git a/include/uapi/linux/keyctl.h b/include/uapi/linux/keyctl.h
index 75923941f1b3..00cc0942203e 100644
--- a/include/uapi/linux/keyctl.h
+++ b/include/uapi/linux/keyctl.h
@@ -26,6 +26,7 @@
 #define KEY_SPEC_REQUESTOR_KEYRING	-8	/* - key ID for request_key() dest keyring */
 #define KEY_SPEC_BPF_KEYRING		-9	/* - key ID for the BPF-specific keyring */
 #define KEY_SPEC_DM_VERITY_KEYRING	-10	/* - key ID for the .dm-verity keyring */
+#define KEY_SPEC_FS_VERITY_KEYRING	-11	/* - key ID for the .fs-verity keyring */
 
 /* request-key default keyrings */
 #define KEY_REQKEY_DEFL_NO_CHANGE		-1
diff --git a/security/keys/process_keys.c b/security/keys/process_keys.c
index dba3df41638b..655c58a96fcb 100644
--- a/security/keys/process_keys.c
+++ b/security/keys/process_keys.c
@@ -29,6 +29,9 @@ static struct key *bpf_keyring __ro_after_init;
 static struct key *dm_verity_keyring;
 static DEFINE_SPINLOCK(dm_verity_keyring_lock);
 
+/* fs-verity keyring reachable through KEY_SPEC_FS_VERITY_KEYRING */
+static struct key *fs_verity_keyring __ro_after_init;
+
 /* The root user's tracking struct */
 struct key_user root_key_user = {
 	.usage		= REFCOUNT_INIT(3),
@@ -629,6 +632,20 @@ void key_register_dm_verity_keyring(struct key *keyring)
 }
 EXPORT_SYMBOL_GPL(key_register_dm_verity_keyring);
 
+/**
+ * key_register_fs_verity_keyring - Publish the keyring for KEY_SPEC_FS_VERITY_KEYRING
+ * @keyring: The keyring to publish
+ *
+ * Make @keyring reachable by userspace through the KEY_SPEC_FS_VERITY_KEYRING
+ * special key ID, so that provisioning it does not require scraping its
+ * serial out of /proc/keys first. Called once, from an initcall, and never
+ * undone.
+ */
+void key_register_fs_verity_keyring(struct key *keyring)
+{
+	fs_verity_keyring = keyring;
+}
+
 /*
  * Look up a key ID given us by userspace with a given permissions mask to get
  * the key it refers to.
@@ -799,6 +816,14 @@ key_ref_t lookup_user_key(key_serial_t id, unsigned long lflags,
 		key_ref = make_key_ref(key, 0);
 		break;
 
+	case KEY_SPEC_FS_VERITY_KEYRING:
+		key = fs_verity_keyring;
+		if (!key)
+			goto error;
+		__key_get(key);
+		key_ref = make_key_ref(key, 0);
+		break;
+
 	default:
 		key_ref = ERR_PTR(-EINVAL);
 		if (id < 1)

-- 
2.55.0

[PATCH 3/3] Documentation: keys: document IDs added since KEY_SPEC_REQKEY_AUTH_KEY

[Andrew Halaney]

The table of special key IDs stops at KEY_SPEC_REQKEY_AUTH_KEY.
Fill in all the new ones.

Suggested-by: Christian Brauner (Amutable) <brauner@kernel.org>
Signed-off-by: Andrew Halaney <andrew@amutable.com>
---
 Documentation/security/keys/core.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index 326b8a973828..37ed42382f16 100644
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -372,6 +372,19 @@ process making the call::
 	KEY_SPEC_GROUP_KEYRING		-6	GID-specific keyring
 	KEY_SPEC_REQKEY_AUTH_KEY	-7	assumed request_key()
 						  authorisation key
+	KEY_SPEC_REQUESTOR_KEYRING	-8	request_key() destination
+						  keyring
+
+There are also values that refer to a specific kernel keyring rather than to
+anything belonging to the caller.  These keyrings are not linked into any
+keyring, so a search cannot reach them and the ID is the only way to name
+one::
+
+	CONSTANT			VALUE	KEY REFERENCED
+	==============================	======	===========================
+	KEY_SPEC_BPF_KEYRING		-9	the ".bpf" keyring
+	KEY_SPEC_DM_VERITY_KEYRING	-10	the ".dm-verity" keyring
+	KEY_SPEC_FS_VERITY_KEYRING	-11	the ".fs-verity" keyring
 
 
 The main syscalls are:

-- 
2.55.0

Re: [PATCH 0/3] keys: Add well known IDs for fs-verity/dm-verity keys

[Christian Brauner]

On Mon, Sep 14, 2026 at 11:41:41AM -0500, Andrew Halaney wrote:
> This more or less follows the bpf keyring approach, allowing userspace
> to easily find the keys instead of having to parse /proc/keys.
> 
> Signed-off-by: Andrew Halaney <andrew@amutable.com>
> ---

Thanks for doing this! Looks good to me,
Reviewed-by: Christian Brauner (Amutable) <brauner@kernel.org>

Re: [PATCH 1/3] keys: add KEY_SPEC_DM_VERITY_KEYRING

[Jarkko Sakkinen]

On Mon, Sep 14, 2026 at 11:41:42AM -0500, Andrew Halaney wrote:
> The .dm-verity keyring is not linked into any process keyring, so
> request_key() and KEYCTL_SEARCH cannot find it. Userspace has to scrape
> /proc/keys for the serial to use.
> 
> That's not great, one could put in a bogus description containing
> a newline to confuse userspace further. For example, thanks to AI
> models, which I run as root but you could show off as any old user:
> 
>     # DESC=$'.dm-verity: 1\n0badf00d I--Q---     1 perm 082f0000     0     0 keyring   .dm-verity'
>     # k=$(echo -n "1234567" | keyctl padd user "$DESC" @s)
>     # keyctl setperm "$k" 0x3f010001
> 
>     # cat /proc/keys | grep dm-verity
>     10402023 I------     2 perm 082f0000     0     0 keyring   .dm-verity: empty
>     12e0bee6 I--Q---     1 perm 3f010001     0     0 user      .dm-verity: 1
>     0badf00d I--Q---     1 perm 082f0000     0     0 keyring   .dm-verity: 7
> 
> 0x0badf00d is not a keyring, it is the text inside our user's key
> description. Telling the two apart needs a KEYCTL_DESCRIBE per row
> which is annoying to do. i.e.:
> 
>     # keyctl rdescribe 0x10402023
>     keyring;0;0;082f0000;.dm-verity
>     # keyctl rdescribe 0x0badf00d
>     keyctl_describe: Required key not available
> 
> Let's just give it a well known identifier, i.e.:
> 
>     # keyctl rdescribe -10
>     keyring;0;0;082f0000;.dm-verity
> 
> This is exactly what
> commit 264d8fd2794f ("bpf, keys: Add a bpf keyring for program signature validation")
> did, and was the inspiration for this commit minus the spinlock bits
> required due to dm-verity being a module.

This is great for discussion but what we want for the commit message
is just motivation and resolution.

I don't think we need all this just to say that /proc/keys in a racy
query mechanism for production, which is an issue for dm-verity, given
that nothing else is available.

And secondly special keys are meant for implicit keyrings so isn't
that all there's to it?


> 
> Suggested-by: Christian Brauner (Amutable) <brauner@kernel.org>
> Signed-off-by: Andrew Halaney <andrew@amutable.com>
> ---
>  drivers/md/dm-verity-verify-sig.c |  3 +++
>  include/linux/key.h               |  1 +
>  include/uapi/linux/keyctl.h       |  1 +
>  security/keys/process_keys.c      | 33 +++++++++++++++++++++++++++++++++
>  4 files changed, 38 insertions(+)
> 
> diff --git a/drivers/md/dm-verity-verify-sig.c b/drivers/md/dm-verity-verify-sig.c
> index b2b55c41e2cb..da509dcdd7e5 100644
> --- a/drivers/md/dm-verity-verify-sig.c
> +++ b/drivers/md/dm-verity-verify-sig.c
> @@ -189,11 +189,14 @@ int __init dm_verity_verify_sig_init(void)
>  	    keyring_restrict(make_key_ref(dm_verity_keyring, true), NULL, NULL))
>  		panic("dm-verity can't seal keyring\n");
>  
> +	key_register_dm_verity_keyring(dm_verity_keyring);
> +
>  	return 0;
>  }
>  
>  void dm_verity_verify_sig_exit(void)
>  {
> +	key_register_dm_verity_keyring(NULL);
>  	key_revoke(dm_verity_keyring);
>  	key_put(dm_verity_keyring);
>  }
> diff --git a/include/linux/key.h b/include/linux/key.h
> index bd10fe45819d..ae8d3314fd93 100644
> --- a/include/linux/key.h
> +++ b/include/linux/key.h
> @@ -441,6 +441,7 @@ extern int keyring_restrict(key_ref_t keyring, const char *type,
>  			    const char *restriction);
>  
>  extern void key_register_bpf_keyring(struct key *keyring);
> +extern void key_register_dm_verity_keyring(struct key *keyring);
>  
>  extern struct key *key_lookup(key_serial_t id);
>  
> diff --git a/include/uapi/linux/keyctl.h b/include/uapi/linux/keyctl.h
> index fa85b9760391..75923941f1b3 100644
> --- a/include/uapi/linux/keyctl.h
> +++ b/include/uapi/linux/keyctl.h
> @@ -25,6 +25,7 @@
>  #define KEY_SPEC_REQKEY_AUTH_KEY	-7	/* - key ID for assumed request_key auth key */
>  #define KEY_SPEC_REQUESTOR_KEYRING	-8	/* - key ID for request_key() dest keyring */
>  #define KEY_SPEC_BPF_KEYRING		-9	/* - key ID for the BPF-specific keyring */
> +#define KEY_SPEC_DM_VERITY_KEYRING	-10	/* - key ID for the .dm-verity keyring */
>  
>  /* request-key default keyrings */
>  #define KEY_REQKEY_DEFL_NO_CHANGE		-1
> diff --git a/security/keys/process_keys.c b/security/keys/process_keys.c
> index 44358388e395..dba3df41638b 100644
> --- a/security/keys/process_keys.c
> +++ b/security/keys/process_keys.c
> @@ -25,6 +25,10 @@ static DEFINE_MUTEX(key_session_mutex);
>  /* BPF keyring reachable through KEY_SPEC_BPF_KEYRING */
>  static struct key *bpf_keyring __ro_after_init;
>  
> +/* dm-verity keyring reachable through KEY_SPEC_DM_VERITY_KEYRING */
> +static struct key *dm_verity_keyring;
> +static DEFINE_SPINLOCK(dm_verity_keyring_lock);
> +
>  /* The root user's tracking struct */
>  struct key_user root_key_user = {
>  	.usage		= REFCOUNT_INIT(3),
> @@ -607,6 +611,24 @@ void key_register_bpf_keyring(struct key *keyring)
>  	bpf_keyring = keyring;
>  }
>  
> +/**
> + * key_register_dm_verity_keyring - Publish the keyring for KEY_SPEC_DM_VERITY_KEYRING
> + * @keyring: The keyring to publish, or NULL to withdraw it
> + *
> + * Make @keyring reachable by userspace through the KEY_SPEC_DM_VERITY_KEYRING
> + * special key ID, so that provisioning it does not require scraping its
> + * serial out of /proc/keys first. dm-verity can be unloaded as a module
> + * and the keyring deregistered, as such serialize access with
> + * dm_verity_keyring_lock.
> + */
> +void key_register_dm_verity_keyring(struct key *keyring)
> +{
> +	spin_lock(&dm_verity_keyring_lock);
> +	dm_verity_keyring = keyring;
> +	spin_unlock(&dm_verity_keyring_lock);
> +}
> +EXPORT_SYMBOL_GPL(key_register_dm_verity_keyring);
> +
>  /*
>   * Look up a key ID given us by userspace with a given permissions mask to get
>   * the key it refers to.
> @@ -766,6 +788,17 @@ key_ref_t lookup_user_key(key_serial_t id, unsigned long lflags,
>  		key_ref = make_key_ref(key, 0);
>  		break;
>  
> +	case KEY_SPEC_DM_VERITY_KEYRING:
> +		spin_lock(&dm_verity_keyring_lock);
> +		key = dm_verity_keyring;
> +		if (key)
> +			__key_get(key);
> +		spin_unlock(&dm_verity_keyring_lock);
> +		if (!key)
> +			goto error;
> +		key_ref = make_key_ref(key, 0);
> +		break;
> +
>  	default:
>  		key_ref = ERR_PTR(-EINVAL);
>  		if (id < 1)
> 
> -- 
> 2.55.0
> 

BR, Jarkko

Re: [PATCH 1/3] keys: add KEY_SPEC_DM_VERITY_KEYRING

[David Howells]

Jarkko Sakkinen <jarkko@kernel.org> wrote:

> This is great for discussion but what we want for the commit message
> is just motivation and resolution.

Actually, I think it's useful that Andrew wrote up the issues in the commit
message - and I think it shows part of the motivation.  The 'writing a fake
/proc/keys line in the description' is something I hadn't considered.

> I don't think we need all this just to say that /proc/keys in a racy
> query mechanism for production, which is an issue for dm-verity, given
> that nothing else is available.

I think at some point, we will need a system call to search all for all
accessible keys matching certain criteria by actually walking the key
database.  The problem there is that there may be multiple hits, so we may
need something like:

	int count = find_key(key_serial_t start_id,
			     const char *type, const char *desc_prefix,
			     key_serial_t *results, size_t results_size,
			     unsigned int flags);

Allowing you to do:

	key_serial_t dm_key;
	int n = find_key(0, "keyring", ".dm_verity", &dm_key, 1,
			 FIND_KEY_EXACT_DESC);

This wouldn't be as fast as a direct lookup since it would have to walk the
key tree, doing name comparisons and perm checks on each key of the type.

> And secondly special keys are meant for implicit keyrings so isn't
> that all there's to it?

I have no particular objection to setting aside a block of negative key IDs
for special keyrings that need to be accessed a lot - though I would make
common reg/unreg functions that take the ID to be registered and, say, set the
block at -257..-512.  Moving the BFP keyring to -257 and DM to -258.

David