ESP8266
|
The standard interface in C. More...
Functions | |
SSL_CTX * | ssl_ctx_new (uint32_t options, int num_sessions) |
Establish a new client/server context. More... | |
void | ssl_ctx_free (SSL_CTX *ssl_ctx) |
Remove a client/server context. More... | |
SSL * | ssl_server_new (SSL_CTX *ssl_ctx, int client_fd) |
(server only) Establish a new SSL connection to an SSL client. More... | |
SSL * | ssl_client_new (SSL_CTX *ssl_ctx, int client_fd, const uint8_t *session_id, uint8_t sess_id_size) |
(client only) Establish a new SSL connection to an SSL server. More... | |
void | ssl_free (SSL *ssl) |
Free any used resources on this connection. More... | |
int | ssl_read (SSL *ssl, uint8_t **in_data) |
Read the SSL data stream. If the socket is non-blocking and data is blocked then SSO_OK will be returned. More... | |
int | ssl_write (SSL *ssl, const uint8_t *out_data, int out_len) |
Write to the SSL data stream. if the socket is non-blocking and data is blocked then a check is made to ensure that all data is sent (i.e. blocked mode is forced). More... | |
SSL * | ssl_find (SSL_CTX *ssl_ctx, int client_fd) |
Find an ssl object based on a file descriptor. More... | |
const uint8_t * | ssl_get_session_id (const SSL *ssl) |
Get the session id for a handshake. More... | |
uint8_t | ssl_get_session_id_size (const SSL *ssl) |
Get the session id size for a handshake. More... | |
uint8_t | ssl_get_cipher_id (const SSL *ssl) |
Return the cipher id (in the SSL form). More... | |
int | ssl_handshake_status (const SSL *ssl) |
Return the status of the handshake. More... | |
int | ssl_get_config (int offset) |
Retrieve various parameters about the axTLS engine. More... | |
void | ssl_display_error (int error_code) |
Display why the handshake failed. More... | |
int | ssl_verify_cert (const SSL *ssl) |
Authenticate a received certificate. More... | |
int | ssl_match_fingerprint (const SSL *ssl, const uint8_t *fp) |
Check if certificate fingerprint (SHA1) matches the one given. More... | |
const char * | ssl_get_cert_dn (const SSL *ssl, int component) |
Retrieve an X.509 distinguished name component. More... | |
const char * | ssl_get_cert_subject_alt_dnsname (const SSL *ssl, int dnsindex) |
Retrieve a Subject Alternative DNSName. More... | |
int | ssl_renegotiate (SSL *ssl) |
Force the client to perform its handshake again. More... | |
int | ssl_obj_load (SSL_CTX *ssl_ctx, int obj_type, const char *filename, const char *password) |
Process a file that is in binary DER or ASCII PEM format. More... | |
int | ssl_obj_memory_load (SSL_CTX *ssl_ctx, int obj_type, const uint8_t *data, int len, const char *password) |
Process binary data. More... | |
const char * | ssl_version (void) |
Return the axTLS library version as a string. More... | |
The standard interface in C.
SSL* ssl_client_new | ( | SSL_CTX * | ssl_ctx, |
int | client_fd, | ||
const uint8_t * | session_id, | ||
uint8_t | sess_id_size | ||
) |
(client only) Establish a new SSL connection to an SSL server.
It is up to the application to establish the initial logical connection (whether it is a socket, serial connection etc).
This is a normally a blocking call - it will finish when the handshake is complete (or has failed). To use in non-blocking mode, set SSL_CONNECT_IN_PARTS in ssl_ctx_new().
ssl_ctx | [in] The client context. |
client_fd | [in] The client's file descriptor. |
session_id | [in] A 32 byte session id for session resumption. This can be null if no session resumption is being used or required. This option is not used in skeleton mode. |
sess_id_size | The size of the session id (max 32) |
void ssl_ctx_free | ( | SSL_CTX * | ssl_ctx | ) |
Remove a client/server context.
Frees any used resources used by this context. Each connection will be sent a "Close Notify" alert (if possible).
ssl_ctx | [in] The client/server context. |
SSL_CTX* ssl_ctx_new | ( | uint32_t | options, |
int | num_sessions | ||
) |
Establish a new client/server context.
This function is called before any client/server SSL connections are made.
Each new connection will use the this context's private key and certificate chain. If a different certificate chain is required, then a different context needs to be be used.
There are two threading models supported - a single thread with one SSL_CTX can support any number of SSL connections - and multiple threads can support one SSL_CTX object each (the default). But if a single SSL_CTX object uses many SSL objects in individual threads, then the CONFIG_SSL_CTX_MUTEXING option needs to be configured.
options | [in] Any particular options. At present the options supported are:
|
num_sessions | [in] The number of sessions to be used for session caching. If this value is 0, then there is no session caching. This option is not used in skeleton mode. |
void ssl_display_error | ( | int | error_code | ) |
Display why the handshake failed.
This call is only useful in a 'full mode' build. The output is to stdout.
error_code | [in] An error code. |
SSL* ssl_find | ( | SSL_CTX * | ssl_ctx, |
int | client_fd | ||
) |
Find an ssl object based on a file descriptor.
Goes through the list of SSL objects maintained in a client/server context to look for a file descriptor match.
ssl_ctx | [in] The client/server context. |
client_fd | [in] The file descriptor. |
void ssl_free | ( | SSL * | ssl | ) |
Free any used resources on this connection.
A "Close Notify" message is sent on this connection (if possible). It is up to the application to close the socket or file descriptor.
ssl | [in] The ssl object reference. |
const char* ssl_get_cert_dn | ( | const SSL * | ssl, |
int | component | ||
) |
Retrieve an X.509 distinguished name component.
When a handshake is complete and a certificate has been exchanged, then the details of the remote certificate can be retrieved.
This will usually be used by a client to check that the server's common name matches the URL.
ssl | [in] An SSL object reference. |
component | [in] one of:
|
const char* ssl_get_cert_subject_alt_dnsname | ( | const SSL * | ssl, |
int | dnsindex | ||
) |
Retrieve a Subject Alternative DNSName.
When a handshake is complete and a certificate has been exchanged, then the details of the remote certificate can be retrieved.
This will usually be used by a client to check that the server's DNS name matches the URL.
ssl | [in] An SSL object reference. |
dnsindex | [in] The index of the DNS name to retrieve. |
uint8_t ssl_get_cipher_id | ( | const SSL * | ssl | ) |
Return the cipher id (in the SSL form).
ssl | [in] An SSL object reference. |
int ssl_get_config | ( | int | offset | ) |
Retrieve various parameters about the axTLS engine.
offset | [in] The configuration offset. It will be one of the following:
|
const uint8_t* ssl_get_session_id | ( | const SSL * | ssl | ) |
Get the session id for a handshake.
This will be a 32 byte sequence and is available after the first handshaking messages are sent.
ssl | [in] An SSL object reference. |
uint8_t ssl_get_session_id_size | ( | const SSL * | ssl | ) |
Get the session id size for a handshake.
This will normally be 32 but could be 0 (no session id) or something else.
ssl | [in] An SSL object reference. |
int ssl_handshake_status | ( | const SSL * | ssl | ) |
Return the status of the handshake.
ssl | [in] An SSL object reference. |
int ssl_match_fingerprint | ( | const SSL * | ssl, |
const uint8_t * | fp | ||
) |
Check if certificate fingerprint (SHA1) matches the one given.
ssl | [in] An SSL object reference. |
fp | [in] SHA1 fingerprint to match against |
int ssl_obj_load | ( | SSL_CTX * | ssl_ctx, |
int | obj_type, | ||
const char * | filename, | ||
const char * | password | ||
) |
Process a file that is in binary DER or ASCII PEM format.
These are temporary objects that are used to load private keys, certificates etc into memory.
ssl_ctx | [in] The client/server context. |
obj_type | [in] The format of the file. Can be one of:
|
PEM files are automatically detected (if supported). The object type is also detected, and so is not relevant for these types of files.
filename | [in] The location of a file in DER/PEM format. |
password | [in] The password used. Can be null if not required. |
int ssl_obj_memory_load | ( | SSL_CTX * | ssl_ctx, |
int | obj_type, | ||
const uint8_t * | data, | ||
int | len, | ||
const char * | password | ||
) |
Process binary data.
These are temporary objects that are used to load private keys, certificates etc into memory.
ssl_ctx | [in] The client/server context. |
obj_type | [in] The format of the memory data. |
data | [in] The binary data to be loaded. |
len | [in] The amount of data to be loaded. |
password | [in] The password used. Can be null if not required. |
int ssl_read | ( | SSL * | ssl, |
uint8_t ** | in_data | ||
) |
Read the SSL data stream. If the socket is non-blocking and data is blocked then SSO_OK will be returned.
ssl | [in] An SSL object reference. |
in_data | [out] If the read was successful, a pointer to the read buffer will be here. Do NOT ever free this memory as this buffer is used in sucessive calls. If the call was unsuccessful, this value will be null. |
int ssl_renegotiate | ( | SSL * | ssl | ) |
Force the client to perform its handshake again.
For a client this involves sending another "client hello" message. For the server is means sending a "hello request" message.
This is a blocking call on the client (until the handshake completes).
ssl | [in] An SSL object reference. |
SSL* ssl_server_new | ( | SSL_CTX * | ssl_ctx, |
int | client_fd | ||
) |
(server only) Establish a new SSL connection to an SSL client.
It is up to the application to establish the logical connection (whether it is a socket, serial connection etc).
ssl_ctx | [in] The server context. |
client_fd | [in] The client's file descriptor. |
int ssl_verify_cert | ( | const SSL * | ssl | ) |
Authenticate a received certificate.
This call is usually made by a client after a handshake is complete and the context is in SSL_SERVER_VERIFY_LATER mode.
ssl | [in] An SSL object reference. |
const char* ssl_version | ( | void | ) |
Return the axTLS library version as a string.
int ssl_write | ( | SSL * | ssl, |
const uint8_t * | out_data, | ||
int | out_len | ||
) |
Write to the SSL data stream. if the socket is non-blocking and data is blocked then a check is made to ensure that all data is sent (i.e. blocked mode is forced).
ssl | [in] An SSL obect reference. |
out_data | [in] The data to be written |
out_len | [in] The number of bytes to be written. |