Junichi Katsu / nRF51822

test

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

source/btle/btle_security.h@600:0978b5626451, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 10:19:36 2016 +0000
Revision:
600:0978b5626451
Parent:
599:3e66e1eb264d
Child:
613:cbc548e9df98
Synchronized with git rev 9d0c6381

Author: Andres Amaya Garcia

Add missing documentation to btle_security for whitelisting

Who changed what in which revision?

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