| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Gazell Pairing
Proprietary stacks

nRF51 only: Gazell Pairing API. More...

## Pairing configuration defines
#define | GZP_PAIRING_PIPE 0
| Pipe reserved for initial pairing communication.
#define | GZP_DATA_PIPE 1
| Pipe reserved for GZP encrypted data communication (one pipe only).
#define | GZP_TX_RX_TRANS_DELAY 10
| Time to wait between request and fetch packets in RX_PERIODS (2 timeslot periods)
#define | GZP_SYSTEM_ADDRESS_WIDTH 4
| Must equal Gazell base address length.
#define | GZP_VALIDATION_ID {0x32, 0x53, 0x66}
| Validation ID. Required to be shared by Host and Device. Not a secret.
#define | GZP_VALIDATION_ID_LENGTH 3
| Validation ID length in bytes.
#define | GZP_HOST_ID_LENGTH 5
| Host ID length in bytes.
#define | GZP_SESSION_TOKEN_LENGTH GZP_HOST_ID_LENGTH
| Session token length in bytes.
#define | GZP_DYN_KEY_LENGTH (16 - GZP_VALIDATION_ID_LENGTH)
| Dynamic key length in bytes.
#define | GZP_HOST_RX_POWER_THRESHOLD -64
| RSSI threshold for when signal strength in RX packet power is high enough.

## Device -> Host packet definitions
#define | GZP_CMD_HOST_ADDRESS_REQ_PAYLOAD_LENGTH 1
| "Host address request" packet, payload length
#define | GZP_CMD_HOST_ADDRESS_FETCH_PAYLOAD_LENGTH 1
| "Host address fetch" packet, payload length
#define | GZP_CMD_HOST_ID_REQ_SESSION_TOKEN 1
| "Host ID request" packet, session token position
#define | GZP_CMD_HOST_ID_REQ_PAYLOAD_LENGTH (GZP_CMD_HOST_ID_REQ_SESSION_TOKEN + GZP_SESSION_TOKEN_LENGTH)
| "Host ID request" payload length
#define | GZP_CMD_HOST_ID_FETCH_VALIDATION_ID 1
| "Host ID fetch" packet
#define | GZP_CMD_HOST_ID_FETCH_PAYLOAD_LENGTH (GZP_CMD_HOST_ID_FETCH_VALIDATION_ID + GZP_VALIDATION_ID_LENGTH)
| "Host ID fetch" payload length
#define | GZP_CMD_KEY_UPDATE_PREPARE_PAYLOAD_LENGTH 1
| "Key update prepare" payload length
#define | GZP_CMD_KEY_UPDATE_VALIDATION_ID 1
| "Key update" packet, validation ID position
#define | GZP_CMD_KEY_UPDATE_NEW_KEY (GZP_CMD_KEY_UPDATE_VALIDATION_ID + GZP_VALIDATION_ID_LENGTH)
| "Key update" packet, new key position
#define | GZP_CMD_KEY_UPDATE_PAYLOAD_LENGTH (GZP_CMD_KEY_UPDATE_NEW_KEY + GZP_DYN_KEY_LENGTH)
| "Key update" packet, payload length
#define | GZP_CMD_ENCRYPTED_USER_DATA_VALIDATION_ID 1
| "Encrypted user data" packet, validation ID position
#define | GZP_CMD_ENCRYPTED_USER_DATA_PAYLOAD ((GZP_CMD_ENCRYPTED_USER_DATA_VALIDATION_ID + GZP_VALIDATION_ID_LENGTH))
| "Encrypted user data" packet, user data position
#define | GZP_ENCRYPTED_USER_DATA_PACKET_OVERHEAD ( GZP_CMD_ENCRYPTED_USER_DATA_VALIDATION_ID + GZP_VALIDATION_ID_LENGTH)
| "Encrypted user data" packet, packet overhead length
#define | GZP_ENCRYPTED_USER_DATA_MAX_LENGTH (17 - GZP_ENCRYPTED_USER_DATA_PACKET_OVERHEAD)
| "Encrypted user data" packet, max payload length
#define | GZP_CMD_FETCH_RESP_PAYLOAD_LENGTH 1
| General "fetch response" packet, payload_length.

