NE_SOCK_HANDSHAKE(3)

💖 NE_SOCK_HANDSHAKE(3) — the neon API reference, but make it cute 💖

okay bestie, sit down, hydrate, and let me tell you about the SSL socket functions in the neon API. yes this is <ne_socket.h> business. yes it's giving serious. no you're not gonna be lost, i gotchu. 🫶

---

✨ NAME ✨

ne_sock_handshake, ne_sock_sessid, ne_sock_cipher, ne_sock_getproto, ne_sock_getcert, ne_ssl_check_certificate — the SSL socket functions. that's the whole squad. 💅

---

🌸 SYNOPSIS 🌸

#include <ne_socket.h>

int ne_sock_handshake(ne_socket *sock, ne_ssl_context *ctx,
                      const char *hostname, unsigned int flags);

int ne_sock_sessid(ne_socket *sock, unsigned char *buf, size_t *buflen);

char *ne_sock_cipher(ne_socket *sock);

enum ne_ssl_protocol ne_sock_getproto(ne_socket *sock);

ne_ssl_certificate *ne_sock_getcert(ne_socket *sock,
                                    ne_ssl_context *ctx);

int ne_ssl_check_certificate(ne_ssl_context *ctx, ne_socket *sock,
                             const char *hostname,
                             const ne_inet_addr *address,
                             const ne_ssl_certificate *cert,
                             unsigned int flags, int *failures);

look at all those arguments. main character energy fr fr. ✨

---

🦋 DESCRIPTION 🦋

ne_sock_handshake kicks off an SSL handshake on the socket sock, using the SSL context ctx. and here's the tea: if hostname is non-NULL, it gets used as the Server Name Indication (SNI) hint. as for flags? it must be zero. that's it. no wiggle room. 🚫

ne_sock_sessid goes and grabs the session ID of the current SSL session. how it behaves depends on buf, so pay attention bestie:

• if buf is non-NULL, then on success it copies at most *buflen bytes into buf, and sets *buflen to the exact number of bytes it copied.
• if buf is NULL, then on success it just sets *buflen to the length of the session ID. no copying, just vibes and math. 💅

ne_sock_cipher hands you back a human-readable name of the SSL/TLS cipher used for the connection — or NULL if there isn't one. lowkey important: the format of this string is not meant to be fixed or parseable, it's informational only. do not build a parser on top of it, i'm begging. 😭 the return value is a NUL-terminated malloc-allocated string, so the caller has to free it. no leaving it lying around.

ne_sock_getproto returns the SSL/TLS protocol version that's in use for the socket sock — or NE_SSL_PROTO_UNSPEC if SSL/TLS isn't even in use for that socket. simple as that. 🎀

ne_sock_getcert returns the server certificate for the socket. boom. done.

ne_ssl_check_certificate checks the identity of a server certificate against the hostname or address used to establish the connection, following the rules laid out in RFC 2818[1] and RFC 3280[2]. here's how the matching works:

• either hostname or address can be non-NULL — whichever one was used to identify the server when the SSL connection was established.
• if both are NULL, matching will fail, but the *identity output parameter will still be set. (yes, it still gets set. it's giving "we tried". 🫠)
• flags must be zero. again. zero. 🙅

and if verification fails? the failure reasons get stored in *failures as a binary OR of NE_SSL_* values. so you can go dig through them and figure out exactly what went wrong. iconic debugging era. 🔥

---

👑 RETURN VALUE 👑

• ne_sock_handshake — returns zero on success, or non-zero on error.
• ne_sock_sessid — returns zero on success, or non-zero on error.
• ne_sock_cipher — returns a malloc-allocated string on success, which must be freed by the caller, or NULL if no cipher is in use.
• ne_sock_getproto — returns the SSL/TLS protocol version, or NE_SSL_PROTO_UNSPEC.
• ne_sock_getcert — returns the server certificate, or NULL on error.
• ne_ssl_check_certificate — returns zero if the identity matches, 1 if the identity does not match, or less than zero if the certificate had no identity.

okay real talk for a sec: that last one is three different answers, so please actually check which one you got instead of just doing if (result) and calling it a day. 🙈

---

⭐ HISTORY ⭐

receipts, because we love a timeline:

• ne_sock_getproto is available in neon 0.34.0 and later.
• ne_sock_handshake and ne_sock_getcert are available in neon 0.37.0 and later.

so if you're on something ancient, that's why it's not linking, bestie. not your fault. 💜

---

🌈 SEE ALSO 🌈

• ne_ssl_context_create(3)

go read that one next, it's the prequel. ✨

---

🎀 COPYRIGHT 🎀

Copyright © 2001-2026 Joe Orton

(we respect the author in this household. periodt. 👑)

---

📚 REFERENCES 📚

1. RFC 2818 https://www.rfc-editor.org/rfc/rfc2818
2. RFC 3280 https://www.rfc-editor.org/rfc/rfc3280

---

and that's the whole page, bestie!! 🦋✨ you now know SSL socket functions better than half the internet. slay.

this has been neon 0.37.1, dated 15 March 2026 — the manual page is NE_SOCK_HANDSHAKE(3) and yes she ate. 💅🌸 mwah, go free your malloc-allocated strings. 🫶