The standard interface in C. More...

Functions
EXP_FUNC SSL_CTX *STDCALL	ssl_ctx_new (SSL_CTX *ssl_ctx, uint32_t options, int num_sessions)
	Establish a new client/server context.
EXP_FUNC void STDCALL	ssl_ctx_free (SSL_CTX *ssl_ctx)
	Remove a client/server context.
EXP_FUNC SSL *STDCALL	ssl_server_new (SSL_CTX *ssl_ctx, int client_fd)
	(server only) Establish a new SSL connection to an SSL client.
EXP_FUNC SSL *STDCALL	ssl_client_new (SSL ssl, int client_fd, const uint8_t session_id, uint8_t sess_id_size)
	(client only) Establish a new SSL connection to an SSL server.
EXP_FUNC void STDCALL	ssl_free (SSL *ssl)
	Free any used resources on this connection.
EXP_FUNC int STDCALL	ssl_write (SSL ssl, const uint8_t out_data, int out_len)
	Read the SSL data stream.
EXP_FUNC SSL *STDCALL	ssl_find (SSL_CTX *ssl_ctx, int client_fd)
	Find an ssl object based on a file descriptor.
EXP_FUNC const uint8_t *STDCALL	ssl_get_session_id (const SSL *ssl)
	Get the session id for a handshake.
EXP_FUNC uint8_t STDCALL	ssl_get_session_id_size (const SSL *ssl)
	Get the session id size for a handshake.
EXP_FUNC uint8_t STDCALL	ssl_get_cipher_id (const SSL *ssl)
	Return the cipher id (in the SSL form).
EXP_FUNC int STDCALL	ssl_handshake_status (const SSL *ssl)
	Return the status of the handshake.
EXP_FUNC int STDCALL	ssl_get_config (int offset)
	Retrieve various parameters about the axTLS engine.
EXP_FUNC void STDCALL	ssl_display_error (int error_code)
	Display why the handshake failed.
EXP_FUNC int STDCALL	ssl_verify_cert (const SSL *ssl)
	Authenticate a received certificate.
EXP_FUNC const char *STDCALL	ssl_get_cert_dn (const SSL *ssl, int component)
	Retrieve an X.509 distinguished name component.
EXP_FUNC const char *STDCALL	ssl_get_cert_subject_alt_dnsname (const SSL *ssl, int dnsindex)
	Retrieve a Subject Alternative DNSName.
EXP_FUNC int STDCALL	ssl_renegotiate (SSL *ssl)
	Force the client to perform its handshake again.
EXP_FUNC int STDCALL	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.
EXP_FUNC int STDCALL	ssl_obj_memory_load (SSL_CTX ssl_ctx, int obj_type, const uint8_t data, int len, const char *password)
	Process binary data.
EXP_FUNC int STDCALL	ssl_x509_create (SSL_CTX ssl_ctx, uint32_t options, const char dn[], uint8_t **cert_data)
	Create an X.509 certificate.
EXP_FUNC const char *STDCALL	ssl_version (void)
	Return the axTLS library version as a string.

Detailed Description

The standard interface in C.

Function Documentation

EXP_FUNC SSL* STDCALL ssl_client_new	(	SSL *	ssl,
		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().

Parameters:

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)

Returns:: An SSL object reference. Use ssl_handshake_status() to check if a handshake succeeded.

Definition at line 50 of file tls1_clnt.c.

EXP_FUNC void STDCALL 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).

Parameters:

ssl_ctx [in] The client/server context.

Definition at line 205 of file tls1.c.

