GNUTLS_CERTIFICATE_SET_RAWPK_KEY_MEM(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

✨ NAME ✨

gnutls_certificate_set_rawpk_key_mem — bestie, it's an API function 💖 (from the gnutls manual, page gnutls_certific...t_rawpk_key_mem(3))

🌸 SYNOPSIS 🌸

#include <gnutls/gnutls.h>

int
gnutls_certificate_set_rawpk_key_mem(gnutls_certificate_credentials_t
cred, const gnutls_datum_t * spki, const gnutls_datum_t * pkey,
gnutls_x509_crt_fmt_t format, const char * pass, unsigned int key_usage,
const char ** names, unsigned int names_length, unsigned int flags);

🎀 ARGUMENTS 🎀

  • gnutls_certificate_credentials_t cred — this is literally a gnutls_certificate_credentials_t type, that's the whole vibe.
  • const gnutls_datum_t * spki — holds a raw public key in PKIX.SubjectPublicKeyInfo format 👑
  • const gnutls_datum_t * pkey — holds a raw private key 🔐
  • gnutls_x509_crt_fmt_t format — the encoding of the keys. DER or PEM, pick your fighter.
  • const char * pass — an optional password to unlock the private key pkey (optional!! so if it's not locked you can just not).
  • unsigned int key_usage — an ORed sequence of GNUTLS_KEY_* flags.
  • const char ** names — an array of DNS names belonging to the public-key (NULL if there are none).
  • unsigned int names_length — holds the length of the names list.
  • unsigned int flags — an ORed sequence of gnutls_pkcs_encrypt_flags_t. These apply to the private key pkey.

💅 DESCRIPTION 💅

So basically, this function sets a public/private keypair inside the gnutls_certificate_credentials_t type so it can be used for authentication and/or encryption. Iconic, honestly.

spki and privkey should match — otherwise the set signatures cannot be validated 😭 and if they don't match, this function returns GNUTLS_E_CERTIFICATE_KEY_MISMATCH. No cap.

Also: call this function once for the client, because rn there is currently no mechanism to determine which raw public-key to select for the peer when there are multiple present. (Multiple raw public keys for the server can be distinguished by setting the names, so server girlies have options. 💁♀️)

Note here that spki is a raw public-key as defined in RFC7250. That means there is no surrounding certificate holding the public key, and 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). So like… vibe check it yourself, bestie.

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. Periodt.

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

Okay and here's the returns tea: this function by default 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 in other functions to refer to the added key-pair. Slay, a little handle for your little keypair 🫶

⭐ RETURNS ⭐

On success, GNUTLS_E_SUCCESS (0) is returned. 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. (Negative = it's giving sad. 😭)

🦋 SINCE 🦋

3.6.6 — she's been around a minute, an OG.

🙈 REPORTING BUGS 🙈

Report bugs to <bugs@gnutls.org>.

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

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 bestie, you can share it, just 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/

Okay that's the whole page, mwah 💋 — this was gnutls version 3.8.13, page gnutls_certific...t_rawpk_key_mem(3), and yes the man page name is literally truncated like that in real life, we don't make the rules. Go forth and set those raw public keys, bestie 🧚✨

📦 where this page comes from