nRF5 SDK for Mesh v5.0.0
Modules | Functions
Provisioning API

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_ctxPointer to the provisioning context structure to initialize.
[in]p_public_keyPointer to the node's public key. The public key is 64 bytes long.
[in]p_private_keyPointer to the node's private key. The private key is 32 bytes long.
[in]p_capsPointer to a structure containing the node's out-of-band authentication capabilities.
[in]event_handlerEvent handler callback function.
Return values
NRF_SUCCESSThe library was successfully initialized.
NRF_ERROR_NULLOne or more parameters were NULL.
NRF_ERROR_INVALID_STATEInitialization 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_ctxProvisioning context structure.
[in,out]p_prov_bearerGeneric provisioning context structure.
Return values
NRF_SUCCESSSuccessfully added bearer.
NRF_ERROR_NULLOne or more parameters were NULL.
NRF_ERROR_FORBIDDENA 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_ctxPointer to a statically allocated provisioning context structure.
[in]URIOptional device URI string used as identifier in some other context. May be NULL.
[in]oob_info_sourcesKnown OOB information sources, see Provisioning OOB information sources..
[in]bearer_typesBitfield of nrf_mesh_prov_bearer_type_t bearers to listen on.
Return values
NRF_SUCCESSThe provisioning bearer was successfully put into listening mode.
NRF_ERROR_INVALID_STATEThe 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_ctxPointer to a statically allocated provisioning context structure.
Return values
NRF_SUCCESSThe provisioning bearer was successfully put into listening mode.
NRF_ERROR_INVALID_STATEThe 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_publicPointer to where the generated public key is stored.
[out]p_privatePointer to where the generated private key is stored.
Return values
NRF_SUCCESSThe 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_ctxPointer to a statically allocated provisioning context structure.
[in]p_target_uuidDevice UUID of the device that is to be provisioned.
[in]attention_duration_sTime in seconds during which the device will identify itself using any means it can.
[in]p_dataPointer to a structure containing the provisioning data for the device.
[in]bearerWhich bearer to establish the provisioning link on.
Return values
NRF_SUCCESSThe provisioning process was started.
NRF_ERROR_NULLOne or more parameters were NULL.
NRF_ERROR_NOT_SUPPORTEDThe given bearer type is not supported.
NRF_ERROR_INVALID_DATAThe provisioning data failed some boundary conditions.
NRF_ERROR_INVALID_STATEThe 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_ctxPointer to a statically allocated provisioning context structure.
[in]methodSpecifies the authentication method to use.
[in]actionThe 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]sizeSize 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_SUCCESSThe out-of-band method was accepted by the provisioning system.
NRF_ERROR_INVALID_LENGTHThe 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_ctxPointer to a statically allocated provisioning context structure.
[in]p_dataPointer 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]sizeSize according to nrf_mesh_prov_evt_input_request_t::size.
Return values
NRF_SUCCESSThe authentication data was accepted by the provisioning system.
NRF_ERROR_INVALID_STATEAuthentication data was provided even though it was not requested by the current provisioning context.
NRF_ERROR_INVALID_LENGTHThe size of the authentication data was invalid.
NRF_ERROR_INVALID_DATAThe 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_ctxProvisioning context pointer.
[in]numberNumber 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_ctxPointer to a statically allocated provisioning context structure.
[in]p_sharedPointer to the shared secret calculated by the external ECDH code.
Return values
NRF_SUCCESSThe shared secret was accepted by the provisioning system.
NRF_ERROR_INVALID_STATEA shared secret was not requested by the current provisioning context.
NRF_ERROR_NULLThe 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_ctxPointer to a statically allocated provisioning context structure.
[in]p_keyPointer to the start of an array containing the public key for the provisionee.
Return values
NRF_SUCCESSThe public key was valid and accepted by the provisioning system.
NRF_ERROR_INVALID_STATEThe public key was provided even tough it was not requested by the specified provisioning context.
NRF_ERROR_INVALID_PARAMThe public key was invalid.
NRF_ERROR_NULLThe 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_handlerEvent handler callback function for reporting unprovisioned device events.
Return values
NRF_SUCCESSSuccessfully started scanning for unprovisioned devices.
NRF_ERROR_NULLCallback function pointer was NULL.

Referenced by nrf_mesh_prov_oob_number_provide().


Documentation feedback | Developer Zone | Subscribe | Updated