## Host -> Device packet definitions
#define | GZP_CMD_HOST_ADDRESS_RESP_ADDRESS 1
| "Host address fetch" response packet, address position
#define | GZP_CMD_HOST_ADDRESS_RESP_PAYLOAD_LENGTH (GZP_CMD_HOST_ADDRESS_RESP_ADDRESS + GZP_SYSTEM_ADDRESS_WIDTH)
| ///< "Host address fetch" response packet, payload length
#define | GZP_CMD_HOST_ID_FETCH_RESP_VALIDATION_ID 1
| "Host ID fetch" response packet, validation ID position
#define | GZP_CMD_HOST_ID_FETCH_RESP_STATUS (GZP_CMD_HOST_ID_FETCH_RESP_VALIDATION_ID + GZP_VALIDATION_ID_LENGTH)
| "Host ID fetch" response packet, status position
#define | GZP_CMD_HOST_ID_FETCH_RESP_HOST_ID (GZP_CMD_HOST_ID_FETCH_RESP_STATUS + 1)
| "Host ID fetch" response packet, Host ID position
#define | GZP_CMD_HOST_ID_FETCH_RESP_PAYLOAD_LENGTH (GZP_CMD_HOST_ID_FETCH_RESP_HOST_ID + GZP_HOST_ID_LENGTH)
| "Host ID fetch" response packet, payload length
#define | GZP_CMD_KEY_UPDATE_PREPARE_RESP_SESSION_TOKEN 1
| "Key update prepare" response packet, session token position
#define | GZP_CMD_KEY_UPDATE_PREPARE_RESP_PAYLOAD_LENGTH (GZP_CMD_KEY_UPDATE_PREPARE_RESP_SESSION_TOKEN + GZP_SESSION_TOKEN_LENGTH)
| "Key update prepare" response packet, payload length position
#define | GZP_CMD_ENCRYPTED_USER_DATA_RESP_SESSION_TOKEN 1
| "Encrypted user data" response packet, session token position
#define | GZP_CMD_ENCRYPTED_USER_DATA_RESP_VALIDATION_ID (GZP_CMD_ENCRYPTED_USER_DATA_RESP_SESSION_TOKEN + GZP_SESSION_TOKEN_LENGTH)
| "Encrypted user data" response packet, validation ID position
#define | GZP_CMD_ENCRYPTED_USER_DATA_RESP_PAYLOAD_LENGTH (GZP_CMD_ENCRYPTED_USER_DATA_RESP_VALIDATION_ID + GZP_VALIDATION_ID_LENGTH)
| "Encrypted user data" response packet, payload length position

## Typedefs
enum | gzp_key_select_t { GZP_ID_EXCHANGE, GZP_KEY_EXCHANGE, GZP_DATA_EXCHANGE }
| Enumerator used for selecting the key to be used for encryption. More...
enum | gzp_cmd_t { GZP_CMD_HOST_ADDRESS_REQ = 0, GZP_CMD_HOST_ADDRESS_FETCH, GZP_CMD_HOST_ID_REQ, GZP_CMD_HOST_ID_FETCH, GZP_CMD_KEY_UPDATE_PREPARE, GZP_CMD_KEY_UPDATE, GZP_CMD_ENCRYPTED_USER_DATA, GZP_CMD_FETCH_RESP, GZP_CMD_HOST_ADDRESS_RESP, GZP_CMD_HOST_ID_FETCH_RESP, GZP_CMD_KEY_UPDATE_PREPARE_RESP, GZP_CMD_ENCRYPTED_USER_DATA_RESP }
| Enumerator used in the first payload byte of each packet to indicate the packet type. More...
enum | gzp_id_req_res_t { GZP_ID_RESP_PENDING, GZP_ID_RESP_GRANTED, GZP_ID_RESP_REJECTED, GZP_ID_RESP_FAILED, GZP_ID_RESP_NO_REQUEST }
| Enumerator used to identify the state of the current Host ID request. More...

## Misc. function prototypes
void | gzp_crypt_set_session_token (const uint8_t *token)
void | gzp_crypt_get_session_token (uint8_t *dst_token)
void | gzp_crypt_set_dyn_key (const uint8_t *dyn_key)
void | gzp_crypt_get_dyn_key (uint8_t *dst_key)
static void | gzp_set_host_id (const uint8_t *src)
void | gzp_get_host_id (uint8_t *dst)
void | gzp_crypt_select_key (gzp_key_select_t key_select)
void | gzp_crypt (uint8_t *dst, const uint8_t *src, uint8_t length)
bool | gzp_validate_id (const uint8_t *src_id)
void | gzp_add_validation_id (uint8_t *dst_id)
void | gzp_random_numbers_generate (uint8_t *dst, uint8_t n)
bool | gzp_update_radio_params (const uint8_t *system_address)
void | gzp_generate_channels (uint8_t *ch_dst, const uint8_t *address, uint8_t channel_set_size)
void | gzp_xor_cipher (uint8_t *dst, const uint8_t *src, const uint8_t *pad, uint8_t length)

