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::secure_connections_oob_request_reply
00375          * or a cancellation of the procedure.
00376          */
00377         virtual void on_secure_connections_oob_request(
00378             connection_handle_t connection
00379         ) = 0;
00380 
00381         /**
00382          * Request OOB data from the user application.
00383          *
00384          * @param[in] connection connection handle
00385          * @note shall be followed by: pal::SecurityManager::legacy_pairing_oob_request_reply
00386          * or a cancellation of the procedure.
00387          */
00388         virtual void on_legacy_pairing_oob_request(
00389             connection_handle_t connection
00390         ) = 0;
00391 
00392         /**
00393          * Send OOB data to the application for transport to the peer.
00394          *
00395          * @param[in] connection connection handle
00396          * @param[in] random random number used to generate the confirmation
00397          * @param[in] confirm confirmation value to be use for authentication
00398          *                    in secure connections pairing
00399          * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00400          */
00401         virtual void on_secure_connections_oob_generated(
00402             const oob_lesc_value_t &random,
00403             const oob_confirm_t &confirm
00404         ) = 0;
00405 
00406         ////////////////////////////////////////////////////////////////////////////
00407         // Keys
00408         //
00409 
00410         /**
00411          * Store the results of key generation of the stage 2 of secure connections pairing
00412          * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.3.5.6.5
00413          *
00414          * @param[in] connection connection handle
00415          * @param[in] ltk long term key from the peer
00416          */
00417         virtual void on_secure_connections_ltk_generated(
00418             connection_handle_t connection,
00419             const ltk_t &ltk
00420         ) = 0;
00421 
00422         /**
00423          * Store the results of key distribution after LTK has been received.
00424          *
00425          * @param[in] connection connection handle
00426          * @param[in] ltk long term key from the peer
00427          */
00428         virtual void on_keys_distributed_ltk(
00429             connection_handle_t connection,
00430             const ltk_t &ltk
00431         ) = 0;
00432 
00433         /**
00434          * Store the results of key distribution after EDIV and RAND has been received.
00435          *
00436          * @param[in] connection connection handle
00437          * @param[in] ltk long term key from the peer
00438          */
00439         virtual void on_keys_distributed_ediv_rand(
00440             connection_handle_t connection,
00441             const ediv_t &ediv,
00442             const rand_t &rand
00443         ) = 0;
00444 
00445         /**
00446          * Store the local key, if we are slave now or in the future
00447          * this will be used to encrypt.
00448          *
00449          * @param[in] connection connection handle
00450          * @param[in] ltk key sent to the peer
00451          */
00452         virtual void on_keys_distributed_local_ltk(
00453             connection_handle_t connection,
00454             const ltk_t &ltk
00455         ) = 0;
00456 
00457         /**
00458          * Store the EDIV and RAND that will be used to identify
00459          * the stored local LTK. if we are slave that LTK will be
00460          * used to encrypt, otherwise this will be stored to
00461          * be used in case of role reversal.
00462          *
00463          * @param[in] connection connection handle
00464          * @param[in] ediv identifies LTK
00465          * @param[in] rand identifies LTK
00466          */
00467         virtual void on_keys_distributed_local_ediv_rand(
00468             connection_handle_t connection,
00469             const ediv_t &ediv,
00470             const rand_t &rand
00471         ) = 0;
00472 
00473         /**
00474          * Store the results of key distribution after IRK has been received.
00475          *
00476          * @param[in] connection connection handle
00477          * @param[in] irk identity resolution key
00478          */
00479         virtual void on_keys_distributed_irk(
00480             connection_handle_t connection,
00481             const irk_t &irk
00482         ) = 0;
00483 
00484         /**
00485          * Store the identity address of the peer after it has been distributed.
00486          *
00487          * @param[in] connection connection handle
00488          * @param[in] peer_identity_address_type public or private address indication
00489          * @param[in] peer_identity_address peer address
00490          */
00491         virtual void on_keys_distributed_bdaddr(
00492             connection_handle_t connection,
00493             advertising_peer_address_type_t peer_identity_address_type,
00494             const address_t &peer_identity_address
00495         ) = 0;
00496 
00497         /**
00498          * Store the peer's CSRK after it has been distributed.
00499          *
00500          * @param[in] connection connection handle
00501          * @param[in] csrk signing key
00502          */
00503         virtual void on_keys_distributed_csrk(
00504             connection_handle_t connection,
00505             const csrk_t &csrk
00506         ) = 0;
00507 
00508         /**
00509          * Request the LTK since the peer is asking us to encrypt the link. We need to
00510          * provide the LTK based on the EDIV and RAND provided by the other side. This
00511          * is called on the slave.
00512          *
00513          * @param[in] connection connection handle
00514          * @param[in] ediv identifies LTK
00515          * @param[in] rand identifies LTK
00516          */
00517         virtual void on_ltk_request(
00518             connection_handle_t connection,
00519             const ediv_t &ediv,
00520             const rand_t &rand
00521         ) = 0;
00522 
00523         /**
00524          * Request the LTK since the peer is asking us to encrypt the link.
00525          * @note No EDIV or RAND is provided as this requests a secure
00526          * connections LTK where their values are all zeroes
00527          *
00528          * @param[in] connection connection handle
00529          */
00530         virtual void on_ltk_request(
00531             connection_handle_t connection
00532         ) = 0;
00533     };
00534 
00535 public:
00536     SecurityManager() : _pal_event_handler(NULL) { };
00537 
00538     virtual ~SecurityManager() { };
00539 
00540     ////////////////////////////////////////////////////////////////////////////
00541     // SM lifecycle management
00542     //
00543 
00544     /**
00545      * Initialise stack. Called before first use.
00546      *
00547      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00548      */
00549     virtual ble_error_t initialize() = 0;
00550 
00551     /**
00552      * Finalise all actions. Called before shutdown.
00553      *
00554      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00555      */
00556     virtual ble_error_t terminate() = 0;
00557 
00558     /**
00559      * Reset to same state as after initialize.
00560      *
00561      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00562      */
00563     virtual ble_error_t reset()  = 0;
00564 
00565     ////////////////////////////////////////////////////////////////////////////
00566     // Resolving list management
00567     //
00568 
00569     /**
00570      * Return the number of address translation entries that can be stored by the
00571      * subsystem.
00572      *
00573      * @warning: The number of entries is considered fixed.
00574      *
00575      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.41
00576      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00577      */
00578     virtual uint8_t read_resolving_list_capacity() = 0;
00579 
00580     /**
00581      * Add a device definition into the resolving list of the LE subsystem.
00582      *
00583      * @param[in] peer_identity_address_type public/private indicator
00584      * @param[in] peer_identity_address address of the device whose entry is to be added
00585      * @param[in] peer_irk peer identity resolving key
00586      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.38
00587      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00588      */
00589     virtual ble_error_t add_device_to_resolving_list(
00590         advertising_peer_address_type_t peer_identity_address_type,
00591         const address_t &peer_identity_address,
00592         const irk_t &peer_irk
00593     ) = 0;
00594 
00595     /**
00596      * Add a device definition from the resolving list of the LE subsystem.
00597      *
00598      * @param[in] peer_identity_address_type public/private indicator
00599      * @param[in] peer_identity_address address of the device whose entry is to be removed
00600      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.39
00601      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00602      */
00603     virtual ble_error_t remove_device_from_resolving_list(
00604         advertising_peer_address_type_t peer_identity_address_type,
00605         const address_t &peer_identity_address
00606     ) = 0;
00607 
00608     /**
00609      * Remove all devices from the resolving list.
00610      *
00611      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.40
00612      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00613      */
00614     virtual ble_error_t clear_resolving_list() = 0;
00615 
00616     ////////////////////////////////////////////////////////////////////////////
00617     // Pairing
00618     //
00619 
00620     /**
00621      * Send a pairing request to a slave.
00622      *
00623      * @param[in] connection connection handle
00624      * @param[in] oob_data_flag is oob data present
00625      * @param[in] authentication_requirements authentication requirements
00626      * @param[in] initiator_dist key distribution
00627      * @param[in] responder_dist key distribution
00628      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.1
00629      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00630      */
00631     virtual ble_error_t send_pairing_request(
00632         connection_handle_t connection,
00633         bool oob_data_flag,
00634         AuthenticationMask authentication_requirements,
00635         KeyDistribution initiator_dist,
00636         KeyDistribution responder_dist
00637     ) = 0;
00638 
00639     /**
00640      * Send a pairing response to a master.
00641      *
00642      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.2*
00643      * @param[in] connection connection handle
00644      * @param[in] oob_data_flag is oob data present
00645      * @param[in] authentication_requirements authentication requirements
00646      * @param[in] initiator_dist key distribution
00647      * @param[in] responder_dist key distribution
00648      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00649      */
00650     virtual ble_error_t send_pairing_response(
00651         connection_handle_t connection,
00652         bool oob_data_flag,
00653         AuthenticationMask authentication_requirements,
00654         KeyDistribution initiator_dist,
00655         KeyDistribution responder_dist
00656     ) = 0;
00657 
00658     /**
00659      * Cancel an ongoing pairing.
00660      *
00661      * @param[in] connection connection handle
00662      * @param[in] reason pairing failure error
00663      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.5
00664      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00665      */
00666     virtual ble_error_t cancel_pairing(
00667         connection_handle_t connection,
00668         pairing_failure_t reason
00669     ) = 0;
00670 
00671     ////////////////////////////////////////////////////////////////////////////
00672     // Feature support
00673     //
00674 
00675     /**
00676      * Check if the Secure Connections feature is supported by the stack and controller.
00677      *
00678      * @param[out] enabled true if SC are supported
00679      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00680      */
00681     virtual ble_error_t get_secure_connections_support(
00682         bool &enabled
00683     ) = 0;
00684 
00685     /**
00686      * Set the IO capability that will be used during pairing feature exchange.
00687      *
00688      * @param[in] io_capability type of IO capabilities available on the local device
00689      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00690      */
00691     virtual ble_error_t set_io_capability(
00692         io_capability_t io_capability
00693     ) = 0;
00694 
00695     ////////////////////////////////////////////////////////////////////////////
00696     // Security settings
00697     //
00698 
00699     /**
00700      * Set the time after which an event will be generated unless we received a packet with
00701      * a valid MIC.
00702      *
00703      * @param[in] connection connection handle
00704      * @param[in] timeout_in_10ms time measured in units of 10 milliseconds
00705      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00706      */
00707     virtual ble_error_t set_authentication_timeout(
00708         connection_handle_t connection,
00709         uint16_t timeout_in_10ms
00710     ) = 0;
00711 
00712     /**
00713      * Get the time after which an event will be generated unless we received a packet with
00714      * a valid MIC.
00715      *
00716      * @param[in] connection connection handle
00717      * @param[out] timeout_in_10ms time measured in units of 10 milliseconds
00718      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00719      */
00720     virtual ble_error_t get_authentication_timeout(
00721         connection_handle_t connection,
00722         uint16_t &timeout_in_10ms
00723     ) = 0;
00724 
00725     /**
00726      * Set the key size boundaries that will be used during pairing feature
00727      * exchange.
00728      *
00729      * @param[in] min_encryption_key_size The minimum encryption key size in bytes
00730      * required for pairing. This value shall be in the range [7 : 16].
00731      *
00732      * @param[in] max_encryption_key_size The maximum encryption key size in bytes
00733      * required for pairing. This value shall be in the range
00734      * [min_encryption_key_size : 16].
00735      *
00736      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00737      */
00738     virtual ble_error_t set_encryption_key_requirements(
00739         uint8_t min_encryption_key_size,
00740         uint8_t max_encryption_key_size
00741     ) = 0;
00742 
00743     /**
00744      * Request change of security level from the master. This is called by the slave when
00745      * it needs to elevate the security level as it can't change it itself. This will be
00746      * received by the master who will take the decision about what action to take
00747      * (encryption, pairing, re-paring).
00748      *
00749      * @param[in] connection connection handle
00750      * @param[in] authentication authentication requirements
00751      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00752      */
00753     virtual ble_error_t slave_security_request(
00754         connection_handle_t connection,
00755         AuthenticationMask authentication
00756     ) = 0;
00757 
00758     ////////////////////////////////////////////////////////////////////////////
00759     // Encryption
00760     //
00761 
00762     /**
00763      * Enabled encryption using the LTK given. The EDIV and RAND will be sent to the peer and
00764      * used to identify the LTK. This is called by the master. This will refresh the key if
00765      * enabled on an already encrypted link.
00766      *
00767      * @param[in] connection connection handle
00768      * @param[in] ltk long term key from the peer
00769      * @param[in] ediv encryption diversifier from the peer
00770      * @param[in] rand random value from the peer
00771      * @param[in] mitm does the LTK have man in the middle protection
00772      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00773      */
00774     virtual ble_error_t enable_encryption(
00775         connection_handle_t connection,
00776         const ltk_t &ltk,
00777         const rand_t &rand,
00778         const ediv_t &ediv,
00779         bool mitm
00780     ) = 0;
00781 
00782     /**
00783      * Enabled encryption using the LTK given on a connection established with secure
00784      * connections pairing.
00785      *
00786      * @param[in] connection connection handle
00787      * @param[in] ltk long term key from the peer
00788      * @param[in] mitm does the LTK have man in the middle protection
00789      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00790      */
00791     virtual ble_error_t enable_encryption(
00792         connection_handle_t connection,
00793         const ltk_t &ltk,
00794         bool mitm
00795     ) = 0;
00796 
00797     /**
00798      * Encrypt data with a given key. This uses the facility on the controller to
00799      * perform the encryption.
00800      *
00801      * @param[in] key encryption key
00802      * @param[in,out] data data to be encrypted, if successful contains the result
00803      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00804      */
00805     virtual ble_error_t encrypt_data(
00806         const byte_array_t<16> &key,
00807         encryption_block_t &data
00808     ) = 0;
00809 
00810     ////////////////////////////////////////////////////////////////////////////
00811     // Privacy
00812     //
00813 
00814     virtual ble_error_t set_private_address_timeout(
00815         uint16_t timeout_in_seconds
00816     ) = 0;
00817 
00818     ////////////////////////////////////////////////////////////////////////////
00819     // Keys
00820     //
00821 
00822     /**
00823      * Set the LTK that is to be used for encryption.
00824      *
00825      * @param[in] connection connection handle
00826      * @param[in] ltk long term key
00827      * @param[in] mitm does the LTK have man in the middle protection
00828      * @param[in] secure_connections is this a secure_connections pairing
00829      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00830      */
00831     virtual ble_error_t set_ltk(
00832         connection_handle_t connection,
00833         const ltk_t &ltk,
00834         bool mitm,
00835         bool secure_connections
00836     ) = 0;
00837 
00838     /**
00839      * Inform the stack we don't have the LTK.
00840      *
00841      * @param[in] connection connection handle
00842      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00843      */
00844     virtual ble_error_t set_ltk_not_found(
00845         connection_handle_t connection
00846     ) = 0;
00847 
00848     /**
00849      * Set the local IRK.
00850      *
00851      * @param[in] irk identity resolution key
00852      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00853      */
00854     virtual ble_error_t set_irk(
00855         const irk_t &irk
00856     ) = 0;
00857 
00858     /**
00859      * Set the local CSRK.
00860      *
00861      * @param[in] csrk local signing key
00862      * @param[in] sign_counter local signing counter
00863      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00864      */
00865     virtual ble_error_t set_csrk(
00866         const csrk_t &csrk,
00867         sign_count_t sign_counter
00868     ) = 0;
00869 
00870     /**
00871      * Set the peer CSRK for particular connection.
00872      *
00873      * @param[in] connection connection handle
00874      * @param[in] csrk signing key
00875      * @param[in] authenticated is the CSRK authenticated
00876      * @param[in] sign_counter signing counter
00877      * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
00878      */
00879     virtual ble_error_t set_peer_csrk(
00880         connection_handle_t connection,
00881         const csrk_t &csrk,
00882         bool authenticated,
00883         sign_count_t sign_counter
00884     ) = 0;
00885 
00886     virtual ble_error_t remove_peer_csrk(connection_handle_t connection) = 0;
00887 
00888     ////////////////////////////////////////////////////////////////////////////
00889     // Authentication
00890     //
00891 
00892     /**
00893      * Generate and return 8 octets of random data compliant with [FIPS PUB 140-2]
00894      *
00895      * @param[out] random_data returns 8 octets of random data
00896      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part H 2
00897      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00898      */
00899     virtual ble_error_t get_random_data(
00900         byte_array_t<8> &random_data
00901     ) = 0;
00902 
00903     ////////////////////////////////////////////////////////////////////////////
00904     // MITM
00905     //
00906 
00907     /**
00908      * Set the default passkey that will be used when the SM needs a passkey to
00909      * be displayed.
00910      *
00911      * By default, the pal security manager generates a random passkey when a
00912      * passkey has to be displayed by the application. A call to this function
00913      * with a valid passkey alter this behaviour and the SecurityManager shall
00914      * pass the passkey set into SecurityManagerEvent::on_passkey_display .
00915      *
00916      * A call to this function with a zero value will reset the behaviour and
00917      * indicates to the security manager that passkeys passed to
00918      * SecurityManagerEvent::on_passkey_display shall be randomly generated.
00919      *
00920      * @param[in] passkey Set the passkey that shall be used by the security
00921      * manager when SecurityManagerEvent::on_passkey_display is called. If
00922      * passkey is set to 0 then the security manager generates a random
00923      * passkey every time it calls SecurityManagerEvent::on_passkey_display.
00924      *
00925      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00926      */
00927     virtual ble_error_t set_display_passkey(
00928         passkey_num_t passkey
00929     ) = 0;
00930 
00931     /**
00932      * Reply to a passkey request received from the SecurityManagerEventHandler.
00933      *
00934      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00935      */
00936     virtual ble_error_t passkey_request_reply(
00937         connection_handle_t connection,
00938         passkey_num_t passkey
00939     ) = 0;
00940 
00941     /**
00942      * Reply to a Secure Connections oob data request received from the SecurityManagerEventHandler.
00943      *
00944      * @param[in] connection connection handle
00945      * @param[in] local_random local random number used for the last oob exchange
00946      * @param[in] peer_random random number used to generate the confirmation on peer
00947      * @param[in] peer_confirm confirmation value to be use for authentication
00948      *                         in secure connections pairing
00949      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00950      */
00951     virtual ble_error_t secure_connections_oob_request_reply(
00952         connection_handle_t connection,
00953         const oob_lesc_value_t &local_random,
00954         const oob_lesc_value_t &peer_random,
00955         const oob_confirm_t &peer_confirm
00956     ) = 0;
00957 
00958     /**
00959      * Reply to a legacy pairing oob data request received from the SecurityManagerEventHandler.
00960      *
00961      * @param[in] connection connection handle
00962      * @param[in] oob_data pointer to out of band data
00963      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00964      */
00965     virtual ble_error_t legacy_pairing_oob_request_reply(
00966         connection_handle_t connection,
00967         const oob_tk_t &oob_data
00968     ) = 0;
00969 
00970     /**
00971      * Notify the stack that the user has confirmed the values during numerical
00972      * comparison stage of pairing.
00973      *
00974      * @param[in] connection connection handle
00975      * @param[in] confirmation true if the user indicated the numbers match
00976      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00977      */
00978     virtual ble_error_t confirmation_entered(
00979         connection_handle_t connection,
00980         bool confirmation
00981     ) = 0;
00982 
00983     /**
00984      * Notify the stack that the user pressed a key. This will be sent to the peer and create
00985      * an appropriate event there if the keypress protocol is enabled.
00986      *
00987      * @param[in] connection connection handle
00988      * @param[in] keypress type of keypress event
00989      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00990      */
00991     virtual ble_error_t send_keypress_notification(
00992         connection_handle_t connection,
00993         Keypress_t keypress
00994     ) = 0;
00995 
00996     /**
00997      * Generate local OOB data to be sent to the application which sends it to the peer.
00998      * @return BLE_ERROR_NONE On success, else an error code indicating reason for failure
00999      */
01000     virtual ble_error_t generate_secure_connections_oob() = 0;
01001 
01002     /* Entry points for the underlying stack to report events back to the user. */
01003 public:
01004     /**
01005      * Sets the event handler that us called by the PAL porters to notify the stack of events
01006      * which will in turn be passed onto the user application when appropriate.
01007      *
01008      * @param[in] event_handler the new event handler interface implementation. Memory
01009      * owned by caller who is responsible for updating this pointer if interface changes.
01010      */
01011     void set_event_handler(
01012         EventHandler *event_handler
01013     ) {
01014         _pal_event_handler = event_handler;
01015     }
01016 
01017     EventHandler* get_event_handler() {
01018         return _pal_event_handler;
01019     }
01020 
01021 private:
01022     EventHandler *_pal_event_handler;
01023 
01024 };
01025 
01026 } /* namespace pal */
01027 } /* namespace ble */
01028 
01029 #endif /* MBED_OS_FEATURES_FEATURE_BLE_BLE_PAL_PALSM_H_ */