GNUTLS_CERTIFICATE_SET_X509_KEY_FILE(3)

📦
version 3.8.13 · 7 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, ubuntu stonking

💖 gnutls_certificate_set_x509_key_file — the manual page, but make it make sense 💖

okay bestie, sit down, grab your boba, because we're reading a gnutls man page together and honestly? it's a good one. this lives in the gnutls manual, section 3 (library functions, for the girlies keeping track at home). let's go 🫶

✨ NAME ✨

gnutls_certificate_set_x509_key_file — an API function. yes that's it, that's the name, she's long but she's iconic 👑

✨ SYNOPSIS ✨

first you gotta pull in the header, then call her:

#include <gnutls/gnutls.h>

int
gnutls_certificate_set_x509_key_file(gnutls_certificate_credentials_t
res, const char * certfile, const char * keyfile, gnutls_x509_crt_fmt_t
type);

✨ ARGUMENTS ✨

four things, four vibes, let's do them one by one:

  • gnutls_certificate_credentials_t res — this is your gnutls_certificate_credentials_t type. she's the whole point, the main character of this function 💅
  • const char * certfile — a file holding the certificate list (the path) for the private key you're specifying. it's in PKCS7 format, or it's just a list of certificates. either way she's serving ✨
  • const char * keyfile — a file with the private key in it. keep this one safe, she's private for a reason 🙈
  • gnutls_x509_crt_fmt_t type — PEM or DER. pick your format bestie, those are the options 🌸

✨ DESCRIPTION ✨

so what does she even do? she sets a certificate/private key pair inside the gnutls_certificate_credentials_t type. that's the whole job. slay.

here's the tea though — you can call this function more than once, which is exactly what you want if your server has multiple keys/certificates chilling in there. no cap. for clients that need to send more than just their own end entity certificate — like, say, also an intermediate CA cert — then the certfile has to contain the ordered certificate chain. ordered, bestie. the order matters. don't just throw them in there like laundry.

also note (not me, the manpage) that the names inside the certificate you hand over will be considered when picking which certificate to actually use — this is the move when you've got multiple certificate/key pairs and you need the right one to show up. vibe check on the names, essentially 🌈

oh and she's flexible too: this function can also accept URLs at keyfile and certfile. in that case she'll use the private key and certificate that the URLs point at. and which URLs does she support? the ones indicated by gnutls_url_is_supported(). that's the list, go check her 🦋

and if the certfile comes in as a PKCS 11 URL, then the certificate — plus its present issuers in the token — get imported. that means they form the required trust chain. cute, right?

⚠️ real talk, this one's important: if that function fails to load, the res structure is left in an undefined state. you must not reuse it to load other keys or certificates. like, do not. she's done. start over 😭

one more thing — by default she returns zero on success and a negative value on error. but since 3.5.6, if the flag GNUTLS_CERTIFICATE_API_V2 is set using gnutls_certificate_set_flags(), she returns an index (greater or equal to zero). that index can be used by other functions to refer back to the key-pair you just added. literally so useful 💜

✨ RETURNS ✨

on success she returns zero. otherwise you get a negative value, because something went wrong (and yes, see above if you want to modify that behavior, the GNUTLS_CERTIFICATE_API_V2 situation) 💀

✨ SINCE ✨

3.1.11 — she's been around, she's a legend 🎀

✨ REPORTING BUGS ✨

found a bug? don't suffer in silence, tell the people:

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. (yes, that's the legal bit, and yes, we keep it exactly as it is, no edits 💖)

✨ 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, go visit:

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

and that's the whole page bestie!! 🦋 this was gnutls version 3.8.13, and the page itself is gnutls_certificate_set_x509_key_file(3). go forth, set those key pairs, and remember: ordered chain, no undefined res reuse, periodt 💅✨

📦 where this page comes from