## Common Device and Host functions
void | gzp_init (void)
void | gzp_erase_pairing_data (void)
void | nrf_gzp_disable_gzll (void)
void | gzp_id_req_cancel (void)
void | nrf_gzp_flush_rx_fifo (uint32_t pipe)

## Device functions
bool | nrf_gzp_tx_complete (void)
bool | nrf_gzp_tx_success (void)
void | nrf_gzp_reset_tx_complete (void)
void | nrf_gzp_reset_tx_success (void)
int8_t | gzp_get_pairing_status (void)
bool | gzp_address_req_send (void)
gzp_id_req_res_t | gzp_id_req_send (void)
bool | gzp_crypt_data_send (const uint8_t *src, uint8_t length)

## Host functions
void | gzp_pairing_enable (bool enable)
void | gzp_host_execute (void)
bool | gzp_address_exchanged (void)
bool | gzp_id_req_received (void)
void | gzp_id_req_reject (void)
void | gzp_id_req_grant (void)
bool | gzp_crypt_user_data_received (void)
bool | gzp_crypt_user_data_read (uint8_t *dst, uint8_t *length)
void | gzll_rx_start (void)

## Detailed Description

nRF51 only: Gazell Pairing API.

## Enumeration Type Documentation

enum gzp_cmd_t

Enumerator used in the first payload byte of each packet to indicate the packet type.

Enumerator
GZP_CMD_HOST_ADDRESS_REQ | Host address request.
GZP_CMD_HOST_ADDRESS_FETCH | Host address fetch.
GZP_CMD_HOST_ID_REQ | Host ID request.
GZP_CMD_HOST_ID_FETCH | Host ID fetch request.
GZP_CMD_KEY_UPDATE_PREPARE | Key update prepare.
GZP_CMD_KEY_UPDATE | Key update.
GZP_CMD_ENCRYPTED_USER_DATA | Encrypted user data.
GZP_CMD_FETCH_RESP | Fetch response.
GZP_CMD_HOST_ADDRESS_RESP | Host address response.
GZP_CMD_HOST_ID_FETCH_RESP | Host ID fetch response.
GZP_CMD_KEY_UPDATE_PREPARE_RESP | Key update prepare.
GZP_CMD_ENCRYPTED_USER_DATA_RESP | Encrypted user data response.

enum gzp_id_req_res_t

Enumerator used to identify the state of the current Host ID request.

Enumerator
GZP_ID_RESP_PENDING | ID response pending.
GZP_ID_RESP_GRANTED | ID response granted.
GZP_ID_RESP_REJECTED | ID response rejected.
GZP_ID_RESP_FAILED | ID response failed.
GZP_ID_RESP_NO_REQUEST | Default value. No ID request has yet been received.

enum gzp_key_select_t

Enumerator used for selecting the key to be used for encryption.

Enumerator
GZP_ID_EXCHANGE | "Secret key" only
GZP_KEY_EXCHANGE | "Secret key" and "Host ID"
GZP_DATA_EXCHANGE | "Dynamic key" and "Host ID"

## Function Documentation

void gzll_rx_start | ( | void |  | ) |

Function emulating behavior of gzll_rx_start() in legeacy nRF24xx Gaell linbrary.

This functions sets Gazell in Host mode and starts reception (enable).

void gzp_add_validation_id | ( | uint8_t * | dst_id | ) |

Add the pre-defined validation ID to dst_id. GZP_VALIDATION_ID_LENGTH bytes will be added.

Parameters

  dst_id | Pointer to add the GZP validation ID to.

bool gzp_address_exchanged | ( | void |  | ) |

Address exchanged check.

Return values

  true | If a "system address" was delivered to a requesting Device during the previous call to gzp_host_execute();
  false | Otherwise.

bool gzp_address_req_send | ( | void |  | ) |

Function for sending a "system address" request to a Host.

When calling this function the Device will attempt acquiring the "system address" from any Host within close proximity.

If a host is located within close proximity and pairing is enabled in the Host, a "system address" will be sent in return to the Device.

The new "system address" will apply immediately in the Device, and the new "system address" will be stored in non volatile (NV) memory.

Note. Using OTP devices limits the number of times a new "system address" can be stored in NV memory.

Returns

Return values

  true | if new "system address" was received from a Host.
  false | if no "system address" was received from a Host.

void gzp_crypt | ( | uint8_t * | dst,
|  | const uint8_t * | src,
|  | uint8_t | length
| ) |  |

