btle_security.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef _BTLE_SECURITY_H_
00018 #define _BTLE_SECURITY_H_
00019 
00020 #include "ble/Gap.h"
00021 #include "ble/SecurityManager.h"
00022 
00023 /**
00024  * Function to test whether the SecurityManager has been initialized.
00025  * Possible by a call to @ref btle_initializeSecurity().
00026  *
00027  * @return True if the SecurityManager was previously initialized, false
00028  *         otherwise.
00029  */
00030 bool btle_hasInitializedSecurity(void);
00031 
00032 /**
00033  * Enable Nordic's Device Manager, which brings in functionality from the
00034  * stack's Security Manager. The Security Manager implements the actual
00035  * cryptographic algorithms and protocol exchanges that allow two devices to
00036  * securely exchange data and privately detect each other.
00037  *
00038  * @param[in]  enableBonding Allow for bonding.
00039  * @param[in]  requireMITM   Require protection for man-in-the-middle attacks.
00040  * @param[in]  iocaps        To specify IO capabilities of this peripheral,
00041  *                           such as availability of a display or keyboard to
00042  *                           support out-of-band exchanges of security data.
00043  * @param[in]  passkey       To specify a static passkey.
00044  *
00045  * @return BLE_ERROR_NONE on success.
00046  */
00047 ble_error_t btle_initializeSecurity(bool                                      enableBonding = true,
00048                                     bool                                      requireMITM   = true,
00049                                     SecurityManager::SecurityIOCapabilities_t iocaps        = SecurityManager::IO_CAPS_NONE,
00050                                     const SecurityManager::Passkey_t          passkey       = NULL);
00051 
00052 /**
00053  * Get the security status of a link.
00054  *
00055  * @param[in]  connectionHandle
00056  *               Handle to identify the connection.
00057  * @param[out] securityStatusP
00058  *               security status.
00059  *
00060  * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
00061  */
00062 ble_error_t btle_getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP);
00063 
00064 /**
00065  * Set the security mode on a connection. Useful for elevating the security mode
00066  * once certain conditions are met, e.g., a particular service is found.
00067  *
00068  * @param[in]  connectionHandle
00069  *               Handle to identify the connection.
00070  * @param[in]  securityMode
00071  *               security mode.
00072  *
00073  * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
00074  */
00075 ble_error_t btle_setLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::SecurityMode_t securityMode);
00076 
00077 /**
00078  * Function for deleting all peer device context and all related bonding
00079  * information from the database.
00080  *
00081  * @retval BLE_ERROR_NONE             On success, else an error code indicating reason for failure.
00082  * @retval BLE_ERROR_INVALID_STATE    If the API is called without module initialization and/or
00083  *                                    application registration.
00084  */
00085 ble_error_t btle_purgeAllBondingState(void);
00086 
00087 /**
00088  * Query the SoftDevice bond table to extract a whitelist containing the BLE
00089  * addresses and IRKs of bonded devices.
00090  *
00091  * @param[in/out]  p_whitelist
00092  *                  (on input) p_whitelist->addr_count and
00093  *                  p_whitelist->irk_count specify the maximum number of
00094  *                  addresses and IRKs added to the whitelist structure.
00095  *                  (on output) *p_whitelist is a whitelist containing the
00096  *                  addresses and IRKs of the bonded devices.
00097  *
00098  * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
00099  */
00100 ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist);
00101 
00102 /**
00103  * Function to test whether a BLE address is generated using an IRK.
00104  *
00105  * @param[in]   p_addr
00106  *                  Pointer to a BLE address.
00107  * @param[in]   p_irk
00108  *                  Pointer to an IRK.
00109  *
00110  * @return True if p_addr can be generated using p_irk, false otherwise.
00111  */
00112 bool btle_matchAddressAndIrk(ble_gap_addr_t const * p_addr, ble_gap_irk_t const * p_irk);
00113 
00114 /**
00115  * Function to generate a private resolvable BLE address.
00116  *
00117  * @param[out]  p_addr
00118  *                  The output address.
00119  * @param[in]   p_irk
00120  *                  A reference to a IRK.
00121  *
00122  * @note This function does not generate a secure address since the prand number in the
00123  *       resolvable address is not truly random. Therefore, the output of this function
00124  *       is only meant to be used by the application internally but never exported.
00125  */
00126 void btle_generateResolvableAddress(const ble_gap_irk_t &irk, ble_gap_addr_t &address);
00127 
00128 #endif /* _BTLE_SECURITY_H_ */