5.10. ssl — Secure socket layer

SSL/TLS based on mbedTLS. Server side sockets works, but not client side.

Warning

This module may lead to a false sense of security, as it is implemented by a TLS/SSL novice, me. Use with care!

Simplified server and client side examples to illustrate how to use the module. All error checking is left out to make the example easier to understand. There are links to the full examples further down in this document.

Server side:

/* Create the SSL context. */
ssl_context_init(&context, ssl_protocol_tls_v1_0);
ssl_context_load_cert_chain(&context, &certificate[0], &key[0]);

/* Create the TCP listener socket. */
socket_open_tcp(&listener_sock);
socket_bind(&listener_sock, &addr);
socket_listen(&listener_sock, 5);

/* Accept a client.*/
socket_accept(&listener_sock, &sock, &addr);
ssl_socket_open(&ssl_sock,
                &context,
                &sock,
                SSL_SOCKET_SERVER_SIDE,
                NULL);

/* Communicate with the client. */
ssl_socket_read(&ssl_sock, &buf[0], 6);
ssl_socket_write(&ssl_sock, "Goodbye!", 8);
ssl_socket_close(&ssl_sock);
socket_close(&sock);

Client side:

/* Create the SSL context. */
ssl_context_init(&context, ssl_protocol_tls_v1_0);
ssl_context_load_verify_location(&context, &certificate[0]);

/* Create the TCP socket and connect to the server. */
socket_open_tcp(&sock);
socket_connect(&sock, &addr);
ssl_socket_open(&ssl_sock,
                &context,
                &sock,
                0,
                "foobar.org");

/* Communicate with the client. */
ssl_socket_write(&ssl_sock, "Hello!", 6);
ssl_socket_read(&ssl_sock, &buf[0], 8);
ssl_socket_close(&ssl_sock);
socket_close(&ssl_sock);

Source code: src/inet/ssl.h, src/inet/ssl.c

Test code: tst/inet/ssl/main.c,

Test coverage: src/inet/ssl.c

Example code: examples/ssl_client/main.c, examples/ssl_server/main.c


Defines

SSL_SOCKET_SERVER_SIDE 0x1

Enums

enum ssl_protocol_t

Values:

ssl_protocol_tls_v1_0
enum ssl_verify_mode_t

Values:

ssl_verify_mode_cert_none_t = 0
ssl_verify_mode_cert_required_t = 2

Functions

int ssl_module_init(void)

Initialize the SSL module. This function must be called before calling any other function in this module.

The module will only be initialized once even if this function is called multiple times.

Return
zero(0) or negative error code.

int ssl_context_init(struct ssl_context_t *self_p, enum ssl_protocol_t protocol)

Initialize given SSL context. A SSL context contains settings that lives longer than a socket.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL context to initialize.
  • protocol: SSL protocol to use.

int ssl_context_destroy(struct ssl_context_t *self_p)

Destroy given SSL context. The context may not be used after it has been destroyed.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL context to destroy.

int ssl_context_load_cert_chain(struct ssl_context_t *self_p, const char *cert_p, const char *key_p)

Load given certificate chain into given context.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL context.
  • self_p: Certificate to load.
  • self_p: Optional key to load. May be NULL.

int ssl_context_load_verify_location(struct ssl_context_t *self_p, const char *ca_certs_p)

Load a set of “certification authority” (CA) certificates used to validate other peers’ certificates when verify_mode is other than ssl_verify_mode_cert_none_t.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL context.
  • ca_certs_p: CA certificates.

int ssl_context_set_verify_mode(struct ssl_context_t *self_p, enum ssl_verify_mode_t mode)

Whether to try to verify other peers’ certificates.

Load CA certificates with ssl_context_load_verify_location().

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL context.
  • mode: Mode to set.

int ssl_socket_open(struct ssl_socket_t *self_p, struct ssl_context_t *context_p, void *socket_p, int flags, const char *server_hostname_p)

Initialize given SSL socket with given socket and SSL context. Performs the SSL handshake.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL socket to initialize.
  • context_p: SSL context to execute in.
  • socket_p: Socket to wrap in the SSL socket.
  • flags: Give as SSL_SOCKET_SERVER_SIDE for server side sockets. Otherwise 0.
  • server_hostname_p: The server hostname used by client side sockets to verify the server. Give as NULL to skip the verification. Must be NULL for server side sockets.

int ssl_socket_close(struct ssl_socket_t *self_p)

Close given SSL socket.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL socket to close.

ssize_t ssl_socket_write(struct ssl_socket_t *self_p, const void *buf_p, size_t size)

Write data to given SSL socket.

Return
Number of written bytes or negative error code.
Parameters
  • self_p: SSL socket.
  • buf_p: Buffer to send.
  • size: Numer of bytes to send.

ssize_t ssl_socket_read(struct ssl_socket_t *self_p, void *buf_p, size_t size)

Read data from given SSL socket.

Return
Number of read bytes or negative error code.
Parameters
  • self_p: SSL socket.
  • buf_p: Buffer to read into.
  • size: Number of bytes to read.

ssize_t ssl_socket_size(struct ssl_socket_t *self_p)

Get the number of input bytes currently stored in the SSL socket.

Return
Number of input bytes in the SSL socket.
Parameters
  • self_p: SSL socket.

const char *ssl_socket_get_server_hostname(struct ssl_socket_t *self_p)

Get the hostname of the server.

Return
Server hostname or NULL.
Parameters
  • self_p: SSL socket.

int ssl_socket_get_cipher(struct ssl_socket_t *self_p, const char **cipher_pp, const char **protocol_pp, int *number_of_secret_bits_p)

Get the cipher information.

Return
zero(0) or negative error code.
Parameters
  • self_p: SSL socket.
  • cipher_pp: Connection cipher.
  • protocol_pp: Connection protocol.
  • number_of_secret_bits_p: Number of secret bits.

struct ssl_context_t

Public Members

ssl_protocol_t protocol
void *conf_p
int server_side
int verify_mode
struct ssl_socket_t

Public Members

struct chan_t base
void *ssl_p
void *socket_p