Encypt / decrypt data.

The current "session token" will be used as initialization vector (IV). The AES key to be used is selected by gzp_crypt_select_key(). AES is a symmetric encryption scheme, this function can be used to perform both encryption and decryption.

Parameters

  dst | Destination to write encrypted data to. Should be 16 bytes long.
  src | Source data to encrypt.
  length | Length in bytes of src.

bool gzp_crypt_data_send | ( | const uint8_t * | src,
|  | uint8_t | length
| ) |  |

Function for sending encrypted user data to the Host.

Before any data can be sent the Device must acquire both the Host's "system address" by using gzp_address_req_send() and the "Host ID" by using gzp_id_req_send().

Parameters

  *src | is a pointer to the data packet to be sent.
  length | is the length of the data packet to be sent.

Returns

Return values

  true | if the data was successfully transmitted and decrypted by the Host.
  false | if data transmission failed or Host failed to decryption data correctly.

void gzp_crypt_get_dyn_key | ( | uint8_t * | dst_key | ) |

Get the dynamic key.

Parameters

  dst_key | Pointer to write the dynamic key too.

void gzp_crypt_get_session_token | ( | uint8_t * | dst_token | ) |

Get the session token.

Parameters

  dst_token | Pointer to write the session token.

void gzp_crypt_select_key | ( | gzp_key_select_t | key_select | ) |

Selecting what key-set that should be used when encrypting data using gzp_crypt().

Parameters

  key_select | Key-set to use.

void gzp_crypt_set_dyn_key | ( | const uint8_t * | dyn_key | ) |

Set the dynamic key.

Parameters

  dyn_key | Pointer to the dynamic key to set.

void gzp_crypt_set_session_token | ( | const uint8_t * | token | ) |

Set the session token.

Parameters

  token | Pointer to the session token to set.

bool gzp_crypt_user_data_read | ( | uint8_t * | dst,
|  | uint8_t * | length
| ) |  |

Function for reading encrypted user data.

Note that the read user data will be automatically decrypted. Only data that was decrypted correctly will be presented.

Parameters

  dst* | is a pointer to where the received data will be written.
  length* | is a pointer for returning the number of bytes received. Only 1 byte will be writtem to length*.

Returns

Return values

  true | if data has been received and is written to dst*
  false | if no data has been received.

bool gzp_crypt_user_data_received | ( | void |  | ) |

Check if user data has been received.

Return values

  true | If encrypted user data has been received.
  false | Otherwise.

void gzp_erase_pairing_data | ( | void |  | ) |

Function for erasing all pairing data.

void gzp_generate_channels | ( | uint8_t * | ch_dst,
|  | const uint8_t * | address,
|  | uint8_t | channel_set_size
| ) |  |

Generate a set of channels from a 4 byte address.

Parameters

  ch_dst | Destination to write the channel set to. The channel set includes GZP_CHANNEL_MAX and GZP_CHANNEL_MIN.
  address | Four byte address to generate the channel set from.
  channel_set_size | Size of the channel set to generate.

void gzp_get_host_id | ( | uint8_t * | dst | ) |

Get the Host ID.

Parameters

  dst | Pointer to write the Host ID to.

int8_t gzp_get_pairing_status | ( | void |  | ) |

Function to check whether a Device has existing pairing data, implying that it is paired to a Host.

Return values

  -2 | The pairing database is empty.
  -1 | The device has a system address but no Host ID.
  >=0 | The device has a system address and HostID at this index value in the database.

void gzp_host_execute | ( | void |  | ) |

Execute the Gazell Pairing Library Host operation.

This function must be called regularly by the Host application.

void gzp_id_req_cancel | ( | void |  | ) |

Function for cancelling an ongoing (pending) "Host ID request".

After calling this function the "Host ID request" status will go to "ID request Idle".

void gzp_id_req_grant | ( | void |  | ) |

Function for granting the previously received "Host ID request". This function should be called only when a "Host ID request" has been received (internal state is "ID request pending").

The internal state of the Pairing library will remain "ID request pending" until the "Host ID" has been successfully transmitted to the requesting Device. After this the internal state will change to "ID request idle".

bool gzp_id_req_received | ( | void |  | ) |

Function for checking if a "Host ID request" has been received from a Device.

If a request has been received, the Pairing library will enter "ID request pending" state.

The application is responsible for responding to this request by calling one of the following functions:

- gzp_id_req_grant()
- gzp_id_req_reject()
- gzp_id_req_cancel()

