Michael Galis / nRF51822

No changes

Fork of nRF51822 by Nordic Semiconductor

source/btle/btle_security.h@599:3e66e1eb264d, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 10:19:36 2016 +0000
Revision:
599:3e66e1eb264d
Parent:
598:814c1ce92947
Child:
600:0978b5626451
Synchronized with git rev 2ebbcb08

Author: Andres Amaya Garcia

Add documentation and fix style of SecurityManager

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 558:c4b56f9d6f3b 24 * Enable Nordic's Device Manager, which brings in functionality from the
vcoubard 558:c4b56f9d6f3b 25 * stack's Security Manager. The Security Manager implements the actual
vcoubard 558:c4b56f9d6f3b 26 * cryptographic algorithms and protocol exchanges that allow two devices to
vcoubard 558:c4b56f9d6f3b 27 * securely exchange data and privately detect each other.
vcoubard 558:c4b56f9d6f3b 28 *
vcoubard 558:c4b56f9d6f3b 29 * @param[in] enableBonding Allow for bonding.
vcoubard 558:c4b56f9d6f3b 30 * @param[in] requireMITM Require protection for man-in-the-middle attacks.
vcoubard 558:c4b56f9d6f3b 31 * @param[in] iocaps To specify IO capabilities of this peripheral,
vcoubard 558:c4b56f9d6f3b 32 * such as availability of a display or keyboard to
vcoubard 558:c4b56f9d6f3b 33 * support out-of-band exchanges of security data.
vcoubard 558:c4b56f9d6f3b 34 * @param[in] passkey To specify a static passkey.
vcoubard 558:c4b56f9d6f3b 35 *
vcoubard 558:c4b56f9d6f3b 36 * @return BLE_ERROR_NONE on success.
vcoubard 558:c4b56f9d6f3b 37 */
vcoubard 558:c4b56f9d6f3b 38 ble_error_t btle_initializeSecurity(bool enableBonding = true,
vcoubard 558:c4b56f9d6f3b 39 bool requireMITM = true,
vcoubard 558:c4b56f9d6f3b 40 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
vcoubard 558:c4b56f9d6f3b 41 const SecurityManager::Passkey_t passkey = NULL);
vcoubard 558:c4b56f9d6f3b 42
vcoubard 598:814c1ce92947 43 ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist);
vcoubard 597:bcd5e287c494 44
vcoubard 558:c4b56f9d6f3b 45 /**
vcoubard 558:c4b56f9d6f3b 46 * Get the security status of a link.
vcoubard 558:c4b56f9d6f3b 47 *
vcoubard 558:c4b56f9d6f3b 48 * @param[in] connectionHandle
vcoubard 558:c4b56f9d6f3b 49 * Handle to identify the connection.
vcoubard 558:c4b56f9d6f3b 50 * @param[out] securityStatusP
vcoubard 558:c4b56f9d6f3b 51 * security status.
vcoubard 558:c4b56f9d6f3b 52 *
vcoubard 558:c4b56f9d6f3b 53 * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
vcoubard 558:c4b56f9d6f3b 54 */
vcoubard 558:c4b56f9d6f3b 55 ble_error_t btle_getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP);
vcoubard 558:c4b56f9d6f3b 56
vcoubard 558:c4b56f9d6f3b 57 /**
vcoubard 558:c4b56f9d6f3b 58 * Set the security mode on a connection. Useful for elevating the security mode
vcoubard 558:c4b56f9d6f3b 59 * once certain conditions are met, e.g., a particular service is found.
vcoubard 558:c4b56f9d6f3b 60 *
vcoubard 558:c4b56f9d6f3b 61 * @param[in] connectionHandle
vcoubard 558:c4b56f9d6f3b 62 * Handle to identify the connection.
vcoubard 558:c4b56f9d6f3b 63 * @param[in] securityMode
vcoubard 558:c4b56f9d6f3b 64 * security mode.
vcoubard 558:c4b56f9d6f3b 65 *
vcoubard 558:c4b56f9d6f3b 66 * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
vcoubard 558:c4b56f9d6f3b 67 */
vcoubard 558:c4b56f9d6f3b 68 ble_error_t btle_setLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::SecurityMode_t securityMode);
vcoubard 558:c4b56f9d6f3b 69
vcoubard 558:c4b56f9d6f3b 70 /**
vcoubard 558:c4b56f9d6f3b 71 * Function for deleting all peer device context and all related bonding
vcoubard 558:c4b56f9d6f3b 72 * information from the database.
vcoubard 558:c4b56f9d6f3b 73 *
vcoubard 558:c4b56f9d6f3b 74 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
vcoubard 558:c4b56f9d6f3b 75 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or
vcoubard 558:c4b56f9d6f3b 76 * application registration.
vcoubard 558:c4b56f9d6f3b 77 */
vcoubard 558:c4b56f9d6f3b 78 ble_error_t btle_purgeAllBondingState(void);
vcoubard 558:c4b56f9d6f3b 79
vcoubard 599:3e66e1eb264d 80 /**
vcoubard 599:3e66e1eb264d 81 * Function to test whether the SecurityManager has been initialized.
vcoubard 599:3e66e1eb264d 82 * Possible by a call to @ref btle_initializeSecurity().
vcoubard 599:3e66e1eb264d 83 *
vcoubard 599:3e66e1eb264d 84 * @return True if the SecurityManager was previously initialized, false
vcoubard 599:3e66e1eb264d 85 * otherwise.
vcoubard 599:3e66e1eb264d 86 */
vcoubard 598:814c1ce92947 87 bool btle_hasInitializedSecurity(void);
vcoubard 598:814c1ce92947 88
vcoubard 599:3e66e1eb264d 89 /**
vcoubard 599:3e66e1eb264d 90 * Function to test whether a BLE address is generated using an IRK.
vcoubard 599:3e66e1eb264d 91 *
vcoubard 599:3e66e1eb264d 92 * @param[in] p_addr
vcoubard 599:3e66e1eb264d 93 * Pointer to a BLE address.
vcoubard 599:3e66e1eb264d 94 * @param[in] p_irk
vcoubard 599:3e66e1eb264d 95 * Pointer to an IRK.
vcoubard 599:3e66e1eb264d 96 *
vcoubard 599:3e66e1eb264d 97 * @return True if p_addr can be generated using p_irk, false otherwise.
vcoubard 599:3e66e1eb264d 98 */
vcoubard 598:814c1ce92947 99 bool btle_matchAddressAndIrk(ble_gap_addr_t const * p_addr, ble_gap_irk_t const * p_irk);
vcoubard 598:814c1ce92947 100
rgrover1 134:df7e7964a9c3 101 #endif /* _BTLE_SECURITY_H_ */