SecurityDb.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 PAL_SECURITY_MANAGER_DB_H__
00018 #define PAL_SECURITY_MANAGER_DB_H__
00019 
00020 #include "platform/Callback.h"
00021 #include "ble/pal/GapTypes.h"
00022 #include "ble/BLETypes.h"
00023 #include "ble/Gap.h"
00024 #include <stdlib.h>
00025 
00026 namespace ble {
00027 namespace pal {
00028 
00029 
00030 /**
00031  * Security flags associated with a bond.
00032  */
00033 struct SecurityDistributionFlags_t {
00034     SecurityDistributionFlags_t() :
00035         peer_address(),
00036         encryption_key_size(0),
00037         peer_address_is_public(false),
00038         local_address_is_public(false),
00039         csrk_stored(false),
00040         csrk_mitm_protected(false),
00041         ltk_stored(false),
00042         ltk_mitm_protected(false),
00043         secure_connections_paired(false) {
00044     }
00045 
00046     /** peer address */
00047     address_t peer_address;
00048 
00049     /** encryption key size */
00050     uint8_t encryption_key_size;
00051     /** true if peer address is public, false if it's static random */
00052     uint8_t peer_address_is_public:1;
00053     /** true if local address is public, false if it's static random */
00054     uint8_t local_address_is_public:1;
00055 
00056     /** CSRK (Connection Signature Resolving Key) has been distributed and stored */
00057     uint8_t csrk_stored:1;
00058     /** CSRK that is stored has MITM protection */
00059     uint8_t csrk_mitm_protected:1;
00060     /** LTK (Long Term Key) has been distributed and stored */
00061     uint8_t ltk_stored:1;
00062     /** LTK that is stored has MITM protection */
00063     uint8_t ltk_mitm_protected:1;
00064     /** the current pairing was done using Secure Connections */
00065     uint8_t secure_connections_paired:1;
00066 };
00067 
00068 /** Long Term Key and data used to identify it */
00069 struct SecurityEntryKeys_t {
00070     /** Long Term Key */
00071     ltk_t ltk;
00072     /** EDIV (Encryption diversifier) used to identify LTK during legacy pairing */
00073     ediv_t ediv;
00074     /** Rand (random number) used to identify LTK during legacy pairing */
00075     rand_t rand;
00076 };
00077 
00078 /** Data for resolving random resolvable addresses */
00079 struct SecurityEntryIdentity_t {
00080     /** identity address */
00081     address_t identity_address;
00082     /** Identity Resolving Key */
00083     irk_t irk;
00084 };
00085 
00086 /**
00087  * SecurityDb holds the state for active connections and bonded devices.
00088  * Keys can be stored in NVM and are returned via callbacks.
00089  * SecurityDb is responsible for serialising any requests and keeping
00090  * the store in a consistent state.
00091  * Active connections state must be returned immediately.
00092  */
00093 class SecurityDb {
00094 public:
00095     /**
00096      * Opaque type representing a handle to a database entry.
00097      */
00098     typedef void* entry_handle_t;
00099 
00100     /* callbacks for asynchronous data retrieval from the security db */
00101 
00102     typedef mbed::Callback<void(entry_handle_t, const SecurityEntryKeys_t*)>
00103         SecurityEntryKeysDbCb_t;
00104     typedef mbed::Callback<void(entry_handle_t, const csrk_t*)>
00105         SecurityEntryCsrkDbCb_t;
00106     typedef mbed::Callback<void(::Gap::Whitelist_t*)>
00107         WhitelistDbCb_t;
00108 
00109     SecurityDb() { };
00110     virtual ~SecurityDb() { };
00111 
00112     /**
00113      * Return immediately security flags associated to a db entry.
00114      *
00115      * @param[in] db_entry Entry of the database queried.
00116      * @return pointer to the flags or NULL if the entry do not have any
00117      * associated flags.
00118      */
00119     virtual const SecurityDistributionFlags_t* get_distribution_flags(
00120         entry_handle_t db_entry
00121     ) = 0;
00122 
00123     /**
00124      * Set the distribution flags of a DB entry.
00125      *
00126      * @param[in] db_entry Entry of the database that will store the flags.
00127      * @param[in] flags Distribution flags to store in @p db_entry.
00128      */
00129     virtual void set_distribution_flags(
00130         entry_handle_t db_entry,
00131         const SecurityDistributionFlags_t& flags
00132     ) = 0;
00133 
00134     /* local keys */
00135 
00136     /**
00137      * Retrieve stored LTK based on passed in EDIV and RAND values.
00138      *
00139      * @param[in] cb callback that will receive the LTK struct
00140      * @param[in] db_entry handle of the entry being queried.
00141      * @param[in] ediv one of the values used to identify the LTK
00142      * @param[in] rand one of the values used to identify the LTK
00143      */
00144     virtual void get_entry_local_keys(
00145         SecurityEntryKeysDbCb_t cb,
00146         entry_handle_t db_entry,
00147         const ediv_t &ediv,
00148         const rand_t &rand
00149     ) = 0;
00150 
00151     /**
00152      * Retrieve stored LTK generated during secure connections pairing.
00153      *
00154      * @param[in] cb callback that will receive the LTK struct
00155      * @param[in] db_entry handle of the entry being queried.
00156      */
00157     virtual void get_entry_local_keys(
00158         SecurityEntryKeysDbCb_t cb,
00159         entry_handle_t db_entry
00160     ) = 0;
00161 
00162     /**
00163      * Save new local LTK for a connection.
00164      *
00165      * @param[in] db_entry handle of the entry being updated.
00166      * @param[in] ltk the new LTK, if the device is slave, this is the LTK that
00167      * will be used when link is encrypted
00168      */
00169     virtual void set_entry_local_ltk(
00170         entry_handle_t db_entry,
00171         const ltk_t &ltk
00172     ) = 0;
00173 
00174     /**
00175      * Update EDIV and RAND used to identify the LTK.
00176      *
00177      * @param[in] db_entry handle of the entry being updated.
00178      * @param[in] ediv new EDIV value
00179      * @param[in] rand new RAND value
00180      */
00181     virtual void set_entry_local_ediv_rand(
00182         entry_handle_t db_entry,
00183         const ediv_t &ediv,
00184         const rand_t &rand
00185     ) = 0;
00186 
00187     /* peer's keys */
00188 
00189     /**
00190      * Return asynchronously the peer signing key through a callback
00191      * so that signed packets can be verified.
00192      *
00193      * @param[in] cb callback which will receive the key
00194      * @param[in] db_entry handle of the entry being queried.
00195      */
00196     virtual void get_entry_peer_csrk(
00197         SecurityEntryCsrkDbCb_t cb,
00198         entry_handle_t db_entry
00199     ) = 0;
00200 
00201     /**
00202      * Return asynchronously the peer encryption key through a callback
00203      * so that encryption can be enabled.
00204      *
00205      * @param[in] cb callback which will receive the key
00206      * @param[in] db_entry handle of the entry being queried.
00207      */
00208     virtual void get_entry_peer_keys(
00209         SecurityEntryKeysDbCb_t cb,
00210         entry_handle_t db_entry
00211     ) = 0;
00212 
00213     /**
00214      * Save new LTK received from the peer.
00215      *
00216      * @param[in] db_entry handle of the entry being updated.
00217      * @param[in] ltk the new LTK, if the peer device is slave, this is the LTK
00218      * that will be used when link is encrypted
00219      */
00220     virtual void set_entry_peer_ltk(
00221         entry_handle_t db_entry,
00222         const ltk_t &ltk
00223     ) = 0;
00224 
00225     /**
00226      * Update EDIV and RAND used to identify the LTK sent by the peer.
00227      *
00228      * @param[in] db_entry handle of the entry being updated.
00229      * @param[in] ediv new EDIV value
00230      * @param[in] rand new RAND value
00231      */
00232     virtual void set_entry_peer_ediv_rand(
00233         entry_handle_t db_entry,
00234         const ediv_t &ediv,
00235         const rand_t &rand
00236     ) = 0;
00237 
00238     /**
00239      * Update IRK for this connection.
00240      *
00241      * @param[in] db_entry handle of the entry being updated.
00242      * @param[in] irk new IRK value
00243      */
00244     virtual void set_entry_peer_irk(
00245         entry_handle_t db_entry,
00246         const irk_t &irk
00247     ) = 0;
00248 
00249     /**
00250      * Update the identity address of the peer.
00251      *
00252      * @param[in] db_entry handle of the entry being updated.
00253      * @param[in] address_is_public is the identity address public or private
00254      * @param[in] peer_address the new address
00255      */
00256     virtual void set_entry_peer_bdaddr(
00257         entry_handle_t db_entry,
00258         bool address_is_public,
00259         const address_t &peer_address
00260     ) = 0;
00261 
00262     /**
00263      * Update peer signing key.
00264      *
00265      * @param[in] db_entry handle of the entry being updated.
00266      * @param[in] csrk new CSRK value
00267      */
00268     virtual void set_entry_peer_csrk(
00269         entry_handle_t db_entry,
00270         const csrk_t &csrk
00271     ) = 0;
00272 
00273     /* local csrk */
00274 
00275     /**
00276      * Return local signing key used for signing packets.
00277      *
00278      * @return pointer to local CSRK
00279      */
00280     virtual const csrk_t* get_local_csrk() = 0;
00281 
00282     /**
00283      * Update local signing key.
00284      *
00285      * @param[in] csrk new CSRK value
00286      */
00287     virtual void set_local_csrk(const csrk_t &csrk) = 0;
00288 
00289     /* public keys */
00290 
00291     /**
00292      * Return local public key.
00293      *
00294      * @return ref to x component of public key
00295      */
00296     virtual const public_key_coord_t& get_public_key_x() = 0;
00297 
00298     /**
00299      * Return local public key.
00300      *
00301      * @return ref to y component of public key
00302      */
00303     virtual const public_key_coord_t& get_public_key_y() = 0;
00304 
00305     /**
00306      * Set local public key.
00307      *
00308      * @param[in] public_key_x new public key value of the x coordinate
00309      * @param[in] public_key_y new public key value of the y coordinate
00310      */
00311     virtual void set_public_key(
00312         const public_key_coord_t &public_key_x,
00313         const public_key_coord_t &public_key_y
00314     ) = 0;
00315 
00316     /* list management */
00317 
00318     /**
00319      * Open a database entry.
00320      *
00321      * While this entry is opened; it can be queried and updated with the help
00322      * of the database setter and getter functions.
00323      *
00324      * @param[in] peer_address_type type of address
00325      * @param[in] peer_address this address will be used to locate an existing
00326      * entry.
00327      *
00328      * @return A handle to the entry.
00329      */
00330     virtual entry_handle_t open_entry(
00331         BLEProtocol::AddressType_t peer_address_type,
00332         const address_t &peer_address
00333     ) = 0;
00334 
00335     /**
00336      * Close a connection entry.
00337      *
00338      * @param[in] db_entry this handle will be freed up from the security db.
00339      */
00340     virtual void close_entry(entry_handle_t db_entry) = 0;
00341 
00342     /**
00343      * Remove entry for this peer from NVM.
00344      *
00345      * @param[in] peer_identity_address peer address that no longer needs NVM
00346      * storage.
00347      */
00348     virtual void remove_entry(const address_t peer_identity_address) = 0;
00349 
00350     /**
00351      * Remove all entries from the security DB.
00352      */
00353     virtual void clear_entries() = 0;
00354 
00355     /**
00356      * Asynchronously return the whitelist stored in NVM through a callback.
00357      * Function takes ownership of the memory. The whitelist and the ownership
00358      * will be returned in the callback.
00359      *
00360      * @param[in] cb callback that will receive the whitelist
00361      * @param[in] whitelist preallocated whitelist that will be filled in
00362      */
00363     virtual void get_whitelist(
00364         WhitelistDbCb_t cb,
00365         ::Gap::Whitelist_t *whitelist
00366     ) = 0;
00367 
00368     /**
00369      * Asynchronously return a whitelist through a callback, generated from the
00370      * bond table.
00371      *
00372      * @param[in] cb callback that will receive the whitelist
00373      * @param[in] whitelist preallocated whitelist that will be filled in
00374      */
00375     virtual void generate_whitelist_from_bond_table(
00376         WhitelistDbCb_t cb,
00377         ::Gap::Whitelist_t *whitelist
00378     ) = 0;
00379 
00380     /**
00381      * Update the whitelist stored in NVM by replacing it with new one.
00382      *
00383      * @param[in] whitelist
00384      */
00385     virtual void set_whitelist(const ::Gap::Whitelist_t &whitelist) = 0;
00386 
00387     /**
00388      * Add a new entry to the whitelist in the NVM.
00389      *
00390      * @param[in] address new whitelist entry
00391      */
00392     virtual void add_whitelist_entry(const address_t &address) = 0;
00393 
00394     /**
00395      * Remove whitelist entry from NVM.
00396      *
00397      * @param[in] address entry to be removed
00398      */
00399     virtual void remove_whitelist_entry(const address_t &address) = 0;
00400 
00401     /**
00402      *Remove all whitelist entries stored in the NVM.
00403      */
00404     virtual void clear_whitelist() = 0;
00405 
00406     /* saving and loading from nvm */
00407 
00408     /**
00409      * Read values from storage.
00410      */
00411     virtual void restore() = 0;
00412 
00413     /**
00414      * Flush all values which might be stored in memory into NVM.
00415      */
00416     virtual void sync() = 0;
00417 
00418     /**
00419      * Toggle whether values should be preserved across resets.
00420      *
00421      * @param[in] reload if true values will be preserved across resets.
00422      */
00423     virtual void set_restore(bool reload) = 0;
00424 };
00425 
00426 } /* namespace pal */
00427 } /* namespace ble */
00428 
00429 #endif /*PAL_SECURITY_MANAGER_DB_H__*/