KEYCTL_PKEY_QUERY(3)

💖 keyctl_pkey_query — the vibe check for your public keys 💖

okay bestie, listen up, this is a Linux Key Management Calls moment, section 3 of the manual, and we're about to learn how to query public key parameters. No cap. 🎀

---

✨ NAME ✨

keyctl_pkey_query — ask a key "so… what can you even do, babes?" 💅

---

🌸 SYNOPSIS 🌸

#include <keyutils.h>

long keyctl_pkey_query(key_serial_t key, const char *info,
                       struct keyctl_pkey_query *result);

---

🦋 DESCRIPTION 🦋

So keyctl_pkey_query() goes and asks a kernel key that supports these kinds of operations — typically an asymmetric-type key — all about its public key parameters. Iconic behaviour honestly. 🫶

Heads up: the caller must have search permission on the target key to be able to query its parameters. No permission, no tea. ☕

When you invoke this function:

• key — which key we're interrogating, bestie 🔍
• info — a pointer to a space- or tab-separated string of "key[=value]" parameters 📝
• result — a pointer to a buffer where the answer gets dropped off 🎁

The parameters you can put in that info string? Depends entirely on the type of key. They can specify stuff like encoding types (for example enc=pkcs1) — go peek at asymmetric-key(7) for more on that. iykyk. 👑

If it works, the result lands in this struct, exactly like this:

struct keyctl_pkey_query {
        unsigned int    supported_ops;
        unsigned int    key_size;
        unsigned short  max_data_size;
        unsigned short  max_sig_size;
        unsigned short  max_enc_size;
        unsigned short  max_dec_size;
};

The supported_ops field is a bitmask of these constants, and they tell you what's supported — aka which of the other keyctl_pkey_*() operations you can actually use with this key: ⭐

• KEYCTL_SUPPORTS_ENCRYPT
• KEYCTL_SUPPORTS_DECRYPT
• KEYCTL_SUPPORTS_SIGN
• KEYCTL_SUPPORTS_VERIFY

And the rest of the squad:

• key_size — the number of bits in the key size 🔢
• max_data_size — max size in bytes of a blob of data to be signed
• max_sig_size — max size in bytes of a signature blob
• max_enc_size — max size in bytes of a blob to be encrypted
• max_dec_size — max size in bytes of a blob to be decrypted

slay. that's the whole report card. 💯

---

🎀 RETURN VALUE 🎀

• On success, keyctl_pkey_query() returns 0. 🥳
• On error, you get -1 back, and errno will have been set to an appropriate error. 😭

---

💀 ERRORS 💀

• ENOKEY — the key specified is invalid. not a real key, bestie, we can't work with that 🙈
• EKEYEXPIRED — the key specified has expired. it's giving ghosted. 👻
• EKEYREVOKED — the key specified has been revoked. it's over, it's done 💔
• EACCES — the key exists, but it's not searchable by the calling process. you can look but you cannot look, y'know? 🚫
• ENOPKG — some facility needed to complete the requested operation is not available. this is most probably a requested or required digest or encryption algorithm. the algorithm ghosted us fr fr 😤
• EFAULT — bad address. 🛑

---

🔗 LINKING 🔗

This is a library function, and it lives in libkeyutils. When you're linking, you need to pass -lkeyutils to the linker. Don't forget it, it's the whole vibe. 🧚

---

👀 SEE ALSO 👀

keyctl(1), add_key(2), keyctl(2), keyctl(3), keyctl_pkey_encrypt(3), keyctl_pkey_sign(3), asymmetric-key(7), keyrings(7), keyutils(7)

---

and that's the whole page, bestie!! 💖✨ this one's brought to you by the Linux girlies, dated 8 Nov 2018 — periodt. go query those keys, you absolute icon. 👑🦋🌸