gnutls_certificate_set_key(3)

💖 gnutls_certificate_set_key 💖

okay bestie, sit DOWN, because we're diving into a gnutls manual page — yes, the gnutls one, from the gnutls manual, page gnutls_certificate_set_key(3) — and this one is literally about handing your credentials a whole public/private key pair. no cap. it's giving "crypto admin but make it cute". 🎀

---

✨ NAME ✨

gnutls_certificate_set_key — API function. that's it, that's the name, and yes it does exactly what it says on the tin. 🫶

---

🌸 SYNOPSIS 🌸

#include <gnutls/abstract.h>

int gnutls_certificate_set_key(gnutls_certificate_credentials_t res,
const char ** names, int names_size, gnutls_pcert_st * pcert_list, int
pcert_list_size, gnutls_privkey_t key);

look at that signature. six whole arguments. main character energy honestly. 💅

---

🦋 ARGUMENTS 🦋

• gnutls_certificate_credentials_t res — this is, surprise surprise, a gnutls_certificate_credentials_t type. the whole point of the function, the queen bee, the structure everything gets loaded into. 👑
• const char ** names — an array of DNS names that belong to the public-key. if there aren't any, you just pass NULL. it's optional, babe. 🌈
• int names_size — holds the size of the names list. gotta tell it how many names you brought. ✨
• gnutls_pcert_st * pcert_list — contains a certificate list (aka the chain) or a raw public-key. your pick, both are valid. 🎀
• int pcert_list_size — holds the size of the certificate list. same deal, count your certs bestie. 💜
• gnutls_privkey_t key — a gnutls_privkey_t key that corresponds to the first public-key in pcert_list. so like, key ↔ first cert, they're a matched set, they go together. 💞

---

💅 DESCRIPTION 💅

so what does this actually do? it sets a public/private key pair into the gnutls_certificate_credentials_t type. that's the vibe.

the given public key may be encapsulated in a certificate, or it can just be given as a raw key. either way works.

this function may be called more than once, which is so iconic of it — that's for when multiple key pairs exist for the server. so like, if your server has multiple identities, go off, call it again. 🔥

for clients that want to send more than their own end-entity certificate (e.g., also an intermediate CA cert), the full certificate chain must be provided in pcert_list. don't be shy, send the whole chain. 🌸

okay IMPORTANT one: note that the key will become part of the credentials structure and must not be deallocated. it will be automatically deallocated when the res structure is deinitialized. so do NOT free it yourself, bestie, that's a whole situation. 😭

and another warning, fr fr: if this function fails, the res structure is at an undefined state and it must not be reused to load other keys or certificates. like, it's done. don't touch it. 💀

now the return-value tea ☕ — by default this function returns zero on success and a negative value on error. but! since 3.5.6, when the flag GNUTLS_CERTIFICATE_API_V2 is set using gnutls_certificate_set_flags(), it returns an index (greater or equal to zero). that index can be used for other functions to refer to the added key-pair. so you get a lil ticket number for your key. so handy. 🎟️

and since GnuTLS 3.6.6, this function also handles raw public keys. glow up. ✨

---

⭐ RETURNS ⭐

on success this functions returns zero, and otherwise a negative value on error — see above if you wanna know how to modify that behavior. (spoiler: it's the GNUTLS_CERTIFICATE_API_V2 thing. you knew that. iykyk.) 💖

---

🎀 SINCE 🎀

3.0

like, ancient by internet standards, but make it legacy-supported. 👑

---

🙈 REPORTING BUGS 🙈

found something cursed? report bugs to <bugs@gnutls.org>.

home page: https://www.gnutls.org

they wanna hear from you, bestie, don't gatekeep your bug reports. 🫶

---

🌈 COPYRIGHT 🌈

Copyright © 2001-2023 Free Software Foundation, Inc., and others.

copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. slay, and legally so. ⭐

---

💜 SEE ALSO 💜

the full documentation for gnutls is maintained as a Texinfo manual. if the /usr/share/doc/gnutls/ directory does not contain the HTML form, visit

https://www.gnutls.org/manual/

that's the lore. go read it. 🧚

---

and that's the whole page, bestie — gnutls manual, version 3.8.13, page gnutls_certificate_set_key(3). now go forth and set some keys, but do NOT free that key, i'm watching you. 💅🌸✨