ne_sock_handshake
Prev | neon API reference | Next

## 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 and RFC 3280. 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

Prev | Up | Next
ne_ssl_context_create | Home | ne_ssl_client_cert