gnutls_certificate_verify_peers3(3)

💅 gnutls_certificate_verify_peers3(3) — the cert vibe check 💅

okay bestie so this is a page from the gnutls manual (yes, the whole manual, that's the name) and it's about one very specific little function that checks whether the person you're talking to on the other end of the wire is actually who they say they are. it's giving "trust but verify", fr fr. 🦋

---

✨ NAME ✨

gnutls_certificate_verify_peers3 — API function. that's it, that's the name, no notes. 💖

---

🌸 SYNOPSIS 🌸

#include <gnutls/gnutls.h>

int gnutls_certificate_verify_peers3(gnutls_session_t session, const
char * hostname, unsigned int * status);

look at her. three args. iconic. 👑

---

🎀 ARGUMENTS 🎀

• gnutls_session_t session — is a gnutls session. that's the whole description, she's self-explanatory, main character energy.
• const char * hostname — the name you're expecting the peer to have. it may be NULL, and that's totally fine, no pressure. 💜
• unsigned int * status — this is where the answer gets dropped off. it's the output of the verification, so like, the receipts. 🧾

---

✨ DESCRIPTION ✨

so what does she actually do? this function verifies the peer's certificate, and then it stores the status in the status variable as a bitwise OR of gnutls_certificate_status_t values, or zero if the certificate is trusted. zero equals blessed equals no cap trusted. 🫶

not me about to say the most important thing: the value in status is only set when the return value of this function is success. like, failure to trust a certificate does not imply a negative return value. so don't you dare skip checking status, okay? the return code and the status are two different girls. 💀

the default verification flags this function uses can be overridden with gnutls_certificate_set_verify_flags(). and if you want the full tea on how the verification process actually goes down, go read gnutls_certificate_verify_peers2(). it's all there, iykyk. 📖

she also takes into account the stapled OCSP responses sent by the server, plus these X.509 certificate extensions:

• Name Constraints
• Key Usage
• Basic Constraints (pathlen)

all of them. she checks them. obsessed. 🌈

if the hostname you provided is non-NULL, then she compares the hostname inside the certificate against it. the comparison follows the RFC6125 recommendations. and if the names do not match, the GNUTLS_CERT_UNEXPECTED_OWNER status flag gets set. red flag detected, bestie. 🚩

if you wanna verify the purpose of the end-certificate (that's the extended key usage check), use gnutls_certificate_verify_peers() instead. different function, different job. 💅

to avoid denial of service attacks, some default upper limits are set regarding the certificate key size and the chain size. to override them, use gnutls_certificate_set_verify_limits(). safety first, always. 🛡️

and now the sad part: when using raw public-keys, verification will not work, because there is no corresponding certificate body belonging to the raw key that can be verified. in that case this function will return GNUTLS_E_INVALID_REQUEST. it's not her fault, there's just literally nothing to check. 😭

---

🌟 RETURNS 🌟

• GNUTLS_E_SUCCESS (0) when the validation is performed
• or a negative error code otherwise

and a successful error code means that the status parameter must be checked to obtain the validation status. say it with me: check the status. CHECK. THE. STATUS. 🗣️

---

🦋 SINCE 🦋

3.1.4 — she's been around a minute, a seasoned queen. ⭐

---

🙈 REPORTING BUGS 🙈

found a bug? tell the girlies at <bugs@gnutls.org>.

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

---

👑 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. (translation: go off, 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/

---

and that's the whole page bestie, no crumbs left behind. this was gnutls 3.8.13, page gnutls_certificate_verify_peers3(3) — go forth and verify those peers, you absolute icon. periodt. 💅✨