Michael Galis / nRF51822

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of nRF51822 by Nordic Semiconductor

TARGET_MCU_NRF51822/source/btle/btle_security.h@638:c90ae1400bf2, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:39:43 2016 +0100
Revision:
638:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vincent Coubard 638:c90ae1400bf2 1 /* mbed Microcontroller Library
Vincent Coubard 638:c90ae1400bf2 2 * Copyright (c) 2006-2013 ARM Limited
Vincent Coubard 638:c90ae1400bf2 3 *
Vincent Coubard 638:c90ae1400bf2 4 * Licensed under the Apache License, Version 2.0 (the "License");
Vincent Coubard 638:c90ae1400bf2 5 * you may not use this file except in compliance with the License.
Vincent Coubard 638:c90ae1400bf2 6 * You may obtain a copy of the License at
Vincent Coubard 638:c90ae1400bf2 7 *
Vincent Coubard 638:c90ae1400bf2 8 * http://www.apache.org/licenses/LICENSE-2.0
Vincent Coubard 638:c90ae1400bf2 9 *
Vincent Coubard 638:c90ae1400bf2 10 * Unless required by applicable law or agreed to in writing, software
Vincent Coubard 638:c90ae1400bf2 11 * distributed under the License is distributed on an "AS IS" BASIS,
Vincent Coubard 638:c90ae1400bf2 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Vincent Coubard 638:c90ae1400bf2 13 * See the License for the specific language governing permissions and
Vincent Coubard 638:c90ae1400bf2 14 * limitations under the License.
Vincent Coubard 638:c90ae1400bf2 15 */
Vincent Coubard 638:c90ae1400bf2 16
Vincent Coubard 638:c90ae1400bf2 17 #ifndef _BTLE_SECURITY_H_
Vincent Coubard 638:c90ae1400bf2 18 #define _BTLE_SECURITY_H_
Vincent Coubard 638:c90ae1400bf2 19
Vincent Coubard 638:c90ae1400bf2 20 #include "ble/Gap.h"
Vincent Coubard 638:c90ae1400bf2 21 #include "ble/SecurityManager.h"
Vincent Coubard 638:c90ae1400bf2 22
Vincent Coubard 638:c90ae1400bf2 23 /**
Vincent Coubard 638:c90ae1400bf2 24 * Function to test whether the SecurityManager has been initialized.
Vincent Coubard 638:c90ae1400bf2 25 * Possible by a call to @ref btle_initializeSecurity().
Vincent Coubard 638:c90ae1400bf2 26 *
Vincent Coubard 638:c90ae1400bf2 27 * @return True if the SecurityManager was previously initialized, false
Vincent Coubard 638:c90ae1400bf2 28 * otherwise.
Vincent Coubard 638:c90ae1400bf2 29 */
Vincent Coubard 638:c90ae1400bf2 30 bool btle_hasInitializedSecurity(void);
Vincent Coubard 638:c90ae1400bf2 31
Vincent Coubard 638:c90ae1400bf2 32 /**
Vincent Coubard 638:c90ae1400bf2 33 * Enable Nordic's Device Manager, which brings in functionality from the
Vincent Coubard 638:c90ae1400bf2 34 * stack's Security Manager. The Security Manager implements the actual
Vincent Coubard 638:c90ae1400bf2 35 * cryptographic algorithms and protocol exchanges that allow two devices to
Vincent Coubard 638:c90ae1400bf2 36 * securely exchange data and privately detect each other.
Vincent Coubard 638:c90ae1400bf2 37 *
Vincent Coubard 638:c90ae1400bf2 38 * @param[in] enableBonding Allow for bonding.
Vincent Coubard 638:c90ae1400bf2 39 * @param[in] requireMITM Require protection for man-in-the-middle attacks.
Vincent Coubard 638:c90ae1400bf2 40 * @param[in] iocaps To specify IO capabilities of this peripheral,
Vincent Coubard 638:c90ae1400bf2 41 * such as availability of a display or keyboard to
Vincent Coubard 638:c90ae1400bf2 42 * support out-of-band exchanges of security data.
Vincent Coubard 638:c90ae1400bf2 43 * @param[in] passkey To specify a static passkey.
Vincent Coubard 638:c90ae1400bf2 44 *
Vincent Coubard 638:c90ae1400bf2 45 * @return BLE_ERROR_NONE on success.
Vincent Coubard 638:c90ae1400bf2 46 */
Vincent Coubard 638:c90ae1400bf2 47 ble_error_t btle_initializeSecurity(bool enableBonding = true,
Vincent Coubard 638:c90ae1400bf2 48 bool requireMITM = true,
Vincent Coubard 638:c90ae1400bf2 49 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
Vincent Coubard 638:c90ae1400bf2 50 const SecurityManager::Passkey_t passkey = NULL);
Vincent Coubard 638:c90ae1400bf2 51
Vincent Coubard 638:c90ae1400bf2 52 /**
Vincent Coubard 638:c90ae1400bf2 53 * Get the security status of a link.
Vincent Coubard 638:c90ae1400bf2 54 *
Vincent Coubard 638:c90ae1400bf2 55 * @param[in] connectionHandle
Vincent Coubard 638:c90ae1400bf2 56 * Handle to identify the connection.
Vincent Coubard 638:c90ae1400bf2 57 * @param[out] securityStatusP
Vincent Coubard 638:c90ae1400bf2 58 * security status.
Vincent Coubard 638:c90ae1400bf2 59 *
Vincent Coubard 638:c90ae1400bf2 60 * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
Vincent Coubard 638:c90ae1400bf2 61 */
Vincent Coubard 638:c90ae1400bf2 62 ble_error_t btle_getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP);
Vincent Coubard 638:c90ae1400bf2 63
Vincent Coubard 638:c90ae1400bf2 64 /**
Vincent Coubard 638:c90ae1400bf2 65 * Set the security mode on a connection. Useful for elevating the security mode
Vincent Coubard 638:c90ae1400bf2 66 * once certain conditions are met, e.g., a particular service is found.
Vincent Coubard 638:c90ae1400bf2 67 *
Vincent Coubard 638:c90ae1400bf2 68 * @param[in] connectionHandle
Vincent Coubard 638:c90ae1400bf2 69 * Handle to identify the connection.
Vincent Coubard 638:c90ae1400bf2 70 * @param[in] securityMode
Vincent Coubard 638:c90ae1400bf2 71 * security mode.
Vincent Coubard 638:c90ae1400bf2 72 *
Vincent Coubard 638:c90ae1400bf2 73 * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
Vincent Coubard 638:c90ae1400bf2 74 */
Vincent Coubard 638:c90ae1400bf2 75 ble_error_t btle_setLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::SecurityMode_t securityMode);
Vincent Coubard 638:c90ae1400bf2 76
Vincent Coubard 638:c90ae1400bf2 77 /**
Vincent Coubard 638:c90ae1400bf2 78 * Function for deleting all peer device context and all related bonding
Vincent Coubard 638:c90ae1400bf2 79 * information from the database.
Vincent Coubard 638:c90ae1400bf2 80 *
Vincent Coubard 638:c90ae1400bf2 81 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
Vincent Coubard 638:c90ae1400bf2 82 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or
Vincent Coubard 638:c90ae1400bf2 83 * application registration.
Vincent Coubard 638:c90ae1400bf2 84 */
Vincent Coubard 638:c90ae1400bf2 85 ble_error_t btle_purgeAllBondingState(void);
Vincent Coubard 638:c90ae1400bf2 86
Vincent Coubard 638:c90ae1400bf2 87 /**
Vincent Coubard 638:c90ae1400bf2 88 * Query the SoftDevice bond table to extract a whitelist containing the BLE
Vincent Coubard 638:c90ae1400bf2 89 * addresses and IRKs of bonded devices.
Vincent Coubard 638:c90ae1400bf2 90 *
Vincent Coubard 638:c90ae1400bf2 91 * @param[in/out] p_whitelist
Vincent Coubard 638:c90ae1400bf2 92 * (on input) p_whitelist->addr_count and
Vincent Coubard 638:c90ae1400bf2 93 * p_whitelist->irk_count specify the maximum number of
Vincent Coubard 638:c90ae1400bf2 94 * addresses and IRKs added to the whitelist structure.
Vincent Coubard 638:c90ae1400bf2 95 * (on output) *p_whitelist is a whitelist containing the
Vincent Coubard 638:c90ae1400bf2 96 * addresses and IRKs of the bonded devices.
Vincent Coubard 638:c90ae1400bf2 97 *
Vincent Coubard 638:c90ae1400bf2 98 * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
Vincent Coubard 638:c90ae1400bf2 99 */
Vincent Coubard 638:c90ae1400bf2 100 ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist);
Vincent Coubard 638:c90ae1400bf2 101
Vincent Coubard 638:c90ae1400bf2 102 /**
Vincent Coubard 638:c90ae1400bf2 103 * Function to test whether a BLE address is generated using an IRK.
Vincent Coubard 638:c90ae1400bf2 104 *
Vincent Coubard 638:c90ae1400bf2 105 * @param[in] p_addr
Vincent Coubard 638:c90ae1400bf2 106 * Pointer to a BLE address.
Vincent Coubard 638:c90ae1400bf2 107 * @param[in] p_irk
Vincent Coubard 638:c90ae1400bf2 108 * Pointer to an IRK.
Vincent Coubard 638:c90ae1400bf2 109 *
Vincent Coubard 638:c90ae1400bf2 110 * @return True if p_addr can be generated using p_irk, false otherwise.
Vincent Coubard 638:c90ae1400bf2 111 */
Vincent Coubard 638:c90ae1400bf2 112 bool btle_matchAddressAndIrk(ble_gap_addr_t const * p_addr, ble_gap_irk_t const * p_irk);
Vincent Coubard 638:c90ae1400bf2 113
Vincent Coubard 638:c90ae1400bf2 114 /**
Vincent Coubard 638:c90ae1400bf2 115 * Function to generate a private resolvable BLE address.
Vincent Coubard 638:c90ae1400bf2 116 *
Vincent Coubard 638:c90ae1400bf2 117 * @param[out] p_addr
Vincent Coubard 638:c90ae1400bf2 118 * The output address.
Vincent Coubard 638:c90ae1400bf2 119 * @param[in] p_irk
Vincent Coubard 638:c90ae1400bf2 120 * A reference to a IRK.
Vincent Coubard 638:c90ae1400bf2 121 *
Vincent Coubard 638:c90ae1400bf2 122 * @note This function does not generate a secure address since the prand number in the
Vincent Coubard 638:c90ae1400bf2 123 * resolvable address is not truly random. Therefore, the output of this function
Vincent Coubard 638:c90ae1400bf2 124 * is only meant to be used by the application internally but never exported.
Vincent Coubard 638:c90ae1400bf2 125 */
Vincent Coubard 638:c90ae1400bf2 126 void btle_generateResolvableAddress(const ble_gap_irk_t &irk, ble_gap_addr_t &address);
Vincent Coubard 638:c90ae1400bf2 127
Vincent Coubard 638:c90ae1400bf2 128 #endif /* _BTLE_SECURITY_H_ */