nRF5 SDK for Mesh v3.2.0  08c60f6
nrf_mesh_prov.h
1 /* Copyright (c) 2010 - 2019, Nordic Semiconductor ASA
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without modification,
5  * are permitted provided that the following conditions are met:
6  *
7  * 1. Redistributions of source code must retain the above copyright notice, this
8  * list of conditions and the following disclaimer.
9  *
10  * 2. Redistributions in binary form, except as embedded into a Nordic
11  * Semiconductor ASA integrated circuit in a product or a software update for
12  * such product, must reproduce the above copyright notice, this list of
13  * conditions and the following disclaimer in the documentation and/or other
14  * materials provided with the distribution.
15  *
16  * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
17  * contributors may be used to endorse or promote products derived from this
18  * software without specific prior written permission.
19  *
20  * 4. This software, with or without modification, must only be used with a
21  * Nordic Semiconductor ASA integrated circuit.
22  *
23  * 5. Any software provided in binary form under this license must not be reverse
24  * engineered, decompiled, modified and/or disassembled.
25  *
26  * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
27  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28  * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
29  * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
30  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
32  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
35  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36  */
37 
38 #ifndef NRF_MESH_PROV_H__
39 #define NRF_MESH_PROV_H__
40 
41 #include <ble.h>
42 #include <stdbool.h>
43 #include <stdint.h>
44 
45 #include "nrf_mesh_config_prov.h"
46 #include "nrf_mesh_prov_types.h"
47 #include "nrf_mesh_prov_events.h"
48 #include "nrf_mesh_prov_bearer.h"
49 #include "nrf_mesh_assert.h"
50 #include "bitfield.h"
51 
52 /* Ensure that the supported bearers only fills one uint32_t. */
53 NRF_MESH_STATIC_ASSERT(BITFIELD_BLOCK_COUNT(NRF_MESH_PROV_BEARER_COUNT) == 1);
54 
71 #define NRF_MESH_PROV_OOB_CAPS_DEFAULT(NUM_ELEMENTS) \
72  {NUM_ELEMENTS, NRF_MESH_PROV_ALGORITHM_FIPS_P256EC, 0, NRF_MESH_PROV_OOB_STATIC_TYPE_SUPPORTED, 0, 0, 0, 0}
73 
82 {
83  list_node_t * p_bearers;
84  uint32_t supported_bearers;
85  prov_bearer_t * p_active_bearer;
88  const uint8_t * p_public_key;
89  const uint8_t * p_private_key;
106  uint8_t oob_size;
107  uint8_t oob_action;
108  bool pubkey_oob;
118 };
138 uint32_t nrf_mesh_prov_init(nrf_mesh_prov_ctx_t * p_ctx,
139  const uint8_t * p_public_key,
140  const uint8_t * p_private_key,
141  const nrf_mesh_prov_oob_caps_t * p_caps,
142  nrf_mesh_prov_evt_handler_cb_t event_handler);
143 
157 uint32_t nrf_mesh_prov_bearer_add(nrf_mesh_prov_ctx_t * p_ctx,
158  prov_bearer_t * p_prov_bearer);
159 
174 uint32_t nrf_mesh_prov_listen(nrf_mesh_prov_ctx_t * p_ctx,
175  const char * URI,
176  uint16_t oob_info_sources,
177  uint32_t bearer_types);
178 
187 uint32_t nrf_mesh_prov_listen_stop(nrf_mesh_prov_ctx_t * p_ctx);
188 
197 uint32_t nrf_mesh_prov_generate_keys(uint8_t * p_public, uint8_t * p_private);
198 
215 uint32_t nrf_mesh_prov_provision(nrf_mesh_prov_ctx_t * p_ctx,
216  const uint8_t * p_target_uuid,
217  uint8_t attention_duration_s,
218  const nrf_mesh_prov_provisioning_data_t * p_data,
220 
238 uint32_t nrf_mesh_prov_oob_use(nrf_mesh_prov_ctx_t * p_ctx,
240  uint8_t action,
241  uint8_t size);
242 
298 uint32_t nrf_mesh_prov_auth_data_provide(nrf_mesh_prov_ctx_t * p_ctx,
299  const uint8_t * p_data,
300  uint8_t size);
312 static inline uint32_t nrf_mesh_prov_oob_number_provide(nrf_mesh_prov_ctx_t * p_ctx,
313  uint32_t number)
314 {
315  /* Input sanitation is done by nrf_mesh_prov_auth_data_provide() */
316  return nrf_mesh_prov_auth_data_provide(p_ctx, (const uint8_t *) &number, p_ctx->oob_size);
317 }
318 
331 uint32_t nrf_mesh_prov_shared_secret_provide(nrf_mesh_prov_ctx_t * p_ctx, const uint8_t * p_shared);
332 
346 uint32_t nrf_mesh_prov_pubkey_provide(nrf_mesh_prov_ctx_t * p_ctx, const uint8_t * p_key);
347 
358 
362 void nrf_mesh_prov_scan_stop(void);
363 
365 #endif
nrf_mesh_prov_ctx::peer_public_key
uint8_t peer_public_key[NRF_MESH_PROV_PUBKEY_SIZE]
Public key of the peer node.
Definition: nrf_mesh_prov.h:91
nrf_mesh_prov_ctx::failure_code
nrf_mesh_prov_failure_code_t failure_code
Error code sent with the previous provisioning failed packet.
Definition: nrf_mesh_prov.h:111
nrf_mesh_prov_ctx::pubkey_oob
bool pubkey_oob
Uses out-of-band public key.
Definition: nrf_mesh_prov.h:108
nrf_mesh_prov_scan_stop
void nrf_mesh_prov_scan_stop(void)
Stops the scanning for unprovisioned devices (if started).
PROV_NONCE_LEN
#define PROV_NONCE_LEN
Length of Nonce.
Definition: nrf_mesh_prov_types.h:74
NRF_MESH_PROV_ECDHSECRET_SIZE
#define NRF_MESH_PROV_ECDHSECRET_SIZE
Size of the elliptic curve secret key.
Definition: nrf_mesh_prov_types.h:58
NRF_MESH_KEY_SIZE
#define NRF_MESH_KEY_SIZE
Size (in octets) of an encryption key.
Definition: nrf_mesh_defines.h:80
nrf_mesh_prov_ctx::node_random
uint8_t node_random[PROV_RANDOM_LEN]
Random number for the current node.
Definition: nrf_mesh_prov.h:98
nrf_mesh_prov_ctx::auth_value
uint8_t auth_value[PROV_AUTH_LEN]
Authentication value.
Definition: nrf_mesh_prov.h:100
nrf_mesh_prov_ctx::state
nrf_mesh_prov_state_t state
Provisioning state machine state.
Definition: nrf_mesh_prov.h:112
nrf_mesh_prov_ctx::confirmation_salt
uint8_t confirmation_salt[PROV_SALT_LEN]
Confirmation salt value.
Definition: nrf_mesh_prov.h:102
nrf_mesh_prov_ctx::data_nonce
uint8_t data_nonce[PROV_NONCE_LEN]
Provisioning data nonce.
Definition: nrf_mesh_prov.h:96
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.
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.
nrf_mesh_prov_ctx::peer_random
uint8_t peer_random[PROV_RANDOM_LEN]
Random number for the peer node.
Definition: nrf_mesh_prov.h:99
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.
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.
nrf_mesh_prov_ctx::session_key
uint8_t session_key[NRF_MESH_KEY_SIZE]
Provisioning session key.
Definition: nrf_mesh_prov.h:95
nrf_mesh_prov_ctx::oob_action
uint8_t oob_action
Chosen OOB action.
Definition: nrf_mesh_prov.h:107
PROV_CONFIRMATION_INPUT_LEN
#define PROV_CONFIRMATION_INPUT_LEN
Combined length of confirmation inputs: provisioning invite, capabilities and start PDUs.
Definition: nrf_mesh_prov_types.h:76
NRF_MESH_PROV_BEARER_COUNT
#define NRF_MESH_PROV_BEARER_COUNT
Number of supported bearers.
Definition: nrf_mesh_prov_bearer.h:207
PROV_SALT_LEN
#define PROV_SALT_LEN
Length of Salt value.
Definition: nrf_mesh_prov_types.h:72
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.
nrf_mesh_prov_ctx::p_public_key
const uint8_t * p_public_key
Public key of this node.
Definition: nrf_mesh_prov.h:88
nrf_mesh_prov_ctx::oob_size
uint8_t oob_size
Size of the chosen OOB authentication data.
Definition: nrf_mesh_prov.h:106
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.
nrf_mesh_prov_ctx::p_private_key
const uint8_t * p_private_key
Private key of this node.
Definition: nrf_mesh_prov.h:89
nrf_mesh_prov_ctx::attention_duration_s
uint8_t attention_duration_s
Time in seconds during which the device will identify itself using any means it can.
Definition: nrf_mesh_prov.h:117
nrf_mesh_prov_ctx::p_active_bearer
prov_bearer_t * p_active_bearer
Pointer to the currently active bearer (valid when )
Definition: nrf_mesh_prov.h:85
nrf_mesh_prov_state_t
nrf_mesh_prov_state_t
Provisioning state machine states.
Definition: nrf_mesh_prov_types.h:248
nrf_mesh_prov_ctx::supported_bearers
uint32_t supported_bearers
Supported bearer types bitfield, nrf_mesh_prov_bearer_type_t.
Definition: nrf_mesh_prov.h:84
nrf_mesh_prov_ctx::event_handler
nrf_mesh_prov_evt_handler_cb_t event_handler
Application event handler callback function.
Definition: nrf_mesh_prov.h:86
nrf_mesh_prov_evt_handler_cb_t
void(* nrf_mesh_prov_evt_handler_cb_t)(const nrf_mesh_prov_evt_t *p_evt)
Provisioning event handler callback type.
Definition: nrf_mesh_prov_events.h:292
PROV_CONFIRMATION_LEN
#define PROV_CONFIRMATION_LEN
Length of Confirmation value.
Definition: nrf_mesh_prov_types.h:68
nrf_mesh_prov_failure_code_t
nrf_mesh_prov_failure_code_t
Provisioning failure codes.
Definition: nrf_mesh_prov_types.h:213
nrf_mesh_prov_role_t
nrf_mesh_prov_role_t
Provisioning role.
Definition: nrf_mesh_prov_types.h:299
nrf_mesh_prov_ctx::peer_confirmation
uint8_t peer_confirmation[PROV_CONFIRMATION_LEN]
Confirmation value for the peer node.
Definition: nrf_mesh_prov.h:103
nrf_mesh_prov_ctx::device_key
uint8_t device_key[NRF_MESH_KEY_SIZE]
Node device key.
Definition: nrf_mesh_prov.h:94
nrf_mesh_prov_ctx::p_bearers
list_node_t * p_bearers
Bearer linked list head pointer.
Definition: nrf_mesh_prov.h:83
nrf_mesh_prov_oob_caps_t
Provisioning authentication capabilities.
Definition: nrf_mesh_prov_types.h:232
nrf_mesh_prov_ctx
Common provisioning context forward declaration.
Definition: nrf_mesh_prov.h:81
nrf_mesh_prov_ctx::capabilities
nrf_mesh_prov_oob_caps_t capabilities
Node OOB and authentication capabilities.
Definition: nrf_mesh_prov.h:114
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.
nrf_mesh_prov_ctx::confirmation_inputs
uint8_t confirmation_inputs[PROV_CONFIRMATION_INPUT_LEN]
Confirmation inputs, used to calculate the confirmation key.
Definition: nrf_mesh_prov.h:104
nrf_mesh_prov_ctx::oob_method
nrf_mesh_prov_oob_method_t oob_method
Chosen OOB authentication method.
Definition: nrf_mesh_prov.h:113
NRF_MESH_STATIC_ASSERT
#define NRF_MESH_STATIC_ASSERT(...)
Compile-time assertion.
Definition: nrf_mesh_assert.h:99
nrf_mesh_prov_provisioning_data_t
Provisioning data to transmit to a device.
Definition: nrf_mesh_prov_types.h:277
nrf_mesh_prov_ctx::shared_secret
uint8_t shared_secret[NRF_MESH_PROV_ECDHSECRET_SIZE]
ECDH shared secret: P-256(private key, peer public key).
Definition: nrf_mesh_prov.h:92
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.
nrf_mesh_prov_oob_method_t
nrf_mesh_prov_oob_method_t
Out-of-band authentication methods for provisioning.
Definition: nrf_mesh_prov_types.h:176
nrf_mesh_prov_ctx::data
nrf_mesh_prov_provisioning_data_t data
Provisioning data to send to the provisionee or received from the provisioner.
Definition: nrf_mesh_prov.h:115
nrf_mesh_prov_ctx::role
nrf_mesh_prov_role_t role
Provisioning role, provisioner or provisionee.
Definition: nrf_mesh_prov.h:110
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.
NRF_MESH_PROV_PUBKEY_SIZE
#define NRF_MESH_PROV_PUBKEY_SIZE
Size of the elliptic curve public key.
Definition: nrf_mesh_prov_types.h:54
PROV_RANDOM_LEN
#define PROV_RANDOM_LEN
Length of Random value.
Definition: nrf_mesh_prov_types.h:66
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)
Provides out-of-band authentication number to the provisioning stack.
Definition: nrf_mesh_prov.h:312
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.
nrf_mesh_prov_bearer_type_t
nrf_mesh_prov_bearer_type_t
Provisioning bearer types.
Definition: nrf_mesh_prov_bearer.h:212
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.
PROV_AUTH_LEN
#define PROV_AUTH_LEN
Length of Auth value.
Definition: nrf_mesh_prov_types.h:70