GenericSecurityManager.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 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 _GENERIC_SECURITY_MANAGER_H_
00018 #define _GENERIC_SECURITY_MANAGER_H_
00019 
00020 #include "ble/pal/GapTypes.h"
00021 #include "ble/BLETypes.h"
00022 #include "ble/pal/SecurityDb.h"
00023 #include "platform/Callback.h"
00024 #include "ble/pal/ConnectionEventMonitor.h"
00025 #include "ble/generic/GenericGap.h"
00026 #include "ble/pal/PalSecurityManager.h"
00027 
00028 namespace ble {
00029 namespace generic {
00030 
00031 typedef SecurityManager::SecurityIOCapabilities_t SecurityIOCapabilities_t;
00032 
00033 class GenericSecurityManager : public SecurityManager,
00034                                public pal::SecurityManager::EventHandler,
00035                                public pal::ConnectionEventMonitor::EventHandler {
00036 public:
00037     typedef ble::pal::SecurityDistributionFlags_t SecurityDistributionFlags_t;
00038     typedef ble::pal::SecurityEntryKeys_t SecurityEntryKeys_t;
00039 
00040     /* implements SecurityManager */
00041 
00042     ////////////////////////////////////////////////////////////////////////////
00043     // SM lifecycle management
00044     //
00045 
00046     virtual ble_error_t init(
00047         bool bondable = true,
00048         bool mitm = true,
00049         SecurityIOCapabilities_t iocaps = IO_CAPS_NONE,
00050         const Passkey_t passkey = NULL,
00051         bool signing = true
00052     );
00053 
00054     virtual ble_error_t reset();
00055 
00056     virtual ble_error_t preserveBondingStateOnReset(
00057         bool enabled
00058     );
00059 
00060     ////////////////////////////////////////////////////////////////////////////
00061     // List management
00062     //
00063 
00064     virtual ble_error_t purgeAllBondingState();
00065 
00066     virtual ble_error_t generateWhitelistFromBondTable(
00067         Gap::Whitelist_t *whitelist
00068     ) const;
00069 
00070     ////////////////////////////////////////////////////////////////////////////
00071     // Pairing
00072     //
00073 
00074     virtual ble_error_t requestPairing(
00075         connection_handle_t connection
00076     );
00077 
00078     virtual ble_error_t acceptPairingRequest(
00079         connection_handle_t connection
00080     );
00081 
00082     virtual ble_error_t cancelPairingRequest(
00083         connection_handle_t connection
00084     );
00085 
00086     virtual ble_error_t setPairingRequestAuthorisation(
00087         bool required = true
00088     );
00089 
00090     ////////////////////////////////////////////////////////////////////////////
00091     // Feature support
00092     //
00093 
00094     virtual ble_error_t allowLegacyPairing(
00095         bool allow = true
00096     );
00097 
00098     virtual ble_error_t getSecureConnectionsSupport(
00099         bool *enabled
00100     );
00101 
00102     ////////////////////////////////////////////////////////////////////////////
00103     // Security settings
00104     //
00105 
00106     virtual ble_error_t setIoCapability(
00107         SecurityIOCapabilities_t iocaps
00108     );
00109 
00110     virtual ble_error_t setDisplayPasskey(
00111         const Passkey_t passkey
00112     );
00113 
00114     virtual ble_error_t setAuthenticationTimeout(
00115         connection_handle_t connection,
00116         uint32_t timeout_in_ms
00117     );
00118 
00119     virtual ble_error_t getAuthenticationTimeout(
00120         connection_handle_t connection,
00121         uint32_t *timeout_in_ms
00122     );
00123 
00124     virtual ble_error_t setLinkSecurity(
00125         connection_handle_t connection,
00126         SecurityMode_t securityMode
00127     );
00128 
00129     virtual ble_error_t setKeypressNotification(
00130         bool enabled = true
00131     );
00132 
00133     virtual ble_error_t enableSigning(
00134         connection_handle_t connection,
00135         bool enabled = true
00136     );
00137 
00138     virtual ble_error_t setHintFutureRoleReversal(
00139         bool enable = true
00140     );
00141 
00142     ////////////////////////////////////////////////////////////////////////////
00143     // Encryption
00144     //
00145 
00146     virtual ble_error_t getLinkEncryption(
00147         connection_handle_t connection,
00148         link_encryption_t *encryption
00149     );
00150 
00151     virtual ble_error_t setLinkEncryption(
00152         connection_handle_t connection,
00153         link_encryption_t encryption
00154     );
00155 
00156     virtual ble_error_t getEncryptionKeySize(
00157         connection_handle_t connection,
00158         uint8_t *size
00159     );
00160 
00161     virtual ble_error_t setEncryptionKeyRequirements(
00162         uint8_t minimumByteSize,
00163         uint8_t maximumByteSize
00164     );
00165 
00166     ////////////////////////////////////////////////////////////////////////////
00167     // Privacy
00168     //
00169 
00170     virtual ble_error_t setPrivateAddressTimeout(
00171         uint16_t timeout_in_seconds
00172     );
00173 
00174     ////////////////////////////////////////////////////////////////////////////
00175     // Keys
00176     //
00177 
00178     virtual ble_error_t getSigningKey(
00179         connection_handle_t connection,
00180         bool authenticated
00181     );
00182 
00183     ////////////////////////////////////////////////////////////////////////////
00184     // Authentication
00185     //
00186 
00187     virtual ble_error_t requestAuthentication(
00188         connection_handle_t connection
00189     );
00190 
00191     ////////////////////////////////////////////////////////////////////////////
00192     // MITM
00193     //
00194 
00195     virtual ble_error_t setOOBDataUsage(
00196         connection_handle_t connection,
00197         bool useOOB,
00198         bool OOBProvidesMITM = true
00199     );
00200 
00201     virtual ble_error_t confirmationEntered(
00202         connection_handle_t connection,
00203         bool confirmation
00204     );
00205 
00206     virtual ble_error_t passkeyEntered(
00207         connection_handle_t connection,
00208         Passkey_t passkey
00209     );
00210 
00211     virtual ble_error_t sendKeypressNotification(
00212         connection_handle_t connection,
00213         Keypress_t keypress
00214     );
00215 
00216     virtual ble_error_t legacyPairingOobReceived(
00217         const address_t *address,
00218         const oob_tk_t *tk
00219     );
00220 
00221     virtual ble_error_t oobReceived(
00222         const address_t *address,
00223         const oob_lesc_value_t *random,
00224         const oob_confirm_t *confirm
00225     );
00226 
00227     /* ends implements SecurityManager */
00228 
00229 public:
00230     GenericSecurityManager(
00231         pal::SecurityManager &palImpl,
00232         pal::SecurityDb &dbImpl,
00233         pal::ConnectionEventMonitor &connMonitorImpl
00234     ) : _pal(palImpl),
00235         _db(dbImpl),
00236         _connection_monitor(connMonitorImpl),
00237         _default_authentication(0),
00238         _default_key_distribution(pal::KeyDistribution::KEY_DISTRIBUTION_ALL),
00239         _pairing_authorisation_required(false),
00240         _legacy_pairing_allowed(true),
00241         _master_sends_keys(false),
00242         _public_keys_generated(false) {
00243         _pal.set_event_handler(this);
00244     }
00245 
00246     ////////////////////////////////////////////////////////////////////////////
00247     // Helper functions
00248     //
00249 
00250 private:
00251     /**
00252      * Generate the CSRK if needed.
00253      *
00254      * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00255      */
00256     ble_error_t init_signing();
00257 
00258     /**
00259      * Fills the buffer with the specified number of bytes of random data
00260      * produced by the link controller
00261      *
00262      * @param[out] buffer buffer to be filled with random data
00263      * @param[in] size number of bytes to fill with random data
00264      * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00265      */
00266     ble_error_t get_random_data(
00267         uint8_t *buffer,
00268         size_t size
00269     );
00270 
00271     /**
00272      * Send slave security request based on current link settings.
00273      *
00274      * @param[in] connectionHandle Handle to identify the connection.
00275      * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00276      */
00277     ble_error_t slave_security_request(
00278         connection_handle_t connection
00279     );
00280 
00281     /**
00282      * Enable encryption on the link, depending on whether device is master or slave.
00283      *
00284      * @param[in] connectionHandle Handle to identify the connection.
00285      * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00286      */
00287     ble_error_t enable_encryption(
00288         connection_handle_t connection
00289     );
00290 
00291     /**
00292      * Returns the requested LTK to the PAL. Called by the security db.
00293      *
00294      * @param[in] entry security entry returned by the database.
00295      * @param[in] entryKeys security entry containing keys.
00296      */
00297     void enable_encryption_cb(
00298         pal::SecurityDb::entry_handle_t entry,
00299         const SecurityEntryKeys_t* entryKeys
00300     );
00301 
00302     /**
00303      * Returns the requested LTK to the PAL. Called by the security db.
00304      *
00305      * @param[in] entry security entry returned by the database.
00306      * @param[in] entryKeys security entry containing keys.
00307      */
00308     void set_ltk_cb(
00309         pal::SecurityDb::entry_handle_t entry,
00310         const SecurityEntryKeys_t* entryKeys
00311     );
00312 
00313     /**
00314      * Returns the CSRK for the connection. Called by the security db.
00315      *
00316      * @param[in] connectionHandle Handle to identify the connection.
00317      * @param[in] entryKeys security entry containing keys.
00318      */
00319     void return_csrk_cb(
00320         pal::SecurityDb::entry_handle_t connection,
00321         const csrk_t *csrk
00322     );
00323 
00324 #if defined(MBEDTLS_CMAC_C)
00325     /**
00326      * Generate local OOB data to be sent to the application which sends it to the peer.
00327      *
00328      * @param[in] connectionHandle Handle to identify the connection.
00329      */
00330     void generate_secure_connections_oob(
00331         connection_handle_t connection
00332     );
00333 #endif
00334 
00335     /**
00336      * Updates the entry for the connection with OOB data presence.
00337      *
00338      * @param[in] connectionHandle Handle to identify the connection.
00339      */
00340     void update_oob_presence(
00341         connection_handle_t connection
00342     );
00343 
00344 #if defined(MBEDTLS_CMAC_C)
00345     /**
00346      * Calculate the confirmation value for secure connections OOB data based
00347      * on local public key and a random number.
00348      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.2.6
00349 
00350      * @param[in] U public key x component
00351      * @param[in] V public key y component
00352      * @param[in] X random number
00353      * @param[out] confirm confirmation value
00354      * @return true if cryptography functioned worked
00355      */
00356     static bool crypto_toolbox_f4(
00357         const public_key_t &U,
00358         const public_key_t &V,
00359         const oob_lesc_value_t &X,
00360         oob_confirm_t &confirm
00361     );
00362 #endif
00363 
00364     /**
00365      * Set the MITM protection setting on the database entry
00366      *
00367      * @param[in] connectionHandle Handle to identify the connection.
00368      * @param[in] enable if true set the MITM protection to on.
00369      */
00370     virtual void set_mitm_performed(
00371         connection_handle_t connection,
00372         bool enable = true
00373     );
00374 
00375     /**
00376      * Inform the Security manager of a new connection. This will create
00377      * or retrieve an existing security manager entry for the connected device.
00378      * Called by GAP.
00379      *
00380      * @param[in] connectionHandle Handle to identify the connection.
00381      * @param[in] is_master True if device is the master.
00382      * @param[in] peer_address_type type of address.
00383      * @param[in] peer_address Address of the connected device.
00384      * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00385      */
00386     virtual void on_connected(
00387         connection_handle_t connection,
00388         Gap::Role_t role,
00389         BLEProtocol::AddressType_t peer_address_type,
00390         const BLEProtocol::AddressBytes_t peer_address,
00391         BLEProtocol::AddressType_t local_address_type,
00392         const BLEProtocol::AddressBytes_t local_address,
00393         const Gap::ConnectionParams_t *connection_params
00394     );
00395 
00396     /**
00397      * Inform the security manager that a device has been disconnected and its
00398      * entry can be put in NVM storage. Called by GAP.
00399      *
00400      * @param[in] connectionHandle Handle to identify the connection.
00401      * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
00402      */
00403     virtual void on_disconnected(
00404         connection_handle_t connection,
00405         Gap::DisconnectionReason_t reason
00406     );
00407 
00408     /**
00409      * Inform the security manager of a new connection.
00410      *
00411      * @param[in] params information about the new connection.
00412      */
00413     void connection_callback(
00414         const Gap::ConnectionCallbackParams_t* params
00415     );
00416 
00417     /**
00418      * Inform the security manager that a connection ended.
00419      *
00420      * @param[in] params handle and reason of the disconnection.
00421      */
00422     void disconnection_callback(
00423         const Gap::DisconnectionCallbackParams_t* params
00424     );
00425 
00426 private:
00427     struct ControlBlock_t : public pal::SecurityDistributionFlags_t {
00428         ControlBlock_t();
00429 
00430         pal::KeyDistribution get_initiator_key_distribution() {
00431             return pal::KeyDistribution(initiator_key_distribution);
00432         };
00433         pal::KeyDistribution get_responder_key_distribution() {
00434             return pal::KeyDistribution(responder_key_distribution);
00435         };
00436         void set_initiator_key_distribution(pal::KeyDistribution mask) {
00437             initiator_key_distribution = mask.value();
00438         };
00439         void set_responder_key_distribution(pal::KeyDistribution mask) {
00440             responder_key_distribution = mask.value();
00441         };
00442 
00443         connection_handle_t connection;
00444         pal::SecurityDb::entry_handle_t db_entry;
00445 
00446         address_t local_address; /**< address used for connection, possibly different from identity */
00447 
00448     private:
00449         uint8_t initiator_key_distribution:4;
00450         uint8_t responder_key_distribution:4;
00451     public:
00452         uint8_t connected:1;
00453         uint8_t authenticated:1; /**< have we turned encryption on during this connection */
00454         uint8_t is_master:1;
00455 
00456         uint8_t encryption_requested:1;
00457         uint8_t encryption_failed:1;
00458         uint8_t encrypted:1;
00459         uint8_t signing_requested:1;
00460         uint8_t signing_override_default:1;
00461 
00462         uint8_t mitm_requested:1;
00463         uint8_t mitm_performed:1; /**< keys exchange will have MITM protection */
00464 
00465         uint8_t attempt_oob:1;
00466         uint8_t oob_mitm_protection:1;
00467         uint8_t oob_present:1;
00468     };
00469 
00470     pal::SecurityManager &_pal;
00471     pal::SecurityDb &_db;
00472     pal::ConnectionEventMonitor &_connection_monitor;
00473 
00474     pal::AuthenticationMask _default_authentication;
00475     pal::KeyDistribution _default_key_distribution;
00476 
00477     bool _pairing_authorisation_required;
00478     bool _legacy_pairing_allowed;
00479     bool _master_sends_keys;
00480     bool _public_keys_generated;
00481 
00482     /** There is always only one OOB data set stored at a time */
00483     address_t _peer_sc_oob_address;
00484     oob_lesc_value_t _peer_sc_oob_random;
00485     oob_confirm_t _peer_sc_oob_confirm;
00486     oob_lesc_value_t _local_sc_oob_random;
00487 
00488     static const size_t MAX_CONTROL_BLOCKS = 5;
00489     ControlBlock_t _control_blocks[MAX_CONTROL_BLOCKS];
00490 
00491     /* implements ble::pal::SecurityManager::EventHandler */
00492 public:
00493     ////////////////////////////////////////////////////////////////////////////
00494     // Pairing
00495     //
00496 
00497     /** @copydoc ble::pal::SecurityManager::on_pairing_request
00498      */
00499     virtual void on_pairing_request(
00500         connection_handle_t connection,
00501         bool use_oob,
00502         pal::AuthenticationMask authentication,
00503         pal::KeyDistribution initiator_dist,
00504         pal::KeyDistribution responder_dist
00505     );
00506 
00507     /** @copydoc ble::pal::SecurityManager::on_pairing_error
00508      */
00509     virtual void on_pairing_error(
00510         connection_handle_t connection,
00511         pairing_failure_t error
00512     );
00513 
00514     /** @copydoc ble::pal::SecurityManager::on_pairing_timed_out
00515      */
00516     virtual void on_pairing_timed_out(
00517         connection_handle_t connection
00518     );
00519 
00520     /** @copydoc ble::pal::SecurityManager::on_pairing_completed
00521      */
00522     virtual void on_pairing_completed(
00523         connection_handle_t connection
00524     );
00525 
00526     ////////////////////////////////////////////////////////////////////////////
00527     // Security
00528     //
00529 
00530     /** @copydoc ble::pal::SecurityManager::on_valid_mic_timeout
00531      */
00532     virtual void on_valid_mic_timeout(
00533         connection_handle_t connection
00534     );
00535 
00536     /** @copydoc ble::pal::SecurityManager::on_slave_security_request
00537      */
00538     virtual void on_slave_security_request(
00539         connection_handle_t connection,
00540         pal::AuthenticationMask authentication
00541     );
00542 
00543     ////////////////////////////////////////////////////////////////////////////
00544     // Encryption
00545     //
00546 
00547     /** @copydoc ble::pal::SecurityManager::on_link_encryption_result
00548      */
00549     virtual void on_link_encryption_result(
00550         connection_handle_t connection,
00551         link_encryption_t result
00552     );
00553 
00554     /** @copydoc ble::pal::SecurityManager::on_link_encryption_request_timed_out
00555      */
00556     virtual void on_link_encryption_request_timed_out(
00557         connection_handle_t connection
00558     );
00559 
00560     ////////////////////////////////////////////////////////////////////////////
00561     // MITM
00562     //
00563 
00564     /** @copydoc ble::pal::SecurityManager::on_passkey_display
00565      */
00566     virtual void on_passkey_display(
00567         connection_handle_t connection,
00568         passkey_num_t passkey
00569     );
00570 
00571     /** @copydoc ble::pal::SecurityManager::on_keypress_notification
00572      */
00573     virtual void on_keypress_notification(
00574         connection_handle_t connection,
00575         SecurityManager::Keypress_t keypress
00576     );
00577 
00578     /** @copydoc ble::pal::SecurityManager::on_passkey_request
00579      */
00580     virtual void on_passkey_request(
00581         connection_handle_t connection
00582     );
00583 
00584     /** @copydoc ble::pal::SecurityManager::on_confirmation_request
00585      */
00586     virtual void on_confirmation_request(
00587         connection_handle_t connection
00588     );
00589 
00590     /** @copydoc ble::pal::SecurityManager::on_legacy_pairing_oob_request
00591      */
00592     virtual void on_legacy_pairing_oob_request(
00593         connection_handle_t connection
00594     );
00595 
00596     /** @copydoc ble::pal::SecurityManager::on_oob_data_verification_request
00597      */
00598     virtual void on_oob_data_verification_request(
00599         connection_handle_t connection,
00600         const public_key_coord_t &peer_public_key_x,
00601         const public_key_coord_t &peer_public_key_y
00602     );
00603 
00604     ////////////////////////////////////////////////////////////////////////////
00605     // Keys
00606     //
00607 
00608     /** @copydoc ble::pal::SecurityManager::on_public_key_generated
00609      */
00610     virtual void on_public_key_generated(
00611         const public_key_coord_t &public_key_x,
00612         const public_key_coord_t &public_key_y
00613     );
00614 
00615     /** @copydoc ble::pal::SecurityManager::on_secure_connections_ltk_generated
00616      */
00617     virtual void on_secure_connections_ltk_generated(
00618         connection_handle_t connection,
00619         const ltk_t &ltk
00620     );
00621 
00622     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_ltk
00623      */
00624     virtual void on_keys_distributed_ltk(
00625         connection_handle_t connection,
00626         const ltk_t &ltk
00627     );
00628 
00629     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_ediv_rand
00630      */
00631     virtual void on_keys_distributed_ediv_rand(
00632         connection_handle_t connection,
00633         const ediv_t &ediv,
00634         const rand_t &rand
00635     );
00636 
00637     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_local_ltk
00638      */
00639     virtual void on_keys_distributed_local_ltk(
00640         connection_handle_t connection,
00641         const ltk_t &ltk
00642     );
00643 
00644     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_local_ediv_rand
00645      */
00646     virtual void on_keys_distributed_local_ediv_rand(
00647         connection_handle_t connection,
00648         const ediv_t &ediv,
00649         const rand_t &rand
00650     );
00651 
00652     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_irk
00653      */
00654     virtual void on_keys_distributed_irk(
00655         connection_handle_t connection,
00656         const irk_t &irk
00657     );
00658 
00659     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_bdaddr
00660      */
00661     virtual void on_keys_distributed_bdaddr(
00662         connection_handle_t connection,
00663         pal::advertising_peer_address_type_t peer_address_type,
00664         const address_t &peer_identity_address
00665     );
00666 
00667     /** @copydoc ble::pal::SecurityManager::on_keys_distributed_csrk
00668      */
00669     virtual void on_keys_distributed_csrk(
00670         connection_handle_t connection,
00671         const csrk_t &csrk
00672     );
00673 
00674     /** @copydoc ble::pal::SecurityManager::on_ltk_requeston_ltk_request
00675      */
00676     virtual void on_ltk_request(
00677         connection_handle_t connection,
00678         const ediv_t &ediv,
00679         const rand_t &rand
00680     );
00681 
00682     /** @copydoc ble::pal::SecurityManager::on_ltk_requeston_ltk_request
00683      */
00684     virtual void on_ltk_request(
00685         connection_handle_t connection
00686     );
00687 
00688     /* end implements ble::pal::SecurityManager::EventHandler */
00689 
00690     /* list management */
00691 
00692     ControlBlock_t* acquire_control_block(connection_handle_t connection);
00693 
00694     ControlBlock_t* get_control_block(connection_handle_t connection);
00695 
00696     ControlBlock_t* get_control_block(const address_t &peer_address);
00697 
00698     ControlBlock_t* get_control_block(pal::SecurityDb::entry_handle_t db_entry);
00699 
00700     void release_control_block(ControlBlock_t* entry);
00701 };
00702 
00703 
00704 } /* namespace generic */
00705 } /* namespace ble */
00706 
00707 
00708 #endif /*_GENERIC_SECURITY_MANAGER_H_*/