Mistake on this page?
Report an issue in GitHub or email us
SecurityManager.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2015 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef SECURITY_MANAGER_H_
18 #define SECURITY_MANAGER_H_
19 
20 #include <stdint.h>
21 
22 #include "ble/common/StaticInterface.h"
23 #include "ble/blecommon.h"
24 #include "ble/BLETypes.h"
25 #include "ble/Gap.h"
26 #include "CallChainOfFunctionPointersWithContext.h"
27 #include "BleImplementationForward.h"
28 
29 #if !defined(DOXYGEN_ONLY)
30 namespace ble {
31 namespace interface {
32 #endif
33 
34 /**
35  * Overview
36  *
37  * Security Manager is used to provide link security through encryption, signing and authentication
38  * which are made possible by pairing and optionally bonding. Pairing is the process of establishing
39  * and/or exchanging keys used for the current connection. Bonding means saving this information so that
40  * it can later be used after reconnecting without having to pair again. This saves time and power.
41  *
42  * @par Paring
43  *
44  * There are several ways to provide different levels of security during pairing depending on your requirements
45  * and the facilities provided by the application. The process starts with initialising the SecurityManager
46  * with default options for new connections. Some settings can later be changed per link or globally.
47  *
48  * The important settings in the init() function are the MITM requirement and IO capabilities. Man in the
49  * Middle (MITM) protection prevents an attack where one device can impersonate another device by
50  * pairing with both devices at the same time. This protection is achieved by sharing some information
51  * between the devices through some independent channel. The IO capabilities of both devices dictate
52  * what algorithm is used. For details @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.3.5.1.
53  * You can change the IO capabilities after initialisation with setIoCapability(). This will take effect
54  * for all subsequent pairings.
55  *
56  * @par Out of Band data used in pairing
57  *
58  * Sharing this information through IO capabilities means user interaction which limits the degree of
59  * protection due to the limit of the amount of data that we can expect the user to transfer. Another
60  * solution is using OOB (out of band) communication to transfer this data instead which can send much
61  * more data making MITM attack even less likely to succeed. OOB data has to be exchanged by the application
62  * and provided to the Security Manager. Use setOOBDataUsage() to indicate you want to use it. The same call also
63  * allows you to set whether or not the communication channel you are using to transmit the OOB data is
64  * itself secure against MITM protection - this will set the level of the link security achieved using pairing
65  * that uses this data.
66  *
67  * The most secure pairing is provided by Secure Connections which relies on Elliptical Curve Cryptography.
68  * Support for Secure Connections is dependent on both the stack and controller on both sides supporting
69  * it. If either side doesn't support it Legacy Pairing will be used. This is an older standard of pairing.
70  * If higher security is required legacy pairing can be disabled by calling allowLegacyPairing(false);
71  *
72  * @par Signing
73  *
74  * Applications may require a level of security providing confidence that data transfers are coming
75  * from a trusted source. This can be achieved by encrypting the link which also provides added confidentiality.
76  * Encryption is a good choice when a device stays connected but introduces latency due to the need of encrypting the
77  * link if the device only connects periodically to transfer data. If confidentiality is not required data GATT
78  * server may allow writes to happen over an unencrypted link but authenticated by a signature present in each packet.
79  * This signature relies on having sent a signing key to the peer during pairing prior to sending any signed packets.
80  *
81  * @par Persistence of Security information
82  *
83  * Security Manager stores all the data required for its operation on active links. Depending on resources
84  * available on the device it will also attempt to store data for disconnected devices which have bonded to be
85  * reused when reconnected.
86  *
87  * If the application has initialised a filesystem and the Security Manager has been provided with a
88  * filepath during the init() call it may also provide data persistence across resets. This must be enabled by
89  * calling preserveBondingStateOnReset(). Persistence is not guaranteed and may fail if abnormally terminated.
90  * The Security Manager may also fall back to a non-persistent implementation if the resources are too limited.
91  *
92  * @par How to use
93  *
94  * First thing you need to do is to initialise the manager by calling init() with your chosen settings.
95  *
96  * The SecurityManager communicates with your application through events. These will trigger calls in
97  * the EventHandler which you must provide by calling the setSecurityManagerEventHandler() function.
98  *
99  * The most important process is pairing. This may be triggered manually by calling requestPairing() or
100  * may be called as a result of the application requiring encryption by calling setLinkEncryption() or
101  * as a result of the application requiring MITM protection through requestAuthentication().
102  *
103  * All these can be implicitly called by using setLinkSecurity() to conveniently set the required
104  * security for the link. The SecurityManager will trigger all the process required to achieve the set
105  * security level. Security level can only be escalated. Asking the Security Manager for a lower
106  * security level than the existing one will not fail but will result in a event informing the
107  * application through linkEncryptionResult() of the current level (which remains unchanged).
108  *
109  * Depending on the IO capabilities and OOB usage settings different pairing algorithms will be chosen.
110  * They will produce appropriate events which must be handled by your EventHandler. If your event handler
111  * doesn't support all the calls you must not set IO capabilities or set OOB usage in such a way that would
112  * trigger them or else the pairing will fail (usually by timing out).
113  *
114  * The simplest example is a pairing of a device with no IO capabilities and no OOB data available.
115  * With such limited pairing capabilities the "just works" method will be employed. This does not provide
116  * any MITM protection. The pairing (triggered implicitly or called explicitly) will result in an event
117  * being generated on the peer calling pairingRequest(). The event handler must make a decision (either in
118  * the application itself or based on user interaction) whether to accept the pairing and call
119  * accetPairing() or cancelPairing(). The result will be communicated on both peers through an event calling
120  * pairingResult() in the EventHandler.
121  *
122  * @par Sequence diagrams
123  *
124  * Sequence diagram "Just Works" pairing
125  *
126  * \verbatim
127  * /----------- Device 1 --------------\ *------ BLE link ------* /-------------- Device 2 -------------\
128  *
129  * App EventHandler SecurityManager SecurityManager EventHandler App
130  * | | | | | |
131  * |---------------------------> requestPairing() | | |
132  * | | |------[pairing start]------>| | |
133  * | | | |----------------> pairingRequest() ->|
134  * | | | acceptPairing() <------------------------ |
135  * | | |<---[pairing complete]----->| | |
136  * |<- pairingResult() <---------------| |----------------> pairingResult() -->|
137  * | | | | | |
138  * @endverbatim
139  *
140  * @note the requestPairing() call isn't required to trigger pairing. Pairing will also be triggered
141  * if you request encryption and authentication and no bonding information is available. The sequence will
142  * be the same save for the lack of explicit requestPairing() call.
143  *
144  *
145  * Sequence diagram Encryption request when bonding information is available
146  *
147  * \verbatim
148  * /----------- Device 1 --------------\ *------ BLE link ------* /-------------- Device 2 -------------\
149  *
150  * App EventHandler SecurityManager SecurityManager EventHandler App
151  * | | | | | |
152  * |---------------------------> setLinkEncryption() | | |
153  * | | |<-[encryption established]->| | |
154  * |<- linkEncryptionResult() <--------| |---------> linkEncryptionResult() -->|
155  * | | | | | |
156  * @endverbatim
157  *
158  * @note if bonding information is not available, pairing will be triggered
159  *
160  *
161  * Sequence diagram for Secure Connections passkey entry pairing with one device having a display only
162  * and other a keyboard
163  *
164  * \verbatim
165  * /----------- Device 1 (keyboard) ---\ *------ BLE link ------* /-------------- Device 2 (display) ---\
166  *
167  * App EventHandler SecurityManager SecurityManager EventHandler App
168  * | | | | | |
169  * |---------------------------> requestPairing() | | |
170  * | | |------[pairing start]------>| | |
171  * | | | |----------------> pairingRequest() ->|
172  * | | | acceptPairing() <------------------------ |
173  * | | |<---[secure con. pairing]-->| | |
174  * |<- passkeyRequest() <--------------| |----------------> passkeyDisplay() ->|
175  * | | | | | |
176  *
177  * user reads the passkey on Device 2 and inputs it on Device 1
178  *
179  * | | | | | |
180  * |-------------------------->passkeyEntered() | | |
181  * | | |<---[pairing complete]----->| | |
182  * |<- pairingResult() <---------------| |----------------> pairingResult() -->|
183  * | | | | | |
184  * @endverbatim
185  *
186  */
187 #if !defined(DOXYGEN_ONLY)
188 template <class Impl>
189 class SecurityManager : public StaticInterface<Impl, SecurityManager> {
190 #else
192 #endif
193 
195 
196 public:
197  /** events sent and received when passkey is being entered */
198  enum Keypress_t {
199  KEYPRESS_STARTED, /**< Passkey entry started */
200  KEYPRESS_ENTERED, /**< Passkey digit entered */
201  KEYPRESS_ERASED, /**< Passkey digit erased */
202  KEYPRESS_CLEARED, /**< Passkey cleared */
203  KEYPRESS_COMPLETED, /**< Passkey entry completed */
204  };
205 
206  /** level of security required from the link by the application */
208  SECURITY_MODE_NO_ACCESS,
209  SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< Require no protection, open link. */
210  SECURITY_MODE_ENCRYPTION_NO_MITM, /**< Require encryption, but no MITM protection. */
211  SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< Require encryption and MITM protection. */
212  SECURITY_MODE_SIGNED_NO_MITM, /**< Require signing or encryption, but no MITM protection. */
213  SECURITY_MODE_SIGNED_WITH_MITM, /**< Require signing or encryption, and MITM protection. */
214  };
215 
216  /**
217  * @brief Defines possible security status or states.
218  *
219  * @details Defines possible security status or states of a link when requested by getLinkSecurity().
220  */
222  NOT_ENCRYPTED, /**< The link is not secured. */
223  ENCRYPTION_IN_PROGRESS, /**< Link security is being established.*/
224  ENCRYPTED /**< The link is secure.*/
225  };
226 
227  /** Input/output capability of the device and application */
229  IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display only. */
230  IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and yes/no entry. */
231  IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */
232  IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */
233  IO_CAPS_KEYBOARD_DISPLAY = 0x04, /**< Keyboard and display. */
234  };
235 
236  /** Result of security requests */
238  SEC_STATUS_SUCCESS = 0x00, /**< Procedure completed with success. */
239  SEC_STATUS_TIMEOUT = 0x01, /**< Procedure timed out. */
240  SEC_STATUS_PDU_INVALID = 0x02, /**< Invalid PDU received. */
241  SEC_STATUS_PASSKEY_ENTRY_FAILED = 0x81, /**< Passkey entry failed (user cancelled or other). */
242  SEC_STATUS_OOB_NOT_AVAILABLE = 0x82, /**< Out of Band Key not available. */
243  SEC_STATUS_AUTH_REQ = 0x83, /**< Authentication requirements not met. */
244  SEC_STATUS_CONFIRM_VALUE = 0x84, /**< Confirm value failed. */
245  SEC_STATUS_PAIRING_NOT_SUPP = 0x85, /**< Pairing not supported. */
246  SEC_STATUS_ENC_KEY_SIZE = 0x86, /**< Encryption key size. */
247  SEC_STATUS_SMP_CMD_UNSUPPORTED = 0x87, /**< Unsupported SMP command. */
248  SEC_STATUS_UNSPECIFIED = 0x88, /**< Unspecified reason. */
249  SEC_STATUS_REPEATED_ATTEMPTS = 0x89, /**< Too little time elapsed since last attempt. */
250  SEC_STATUS_INVALID_PARAMS = 0x8A, /**< Invalid parameters. */
251  SEC_STATUS_DHKEY_CHECK_FAILED = 0x8B, /**< DHKey received doesn’t match locally calculated one. */
252  SEC_STATUS_COMPARISON_FAILED = 0x8C, /**< Values in the numeric comparison protocol do not match. */
253  };
254 
255  /**
256  * Declaration of type containing a passkey to be used during pairing. This
257  * is passed into initializeSecurity() to specify a pre-programmed passkey
258  * for authentication instead of generating a random one.
259  */
260  static const unsigned PASSKEY_LEN = 6;
261  typedef uint8_t Passkey_t[PASSKEY_LEN]; /**< 6-digit passkey in ASCII ('0'-'9' digits only). */
262 
265 
266  /* legacy callbacks, please use SecurityManagerEventHandler instead */
267  typedef void (*HandleSpecificEvent_t)(ble::connection_handle_t connectionHandle);
268  typedef void (*SecuritySetupInitiatedCallback_t)(ble::connection_handle_t, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps);
269  typedef void (*SecuritySetupCompletedCallback_t)(ble::connection_handle_t, SecurityCompletionStatus_t status);
270  typedef void (*LinkSecuredCallback_t)(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode);
271  typedef void (*PasskeyDisplayCallback_t)(ble::connection_handle_t connectionHandle, const Passkey_t passkey);
272 
273  /** The stack will use these functions to signal events to the application,
274  * subclass to override handlers. Use SecurityManager::setSecurityManagerEventHandler
275  * to set the interface implementation to be used. */
276  class EventHandler {
277  public:
278  EventHandler() {};
279  virtual ~EventHandler() {};
280 
281  ////////////////////////////////////////////////////////////////////////////
282  // Pairing
283  //
284 
285  /**
286  * Request application to accept or reject pairing. Application should respond by
287  * calling the appropriate function: acceptPairingRequest or cancelPairingRequest
288  *
289  * @param[in] connectionHandle connection connectionHandle
290  */
291  virtual void pairingRequest(ble::connection_handle_t connectionHandle) {
292  (void)connectionHandle;
293  }
294 
295  /**
296  * Indicate to the application that pairing has completed.
297  *
298  * @param[in] connectionHandle connection connectionHandle
299  * @param[in] result result of the pairing indicating success or reason for failure
300  */
301  virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result) {
302  (void)connectionHandle;
303  (void)result;
304  }
305 
306  ////////////////////////////////////////////////////////////////////////////
307  // Security
308  //
309 
310  /**
311  * Deliver the requested whitelist to the application.
312  *
313  * @param[in] whitelist pointer to the whitelist filled with entries based on bonding information
314  */
315  virtual void whitelistFromBondTable(::Gap::Whitelist_t* whitelist) {
316  (void)whitelist;
317  }
318 
319  ////////////////////////////////////////////////////////////////////////////
320  // Encryption
321  //
322 
323  /**
324  * Inform the device of the encryption state of a given link.
325  *
326  * @param[in] connectionHandle connection connectionHandle
327  * @param[in] result encryption state of the link
328  */
329  virtual void linkEncryptionResult(ble::connection_handle_t connectionHandle, ble::link_encryption_t result) {
330  (void)connectionHandle;
331  (void)result;
332  }
333 
334  ////////////////////////////////////////////////////////////////////////////
335  // MITM
336  //
337 
338  /**
339  * Display the given passkey on the local device.
340  *
341  * @param[in] connectionHandle connection connectionHandle
342  * @param[in] passkey 6 digit passkey to be displayed
343  */
344  virtual void passkeyDisplay(ble::connection_handle_t connectionHandle, const SecurityManager::Passkey_t passkey) {
345  (void)connectionHandle;
346  (void)passkey;
347  }
348 
349  /**
350  * Indicate to the application that a confirmation is required. This is used
351  * when the device does not have a keyboard but has a yes/no button. The device
352  * displays numbers on its display in response to passkeyDisplay and the user
353  * checks if they are the same on both devices. The application should proceed
354  * by supplying the confirmation using the confirmationEntered function.
355  *
356  * @param[in] connectionHandle connection connectionHandle
357  */
358  virtual void confirmationRequest(ble::connection_handle_t connectionHandle) {
359  (void)connectionHandle;
360  }
361 
362  /**
363  * Indicate to the application that a passkey is required. The application should
364  * proceed by supplying the passkey through the passkeyEntered function.
365  *
366  * @param[in] connectionHandle connection connectionHandle
367  */
368  virtual void passkeyRequest(ble::connection_handle_t connectionHandle) {
369  (void)connectionHandle;
370  }
371 
372  /**
373  * Notify the application that a key was pressed by the peer during passkey entry.
374  *
375  * @param[in] connectionHandle connection connectionHandle
376  * @param[in] keypress type of keypress event
377  */
378  virtual void keypressNotification(ble::connection_handle_t connectionHandle, SecurityManager::Keypress_t keypress) {
379  (void)connectionHandle;
380  (void)keypress;
381  }
382 
383  /**
384  * Indicate to the application it needs to return legacy pairing OOB to the stack.
385  *
386  * @param[in] connectionHandle connection connectionHandle
387  */
388  virtual void legacyPairingOobRequest(ble::connection_handle_t connectionHandle) {
389  (void)connectionHandle;
390  }
391 
392  /**
393  * Indicate that the application needs to send legacy pairing OOB data to the peer.
394  *
395  * @param[in] address address that will be used in the pairing
396  * @param[in] temporaryKey temporary key to be used in legacy pairing
397  */
398  virtual void legacyPairingOobGenerated(const ble::address_t *address,
399  const ble::oob_tk_t *temporaryKey) {
400  (void)address;
401  (void)temporaryKey;
402  }
403 
404  /**
405  * Indicate that the application needs to send secure connections OOB data to the peer.
406  *
407  * @param[in] address address that will be used in the pairing
408  * @param[in] random random number used to generate the confirmation
409  * @param[in] confirm confirmation value to be use for authentication
410  * in secure connections pairing
411  */
412  virtual void oobGenerated(const ble::address_t *address,
413  const ble::oob_lesc_value_t *random,
414  const ble::oob_confirm_t *confirm) {
415  (void)address;
416  (void)random;
417  (void)confirm;
418  }
419 
420  ////////////////////////////////////////////////////////////////////////////
421  // Keys
422  //
423 
424  /**
425  * Deliver the signing key to the application.
426  *
427  * @param[in] connectionHandle connection connectionHandle
428  * @param[in] csrk signing key, pointer only valid during call
429  * @param[in] authenticated indicates if the signing key is authenticated
430  */
431  virtual void signingKey(ble::connection_handle_t connectionHandle, const ble::csrk_t *csrk, bool authenticated) {
432  (void)connectionHandle;
433  (void)csrk;
434  (void)authenticated;
435  }
436  };
437 
438  /*
439  * The following functions are meant to be overridden in the platform-specific sub-class.
440  */
441 public:
442  ////////////////////////////////////////////////////////////////////////////
443  // SM lifecycle management
444  //
445 
446  /**
447  * Enable the BLE stack's Security Manager. The Security Manager implements
448  * the actual cryptographic algorithms and protocol exchanges that allow two
449  * devices to securely exchange data and privately detect each other.
450  * Calling this API is a prerequisite for encryption and pairing (bonding).
451  *
452  * @param[in] enableBonding Allow for bonding.
453  * @param[in] requireMITM Require protection for man-in-the-middle attacks.
454  * @param[in] iocaps To specify the I/O capabilities of this peripheral,
455  * such as availability of a display or keyboard, to
456  * support out-of-band exchanges of security data.
457  * @param[in] passkey To specify a static passkey.
458  * @param[in] signing Generate and distribute signing key during pairing
459  * @param[in] dbFilepath Path to the file used to store keys in the filesystem,
460  * if NULL keys will be only stored in memory
461  *
462  *
463  * @return BLE_ERROR_NONE on success.
464  */
465  ble_error_t init(
466  bool enableBonding = true,
467  bool requireMITM = true,
468  SecurityIOCapabilities_t iocaps = IO_CAPS_NONE,
469  const Passkey_t passkey = NULL,
470  bool signing = true,
471  const char *dbFilepath = NULL
472  );
473 
474  /**
475  * Change the file used for the security database. If path is invalid or a NULL is passed
476  * keys will only be stored in memory.
477  *
478  * @note This operation is only allowed with no active connections.
479  *
480  * @param[in] dbFilepath Path to the file used to store keys in the filesystem,
481  * if NULL keys will be only stored in memory
482  *
483  * @return BLE_ERROR_NONE on success.
484  */
485  ble_error_t setDatabaseFilepath(const char *dbFilepath = NULL);
486 
487  /**
488  * Notify all registered onShutdown callbacks that the SecurityManager is
489  * about to be shutdown and clear all SecurityManager state of the
490  * associated object.
491  *
492  * This function is meant to be overridden in the platform-specific
493  * sub-class. Nevertheless, the sub-class is only expected to reset its
494  * state and not the data held in SecurityManager members. This shall be
495  * achieved by a call to SecurityManager::reset() from the sub-class'
496  * reset() implementation.
497  *
498  * @return BLE_ERROR_NONE on success.
499  */
500  ble_error_t reset(void);
501 
502  /**
503  * Normally all bonding information is lost when device is reset, this requests that the stack
504  * attempts to save the information and reload it during initialisation. This is not guaranteed.
505  *
506  * @param[in] enable if true the stack will attempt to preserve bonding information on reset.
507  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
508  */
509  ble_error_t preserveBondingStateOnReset(bool enable);
510 
511  ////////////////////////////////////////////////////////////////////////////
512  // List management
513  //
514 
515  /**
516  * Delete all peer device context and all related bonding information from
517  * the database within the security manager.
518  *
519  * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
520  * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
521  * application registration.
522  */
523  ble_error_t purgeAllBondingState(void);
524 
525  /**
526  * Create a list of addresses from all peers in the bond table and generate
527  * an event which returns it as a whitelist. Pass in the container for the whitelist.
528  * This will be returned by the event.
529  *
530  * @param[in] whitelist Preallocated whitelist which will be filled up to its capacity.
531  * If whitelist already contains entries this will be appended to.
532  * Do not access the whitelist until callback has been called,
533  * returning the filled whitelist.
534  *
535  * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
536  */
537  ble_error_t generateWhitelistFromBondTable(::Gap::Whitelist_t *whitelist) const;
538 
539  ////////////////////////////////////////////////////////////////////////////
540  // Pairing
541  //
542 
543  /**
544  * Request pairing with the peer. Called by the master.
545  * @note Slave can call requestAuthentication or setLinkEncryption to achieve security.
546  *
547  * @param[in] connectionHandle Handle to identify the connection.
548  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
549  */
550  ble_error_t requestPairing(ble::connection_handle_t connectionHandle);
551 
552  /**
553  * Accept the pairing request. Called as a result of pairingRequest being called
554  * on the event handler.
555  *
556  * @param[in] connectionHandle Handle to identify the connection.
557  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
558  */
559  ble_error_t acceptPairingRequest(ble::connection_handle_t connectionHandle);
560 
561  /**
562  * Reject pairing request if the local device is the slave or cancel an outstanding
563  * pairing request if master.
564  *
565  * @param[in] connectionHandle Handle to identify the connection.
566  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
567  */
568  ble_error_t cancelPairingRequest(ble::connection_handle_t connectionHandle);
569 
570  /**
571  * Tell the stack whether the application needs to authorise pairing requests or should
572  * they be automatically accepted.
573  *
574  * @param[in] required If set to true, pairingRequest in the event handler will
575  * will be called and will require an action from the application
576  * to continue with pairing by calling acceptPairingRequest
577  * or cancelPairingRequest if the user wishes to reject it.
578  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
579  */
580  ble_error_t setPairingRequestAuthorisation(bool required = true);
581 
582  ////////////////////////////////////////////////////////////////////////////
583  // Feature support
584  //
585 
586  /**
587  * Allow of disallow the use of legacy pairing in case the application only wants
588  * to force the use of Secure Connections. If legacy pairing is disallowed and either
589  * side doesn't support Secure Connections the pairing will fail.
590  *
591  * @param[out] allow If true legacy pairing will be used if either side doesn't support Secure Connections.
592  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
593  */
594  ble_error_t allowLegacyPairing(bool allow = true);
595 
596  /**
597  * Check if the Secure Connections feature is supported by the stack and controller.
598  *
599  * @param[out] enabled true if SC are supported
600  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
601  */
602  ble_error_t getSecureConnectionsSupport(bool *enabled);
603 
604  ////////////////////////////////////////////////////////////////////////////
605  // Security settings
606  //
607 
608  /**
609  * Set the IO capability of the local device.
610  *
611  * @param[in] iocaps type of IO capabilities available on the local device
612  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
613  */
614  ble_error_t setIoCapability(SecurityIOCapabilities_t iocaps);
615 
616  /**
617  * Set the passkey that is displayed on the local device instead of using
618  * a randomly generated one
619  *
620  * @param[in] passkey ASCII string of 6 digits
621  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
622  */
623  ble_error_t setDisplayPasskey(const Passkey_t passkey);
624 
625  /**
626  * Set the security mode on a connection. Useful for elevating the security mode
627  * once certain conditions are met, e.g., a particular service is found.
628  *
629  * @param[in] connectionHandle Handle to identify the connection.
630  * @param[in] securityMode Requested security mode.
631  *
632  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
633  */
634  ble_error_t setLinkSecurity(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode);
635 
636  /**
637  * Set whether or not we want to send and receive keypress notifications
638  * during passkey entry.
639  *
640  * @param[in] enabled if true pairing will try to enable keypress notifications
641  * (dependent on other side supporting it)
642  *
643  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
644  */
645  ble_error_t setKeypressNotification(bool enabled = true);
646 
647 #if BLE_FEATURE_SIGNING
648  /**
649  * Request generation and exchange of signing keys so that packet signing can be utilised
650  * on this connection.
651  * @note This does not generate a signingKey event. Use getSigningKey for that.
652  *
653  * @param[in] connectionHandle Handle to identify the connection.
654  * @param[in] enabled If set to true, signing keys will be exchanged
655  * during subsequent pairing.
656  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
657  */
658  ble_error_t enableSigning(ble::connection_handle_t connectionHandle, bool enabled = true);
659 #endif // BLE_FEATURE_SIGNING
660 
661  /**
662  * Give a hint to the stack that the master/slave role might change in the future.
663  *
664  * @param[in] enable If set to true it hints the roles are likely to swap in the future.
665  *
666  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
667  */
668  ble_error_t setHintFutureRoleReversal(bool enable = true);
669 
670  ////////////////////////////////////////////////////////////////////////////
671  // Encryption
672  //
673 
674  /**
675  * Current state of encryption on the link.
676  *
677  * @param[in] connectionHandle Handle to identify the connection.
678  * @param[out] encryption
679  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
680  */
681  ble_error_t getLinkEncryption(ble::connection_handle_t connectionHandle, ble::link_encryption_t *encryption);
682 
683  /**
684  * Enabled or disable encryption on the link. The result of this request will be indicated
685  * by a call to linkEncryptionResult in the event handler when the action is completed.
686  *
687  * @param[in] connectionHandle Handle to identify the connection.
688  * @param[in] encryption encryption state requested
689  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
690  */
691  ble_error_t setLinkEncryption(ble::connection_handle_t connectionHandle, ble::link_encryption_t encryption);
692 
693  /**
694  * Set the requirements for encryption key size. If the peer cannot comply with the requirements
695  * paring will fail.
696  *
697  * @param[in] minimumByteSize Smallest allowed encryption key size in bytes. (no smaller than 7)
698  * @param[in] maximumByteSize Largest allowed encryption key size in bytes. (no larger than 16)
699  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
700  */
701  ble_error_t setEncryptionKeyRequirements(uint8_t minimumByteSize, uint8_t maximumByteSize);
702 
703  ////////////////////////////////////////////////////////////////////////////
704  // Authentication
705  //
706 
707  /**
708  * Request that the link be authenticated (keys with MITM protection). This might trigger encryption
709  * or pairing/re-pairing. The success will be indicated through an event indicating security level change.
710  *
711  * @param[in] connectionHandle Handle to identify the connection.
712  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
713  */
714  ble_error_t requestAuthentication(ble::connection_handle_t connectionHandle);
715 
716  ////////////////////////////////////////////////////////////////////////////
717  // MITM
718  //
719 
720  /**
721  * Generate OOB data with the given address. If Secure Connections is supported this will
722  * also generate Secure Connections OOB data on top of legacy pairing OOB data. This can be used
723  * to generate such data before the connection takes place.
724  *
725  * In this model the OOB exchange takes place before the devices connect. Devices should establish
726  * communication over another channel and exchange the OOB data. The address provided will be used
727  * by the peer to associate the received data with the address of the device it will then connect
728  * to over BLE.
729  *
730  * @param[in] address The local address you will use in the connection using this OOB data. This
731  * address will be returned along with the rest of the OOB data when generation
732  * is complete. Using an invalid address is illegal.
733  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
734  */
735  ble_error_t generateOOB(const ble::address_t *address);
736 
737  /**
738  * Enable OOB data usage during paring. If Secure Connections is supported enabling useOOB will
739  * generate Secure Connections OOB data through oobGenerated() on top of legacy pairing OOB data.
740  *
741  * You do not have to call this function to return received OOB data. Use legacyPairingOobReceived
742  * or oobReceived to hand it in. This will allow the stack to use it if possible. You only need to
743  * call this function to attempt legacy OOB data exchange after pairing start and to inform
744  * the stack OOB data does not provide MITM protection (by default it is set to provide this).
745  *
746  * In this model the OOB exchange takes places after the devices have connected but possibly
747  * prior to pairing. For secure connections pairing must not be started until after the OOB
748  * data has been sent and/or received. The address in the OOB data generated will match
749  * the original address used to establish the connection and will be used by the peer to
750  * identify which connection the OOB data belongs to.
751  *
752  * @param[in] connectionHandle Handle to identify the connection.
753  * @param[in] useOOB If set to true, authenticate using OOB data.
754  * @param[in] OOBProvidesMITM If set to true keys exchanged during pairing using OOB data
755  * will provide Man-in-the-Middle protection. This indicates that
756  * the form of exchange used by the OOB data itself provides MITM
757  * protection.
758  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
759  */
760  ble_error_t setOOBDataUsage(ble::connection_handle_t connectionHandle, bool useOOB, bool OOBProvidesMITM = true);
761 
762  /**
763  * Report to the stack if the passkey matches or not. Used during pairing to provide MITM protection.
764  *
765  * @param[in] connectionHandle Handle to identify the connection.
766  * @param[in] confirmation True value indicates the passkey displayed matches.
767  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
768  */
769  ble_error_t confirmationEntered(ble::connection_handle_t connectionHandle, bool confirmation);
770 
771  /**
772  * Supply the stack with the user entered passkey.
773  *
774  * @param[in] connectionHandle Handle to identify the connection.
775  * @param[in] passkey ASCII string of digits entered by the user.
776  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
777  */
778  ble_error_t passkeyEntered(ble::connection_handle_t connectionHandle, Passkey_t passkey);
779 
780  /**
781  * Send a notification to the peer that the user pressed a key on the local device.
782  * @note This will only be delivered if the keypress notifications have been enabled during pairing.
783  *
784  * @param[in] connectionHandle Handle to identify the connection.
785  * @param[in] keypress Type of keypress event.
786  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
787  */
788  ble_error_t sendKeypressNotification(ble::connection_handle_t connectionHandle, Keypress_t keypress);
789 
790  /**
791  * Supply the stack with the OOB data for legacy connections.
792  *
793  * @param[in] address address of the peer device this data comes from
794  * @param[in] tk pointer to out of band data received containing the temporary key.
795  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
796  */
797  ble_error_t legacyPairingOobReceived(const ble::address_t *address, const ble::oob_tk_t *tk);
798 
799  /**
800  * Supply the stack with the OOB data for secure connections.
801  *
802  * @param[in] address address of the peer device this data comes from
803  * @param[in] random random number used to generate the confirmation
804  * @param[in] confirm confirmation value to be use for authentication
805  * in secure connections pairing
806  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
807  */
808  ble_error_t oobReceived(const ble::address_t *address, const ble::oob_lesc_value_t *random, const ble::oob_confirm_t *confirm);
809 
810  ////////////////////////////////////////////////////////////////////////////
811  // Keys
812  //
813 
814  /**
815  * Retrieves a signing key through a signingKey event.
816  * If a signing key is not present, pairing/authentication will be attempted.
817  * @note This will attempt to retrieve the key even if enableSigning hasn't been called prior to pairing.
818  *
819  * @param[in] connectionHandle Handle to identify the connection.
820  * @param[in] authenticated Whether the signing key needs to be authenticated
821  * (provide MITM protection).
822  *
823  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
824  */
825  ble_error_t getSigningKey(ble::connection_handle_t connectionHandle, bool authenticated);
826 
827  /* Event callback handlers. */
828 public:
829  /**
830  * Setup a callback to be invoked to notify the user application that the
831  * SecurityManager instance is about to shutdown (possibly as a result of a call
832  * to BLE::shutdown()).
833  *
834  * @note It is possible to chain together multiple onShutdown callbacks
835  * (potentially from different modules of an application) to be notified
836  * before the SecurityManager is shutdown.
837  *
838  * @note It is also possible to set up a callback into a member function of
839  * some object.
840  *
841  * @note It is possible to unregister a callback using onShutdown().detach(callback)
842  */
843  void onShutdown(const SecurityManagerShutdownCallback_t& callback) {
844  shutdownCallChain.add(callback);
845  }
846  template <typename T>
847  void onShutdown(T *objPtr, void (T::*memberPtr)(const SecurityManager *)) {
848  shutdownCallChain.add(objPtr, memberPtr);
849  }
850 
851  /**
852  * Provide access to the callchain of shutdown event callbacks.
853  * It is possible to register callbacks using onShutdown().add(callback).
854  * It is possible to unregister callbacks using onShutdown().detach(callback).
855  *
856  * @return The shutdown event callbacks chain
857  */
858  SecurityManagerShutdownCallbackChain_t& onShutdown() {
859  return shutdownCallChain;
860  }
861 
862  /**
863  * Assign the event handler implementation that will be used by the stack to signal events
864  * back to the application.
865  *
866  * @param[in] handler Event Handler interface implementation.
867  */
869  if (handler) {
870  eventHandler = handler;
871  } else {
872  eventHandler = &defaultEventHandler;
873  }
874  }
875 
876 protected:
877  SecurityManager() {
878  eventHandler = &defaultEventHandler;
879  }
880 
881  ~SecurityManager() { };
882 
883 public:
884  /**
885  * @deprecated use generateWhitelistFromBondTable instead
886  *
887  * Get a list of addresses from all peers in the bond table.
888  *
889  * @param[in,out] addresses
890  * (on input) addresses.capacity contains the maximum
891  * number of addresses to be returned.
892  * (on output) The populated table with copies of the
893  * addresses in the implementation's whitelist.
894  *
895  * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
896  * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
897  * application registration.
898  */
899  ble_error_t getAddressesFromBondTable(::Gap::Whitelist_t &addresses) const;
900 
901  /**
902  * @deprecated
903  *
904  * Get the security status of a connection.
905  *
906  * @param[in] connectionHandle Handle to identify the connection.
907  * @param[out] securityStatus Security status.
908  *
909  * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
910  */
911  ble_error_t getLinkSecurity(ble::connection_handle_t connectionHandle, LinkSecurityStatus_t *securityStatus) {
913  ble_error_t err = getLinkEncryption(connectionHandle, &encryption);
914  if (err) {
915  return err;
916  }
917 
918  switch (encryption.value()) {
920  *securityStatus = NOT_ENCRYPTED;
921  break;
923  *securityStatus = ENCRYPTION_IN_PROGRESS;
924  break;
928  *securityStatus = ENCRYPTED;
929  break;
930  default:
931  // should never happen
932  MBED_ASSERT(false);
933  *securityStatus = NOT_ENCRYPTED;
934  break;
935  }
936 
937  return BLE_ERROR_NONE;
938  }
939 
940  /**
941  * @deprecated
942  *
943  * To indicate that a security procedure for the link has started.
944  */
945  void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {
946  defaultEventHandler.securitySetupInitiatedCallback = callback;
947  }
948 
949  /**
950  * @deprecated
951  *
952  * To indicate that the security procedure for the link has completed.
953  */
954  void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback) {
955  defaultEventHandler.securitySetupCompletedCallback = callback;
956  }
957 
958  /**
959  * @deprecated
960  *
961  * To indicate that the link with the peer is secured. For bonded devices,
962  * subsequent reconnections with a bonded peer will result only in this callback
963  * when the link is secured; setup procedures will not occur (unless the
964  * bonding information is either lost or deleted on either or both sides).
965  */
966  void onLinkSecured(LinkSecuredCallback_t callback) {
967  defaultEventHandler.linkSecuredCallback = callback;
968  }
969 
970  /**
971  * @deprecated
972  *
973  * To indicate that device context is stored persistently.
974  */
975  void onSecurityContextStored(HandleSpecificEvent_t callback) {
976  defaultEventHandler.securityContextStoredCallback = callback;
977  }
978 
979  /** @deprecated
980  *
981  * To set the callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability.
982  */
983  void onPasskeyDisplay(PasskeyDisplayCallback_t callback) {
984  defaultEventHandler.passkeyDisplayCallback = callback;
985  }
986 
987  /* Entry points for the underlying stack to report events back to the user. */
988 public:
989  /** @deprecated */
990  void processSecuritySetupInitiatedEvent(ble::connection_handle_t connectionHandle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps) {
991  if (defaultEventHandler.securitySetupInitiatedCallback) {
992  defaultEventHandler.securitySetupInitiatedCallback(connectionHandle, allowBonding, requireMITM, iocaps);
993  }
994  }
995  /** @deprecated */
996  void processSecuritySetupCompletedEvent(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t status) {
997  eventHandler->pairingResult(connectionHandle, status);
998  }
999  /** @deprecated */
1000  void processLinkSecuredEvent(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode) {
1001  if (securityMode == SECURITY_MODE_ENCRYPTION_NO_MITM) {
1002  eventHandler->linkEncryptionResult(connectionHandle, ble::link_encryption_t::ENCRYPTED);
1003  } else {
1004  eventHandler->linkEncryptionResult(connectionHandle, ble::link_encryption_t::NOT_ENCRYPTED);
1005  }
1006  }
1007  /** @deprecated */
1008  void processSecurityContextStoredEvent(ble::connection_handle_t connectionHandle) {
1009  if (defaultEventHandler.securityContextStoredCallback) {
1010  defaultEventHandler.securityContextStoredCallback(connectionHandle);
1011  }
1012  }
1013  /** @deprecated */
1014  void processPasskeyDisplayEvent(ble::connection_handle_t connectionHandle, const Passkey_t passkey) {
1015  eventHandler->passkeyDisplay(connectionHandle, passkey);
1016  }
1017 
1018 protected:
1019  /* --- _virtual_ implementations declaration --- */
1020 
1021  /* Note: implementation must call the base class definition */
1022  ble_error_t reset_();
1023 
1024  ble_error_t init_(
1025  bool enableBonding,
1026  bool requireMITM,
1027  SecurityIOCapabilities_t iocaps,
1028  const Passkey_t passkey,
1029  bool signing,
1030  const char *dbFilepath
1031  );
1032 
1033  ble_error_t setDatabaseFilepath_(const char *dbFilepath);
1034 
1035  ble_error_t preserveBondingStateOnReset_(bool enable);
1036 
1037  ble_error_t purgeAllBondingState_(void);
1038 
1039  ble_error_t generateWhitelistFromBondTable_(
1040  ::Gap::Whitelist_t *whitelist
1041  ) const;
1042 
1043  ble_error_t requestPairing_(
1044  ble::connection_handle_t connectionHandle
1045  );
1046 
1047  ble_error_t acceptPairingRequest_(
1048  ble::connection_handle_t connectionHandle
1049  );
1050 
1051  ble_error_t cancelPairingRequest_(
1052  ble::connection_handle_t connectionHandle
1053  );
1054 
1055  ble_error_t setPairingRequestAuthorisation_(
1056  bool required
1057  );
1058 
1059  ble_error_t allowLegacyPairing_(bool allow);
1060 
1061  ble_error_t getSecureConnectionsSupport_(bool *enabled);
1062 
1063  ble_error_t setIoCapability_(SecurityIOCapabilities_t iocaps);
1064 
1065  ble_error_t setDisplayPasskey_(const Passkey_t passkey);
1066 
1067  ble_error_t setLinkSecurity_(
1068  ble::connection_handle_t connectionHandle,
1069  SecurityMode_t securityMode
1070  );
1071 
1072  ble_error_t setKeypressNotification_(bool enabled);
1073 
1074  ble_error_t enableSigning_(
1075  ble::connection_handle_t connectionHandle,
1076  bool enabled
1077  );
1078 
1079  ble_error_t setHintFutureRoleReversal_(bool enable);
1080 
1081  ble_error_t getLinkEncryption_(
1082  ble::connection_handle_t connectionHandle,
1083  ble::link_encryption_t *encryption
1084  );
1085 
1086  ble_error_t setLinkEncryption_(
1087  ble::connection_handle_t connectionHandle,
1088  ble::link_encryption_t encryption
1089  );
1090 
1091  ble_error_t setEncryptionKeyRequirements_(
1092  uint8_t minimumByteSize,
1093  uint8_t maximumByteSize
1094  );
1095 
1096  ble_error_t requestAuthentication_(
1097  ble::connection_handle_t connectionHandle
1098  );
1099 
1100  ble_error_t generateOOB_(const ble::address_t *address);
1101 
1102  ble_error_t setOOBDataUsage_(
1103  ble::connection_handle_t connectionHandle,
1104  bool useOOB,
1105  bool OOBProvidesMITM
1106  );
1107 
1108  ble_error_t confirmationEntered_(
1109  ble::connection_handle_t connectionHandle,
1110  bool confirmation
1111  );
1112 
1113  ble_error_t passkeyEntered_(
1114  ble::connection_handle_t connectionHandle,
1115  Passkey_t passkey
1116  );
1117 
1118  ble_error_t sendKeypressNotification_(
1119  ble::connection_handle_t connectionHandle,
1120  Keypress_t keypress
1121  );
1122 
1123  ble_error_t legacyPairingOobReceived_(
1124  const ble::address_t *address,
1125  const ble::oob_tk_t *tk
1126  );
1127 
1128  ble_error_t oobReceived_(
1129  const ble::address_t *address,
1130  const ble::oob_lesc_value_t *random,
1131  const ble::oob_confirm_t *confirm
1132  );
1133 
1134  ble_error_t getSigningKey_(
1135  ble::connection_handle_t connectionHandle,
1136  bool authenticated
1137  );
1138 
1139  ble_error_t getAddressesFromBondTable_(::Gap::Whitelist_t &addresses) const;
1140 
1141 private:
1142  /* Legacy compatibility with old callbacks (from both sides so any
1143  * combination of new and old works) */
1144  class LegacyEventHandler : public EventHandler {
1145  public:
1146  LegacyEventHandler() :
1147  securitySetupInitiatedCallback(),
1148  securitySetupCompletedCallback(),
1149  linkSecuredCallback(),
1150  securityContextStoredCallback(),
1151  passkeyDisplayCallback() { };
1152 
1153  virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result) {
1154  if (securitySetupCompletedCallback) {
1155  securitySetupCompletedCallback(connectionHandle, result);
1156  }
1157  }
1158 
1159  virtual void linkEncryptionResult(ble::connection_handle_t connectionHandle, ble::link_encryption_t result) {
1160  if (linkSecuredCallback) {
1161  SecurityMode_t securityMode;
1162  if (result == ble::link_encryption_t::ENCRYPTED) {
1163  securityMode = SECURITY_MODE_ENCRYPTION_NO_MITM;
1164  } else if (
1167  ) {
1168  securityMode = SECURITY_MODE_ENCRYPTION_WITH_MITM;
1169  } else {
1170  securityMode = SECURITY_MODE_ENCRYPTION_OPEN_LINK;
1171  }
1172  linkSecuredCallback(connectionHandle, securityMode);
1173  }
1174  };
1175 
1176  virtual void passkeyDisplay(ble::connection_handle_t connectionHandle, const Passkey_t passkey) {
1177  if (passkeyDisplayCallback) {
1178  passkeyDisplayCallback(connectionHandle, passkey);
1179  }
1180  };
1181 
1182  SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
1183  SecuritySetupCompletedCallback_t securitySetupCompletedCallback;
1184  LinkSecuredCallback_t linkSecuredCallback;
1185  HandleSpecificEvent_t securityContextStoredCallback;
1186  PasskeyDisplayCallback_t passkeyDisplayCallback;
1187  };
1188 
1189 private:
1190  SecurityManagerShutdownCallbackChain_t shutdownCallChain;
1191 
1192 protected:
1193  EventHandler* eventHandler;
1194  LegacyEventHandler defaultEventHandler;
1195 };
1196 
1197 
1198 #if !defined(DOXYGEN_ONLY)
1199 } // interface
1200 } // ble
1201 
1202 using ble::impl::SecurityManager;
1203 #endif
1204 
1205 
1206 #endif /*SECURITY_MANAGER_H_*/
virtual void confirmationRequest(ble::connection_handle_t connectionHandle)
Indicate to the application that a confirmation is required.
virtual void keypressNotification(ble::connection_handle_t connectionHandle, SecurityManager::Keypress_t keypress)
Notify the application that a key was pressed by the peer during passkey entry.
virtual void passkeyRequest(ble::connection_handle_t connectionHandle)
Indicate to the application that a passkey is required.
SecurityCompletionStatus_t
Result of security requests.
virtual void passkeyDisplay(ble::connection_handle_t connectionHandle, const SecurityManager::Passkey_t passkey)
Display the given passkey on the local device.
void onShutdown(const SecurityManagerShutdownCallback_t &callback)
Setup a callback to be invoked to notify the user application that the SecurityManager instance is ab...
uintptr_t connection_handle_t
Opaque reference to a connection.
Definition: BLETypes.h:86
uint8_t Passkey_t[PASSKEY_LEN]
6-digit passkey in ASCII (&#39;0&#39;-&#39;9&#39; digits only).
SecurityManagerShutdownCallbackChain_t & onShutdown()
Provide access to the callchain of shutdown event callbacks.
virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result)
Indicate to the application that pairing has completed.
virtual void linkEncryptionResult(ble::connection_handle_t connectionHandle, ble::link_encryption_t result)
Inform the device of the encryption state of a given link.
void processPasskeyDisplayEvent(ble::connection_handle_t connectionHandle, const Passkey_t passkey)
Model fixed size array values.
Definition: BLETypes.h:333
Keypress_t
events sent and received when passkey is being entered
void processLinkSecuredEvent(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode)
SecurityIOCapabilities_t
Input/output capability of the device and application.
Require signing or encryption, but no MITM protection.
LayoutType value() const
Explicit access to the inner value of the SafeEnum instance.
Definition: SafeEnum.h:202
ble_error_t getLinkSecurity(ble::connection_handle_t connectionHandle, LinkSecurityStatus_t *securityStatus)
virtual void legacyPairingOobGenerated(const ble::address_t *address, const ble::oob_tk_t *temporaryKey)
Indicate that the application needs to send legacy pairing OOB data to the peer.
No error.
Definition: blecommon.h:151
Require signing or encryption, and MITM protection.
void onLinkSecured(LinkSecuredCallback_t callback)
Callback< R()> callback(R(*func)()=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:3848
virtual void signingKey(ble::connection_handle_t connectionHandle, const ble::csrk_t *csrk, bool authenticated)
Deliver the signing key to the application.
MAC address data type.
Definition: BLETypes.h:473
Require encryption, but no MITM protection.
void processSecuritySetupInitiatedEvent(ble::connection_handle_t connectionHandle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps)
#define MBED_ASSERT(expr)
MBED_ASSERT Declare runtime assertions: results in runtime error if condition is false.
Definition: mbed_assert.h:65
SecurityMode_t
level of security required from the link by the application
Link security is being established.
virtual void oobGenerated(const ble::address_t *address, const ble::oob_lesc_value_t *random, const ble::oob_confirm_t *confirm)
Indicate that the application needs to send secure connections OOB data to the peer.
void setSecurityManagerEventHandler(EventHandler *handler)
Assign the event handler implementation that will be used by the stack to signal events back to the a...
virtual void legacyPairingOobRequest(ble::connection_handle_t connectionHandle)
Indicate to the application it needs to return legacy pairing OOB to the stack.
void processSecurityContextStoredEvent(ble::connection_handle_t connectionHandle)
void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback)
virtual void pairingRequest(ble::connection_handle_t connectionHandle)
Request application to accept or reject pairing.
Require encryption and MITM protection.
Representation of a whitelist of addresses.
Definition: Gap.h:269
virtual void whitelistFromBondTable(::Gap::Whitelist_t *whitelist)
Deliver the requested whitelist to the application.
void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback)
The link is not secured.
void onPasskeyDisplay(PasskeyDisplayCallback_t callback)
void processSecuritySetupCompletedEvent(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t status)
void onSecurityContextStored(HandleSpecificEvent_t callback)
Entry namespace for all BLE API definitions.
LinkSecurityStatus_t
Defines possible security status or states.
The stack will use these functions to signal events to the application, subclass to override handlers...
ble_error_t
Error codes for the BLE API.
Definition: blecommon.h:147
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.