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
¶ Server side socket.
Enums
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 thanssl_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 asSSL_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
¶
-
struct
ssl_socket_t
¶