Functionality for supporting provisioning of a node. More...

Modules
	Defines
	Provisioning defines.

	Bearers
	Bearer abstraction layer for provisioning.

	Events
	Provisioning event definitions.

	Types
	Provisioning type definitions.

Functions
uint32_t	nrf_mesh_prov_init (nrf_mesh_prov_ctx_t p_ctx, const uint8_t p_public_key, const uint8_t p_private_key, const nrf_mesh_prov_oob_caps_t p_caps, nrf_mesh_prov_evt_handler_cb_t event_handler)
	Initializes the provisioning context structure. More...

uint32_t	nrf_mesh_prov_bearer_add (nrf_mesh_prov_ctx_t p_ctx, prov_bearer_t p_prov_bearer)
	Adds a new bearer to the provisioning context structure. More...

uint32_t	nrf_mesh_prov_listen (nrf_mesh_prov_ctx_t p_ctx, const char URI, uint16_t oob_info_sources, uint32_t bearer_types)
	Listens for an incoming provisioning link. More...

uint32_t	nrf_mesh_prov_listen_stop (nrf_mesh_prov_ctx_t *p_ctx)
	Stops listening for an incoming provisioning link. More...

uint32_t	nrf_mesh_prov_generate_keys (uint8_t p_public, uint8_t p_private)
	Generates a valid keypair for use with the provisioning cryptography. More...

uint32_t	nrf_mesh_prov_provision (nrf_mesh_prov_ctx_t p_ctx, const uint8_t p_target_uuid, uint8_t attention_duration_s, const nrf_mesh_prov_provisioning_data_t *p_data, nrf_mesh_prov_bearer_type_t bearer)
	Provisions a device. More...

uint32_t	nrf_mesh_prov_oob_use (nrf_mesh_prov_ctx_t *p_ctx, nrf_mesh_prov_oob_method_t method, uint8_t action, uint8_t size)
	Selects which out-of-band authentication method to use. More...

uint32_t	nrf_mesh_prov_auth_data_provide (nrf_mesh_prov_ctx_t p_ctx, const uint8_t p_data, uint8_t size)
	Provides out-of-band authentication data input to the provisioning stack. More...

static uint32_t	nrf_mesh_prov_oob_number_provide (nrf_mesh_prov_ctx_t *p_ctx, uint32_t number)
	Provides out-of-band authentication number to the provisioning stack. More...

uint32_t	nrf_mesh_prov_shared_secret_provide (nrf_mesh_prov_ctx_t p_ctx, const uint8_t p_shared)
	Provides the shared secret to the provisioning stack after running a requested ECDH calculation. More...

uint32_t	nrf_mesh_prov_pubkey_provide (nrf_mesh_prov_ctx_t p_ctx, const uint8_t p_key)
	Provides a public key to the provisioner if the provisionee has exposed it out-of-band. More...

uint32_t	nrf_mesh_prov_scan_start (nrf_mesh_prov_evt_handler_cb_t event_handler)
	Starts the scanning for unprovisioned devices. More...

void	nrf_mesh_prov_scan_stop (void)
	Stops the scanning for unprovisioned devices (if started).

Detailed Description

Functionality for supporting provisioning of a node.

Function Documentation

◆ nrf_mesh_prov_init()

uint32_t nrf_mesh_prov_init	(	nrf_mesh_prov_ctx_t *	p_ctx,
		const uint8_t *	p_public_key,
		const uint8_t *	p_private_key,
		const nrf_mesh_prov_oob_caps_t *	p_caps,
		nrf_mesh_prov_evt_handler_cb_t	event_handler
	)

Initializes the provisioning context structure.

Warning: If calling this function the first time, it is required that the p_ctx is zero initialized. Any further calls require that p_ctx is left untouched.

Parameters

