PalSecurityManager.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017-2018 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 MBED_OS_FEATURES_FEATURE_BLE_BLE_PAL_PALSM_H_
00018 #define MBED_OS_FEATURES_FEATURE_BLE_BLE_PAL_PALSM_H_
00019 
00020 #include "platform/Callback.h"
00021 #include "platform/NonCopyable.h"
00022 #include "ble/BLETypes.h"
00023 #include "ble/BLEProtocol.h"
00024 #include "ble/SecurityManager.h"
00025 #include "ble/pal/GapTypes.h"
00026 
00027 namespace ble {
00028 namespace pal {
00029 
00030 typedef SecurityManager::SecurityCompletionStatus_t SecurityCompletionStatus_t;
00031 typedef SecurityManager::SecurityMode_t SecurityMode_t;
00032 typedef SecurityManager::LinkSecurityStatus_t LinkSecurityStatus_t;
00033 typedef SecurityManager::Keypress_t Keypress_t;
00034 
00035 /**
00036  * Key distribution as required by the SMP with convenient setters and getters,
00037  * use value() to get the octet you can use directly in the PDU.
00038  */
00039 class KeyDistribution {
00040 public:
00041     enum KeyDistributionFlags_t {
00042         KEY_DISTRIBUTION_NONE       = 0x00,
00043         KEY_DISTRIBUTION_ENCRYPTION = 0x01,
00044         KEY_DISTRIBUTION_IDENTITY   = 0x02,
00045         KEY_DISTRIBUTION_SIGNING    = 0x04,
00046         KEY_DISTRIBUTION_LINK       = 0x08,
00047         KEY_DISTRIBUTION_ALL        = 0x0F
00048     };
00049 
00050     KeyDistribution() : _value(0) { }
00051     KeyDistribution(uint8_t value) : _value(value) { }
00052     KeyDistribution(bool encryption,
00053                     bool identity,
00054                     bool signing,
00055                     bool link) : _value(0) {
00056         set_encryption(encryption);
00057         set_identity(identity);
00058         set_signing(signing);
00059         set_link(link);
00060     }
00061 
00062     bool get_encryption() const {
00063         return _value & KEY_DISTRIBUTION_ENCRYPTION;
00064     }
00065     bool get_identity() const {
00066         return _value & KEY_DISTRIBUTION_IDENTITY;
00067     }
00068     bool get_signing() const {
00069         return _value & KEY_DISTRIBUTION_SIGNING;
00070     }
00071     bool get_link() const {
00072         return _value & KEY_DISTRIBUTION_LINK;
00073     }
00074 
00075     void set_encryption(bool enabled = true) {
00076         if (enabled) {
00077             _value |= KEY_DISTRIBUTION_ENCRYPTION;
00078         } else {
00079             _value &= ~KEY_DISTRIBUTION_ENCRYPTION;
00080         }
00081     }
00082     void set_identity(bool enabled = true) {
00083         if (enabled) {
00084             _value |= KEY_DISTRIBUTION_IDENTITY;
00085         } else {
00086             _value &= ~KEY_DISTRIBUTION_IDENTITY;
00087         }
00088     }
00089     void set_signing(bool enabled = true) {
00090         if (enabled) {
00091             _value |= KEY_DISTRIBUTION_SIGNING;
00092         } else {
00093             _value &= ~KEY_DISTRIBUTION_SIGNING;
00094         }
00095     }
00096     void set_link(bool enabled = true) {
00097         if (enabled) {
00098             _value |= KEY_DISTRIBUTION_LINK;
00099         } else {
00100             _value &= ~KEY_DISTRIBUTION_LINK;
00101         }
00102     }
00103 
00104     operator uint8_t() {
00105         return _value;
00106     }
00107 
00108     KeyDistribution operator&(const KeyDistribution& other) const {
00109         KeyDistribution result(this->value() & other.value());
00110         return result;
00111     }
00112 
00113     KeyDistribution& operator&=(const KeyDistribution& other) {
00114         this->_value = this->_value & other.value();
00115         return *this;
00116     }
00117 
00118     uint8_t value() const {
00119         return _value;
00120     }
00121 
00122 private:
00123     uint8_t _value;
00124 };
00125 
00126 /**
00127  * Authentication mask as required by the SMP with convenient setters and getters,
00128  * use value() to get the octet you can use directly in the PDU.
00129  */
00130 class AuthenticationMask {
00131 public:
00132     enum AuthenticationFlags_t {
00133         AUTHENTICATION_BONDABLE               = 0x01,
00134         AUTHENTICATION_MITM                   = 0x04, /* 0x02 missing because bonding uses two bits */
00135         AUTHENTICATION_SECURE_CONNECTIONS     = 0x08,
00136         AUTHENTICATION_KEYPRESS_NOTIFICATION  = 0x10
00137     };
00138 
00139     AuthenticationMask() : _value(0) { }
00140     AuthenticationMask(uint8_t value) : _value(value) { }
00141     AuthenticationMask(bool bondable,
00142                        bool mitm,
00143                        bool secure_connections,
00144                        bool keypress) : _value(0) {
00145         set_bondable(bondable);
00146         set_mitm(mitm);
00147         set_secure_connections(secure_connections);
00148         set_keypress_notification(keypress);
00149     }
00150 
00151     bool get_bondable() const {
00152         return _value & AUTHENTICATION_BONDABLE;
00153     }
00154     bool get_mitm() const {
00155         return _value & AUTHENTICATION_MITM;
00156     }
00157     bool get_secure_connections() const {
00158         return _value & AUTHENTICATION_SECURE_CONNECTIONS;
00159     }
00160     bool get_keypress_notification() const {
00161         return _value & AUTHENTICATION_KEYPRESS_NOTIFICATION;
00162     }
00163 
00164     void set_bondable(bool enabled = true) {
00165         if (enabled) {
00166             _value |= AUTHENTICATION_BONDABLE;
00167         } else {
00168             _value &= ~AUTHENTICATION_BONDABLE;
00169         }
00170     }
00171     void set_mitm(bool enabled = true) {
00172         if (enabled) {
00173             _value |= AUTHENTICATION_MITM;
00174         } else {
00175             _value &= ~AUTHENTICATION_MITM;
00176         }
00177     }
00178     void set_secure_connections(bool enabled = true) {
00179         if (enabled) {
00180             _value |= AUTHENTICATION_SECURE_CONNECTIONS;
00181         } else {
00182             _value &= ~AUTHENTICATION_SECURE_CONNECTIONS;
00183         }
00184     }
00185     void set_keypress_notification(bool enabled = true) {
00186         if (enabled) {
00187             _value |= AUTHENTICATION_KEYPRESS_NOTIFICATION;
00188         } else {
00189             _value &= ~AUTHENTICATION_KEYPRESS_NOTIFICATION;
00190         }
00191     }
00192 
00193     operator uint8_t() {
00194         return _value;
00195     }
00196     uint8_t value() const {
00197         return _value;
00198     }
00199 
00200 private:
00201     uint8_t _value;
00202 };
00203 
00204 /**
00205  * Adaptation layer of the Security Manager.
00206  */
00207 class SecurityManager : private mbed::NonCopyable<SecurityManager> {
00208 public:
00209     /**
00210      * Handle events generated by ble::pal::SecurityManager
00211      */
00212     class EventHandler {
00213     public:
00214         ////////////////////////////////////////////////////////////////////////////
00215         // Pairing
00216         //
00217 
00218         /**
00219          * Request pairing. This is called on the slave in response to a request from the master.
00220          * Upper layer shall either send a pairing response (send_pairing_response)
00221          * or cancel the pairing procedure (cancel_pairing).
00222          *
00223          * @param[in] connection connection handle
00224          * @param[in] oob_data_flag is out of band data present
00225          * @param[in] authentication_requirements authentication requirements
00226          * @param[in] initiator_dist key distribution
00227          * @param[in] responder_dist key distribution
00228          */
00229         virtual void on_pairing_request(
00230             connection_handle_t connection,
00231             bool oob_data_flag,
00232             AuthenticationMask authentication_requirements,
00233             KeyDistribution initiator_dist,
00234             KeyDistribution responder_dist
00235         ) = 0;
00236 
00237         /**
00238          * Indicate that the pairing has failed.
00239          *
00240          * @note Any subsequent pairing procedure shall restart from the Pairing
00241          * Feature Exchange phase.
00242          * @param[in] connection connection handle
00243          * @param[in] error reason for the failed pairing
00244          */
00245         virtual void on_pairing_error(
00246             connection_handle_t connection,
00247             pairing_failure_t error
00248         ) = 0;
00249 
00250         /**
00251          * Indicate that the pairing has timed out.
00252          *
00253          * @param[in] connection connection handle
00254          */
00255         virtual void on_pairing_timed_out(
00256             connection_handle_t connection
00257         ) = 0;
00258 
00259         /**
00260          * Indicate that the pairing for the link has completed.
00261          *
00262          * @param[in] connection connection handle
00263          */
00264         virtual void on_pairing_completed(
00265             connection_handle_t connection
00266         ) = 0;
00267 
00268         ////////////////////////////////////////////////////////////////////////////
00269         // Security
00270         //
00271 
00272         /**
00273          * Indicate that the authentication timeout time has elapsed
00274          * and we received no packets with a valid MIC in that time.
00275          *
00276          * @param[in] connection connection handle
00277          * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 6, Part B, 5.4
00278          */
00279         virtual void on_valid_mic_timeout(
00280             connection_handle_t connection
00281         ) = 0;
00282 
00283         /**
00284          * Ask the stack to evaluate the security request received from the slave.
00285          * This might result in the stack enabling encryption, or pairing/re-pairing.
00286          *
00287          * @param[in] connection connection handle
00288          * @param[in] authentication authentication requirements from the slave
00289          */
00290         virtual void on_slave_security_request(
00291             connection_handle_t connection,
00292             AuthenticationMask authentication
00293         ) = 0;
00294 
00295         ////////////////////////////////////////////////////////////////////////////
00296         // Encryption
00297         //
00298 
00299         /**
00300          * Inform the application of the result of an encryption request.
00301          * @note Do no call if request timed out, call on_link_encryption_request_timed_out
00302          * instead.
00303          *
00304          * @param[in] connection connection handle
00305          * @param[in] result encryption state of the link
00306          */
00307         virtual void on_link_encryption_result(
00308             connection_handle_t connection,
00309             link_encryption_t result
00310         ) = 0;
00311 
00312         /**
00313          * Indicate that the encryption request failed due to timeout.
00314          *
00315          * @param[in] connection connection handle
00316          */
00317         virtual void on_link_encryption_request_timed_out(
00318             connection_handle_t connection
00319         ) = 0;
00320 
00321         ////////////////////////////////////////////////////////////////////////////
00322         // MITM
00323         //
00324 
00325         /**
00326          * Inform the application that should display a passkey.
00327          *
00328          * @param[in] connection connection handle
00329          * @param[in] passkey passkey to be displayed
00330          */
00331         virtual void on_passkey_display(
00332             connection_handle_t connection,
00333             passkey_num_t passkey
00334         ) = 0;
00335 
00336         /**
00337          * Indicate that user confirmation is required to confirm matching
00338          * passkeys displayed on devices.
00339          *
00340          * @param[in] connection connection handle
00341          * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E, 7.7.42
00342          */
00343         virtual void on_confirmation_request(
00344             connection_handle_t connection
00345         ) = 0;
00346 
00347         /**
00348          * Request the passkey entered during pairing.
00349          *
00350          * @note shall be followed by: pal::SecurityManager::passkey_request_reply
00351          * @param[in] connection connection handle
00352          * or a cancellation of the procedure.
00353          */
00354         virtual void on_passkey_request(
00355             connection_handle_t connection
00356         ) = 0;
00357 
00358         /**
00359          * Indicate that a key has been pressed by the peer.
00360          *
00361          * @param[in] connection connection handle
00362          * @param[in] keypress type of keypress event
00363          * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H, 3.5.8
00364          */
00365         virtual void on_keypress_notification(
00366             connection_handle_t connection,
00367             Keypress_t keypress
00368         ) = 0;
00369 
00370         /**
00371          * Request OOB data from the user application.
00372          *
00373          * @param[in] connection connection handle
00374          * @note shall be followed by: pal::SecurityManager::legacy_pairing_oob_data_request_reply
00375          * or a cancellation of the procedure.
00376          */
00377         virtual void on_legacy_pairing_oob_request(
00378             connection_handle_t connection
00379         ) = 0;
00380 
00381         /**
00382          * Request OOB data to be verified against received public keys.
00383          *
00384          * @param[in] public_key_x newly generated public key (x coordinate)
00385          * @param[in] public_key_y newly generated public key (y coordinate)
00386          */
00387         virtual void on_oob_data_verification_request(
00388             connection_handle_t connection,
00389             const public_key_coord_t &peer_public_key_x,
00390             const public_key_coord_t &peer_public_key_y
00391         ) = 0;
00392 
00393         ////////////////////////////////////////////////////////////////////////////
00394         // Keys
00395         //
00396 
00397         /**
00398          * Provide the local public key.
00399          *
00400          * @param[in] public_key_x newly generated public key (x coordinate)
00401          * @param[in] public_key_y newly generated public key (y coordinate)
00402          */
00403         virtual void on_public_key_generated(
00404             const public_key_coord_t &public_key_x,
00405             const public_key_coord_t &public_key_y
00406         ) = 0;
00407 
00408         /**
00409          * Store the results of key generation of the stage 2 of secure connections pairing
00410          * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.3.5.6.5
00411          *
00412          * @param[in] connection connection handle
00413          * @param[in] ltk long term key from the peer
00414          */
00415         virtual void on_secure_connections_ltk_generated(
00416             connection_handle_t connection,
00417             const ltk_t &ltk
00418         ) = 0;
00419 
00420         /**
00421          * Store the results of key distribution after LTK has been received.
00422          *
00423          * @param[in] connection connection handle
00424          * @param[in] ltk long term key from the peer
00425          */
00426         virtual void on_keys_distributed_ltk(
00427             connection_handle_t connection,
00428             const ltk_t &ltk
00429         ) = 0;
00430 
00431         /**
00432          * Store the results of key distribution after EDIV and RAND has been received.
00433          *
00434          * @param[in] connection connection handle
00435          * @param[in] ltk long term key from the peer
00436          */
00437         virtual void on_keys_distributed_ediv_rand(
00438             connection_handle_t connection,
00439             const ediv_t &ediv,
00440             const rand_t &rand
00441         ) = 0;
00442 
00443         /**
00444          * Store the local key, if we are slave now or in the future
00445          * this will be used to encrypt.
00446          *
00447          * @param[in] connection connection handle
00448          * @param[in] ltk key sent to the peer
00449          */
00450         virtual void on_keys_distributed_local_ltk(
00451             connection_handle_t connection,
00452             const ltk_t &ltk
00453         ) = 0;
00454 
00455         /**
00456          * Store the EDIV and RAND that will be used to identify
00457          * the stored local LTK. if we are slave that LTK will be
00458          * used to encrypt, otherwise this will be stored to
00459          * be used in case of role reversal.
00460          *
00461          * @param[in] connection connection handle
00462          * @param[in] ediv identifies LTK
00463          * @param[in] rand identifies LTK
00464          */
00465         virtual void on_keys_distributed_local_ediv_rand(
00466             connection_handle_t connection,
00467             const ediv_t &ediv,
00468             const rand_t &rand
00469         ) = 0;
00470 
00471         /**
00472          * Store the results of key distribution after IRK has been received.
00473          *
00474          * @param[in] connection connection handle
00475          * @param[in] irk identity resolution key
00476          */
00477         virtual void on_keys_distributed_irk(
00478             connection_handle_t connection,
00479             const irk_t &irk
00480         ) = 0;
00481 
00482         /**
00483          * Store the identity address of the peer after it has been distributed.
00484          *
00485          * @param[in] connection connection handle
00486          * @param[in] peer_identity_address_type public or private address indication
00487          * @param[in] peer_identity_address peer address
00488          */
00489         virtual void on_keys_distributed_bdaddr(
00490             connection_handle_t connection,
00491             advertising_peer_address_type_t peer_identity_address_type,
00492             const address_t &peer_identity_address
00493         ) = 0;
00494 
00495         /**
00496          * Store the peer's CSRK after it has been distributed.
00497          *
00498          * @param[in] connection connection handle
00499          * @param[in] csrk signing key
00500          */
00501         virtual void on_keys_distributed_csrk(
00502             connection_handle_t connection,
00503             const csrk_t &csrk
00504         ) = 0;
00505 
00506         /**
00507          * Request the LTK since the peer is asking us to encrypt the link. We need to
00508          * provide the LTK based on the EDIV and RAND provided by the other side. This
00509          * is called on the slave.
00510          *
00511          * @param[in] connection connection handle
00512          * @param[in] ediv identifies LTK
00513          * @param[in] rand identifies LTK
00514          */
00515         virtual void on_ltk_request(
00516             connection_handle_t connection,
00517             const ediv_t &ediv,
00518             const rand_t &rand
00519         ) = 0;
00520 
00521         /**
00522          * Request the LTK since the peer is asking us to encrypt the link.
00523          * @note No EDIV or RAND is provided as this requests a secure
00524          * connections LTK where their values are all zeroes
00525          *
00526          * @param[in] connection connection handle
00527          */
00528         virtual void on_ltk_request(
00529             connection_handle_t connection
00530         ) = 0;
00531     };
00532 
00533 public:
00534     SecurityManager() : _pal_event_handler(NULL) { };
00535 
00536     virtual ~SecurityManager() { };
00537 
00538     ////////////////////////////////////////////////////////////////////////////
00539     // SM lifecycle management
00540     //
00541 
00542     /**
00543      * Initialise stack. Called before first use.
00544      *
00545      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00546      */
00547     virtual ble_error_t initialize() = 0;
00548 
00549     /**
00550      * Finalise all actions. Called before shutdown.
00551      *
00552      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00553      */
00554     virtual ble_error_t terminate() = 0;
00555 
00556     /**
00557      * Reset to same state as after initialize.
00558      *
00559      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00560      */
00561     virtual ble_error_t reset()  = 0;
00562 
00563     ////////////////////////////////////////////////////////////////////////////
00564     // Resolving list management
00565     //
00566 
00567     /**
00568      * Return the number of address translation entries that can be stored by the
00569      * subsystem.
00570      *
00571      * @warning: The number of entries is considered fixed.
00572      *
00573      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.41
00574      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00575      */
00576     virtual uint8_t read_resolving_list_capacity() = 0;
00577 
00578     /**
00579      * Add a device definition into the resolving list of the LE subsystem.
00580      *
00581      * @param[in] peer_identity_address_type public/private indicator
00582      * @param[in] peer_identity_address address of the device whose entry is to be added
00583      * @param[in] peer_irk peer identity resolving key
00584      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.38
00585      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00586      */
00587     virtual ble_error_t add_device_to_resolving_list(
00588         advertising_peer_address_type_t peer_identity_address_type,
00589         const address_t &peer_identity_address,
00590         const irk_t &peer_irk
00591     ) = 0;
00592 
00593     /**
00594      * Add a device definition from the resolving list of the LE subsystem.
00595      *
00596      * @param[in] peer_identity_address_type public/private indicator
00597      * @param[in] peer_identity_address address of the device whose entry is to be removed
00598      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.39
00599      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00600      */
00601     virtual ble_error_t remove_device_from_resolving_list(
00602         advertising_peer_address_type_t peer_identity_address_type,
00603         const address_t &peer_identity_address
00604     ) = 0;
00605 
00606     /**
00607      * Remove all devices from the resolving list.
00608      *
00609      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.40
00610      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00611      */
00612     virtual ble_error_t clear_resolving_list() = 0;
00613 
00614     ////////////////////////////////////////////////////////////////////////////
00615     // Pairing
00616     //
00617 
00618     /**
00619      * Send a pairing request to a slave.
00620      *
00621      * @param[in] connection connection handle
00622      * @param[in] oob_data_flag is oob data present
00623      * @param[in] authentication_requirements authentication requirements
00624      * @param[in] initiator_dist key distribution
00625      * @param[in] responder_dist key distribution
00626      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.1
00627      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00628      */
00629     virtual ble_error_t send_pairing_request(
00630         connection_handle_t connection,
00631         bool oob_data_flag,
00632         AuthenticationMask authentication_requirements,
00633         KeyDistribution initiator_dist,
00634         KeyDistribution responder_dist
00635     ) = 0;
00636 
00637     /**
00638      * Send a pairing response to a master.
00639      *
00640      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.2*
00641      * @param[in] connection connection handle
00642      * @param[in] oob_data_flag is oob data present
00643      * @param[in] authentication_requirements authentication requirements
00644      * @param[in] initiator_dist key distribution
00645      * @param[in] responder_dist key distribution
00646      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00647      */
00648     virtual ble_error_t send_pairing_response(
00649         connection_handle_t connection,
00650         bool oob_data_flag,
00651         AuthenticationMask authentication_requirements,
00652         KeyDistribution initiator_dist,
00653         KeyDistribution responder_dist
00654     ) = 0;
00655 
00656     /**
00657      * Cancel an ongoing pairing.
00658      *
00659      * @param[in] connection connection handle
00660      * @param[in] reason pairing failure error
00661      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.5
00662      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00663      */
00664     virtual ble_error_t cancel_pairing(
00665         connection_handle_t connection,
00666         pairing_failure_t reason
00667     ) = 0;
00668 
00669     ////////////////////////////////////////////////////////////////////////////
00670     // Feature support
00671     //
00672 
00673     /**
00674      * Check if the Secure Connections feature is supported by the stack and controller.
00675      *
00676      * @param[out] enabled true if SC are supported
00677      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00678      */
00679     virtual ble_error_t get_secure_connections_support(
00680         bool &enabled
00681     ) = 0;
00682 
00683     /**
00684      * Set the IO capability that will be used during pairing feature exchange.
00685      *
00686      * @param[in] io_capability type of IO capabilities available on the local device
00687      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00688      */
00689     virtual ble_error_t set_io_capability(
00690         io_capability_t io_capability
00691     ) = 0;
00692 
00693     ////////////////////////////////////////////////////////////////////////////
00694     // Security settings
00695     //
00696 
00697     /**
00698      * Set the time after which an event will be generated unless we received a packet with
00699      * a valid MIC.
00700      *
00701      * @param[in] connection connection handle
00702      * @param[in] timeout_in_10ms time measured in units of 10 milliseconds
00703      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00704      */
00705     virtual ble_error_t set_authentication_timeout(
00706         connection_handle_t connection,
00707         uint16_t timeout_in_10ms
00708     ) = 0;
00709 
00710     /**
00711      * Get the time after which an event will be generated unless we received a packet with
00712      * a valid MIC.
00713      *
00714      * @param[in] connection connection handle
00715      * @param[out] timeout_in_10ms time measured in units of 10 milliseconds
00716      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00717      */
00718     virtual ble_error_t get_authentication_timeout(
00719         connection_handle_t connection,
00720         uint16_t &timeout_in_10ms
00721     ) = 0;
00722 
00723     /**
00724      * Set the key size boundaries that will be used during pairing feature
00725      * exchange.
00726      *
00727      * @param[in] min_encryption_key_size The minimum encryption key size in bytes
00728      * required for pairing. This value shall be in the range [7 : 16].
00729      *
00730      * @param[in] max_encryption_key_size The maximum encryption key size in bytes
00731      * required for pairing. This value shall be in the range
00732      * [min_encryption_key_size : 16].
00733      *
00734      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00735      */
00736     virtual ble_error_t set_encryption_key_requirements(
00737         uint8_t min_encryption_key_size,
00738         uint8_t max_encryption_key_size
00739     ) = 0;
00740 
00741     /**
00742      * Request change of security level from the master. This is called by the slave when
00743      * it needs to elevate the security level as it can't change it itself. This will be
00744      * received by the master who will take the decision about what action to take
00745      * (encryption, pairing, re-paring).
00746      *
00747      * @param[in] connection connection handle
00748      * @param[in] authentication authentication requirements
00749      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00750      */
00751     virtual ble_error_t slave_security_request(
00752         connection_handle_t connection,
00753         AuthenticationMask authentication
00754     ) = 0;
00755 
00756     ////////////////////////////////////////////////////////////////////////////
00757     // Encryption
00758     //
00759 
00760     /**
00761      * Enabled encryption using the LTK given. The EDIV and RAND will be sent to the peer and
00762      * used to identify the LTK. This is called by the master. This will refresh the key if
00763      * enabled on an already encrypted link.
00764      *
00765      * @param[in] connection connection handle
00766      * @param[in] ltk long term key from the peer
00767      * @param[in] ediv encryption diversifier from the peer
00768      * @param[in] rand random value from the peer
00769      * @param[in] mitm does the LTK have man in the middle protection
00770      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00771      */
00772     virtual ble_error_t enable_encryption(
00773         connection_handle_t connection,
00774         const ltk_t &ltk,
00775         const rand_t &rand,
00776         const ediv_t &ediv,
00777         bool mitm
00778     ) = 0;
00779 
00780     /**
00781      * Enabled encryption using the LTK given on a connection established with secure
00782      * connections pairing.
00783      *
00784      * @param[in] connection connection handle
00785      * @param[in] ltk long term key from the peer
00786      * @param[in] mitm does the LTK have man in the middle protection
00787      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00788      */
00789     virtual ble_error_t enable_encryption(
00790         connection_handle_t connection,
00791         const ltk_t &ltk,
00792         bool mitm
00793     ) = 0;
00794 
00795     /**
00796      * Encrypt data with a given key. This uses the facility on the controller to
00797      * perform the encryption.
00798      *
00799      * @param[in] key encryption key
00800      * @param[in,out] data data to be encrypted, if successful contains the result
00801      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00802      */
00803     virtual ble_error_t encrypt_data(
00804         const byte_array_t<16> &key,
00805         encryption_block_t &data
00806     ) = 0;
00807 
00808     ////////////////////////////////////////////////////////////////////////////
00809     // Privacy
00810     //
00811 
00812     virtual ble_error_t set_private_address_timeout(
00813         uint16_t timeout_in_seconds
00814     ) = 0;
00815 
00816     ////////////////////////////////////////////////////////////////////////////
00817     // Keys
00818     //
00819 
00820     /**
00821      * Set the LTK that is to be used for encryption.
00822      *
00823      * @param[in] connection connection handle
00824      * @param[in] ltk long term key
00825      * @param[in] mitm does the LTK have man in the middle protection
00826      * @param[in] secure_connections is this a secure_connections pairing
00827      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00828      */
00829     virtual ble_error_t set_ltk(
00830         connection_handle_t connection,
00831         const ltk_t &ltk,
00832         bool mitm,
00833         bool secure_connections
00834     ) = 0;
00835 
00836     /**
00837      * Inform the stack we don't have the LTK.
00838      *
00839      * @param[in] connection connection handle
00840      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00841      */
00842     virtual ble_error_t set_ltk_not_found(
00843         connection_handle_t connection
00844     ) = 0;
00845 
00846     /**
00847      * Set the local IRK.
00848      *
00849      * @param[in] irk identity resolution key
00850      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00851      */
00852     virtual ble_error_t set_irk(
00853         const irk_t &irk
00854     ) = 0;
00855 
00856     /**
00857      * Set the local CSRK.
00858      *
00859      * @param[in] csrk signing key
00860      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00861      */
00862     virtual ble_error_t set_csrk(
00863         const csrk_t &csrk
00864     ) = 0;
00865 
00866     /**
00867      * Generate the Public key. This will also generate the private key.
00868      * Public key will be returned as an event handler callback when it's ready.
00869      *
00870      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00871      */
00872     virtual ble_error_t generate_public_key() = 0;
00873 
00874     ////////////////////////////////////////////////////////////////////////////
00875     // Authentication
00876     //
00877 
00878     /**
00879      * Generate and return 8 octets of random data compliant with [FIPS PUB 140-2]
00880      *
00881      * @param[out] random_data returns 8 octets of random data
00882      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part H 2
00883      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00884      */
00885     virtual ble_error_t get_random_data(
00886         byte_array_t<8> &random_data
00887     ) = 0;
00888 
00889     ////////////////////////////////////////////////////////////////////////////
00890     // MITM
00891     //
00892 
00893     /**
00894      * Set the default passkey that will be used when the SM needs a passkey to
00895      * be displayed.
00896      *
00897      * By default, the pal security manager generates a random passkey when a
00898      * passkey has to be displayed by the application. A call to this function
00899      * with a valid passkey alter this behaviour and the SecurityManager shall
00900      * pass the passkey set into SecurityManagerEvent::on_passkey_display .
00901      *
00902      * A call to this function with a zero value will reset the behaviour and
00903      * indicates to the security manager that passkeys passed to
00904      * SecurityManagerEvent::on_passkey_display shall be randomly generated.
00905      *
00906      * @param[in] passkey Set the passkey that shall be used by the security
00907      * manager when SecurityManagerEvent::on_passkey_display is called. If
00908      * passkey is set to 0 then the security manager generates a random
00909      * passkey every time it calls SecurityManagerEvent::on_passkey_display.
00910      *
00911      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00912      */
00913     virtual ble_error_t set_display_passkey(
00914         passkey_num_t passkey
00915     ) = 0;
00916 
00917     /**
00918      * Reply to a passkey request received from the SecurityManagerEventHandler.
00919      *
00920      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00921      */
00922     virtual ble_error_t passkey_request_reply(
00923         connection_handle_t connection,
00924         passkey_num_t passkey
00925     ) = 0;
00926 
00927     /**
00928      * Reply to an oob data request received from the SecurityManagerEventHandler.
00929      *
00930      * @param[in] connection connection handle
00931      * @param[in] oob_data pointer to out of band data
00932      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00933      */
00934     virtual ble_error_t legacy_pairing_oob_data_request_reply(
00935         connection_handle_t connection,
00936         const oob_tk_t &oob_data
00937     ) = 0;
00938 
00939     /**
00940      * Notify the stack that the user has confirmed the values during numerical
00941      * comparison stage of pairing.
00942      *
00943      * @param[in] connection connection handle
00944      * @param[in] confirmation true if the user indicated the numbers match
00945      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00946      */
00947     virtual ble_error_t confirmation_entered(
00948         connection_handle_t connection,
00949         bool confirmation
00950     ) = 0;
00951 
00952     /**
00953      * Notify the stack that the user pressed a key. This will be sent to the peer and create
00954      * an appropriate event there if the keypress protocol is enabled.
00955      *
00956      * @param[in] connection connection handle
00957      * @param[in] keypress type of keypress event
00958      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00959      */
00960     virtual ble_error_t send_keypress_notification(
00961         connection_handle_t connection,
00962         Keypress_t keypress
00963     ) = 0;
00964 
00965     /**
00966      * Notify the stack that the OOB data has been verified and supply the peer's random number.
00967      * If the verification failed this will not be called and cancel_pairing will be called instead.
00968      *
00969      * @param[in] connection connection handle
00970      * @param[in] local_random random number sent from the local device to be used in further
00971      *                       calculations by the stack, set to 0 if peer reported no OOB present
00972      * @param[in] peer_random random number from the peer to be used in further
00973      *                       calculations by the stack, set to 0 if no OOB data received
00974      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00975      */
00976     virtual ble_error_t oob_data_verified(
00977         connection_handle_t connection,
00978         const oob_lesc_value_t &local_random,
00979         const oob_lesc_value_t &peer_random
00980     ) = 0;
00981 
00982     /* Entry points for the underlying stack to report events back to the user. */
00983 public:
00984     /**
00985      * Sets the event handler that us called by the PAL porters to notify the stack of events
00986      * which will in turn be passed onto the user application when appropriate.
00987      *
00988      * @param[in] event_handler the new event handler interface implementation. Memory
00989      * owned by caller who is responsible for updating this pointer if interface changes.
00990      */
00991     void set_event_handler(
00992         EventHandler *event_handler
00993     ) {
00994         _pal_event_handler = event_handler;
00995     }
00996 
00997     EventHandler* get_event_handler() {
00998         return _pal_event_handler;
00999     }
01000 
01001 private:
01002     EventHandler *_pal_event_handler;
01003 
01004 };
01005 
01006 } /* namespace pal */
01007 } /* namespace ble */
01008 
01009 #endif /* MBED_OS_FEATURES_FEATURE_BLE_BLE_PAL_PALSM_H_ */