Return values

  true | if a "Host ID request" has been received (internal state is "ID request pending")
  false | if no "Host ID request" has been received (internal state is "ID request idle")

void gzp_id_req_reject | ( | void |  | ) |

Function for rejecting the previously received "Host ID request". This function should be called only when a "Host ID request" has been received (internal state is "ID request pending").

The internal state of the Pairing library will remain "ID request pending" until the a "reject" message has been successfully transmitted to the requesting Device. After this the internal state will change to "ID request idle".

gzp_id_req_res_t gzp_id_req_send | ( | void |  | ) |

Function for sending a "Host ID request" to a Host.

The "Host ID" is needed to be able to send encrypted data using gzp_crypt_data_send().

The request will be sent using the "system address" previously received using gzp_address_req_send().

It is not required that the Host is within close proximity in order to acquire the "Host ID".

The new "Host ID" will apply immediately for the Device, and the new "Host ID" will be stored in non volatile (NV) memory.

Note. Using OTP devices limits the number of times a new "Host ID" can be stored in NV memory.

Returns

Return values

  GZP_ID_RESP_PENDING | if a "Host ID request" has been sent to the Host, but the Host application has not yet decided whether to Grant or Reject the "ID request".
  GZP_ID_RESP_GRANTED | if the "Host ID" has been received from the Host. The received "Host ID" will be stored in non volatile memory.
  GZP_ID_RESP_REJECTED | if the Host application has rejected the "Host ID request".
  GZP_ID_RESP_FAILED | if failing to send a request or receive a response from the Host.

void gzp_init | ( | void |  | ) |

Initialization function. This function initializes the Gazell Pairing Library.

This function must be called before any of the other Gazell Pairing Library functions are used and must be called after gzll_init() is called.

void gzp_pairing_enable | ( | bool | enable | ) |

Function for enabling/disabling pairing in a host. When pairing is enabled the host will be monitoring for "system address" and "Host ID" requests from Devices.

A "system address request" received from a Device will always be granted. When a "host ID request" has been received, the Host application have to grant, reject or cancel this by using one of the following functions:

- gzp_id_req_grant()
- gzp_id_req_reject()
- gzp_id_req_cancel()

Parameters

  enable | true enables pairing. false disables pairing.

void gzp_random_numbers_generate | ( | uint8_t * | dst,
|  | uint8_t | n
| ) |  |

Generate random bytes.

Parameters

  dst | Destination to write the random bytes to.
  n | Number of bytes to generate.

static void gzp_set_host_id | ( | const uint8_t * | src | ) |
| static

Set the Host ID.

Parameters

  src | Pointer to the Host ID to set.

bool gzp_update_radio_params | ( | const uint8_t * | system_address | ) |

Update the channel table and the system address.

The channel table is updated to pseudo-random set generated using the system address. The channel table still includes GZP_CHANNEL_MAX and GZP_CHANNEL_MIN. The system address is applied to base address 1 and therefore applies to pipes 1-7.

Parameters

  system_address | Pointer to the system_address to set.

Return values

  true | If theradio parameters were updated successfully.
  false | If there was an error updated the radio parameters.

bool gzp_validate_id | ( | const uint8_t * | src_id | ) |

Compare the *src_id with a pre-defined validation ID.

Parameters

  src_id | Pointer to the source validation ID to compare to.

Return values

  true | If *src_id equals the pre-defined ID.
  false | If *src_id does not equal the pre-defined ID.

void gzp_xor_cipher | ( | uint8_t * | dst,
|  | const uint8_t * | src,
|  | const uint8_t * | pad,
|  | uint8_t | length
| ) |  |

Perform an XOR on two byte strings.

Parameters

  dst | Destination to write the result to. Should be of size length.
  src |
  pad |
  length | Number of bytes to perform the XOR operation on.

void nrf_gzp_disable_gzll | ( | void |  | ) |

Disable Gazell and sleep while waiting for nrf_gzll_disabled callback.

void nrf_gzp_flush_rx_fifo | ( | uint32_t | pipe | ) |

Flush the GZLL RX FIFO for a specific pipe while GZLL is disabled.

Parameters

  pipe | Pipe.

void nrf_gzp_reset_tx_complete | ( | void |  | ) |

Reset tx_complete status.

void nrf_gzp_reset_tx_success | ( | void |  | ) |

Reset tx_success status.

bool nrf_gzp_tx_complete | ( | void |  | ) |

Check whether current GZP packet transaction has completed.

Return values

  true |
  false |

bool nrf_gzp_tx_success | ( | void |  | ) |

Check whether previous GZP packet transaction was successful.

Return values

  true |
  false |