TLS interface on nRF5x. More...

Data Structures
struct	nrf_tls_instance_t
	TLS Instance identifier. More...

struct	nrf_tls_preshared_key_t
	Information needed when using Pre-shared key ciphers. More...

struct	nrf_tls_raw_key_t
	Information provided when using Raw Public key ciphers. More...

struct	nrf_tls_certificate_t
	Certificate to be used when using certificates for key derivation. More...

struct	nrf_tls_key_settings_t
	Key settings to be used for TLS instance. More...

struct	nrf_tls_options_t
	Options when requesting an TLS instance. More...

Macros
#define	NRF_TLS_INVALID_INSTANCE_IDENTIFIER 0xFFFFFFFF
	Maximum number of TLS instances to be supported.

#define	NRF_TLS_INTSANCE_INIT(INSTANCE)
	Initializes the TLS instance. More...

Typedefs
typedef uint32_t(*	nrf_tls_output_t )(nrf_tls_instance_t const p_instance, uint8_t const p_data, uint32_t datalen)
	Transport write function registered for the instance. More...

Enumerations
enum	nrf_transport_type_t { NRF_TLS_TYPE_STREAM, NRF_TLS_TYPE_DATAGRAM }
	Transport type definitions. The type determines whether TLS or DTLS shall be used. More...

enum	nrf_tls_role_t { NRF_TLS_ROLE_CLIENT, NRF_TLS_ROLE_SERVER }
	TLS/DTLS roles definition. More...

Functions
uint32_t	nrf_tls_init (void)
	Initialize TLS interface. More...

uint32_t	nrf_tls_alloc (nrf_tls_instance_t p_instance, nrf_tls_options_t const p_options)
	Allocate an TLS/DTLS instance. More...

uint32_t	nrf_tls_free (nrf_tls_instance_t const *p_instance)
	Free the TLS/DTLS instance. More...

uint32_t	nrf_tls_write (nrf_tls_instance_t const p_instance, uint8_t const p_data, uint32_t *p_datalen)
	Write data on the TLS/DTLS instance. More...

uint32_t	nrf_tls_read (nrf_tls_instance_t const p_instance, uint8_t p_data, uint32_t *p_datalen)
	Read data from the TLS/DTLS instance. More...

uint32_t	nrf_tls_input (nrf_tls_instance_t const p_instance, uint8_t const p_data, uint32_t datalen)
	Function to input data read on the transport to the TLS library. More...

void	nrf_tls_process (void)
	Function to continue TLS/DTLS operation after a busy state on transport. More...

Detailed Description

TLS interface on nRF5x.

Defines TLS interface for securing UDP/TCP transport using DTLS/TLS respectively. The interface integrates TLS library with needed libraries/drivers on the nRF.

Macro Definition Documentation

#define NRF_TLS_INTSANCE_INIT ( INSTANCE )

Value:

do                                                                                         \
        {                                                                                          \
            (INSTANCE)->transport_id = NRF_TLS_INVALID_INSTANCE_IDENTIFIER;                        \
            (INSTANCE)->instance_id  = NRF_TLS_INVALID_INSTANCE_IDENTIFIER;                        \
        }while(0)

Initializes the TLS instance.

Typedef Documentation

typedef uint32_t(* nrf_tls_output_t)(nrf_tls_instance_t const *p_instance, uint8_t const *p_data, uint32_t datalen)

Transport write function registered for the instance.

Function registered with the interface to write on the transport interface. The application shall implement the function registered here to ensure handshake messages and encrypted data can be written by the interface/TLS library on the transport.

Parameters

[in]	p_instance	Identifies the instance on which transport write is requested. Shall not be NULL.
[in]	p_data	Pointer to data to be written on the instance. Shall not be NULL.
[in]	datalen	Length of data to be written on the transport.

Return values

NRF_SUCCESS If the procedure was successful, else an error code indicating reason for failure.

Enumeration Type Documentation

enum nrf_tls_role_t

TLS/DTLS roles definition.

Enumerator
NRF_TLS_ROLE_CLIENT	Client role.
NRF_TLS_ROLE_SERVER	Server role.

enum nrf_transport_type_t

Transport type definitions. The type determines whether TLS or DTLS shall be used.

Enumerator
NRF_TLS_TYPE_STREAM	TCP transport, TLS to be used for the instance.
NRF_TLS_TYPE_DATAGRAM	UDP transport, DTLS to be used for the instance.

Function Documentation

uint32_t nrf_tls_alloc	(	nrf_tls_instance_t *	p_instance,
		nrf_tls_options_t const *	p_options
	)

Allocate an TLS/DTLS instance.

This function allocates an instance for TLS/DTLS. Options indicate whether DTLS/TLS will be used and role is server or client.