[in,out]	p_ctx	Pointer to the provisioning context structure to initialize.
[in]	p_public_key	Pointer to the node's public key. The public key is 64 bytes long.
[in]	p_private_key	Pointer to the node's private key. The private key is 32 bytes long.
[in]	p_caps	Pointer to a structure containing the node's out-of-band authentication capabilities.
[in]	event_handler	Event handler callback function.

Return values

NRF_SUCCESS	The library was successfully initialized.
NRF_ERROR_NULL	One or more parameters were NULL.
NRF_ERROR_INVALID_STATE	Initialization was attempted when the provisioning was already working.

◆ nrf_mesh_prov_bearer_add()

uint32_t nrf_mesh_prov_bearer_add	(	nrf_mesh_prov_ctx_t *	p_ctx,
		prov_bearer_t *	p_prov_bearer
	)

Adds a new bearer to the provisioning context structure.

This function is intented to be used in conjunction with a bearer specific bearer_<type>_interface_get() function. E.g., nrf_mesh_prov_bearer_adv_interface_get().

Parameters

[in,out]	p_ctx	Provisioning context structure.
[in,out]	p_prov_bearer	Generic provisioning context structure.

Return values

NRF_SUCCESS	Successfully added bearer.
NRF_ERROR_NULL	One or more parameters were NULL.
NRF_ERROR_FORBIDDEN	A bearer of the given type already exists in the provisioning context.

◆ nrf_mesh_prov_listen()

uint32_t nrf_mesh_prov_listen	(	nrf_mesh_prov_ctx_t *	p_ctx,
		const char *	URI,
		uint16_t	oob_info_sources,
		uint32_t	bearer_types
	)

Listens for an incoming provisioning link.

Parameters

[in,out]	p_ctx	Pointer to a statically allocated provisioning context structure.
[in]	URI	Optional device URI string used as identifier in some other context. May be NULL.
[in]	oob_info_sources	Known OOB information sources, see Provisioning OOB information sources..
[in]	bearer_types	Bitfield of nrf_mesh_prov_bearer_type_t bearers to listen on.

Return values

NRF_SUCCESS	The provisioning bearer was successfully put into listening mode.
NRF_ERROR_INVALID_STATE	The provisioning context is not in an idle state.
NRF_ERROR_INVALID_PARAM	(One of) the given bearer type(s) is/are not supported.

◆ nrf_mesh_prov_listen_stop()

uint32_t nrf_mesh_prov_listen_stop ( nrf_mesh_prov_ctx_t * p_ctx )

Stops listening for an incoming provisioning link.

Parameters

[in,out] p_ctx Pointer to a statically allocated provisioning context structure.

Return values

NRF_SUCCESS	The provisioning bearer was successfully put into listening mode.
NRF_ERROR_INVALID_STATE	The provisioning context is not listening.

◆ nrf_mesh_prov_generate_keys()

uint32_t nrf_mesh_prov_generate_keys	(	uint8_t *	p_public,
		uint8_t *	p_private
	)

Generates a valid keypair for use with the provisioning cryptography.

Parameters

[out]	p_public	Pointer to where the generated public key is stored.
[out]	p_private	Pointer to where the generated private key is stored.

Return values

NRF_SUCCESS The keypair was successfully generated.

◆ nrf_mesh_prov_provision()

uint32_t nrf_mesh_prov_provision	(	nrf_mesh_prov_ctx_t *	p_ctx,
		const uint8_t *	p_target_uuid,
		uint8_t	attention_duration_s,
		const nrf_mesh_prov_provisioning_data_t *	p_data,
		nrf_mesh_prov_bearer_type_t	bearer
	)

Provisions a device.

Parameters

[in,out]	p_ctx	Pointer to a statically allocated provisioning context structure.
[in]	p_target_uuid	Device UUID of the device that is to be provisioned.
[in]	attention_duration_s	Time in seconds during which the device will identify itself using any means it can.
[in]	p_data	Pointer to a structure containing the provisioning data for the device.
[in]	bearer	Which bearer to establish the provisioning link on.

Return values

