NE_SOCK_HANDSHAKE(3)

NAME
ne_sock_handshake, ne_sock_sessid, ne_sock_cipher, ne_sock_getproto, ne_sock_getcert, ne_ssl_check_certificate - SSL socket functions

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);

DESCRIPTION

The ne_sock_handshake function initiates an SSL handshake on socket sock using SSL context ctx. If hostname is non-NULL, it is used as the Server Name Indication (SNI) hint. The flags parameter must be zero.

The ne_sock_sessid function retrieves the session ID of the current SSL session. If buf is non-NULL, on success, copies at most *buflen bytes to buf and sets *buflen to the exact number of bytes copied. If buf is NULL, on success, sets *buflen to the length of the session ID.

The ne_sock_cipher function returns a human-readable name of the SSL/TLS cipher used for the connection, or NULL if none. The format of this string is not intended to be fixed or parseable, but is informational only. The return value is a NUL-terminated malloc-allocated string which must be freed by the caller.

The ne_sock_getproto function returns the SSL/TLS protocol version used for socket sock, or NE_SSL_PROTO_UNSPEC if SSL/TLS is not in use for the socket.

The ne_sock_getcert function returns the server certificate for the socket.

The ne_ssl_check_certificate function checks the identity of a server certificate against the hostname or address used to establish the connection, following rules specified by RFC 2818[1] and RFC 3280[2]. Either hostname or address can be non-NULL; whichever was used to identify the server when establishing the SSL connection. If both are NULL, matching will fail but the *identity output parameter will still be set. The flags parameter must be zero. If verification fails, the failure reasons are stored in *failures as a binary OR of NE_SSL_* values.

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.

HISTORY

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.

SEE ALSO

ne_ssl_context_create(3)

COPYRIGHT
Copyright © 2001-2026 Joe Orton

REFERENCES

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

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