Shuta Nakamae / nRF51822

sa

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_ */