NRF_SUCCESS	The provisioning process was started.
NRF_ERROR_NULL	One or more parameters were NULL.
NRF_ERROR_NOT_SUPPORTED	The given bearer type is not supported.
NRF_ERROR_INVALID_DATA	The provisioning data failed some boundary conditions.
NRF_ERROR_INVALID_STATE	The given context is in use.

◆ nrf_mesh_prov_oob_use()

uint32_t nrf_mesh_prov_oob_use	(	nrf_mesh_prov_ctx_t *	p_ctx,
		nrf_mesh_prov_oob_method_t	method,
		uint8_t	action,
		uint8_t	size
	)

Selects which out-of-band authentication method to use.

This function is used in response to the reception of a NRF_MESH_PROV_EVT_CAPS_RECEIVED event.

Parameters

[in,out]	p_ctx	Pointer to a statically allocated provisioning context structure.
[in]	method	Specifies the authentication method to use.
[in]	action	The action that must be taken for the specified method is dependent on the provisionee device, and can be read from the NRF_MESH_PROV_EVT_CAPS_RECEIVED event.
[in]	size	Size of the out-of-band authentication data. Must be between 1 and 8 inclusive or 0 when `NRF_MESH_PROV_OOB_METHOD_NONE` is used.

Return values

NRF_SUCCESS	The out-of-band method was accepted by the provisioning system.
NRF_ERROR_INVALID_LENGTH	The size of the authentication data was invalid.

◆ nrf_mesh_prov_auth_data_provide()

uint32_t nrf_mesh_prov_auth_data_provide	(	nrf_mesh_prov_ctx_t *	p_ctx,
		const uint8_t *	p_data,
		uint8_t	size
	)

Provides out-of-band authentication data input to the provisioning stack.

When replying to an NRF_MESH_PROV_EVT_INPUT_REQUEST and acting as a provisionee, the nrf_mesh_prov_input_action_t determines how p_data will be formatted.

p_data must be a pointer to a uint32_t number that contains the authentication data and size must be identical to nrf_mesh_prov_evt_input_request_t::size when the input is one of the following:

When the input action is nrf_mesh_prov_input_action_t::NRF_MESH_PROV_INPUT_ACTION_ENTER_STRING, p_data must be an array of alphanumeric uppercase ASCII values of size . That is, with values in the ranges 'A'-'Z' or '0'-'9'.

When replying to an NRF_MESH_PROV_EVT_INPUT_REQUEST and acting as a provisioner, the nrf_mesh_prov_output_action_t determines how p_data will be formatted.

p_data must be a pointer to a uint32_t number that contains the authentication data and size must be identical to nrf_mesh_prov_evt_input_request_t::size when the input is one of the following:

When the output action is nrf_mesh_prov_output_action_t::NRF_MESH_PROV_OUTPUT_ACTION_ALPHANUMERIC p_data must be an array of alphanumeric uppercase ASCII values of size . That is, with values in the ranges 'A'-'Z' or '0'-'9'.

Parameters

[in,out]	p_ctx	Pointer to a statically allocated provisioning context structure.
[in]	p_data	Pointer to an array of authentication data. The size of this array should match the size of the data requested in the request event for NRF_MESH_PROV_EVT_INPUT_REQUEST, or be 16 bytes for a NRF_MESH_PROV_EVT_STATIC_REQUEST event. The maximum size of the data is 16 bytes.
[in]	size	Size according to nrf_mesh_prov_evt_input_request_t::size.

Return values

NRF_SUCCESS	The authentication data was accepted by the provisioning system.
NRF_ERROR_INVALID_STATE	Authentication data was provided even though it was not requested by the current provisioning context.
NRF_ERROR_INVALID_LENGTH	The size of the authentication data was invalid.
NRF_ERROR_INVALID_DATA	The provided data did not meet the requirements corresponding to the requested data.

Referenced by nrf_mesh_prov_oob_number_provide().