Parameters

[in,out]	p_instance	Instance with transport id set by the application to identify the transport being secured. If the procedure is successful, the instance id is allocated by the interface. The application is expected to remember the instance information for all subsequent procedures on the transport. Shall not be NULL.
[in]	p_options	Pointer to options that indicate transport type, role, keys etc. Output function registered is used write TLS/DTLS data on the raw transport (TCP.UDP) for the instance. Shall not be NULL.

Note

Return values

NRF_SUCCESS If the procedure is successful, else, an error code indicating reason for failure. If the procedure succeeds, the application shall use the instance allocated for all subsequent procedures on the instance.

uint32_t nrf_tls_free ( nrf_tls_instance_t const * p_instance )

Free the TLS/DTLS instance.

This function frees the instance allocated for TLS/DTLS. All sessions, buffered data related to instance are freed as well by this API.

Parameters

[in] p_instance Identifies the instance being freed. Shall not be NULL.

Return values

NRF_SUCCESS If the procedure is successful, else, an error code indicating reason for failure. If the procedure succeeds, the application shall use the instance allocated for all subsequent procedures on the instance.

uint32_t nrf_tls_init ( void )

Initialize TLS interface.

This function initializes TLS interface. Initialization includes initializing the TLS library, RNG driver, and any other dependencies. This API shall be called before using any other APIs of the interface.

Return values

NRF_SUCCESS If the procedure is successful, else, an error code indicating reason for failure. If the procedure fails, the application shall not proceed with using other APIs of the interface.

uint32_t nrf_tls_input	(	nrf_tls_instance_t const *	p_instance,
		uint8_t const *	p_data,
		uint32_t	datalen
	)

Function to input data read on the transport to the TLS library.

Function to input data read on the transport to TLS library for further processing. Further processing could include advancing the handshake or decrypting the received data based on the state of TLS session.

Parameters

[in]	p_instance	Identifies the instance on which transport write is requested. Shall not be NULL.
[in]	p_data	Pointer to data to be processed on the instance. Shall not be NULL.
[in]	datalen	Length of data to be written on the transport.

Return values

NRF_SUCCESS If the procedure was successful, else an error code indicating reason for failure.

void nrf_tls_process ( void )

Function to continue TLS/DTLS operation after a busy state on transport.

The transport writes requested by the TLS interface may return failure if transport data flow was off. In order to resume and retry the operations, this function shall be called periodically. This function shall be called in order to ensure TLS interface and the library behaves as expected.

uint32_t nrf_tls_read	(	nrf_tls_instance_t const *	p_instance,
		uint8_t *	p_data,
		uint32_t *	p_datalen
	)

Read data from the TLS/DTLS instance.

This function reads data from the TLS/DTLS interface. The read data is decrypted based on cipher configuration and selected cipher during handshake. If no data is available on the instance, the API indicates so with an error code. It is possible to request size of data that can be read by passing a NULL parameter on the data.

Parameters

[in]	p_instance	Identifies the instance on which read is requested. Shall not be NULL.
[in]	p_data	Pointer to data where read data is to be copied. Can be NULL. In case, this parameter is NULL, size of bytes that are available to read is returned in the p_datalen parameter.
[in,out]	p_datalen	Pointer to size of data to be read. The application shall ensure that the memory pointed to by p_data parameter is the size indicated. The actual size read can be smaller than requested and is indicated here if the procedure is successful. The application should check for the actual size read. Shall not be NULL.

Return values

NRF_SUCCESS If the procedure is successful, else, an error code indicating reason for failure. If the procedure succeeds, the application should check for the actual size read.

uint32_t nrf_tls_write	(	nrf_tls_instance_t const *	p_instance,
		uint8_t const *	p_data,
		uint32_t *	p_datalen
	)

Write data on the TLS/DTLS instance.

This function writes data on the TLS/DTLS instance. The requested data is encrypted and padded based on cipher configuration and selected cipher during handshake. If no sessions exists already with the peer, a handshake is initiated automatically by the interface, if the role played on the instance is a client role. Requested data to be written is buffered until a session is established.

Parameters

[in]	p_instance	Identifies the instance on which write is requested. Shall not be NULL.
[in]	p_data	Pointer to data to be written on the instance. Shall not be NULL.
[in,out]	p_datalen	Pointer to size of data to be written. The actual size written can be smaller than requested and is indicated here if the procedure is successful. The application shall check for the actual size written and make subsequent requests in case the right was partial. Shall not be NULL.

Return values

NRF_SUCCESS If the procedure is successful, else, an error code indicating reason for failure. If the procedure succeeds, the application shall check for the actual size written and make subsequent requests in case the right was partial.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation