Junichi Katsu / nRF51822

test

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

source/btle/btle_security.h@616:a8f9b022d8fd, 2016-04-06 (annotated)

Committer:
LancasterUniversity
Date:
Wed Apr 06 22:39:17 2016 +0100
Revision:
616:a8f9b022d8fd
Parent:
615:65ea2acfc6a2 
Synchronized with git rev 67d0ac73

Author: Joe Finney

microbit: Update to indicate when system attributes require intialisation

Who changed what in which revision?

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