EXP_FUNC SSL_CTX* STDCALL ssl_ctx_new	(	SSL_CTX *	ssl_ctx,
		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.

Parameters:

options

[in] Any particular options. At present the options supported are:

SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if the server authentication fails. The certificate can be authenticated later with a call to ssl_verify_cert().
SSL_CLIENT_AUTHENTICATION (server only): Enforce client authentication i.e. each handshake will include a "certificate request" message from the server. Only available if verification has been enabled.
SSL_DISPLAY_BYTES (full mode build only): Display the byte sequences during the handshake.
SSL_DISPLAY_STATES (full mode build only): Display the state changes during the handshake.
SSL_DISPLAY_CERTS (full mode build only): Display the certificates that are passed during a handshake.
SSL_DISPLAY_RSA (full mode build only): Display the RSA key details that are passed during a handshake.
SSL_CONNECT_IN_PARTS (client only): To use a non-blocking version of ssl_client_new().

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.

Returns:: A client/server context.

Definition at line 173 of file tls1.c.

EXP_FUNC void STDCALL ssl_display_error ( int error_code )

Display why the handshake failed.

Enable the various language bindings to work regardless of the configuration - they just return an error statement and a bad return code.

This call is only useful in a 'full mode' build. The output is to stdout.

Parameters:

error_code [in] An error code.

See also:: ssl.h for the error code list.

Display why the handshake failed.

Enable the various language bindings to work regardless of the configuration - they just return an error statement and a bad return code.

Definition at line 2288 of file tls1.c.

EXP_FUNC SSL* STDCALL 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.

Parameters:

ssl_ctx	[in] The client/server context.
client_fd	[in] The file descriptor.

Returns:: A reference to the SSL object. Returns null if the object could not be found.

Definition at line 476 of file tls1.c.

EXP_FUNC void STDCALL 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.

Parameters:

ssl	[in] The ssl object reference.

Definition at line 251 of file tls1.c.

EXP_FUNC const char *STDCALL 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.

Parameters:

ssl [in] An SSL object reference.

component

[in] one of:

SSL_X509_CERT_COMMON_NAME
SSL_X509_CERT_ORGANIZATION
SSL_X509_CERT_ORGANIZATIONAL_NAME
SSL_X509_CA_CERT_COMMON_NAME
SSL_X509_CA_CERT_ORGANIZATION
SSL_X509_CA_CERT_ORGANIZATIONAL_NAME

Returns:: The appropriate string (or null if not defined)

Note:: Verification build mode must be enabled.

Definition at line 2309 of file tls1.c.

EXP_FUNC const char *STDCALL 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.

Parameters:

ssl	[in] An SSL object reference.
dnsindex	[in] The index of the DNS name to retrieve.

Returns:: The appropriate string (or null if not defined)

Note:: Verification build mode must be enabled.

Definition at line 2315 of file tls1.c.

EXP_FUNC uint8_t STDCALL ssl_get_cipher_id ( const SSL * ssl )

Return the cipher id (in the SSL form).

Parameters:

ssl	[in] An SSL object reference.

Returns:

The cipher id. This will be one of the following:

SSL_AES128_SHA (0x2f)
SSL_AES256_SHA (0x35)
SSL_RC4_128_SHA (0x05)
SSL_RC4_128_MD5 (0x04)

Definition at line 1876 of file tls1.c.

EXP_FUNC int STDCALL ssl_get_config ( int offset )

Retrieve various parameters about the axTLS engine.

Parameters:

offset

[in] The configuration offset. It will be one of the following:

SSL_BUILD_MODE The build mode. This will be one of the following:
- SSL_BUILD_SERVER_ONLY (basic server mode)
- SSL_BUILD_ENABLE_VERIFICATION (server can do client authentication)
- SSL_BUILD_ENABLE_CLIENT (client/server capabilties)
- SSL_BUILD_FULL_MODE (client/server with diagnostics)
- SSL_BUILD_SKELETON_MODE (skeleton mode)
SSL_MAX_CERT_CFG_OFFSET The maximum number of certificates allowed.
SSL_MAX_CA_CERT_CFG_OFFSET The maximum number of CA certificates allowed.
SSL_HAS_PEM 1 if supported

Returns:: The value of the requested parameter.

Definition at line 1892 of file tls1.c.

EXP_FUNC const uint8_t* STDCALL 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.

Parameters:

ssl	[in] An SSL object reference.

Returns:: The session id as a 32 byte sequence.

Note:: A SSLv23 handshake may have only 16 valid bytes.

Definition at line 1860 of file tls1.c.

EXP_FUNC uint8_t STDCALL 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.

Parameters:

ssl	[in] An SSL object reference.

Returns:: The size of the session id.

Definition at line 1868 of file tls1.c.

EXP_FUNC int STDCALL ssl_handshake_status ( const SSL * ssl )

Return the status of the handshake.

Parameters:

ssl	[in] An SSL object reference.

Returns:: SSL_OK if the handshake is complete and ok.

See also:: ssl.h for the error code list.

Definition at line 1884 of file tls1.c.

EXP_FUNC int STDCALL 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.

Parameters:

ssl_ctx [in] The client/server context.

obj_type

[in] The format of the file. Can be one of:

SSL_OBJ_X509_CERT (no password required)
SSL_OBJ_X509_CACERT (no password required)
SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
SSL_OBJ_PKCS8 (RC4-128 encrypted data supported)
SSL_OBJ_PKCS12 (RC4-128 encrypted data supported)

PEM files are automatically detected (if supported). The object type is also detected, and so is not relevant for these types of files.

Parameters:

filename	[in] The location of a file in DER/PEM format.
password	[in] The password used. Can be null if not required.

Returns:: SSL_OK if all ok

Note:: Not available in skeleton build mode.

Definition at line 58 of file loader.c.

EXP_FUNC int STDCALL 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.

Parameters:

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.

Returns:: SSL_OK if all ok

See also:: ssl_obj_load for more details on obj_type.

Definition at line 105 of file loader.c.

EXP_FUNC int STDCALL 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).

