gnutls_certifi..._rawpk_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_rawpk_key_file — the manual page, but make it make sense 💖

okay bestie, sit down, hydrate, because we're reading a gnutls man page together and honestly? it's giving "raw public keys have no certificate to hide behind" and we're gonna slay it. this is page gnutls_certificate_set_rawpk_key_file(3) from the gnutls manual, and it is lowkey iconic. 🎀

✨ NAME ✨

gnutls_certificate_set_rawpk_key_file — API function. that's it, that's the name, she's a function and she's an API one, periodt. 💅

🌸 SYNOPSIS 🌸

here's the summoning circle, copy it exactly, no typos, i'm watching:

#include <gnutls/gnutls.h>

int
gnutls_certificate_set_rawpk_key_file(gnutls_certificate_credentials_t
cred, const char * rawpkfile, const char * privkeyfile,
gnutls_x509_crt_fmt_t format, const char * pass, unsigned int key_usage,
const char ** names, unsigned int names_length, unsigned int
privkey_flags, unsigned int pkcs11_flags);

🦋 ARGUMENTS 🦋

the whole cast, in order, no one gets cut from the group chat:

  • gnutls_certificate_credentials_t cred — this is a gnutls_certificate_credentials_t type. it's the lil container everything gets stuffed into.
  • const char * rawpkfile — holds a raw public key, in PKIX.SubjectPublicKeyInfo format. raw. unhinged. no certificate wrapper. we love her.
  • const char * privkeyfile — a file path pointing at a private key. yes, a path, not the key itself.
  • gnutls_x509_crt_fmt_t format — the encoding of the keys. DER or PEM, pick one, choose your fighter.
  • const char * pass — an optional password to unlock the private key privkeyfile. optional!! don't come for me if you leave it out.
  • unsigned int key_usage — an ORed sequence of GNUTLS_KEY_* flags. ORed, bestie, bitwise, you know the vibe.
  • const char ** names — an array of DNS names belonging to the public-key. it's NULL if there are none.
  • unsigned int names_length — holds the length of the names list. gotta say how many, she doesn't count for you.
  • unsigned int privkey_flags — an ORed sequence of gnutls_pkcs_encrypt_flags_t. these apply to the private key pkey.
  • unsigned int pkcs11_flags — one of gnutls_pkcs11_obj_flags. these apply to URLs.

💜 DESCRIPTION 💜

so what does this function do? she sets a public/private keypair, read from a file, into the gnutls_certificate_credentials_t type, so it can be used for authentication and/or encryption. main character energy tbh.

⚠️ spki and privkey should match. if they don't, set signatures cannot be validated, and this function returns GNUTLS_E_CERTIFICATE_KEY_MISMATCH. no cap. mismatched keys are a crime scene.

this function should be called once for the client, because there is currently no mechanism to determine which raw public-key to select for the peer when there are multiple present. so like. one and done, babe. multiple raw public keys for the server can be distinguished by setting the names. 👑

note here that spki is a raw public-key as defined in RFC7250. meaning: there is no surrounding certificate that holds the public key, and there is therefore no direct mechanism to prove the authenticity of this key. the keypair can be used during a TLS handshake, but its authenticity should be established via a different mechanism (e.g. TOFU or known fingerprint). that's a big deal, so let's say it louder for the people in the back — no cert around it, no built-in proof. 🫶

the supported formats are basic unencrypted key, PKCS8, PKCS12, and the openssl format — and they will be autodetected. she just knows. ✨

if the raw public-key and the private key are given in PEM encoding, then the strings that hold their values must be null terminated. do not forget the null terminator, i am begging you. 😭

key usage (as defined by X.509 extension (2.5.29.15)) can be explicitly set, because there is no certificate structure around the key to define this value. see for more info gnutls_x509_crt_get_key_usage().

note that this function by default returns zero on success and a negative value on error. 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 in other functions to refer to the added key-pair. a lil receipt, if you will. 🧾

🌈 RETURNS 🌈

  • on success, GNUTLS_E_SUCCESS (0) is returned. slay.
  • in case the key pair does not match, GNUTLS_E_CERTIFICATE_KEY_MISMATCH is returned. 💀
  • in other erroneous cases, a different negative error code is returned.

⭐ SINCE ⭐

3.6.6 — she's been around, she's not new here, respect the elders.

🙈 REPORTING BUGS 🙈

found a bug? do not suffer in silence, bestie:

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. so like, go off, but keep the receipts. 💅

🍓 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/

and that's the whole page, bestie!! go forth and set your raw public key files responsibly 🦋💖✨ — from the gnutls 3.8.13 manual, with love, mwah 🎀

📦 where this page comes from