◆ nrf_mesh_prov_oob_number_provide()

static uint32_t nrf_mesh_prov_oob_number_provide	(	nrf_mesh_prov_ctx_t *	p_ctx,
		uint32_t	number
	)

inlinestatic

Provides out-of-band authentication number to the provisioning stack.

This function is a simple wrapper for the nrf_mesh_prov_auth_data_provide() API.

Parameters

[in,out]	p_ctx	Provisioning context pointer.
[in]	number	Number displayed by the peer device.

Returns: Inherits the returns from nrf_mesh_prov_auth_data_provide().

Definition at line 312 of file nrf_mesh_prov.h.

References nrf_mesh_prov_ctx_t::event_handler, nrf_mesh_prov_auth_data_provide(), nrf_mesh_prov_pubkey_provide(), nrf_mesh_prov_scan_start(), nrf_mesh_prov_scan_stop(), and nrf_mesh_prov_shared_secret_provide().

◆ nrf_mesh_prov_shared_secret_provide()

uint32_t nrf_mesh_prov_shared_secret_provide	(	nrf_mesh_prov_ctx_t *	p_ctx,
		const uint8_t *	p_shared
	)

Provides the shared secret to the provisioning stack after running a requested ECDH calculation.

This function is used only if ECDH offloading is enabled in the options API.

Parameters

[in,out]	p_ctx	Pointer to a statically allocated provisioning context structure.
[in]	p_shared	Pointer to the shared secret calculated by the external ECDH code.

Return values

NRF_SUCCESS	The shared secret was accepted by the provisioning system.
NRF_ERROR_INVALID_STATE	A shared secret was not requested by the current provisioning context.
NRF_ERROR_NULL	The pointer provided to the shared secret was NULL.

Referenced by nrf_mesh_prov_oob_number_provide().

◆ nrf_mesh_prov_pubkey_provide()

uint32_t nrf_mesh_prov_pubkey_provide	(	nrf_mesh_prov_ctx_t *	p_ctx,
		const uint8_t *	p_key
	)

Provides a public key to the provisioner if the provisionee has exposed it out-of-band.

Parameters

[in,out]	p_ctx	Pointer to a statically allocated provisioning context structure.
[in]	p_key	Pointer to the start of an array containing the public key for the provisionee.

Return values

NRF_SUCCESS	The public key was valid and accepted by the provisioning system.
NRF_ERROR_INVALID_STATE	The public key was provided even tough it was not requested by the specified provisioning context.
NRF_ERROR_INVALID_PARAM	The public key was invalid.
NRF_ERROR_NULL	The `p_key` argument was NULL.

Referenced by nrf_mesh_prov_oob_number_provide().

◆ nrf_mesh_prov_scan_start()

uint32_t nrf_mesh_prov_scan_start ( nrf_mesh_prov_evt_handler_cb_t event_handler )

Starts the scanning for unprovisioned devices.

Parameters

[in] event_handler Event handler callback function for reporting unprovisioned device events.

Return values

NRF_SUCCESS	Successfully started scanning for unprovisioned devices.
NRF_ERROR_NULL	Callback function pointer was NULL.

Referenced by nrf_mesh_prov_oob_number_provide().

Provisioning API

nRF5 SDK for Mesh v5.0.0

Modules

Functions

Detailed Description

Function Documentation

◆ nrf_mesh_prov_init()

◆ nrf_mesh_prov_bearer_add()

◆ nrf_mesh_prov_listen()

◆ nrf_mesh_prov_listen_stop()

◆ nrf_mesh_prov_generate_keys()

◆ nrf_mesh_prov_provision()

◆ nrf_mesh_prov_oob_use()

◆ nrf_mesh_prov_auth_data_provide()

◆ nrf_mesh_prov_oob_number_provide()

◆ nrf_mesh_prov_shared_secret_provide()

◆ nrf_mesh_prov_pubkey_provide()

◆ nrf_mesh_prov_scan_start()