Parameters:

ssl	[in] An SSL object reference.

Returns:: SSL_OK if renegotiation instantiation was ok

Definition at line 502 of file tls1.c.

EXP_FUNC SSL* STDCALL 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).

Parameters:

ssl_ctx	[in] The server context.
client_fd	[in] The client's file descriptor.

Returns:: An SSL object reference.

Definition at line 52 of file tls1_svr.c.

EXP_FUNC int STDCALL 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.

Parameters:

ssl	[in] An SSL object reference.

Returns:: SSL_OK if the certificate is verified.

Definition at line 2302 of file tls1.c.

EXP_FUNC const char* STDCALL ssl_version ( void )

Return the axTLS library version as a string.

Definition at line 2277 of file tls1.c.

EXP_FUNC int STDCALL ssl_write	(	SSL *	ssl,
		const uint8_t *	out_data,
		int	out_len
	)

Read the SSL data stream.

If the socket is non-blocking and data is blocked then SSO_OK will be returned.

Parameters:

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.

Returns:

The number of decrypted bytes:

if > 0, then the handshaking is complete and we are returning the number of decrypted bytes.
SSL_OK if the handshaking stage is successful (but not yet complete).
< 0 if an error.

See also:: ssl.h for the error code list.

Note:: Use in_data before doing any successive ssl calls. 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).

Parameters:

ssl	[in] An SSL obect reference.
out_data	[in] The data to be written
out_len	[in] The number of bytes to be written.

Returns:: The number of bytes sent, or if < 0 if an error.

See also:: ssl.h for the error code list.

Definition at line 295 of file tls1.c.

EXP_FUNC int STDCALL ssl_x509_create	(	SSL_CTX *	ssl_ctx,
		uint32_t	options,
		const char *	dn[],
		uint8_t **	cert_data
	)

Create an X.509 certificate.

This certificate is a self-signed v1 cert with a fixed start/stop validity times. It is signed with an internal private key in ssl_ctx.

Parameters:

ssl_ctx	[in] The client/server context.
options	[in] Not used yet.
dn	[in] An array of distinguished name strings. The array is defined by: SSL_X509_CERT_COMMON_NAME (0) If SSL_X509_CERT_COMMON_NAME is empty or not defined, then the hostname will be used. SSL_X509_CERT_ORGANIZATION (1) If SSL_X509_CERT_ORGANIZATION is empty or not defined, then $USERNAME will be used. SSL_X509_CERT_ORGANIZATIONAL_NAME (2) SSL_X509_CERT_ORGANIZATIONAL_NAME is optional.
cert_data	[out] The certificate as a sequence of bytes.

Returns:: < 0 if an error, or the size of the certificate in bytes.

Note:: cert_data must be freed when there is no more need for it.

Definition at line 341 of file gen_cert.c.

Type:	Library
Created:	20 Jul 2017
Imports:	0
Forks:	0
Commits:	2
Dependents:	0
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

Standard C API

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

Standard C API

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning