sec_prot_keys.h

00001 /*
00002  * Copyright (c) 2016-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef SEC_PROT_KEYS_H_
00019 #define SEC_PROT_KEYS_H_
00020 
00021 /*
00022  * Security protocols EAPOL key storage module. This is used by EAPOL protocols to store
00023  * and update key information. This can be used either as supplicant key storage or as
00024  * an authenticator key storage for a specific supplicant. Storage can be also used to
00025  * access global security data (Group Transient Keys and certificate information).
00026  *
00027  */
00028 
00029 #define PMK_LEN                 32
00030 #define PTK_LEN                 48
00031 #define GTK_LEN                 16
00032 #define GTK_NUM                 4
00033 
00034 #define KCK_LEN                 16
00035 #define KEK_LEN                 16
00036 
00037 #define KCK_INDEX               0
00038 #define KEK_INDEX               16
00039 
00040 #define PMKID_LEN               16
00041 #define PTKID_LEN               16
00042 #define KEYID_LEN               16
00043 
00044 #define GTK_DEFAULT_LIFETIME      60 * 60 * 24 * 30       // 30 days
00045 #define GTK_EXPIRE_MISMATCH_TIME  60                      // Supplicant GTK expire time mismatch occurs if GTK expires before this time
00046 
00047 #define GTK_STATUS_NEW            0                       // New GTK, can transition to fresh
00048 #define GTK_STATUS_FRESH          1                       // Fresh GTK, live based on hash, can transition to active
00049 #define GTK_STATUS_ACTIVE         2                       // Active GTK, live based on hash, can transition to old
00050 #define GTK_STATUS_OLD            3                       // Old GTK, not to be used for sending
00051 
00052 #define GTK_INSTALL_ORDER_FIRST   0                       // Install order runs from 0 to 3, where 0 is the GTK to be installed first
00053 #define GTK_INSTALL_ORDER_SECOND  1                       // Install order runs from 0 to 3, where 1 is the GTK to be installed second
00054 
00055 #define GTK_HASH_LEN              8
00056 #define GTK_ALL_HASHES_LEN        GTK_HASH_LEN * GTK_NUM
00057 
00058 #define PMK_LIFETIME_INSTALL      0xFFFFF
00059 #define PTK_LIFETIME_INSTALL      0xFFFFF
00060 
00061 typedef struct {
00062     uint8_t                key[GTK_LEN];              /**< Group Transient Key (128 bits) */
00063     uint32_t               lifetime;                  /**< GTK lifetime in seconds */
00064     unsigned               status : 2;                /**< Group Transient Key status */
00065     unsigned               install_order : 2;         /**< Order in which GTK keys are added */
00066     bool                   set: 1;                    /**< Group Transient Key set (valid value) */
00067 } gtk_key_t;
00068 
00069 typedef struct {
00070     gtk_key_t              gtk[GTK_NUM];              /**< 4 Group Transient Keys */
00071     bool                   updated: 1;                /**< Group Transient Keys has been updated */
00072 } sec_prot_gtk_keys_t;
00073 
00074 // Security key data
00075 typedef struct {
00076     uint64_t               pmk_key_replay_cnt;        /**< Pairwise Master Key replay counter */
00077     uint8_t                pmk[PMK_LEN];              /**< Pairwise Master Key (256 bits) */
00078     uint8_t                ptk[PTK_LEN];              /**< Pairwise Transient Key (384 bits) */
00079     uint8_t                ptk_eui_64[8];             /**< Remote EUI-64 used to derive PTK or NULL */
00080     sec_prot_gtk_keys_t    *gtks;                     /**< Group Transient Keys */
00081     const sec_prot_certs_t *certs;                    /**< Certificates */
00082     uint32_t               pmk_lifetime;              /**< PMK lifetime in seconds */
00083     uint32_t               ptk_lifetime;              /**< PTK lifetime in seconds */
00084     uint8_t                gtkl;                      /**< Remote GTKL information */
00085     int8_t                 gtk_set_index;             /**< Index of GTK to set */
00086     bool                   pmk_set: 1;                /**< Pairwise Master Key set */
00087     bool                   ptk_set: 1;                /**< Pairwise Transient Key set */
00088     bool                   pmk_key_replay_cnt_set: 1; /**< Pairwise Master Key replay counter set */
00089     bool                   updated: 1;                /**< Keys has been updated */
00090     bool                   ptk_eui_64_set: 1;         /**< Remote EUI-64 used to derive PTK is set */
00091     bool                   pmk_mismatch: 1;           /**< Remote PMK mismatch reported */
00092     bool                   ptk_mismatch: 1;           /**< Remote PTK mismatch reported */
00093 } sec_prot_keys_t;
00094 
00095 // Frame counter data
00096 typedef struct {
00097     uint8_t gtk[GTK_LEN];                             /**< GTK of the frame counter */
00098     uint32_t frame_counter;                           /**< Frame counter */
00099     bool set : 1;                                     /**< Value has been set */
00100 } frame_counter_t;
00101 
00102 typedef struct {
00103     frame_counter_t counter[GTK_NUM];                 /**< Frame counter for each GTK key */
00104 } frame_counters_t;
00105 
00106 /*
00107  * GTK mismatch types, list is ordered according to priority of mismatch i.e. if there
00108  * are both hash and lifetime mismatch, hash has greater priority
00109  */
00110 typedef enum {
00111     GTK_NO_MISMATCH = 0,
00112     GTK_LIFETIME_MISMATCH,
00113     GTK_HASH_MISMATCH,
00114 } gtk_mismatch_e;
00115 
00116 /**
00117  * sec_prot_keys_create allocates memory for security keys
00118  *
00119  * \param gtks GTK keys
00120  * \param cert_chain certificates
00121  *
00122  * \return security keys or NULL
00123  */
00124 sec_prot_keys_t *sec_prot_keys_create(sec_prot_gtk_keys_t *gtks, const sec_prot_certs_t *certs);
00125 
00126 /**
00127  * sec_prot_keys_init initialises security keys
00128  *
00129  * \param sec_keys security keys
00130  * \param gtks GTK keys
00131  * \param cert_chain certificates
00132  *
00133  */
00134 void sec_prot_keys_init(sec_prot_keys_t *sec_keys, sec_prot_gtk_keys_t *gtks, const sec_prot_certs_t *certs);
00135 
00136 /**
00137  * sec_prot_keys_delete frees security keys memory
00138  *
00139  * \param sec_keys security keys
00140  *
00141  */
00142 void sec_prot_keys_delete(sec_prot_keys_t *sec_keys);
00143 
00144 /**
00145  * sec_prot_keys_gtks_create allocates memory for GTK keys
00146  *
00147  * \return GTK keys or NULL
00148  *
00149  */
00150 sec_prot_gtk_keys_t *sec_prot_keys_gtks_create(void);
00151 
00152 /**
00153  * sec_prot_keys_gtks_init initialises GTK keys
00154  *
00155  * \param gtks GTK keys
00156  *
00157  */
00158 void sec_prot_keys_gtks_init(sec_prot_gtk_keys_t *gtks);
00159 
00160 /**
00161  * sec_prot_keys_gtks_delete frees GTK keys memory
00162  *
00163  * \param gtks GTK keys
00164  *
00165  */
00166 void sec_prot_keys_gtks_delete(sec_prot_gtk_keys_t *gtks);
00167 
00168 /**
00169  * sec_prot_keys_pmk_write writes Pairwise Master Key
00170  *
00171  * \param sec_keys security keys
00172  * \param pmk Pairwise Master Key
00173  *
00174  */
00175 void sec_prot_keys_pmk_write(sec_prot_keys_t *sec_keys, uint8_t *pmk);
00176 
00177 /**
00178  * sec_prot_keys_pmk_delete deletes PMK
00179  *
00180  * \param sec_keys security keys
00181  *
00182  */
00183 void sec_prot_keys_pmk_delete(sec_prot_keys_t *sec_keys);
00184 
00185 /**
00186  * sec_prot_keys_pmk_get gets Pairwise Master Key
00187  *
00188  * \param sec_keys security keys
00189  *
00190  * \return PMK or NULL
00191  *
00192  */
00193 uint8_t *sec_prot_keys_pmk_get(sec_prot_keys_t *sec_keys);
00194 
00195 /**
00196  * sec_prot_keys_pmk_replay_cnt_get gets PMK replay counter value
00197  *
00198  * \param sec_keys security keys
00199  *
00200  * \return replay counter value
00201  *
00202  */
00203 uint64_t sec_prot_keys_pmk_replay_cnt_get(sec_prot_keys_t *sec_keys);
00204 
00205 /**
00206  * sec_prot_keys_pmk_replay_cnt_set sets PMK replay counter value
00207  *
00208  * \param sec_keys security keys
00209  * \param counter new value for replay counter
00210  *
00211  */
00212 void sec_prot_keys_pmk_replay_cnt_set(sec_prot_keys_t *sec_keys, uint64_t counter);
00213 
00214 /**
00215  * sec_prot_keys_pmk_replay_cnt_increment increments PMK replay counter value by one
00216  *
00217  * \param sec_keys security keys
00218  *
00219  */
00220 void sec_prot_keys_pmk_replay_cnt_increment(sec_prot_keys_t *sec_keys);
00221 
00222 /**
00223  * sec_prot_keys_pmk_replay_cnt_compare compares received replay counter value to PMK replay counter
00224  *
00225  * \param received_counter received replay counter
00226  * \param sec_keys security keys
00227  *
00228  * \return TRUE received replay counter is valid
00229  * \return FALSE received replay counter is not valid
00230  *
00231  */
00232 bool sec_prot_keys_pmk_replay_cnt_compare(uint64_t received_counter, sec_prot_keys_t *sec_keys);
00233 
00234 /**
00235  * sec_prot_keys_pmk_mismatch_set set PMK mismatch
00236  *
00237  * \param sec_keys security keys
00238  *
00239  */
00240 void sec_prot_keys_pmk_mismatch_set(sec_prot_keys_t *sec_keys);
00241 
00242 /**
00243  * sec_prot_keys_pmk_mismatch_reset reset PMK mismatch
00244  *
00245  * \param sec_keys security keys
00246  *
00247  */
00248 void sec_prot_keys_pmk_mismatch_reset(sec_prot_keys_t *sec_keys);
00249 
00250 /**
00251  * sec_prot_keys_pmk_mismatch_is_set check if PMK mismatch is set
00252  *
00253  * \param sec_keys security keys
00254  *
00255  * \return TRUE or FALSE
00256  *
00257  */
00258 bool sec_prot_keys_pmk_mismatch_is_set(sec_prot_keys_t *sec_keys);
00259 
00260 /**
00261  * sec_prot_keys_pmk_lifetime_decrement decrements PMK lifetime
00262  *
00263  * \param sec_keys security keys
00264  * \param default_lifetime default lifetime for PMK
00265  * \param seconds elapsed seconds
00266  *
00267  * \return true PMK expired and deleted both PMK and PTK
00268  * \return false PMK not expired
00269  *
00270  */
00271 bool sec_prot_keys_pmk_lifetime_decrement(sec_prot_keys_t *sec_keys, uint32_t default_lifetime, uint8_t seconds);
00272 
00273 /**
00274  * sec_prot_keys_ptk_write writes Pairwise Transient Key
00275  *
00276  * \param sec_keys security keys
00277  * \param ptk Pairwise Transient Key
00278  *
00279  */
00280 void sec_prot_keys_ptk_write(sec_prot_keys_t *sec_keys, uint8_t *ptk);
00281 
00282 /**
00283  * sec_prot_keys_ptk_delete deletes PTK
00284  *
00285  * \param sec_keys security keys
00286  *
00287  */
00288 void sec_prot_keys_ptk_delete(sec_prot_keys_t *sec_keys);
00289 
00290 /**
00291  * sec_prot_keys_ptk_get gets Pairwise Transient Key
00292  *
00293  * \param sec_keys security keys
00294  *
00295  * \return PTK or NULL
00296  *
00297  */
00298 uint8_t *sec_prot_keys_ptk_get(sec_prot_keys_t *sec_keys);
00299 
00300 /**
00301  * sec_prot_keys_ptk_mismatch_set set PTK mismatch
00302  *
00303  * \param sec_keys security keys
00304  *
00305  */
00306 void sec_prot_keys_ptk_mismatch_set(sec_prot_keys_t *sec_keys);
00307 
00308 /**
00309  * sec_prot_keys_ptk_mismatch_reset reset PTK mismatch
00310  *
00311  * \param sec_keys security keys
00312  *
00313  */
00314 void sec_prot_keys_ptk_mismatch_reset(sec_prot_keys_t *sec_keys);
00315 
00316 /**
00317  * sec_prot_keys_ptk_mismatch_is_set check if PTK mismatch is set
00318  *
00319  * \param sec_keys security keys
00320  *
00321  * \return TRUE or FALSE
00322  *
00323  */
00324 bool sec_prot_keys_ptk_mismatch_is_set(sec_prot_keys_t *sec_keys);
00325 
00326 /**
00327  * sec_prot_keys_ptk_eui_64_write writes PTK EUI-64
00328  *
00329  * \param sec_keys security keys
00330  * \param eui64 EUI-64
00331  *
00332  */
00333 void sec_prot_keys_ptk_eui_64_write(sec_prot_keys_t *sec_keys, const uint8_t *eui_64);
00334 
00335 /**
00336  * sec_prot_keys_ptk_eui_64_get gets PTK EUI-64
00337  *
00338  * \param sec_keys security keys
00339  *
00340  * \return EUI-64 OR NULL
00341  *
00342  */
00343 uint8_t *sec_prot_keys_ptk_eui_64_get(sec_prot_keys_t *sec_keys);
00344 
00345 /**
00346  * sec_prot_keys_ptk_eui_64_delete deletes PTK EUI-64
00347  *
00348  * \param sec_keys security keys
00349  *
00350  */
00351 void sec_prot_keys_ptk_eui_64_delete(sec_prot_keys_t *sec_keys);
00352 
00353 /**
00354  * sec_prot_keys_ptk_lifetime_decrement decrements PTK lifetime
00355  *
00356  * \param sec_keys security keys
00357  * \param default_lifetime default lifetime for PTK
00358  * \param seconds elapsed seconds
00359  *
00360  * \return true PTK expired and deleted
00361  * \return false PTK not expired
00362  *
00363  */
00364 bool sec_prot_keys_ptk_lifetime_decrement(sec_prot_keys_t *sec_keys, uint32_t default_lifetime, uint8_t seconds);
00365 
00366 /**
00367  * sec_prot_keys_are_updated returns security keys have been updated flag
00368  *
00369  * \param sec_keys security keys
00370  *
00371  * \return TRUE keys have been updated, FALSE keys have not been updated
00372  *
00373  */
00374 bool sec_prot_keys_are_updated(sec_prot_keys_t *sec_keys);
00375 
00376 /**
00377  * sec_prot_keys_updated_reset resets security keys have been updated flag
00378  *
00379  * \param sec_keys security keys
00380  *
00381  */
00382 void sec_prot_keys_updated_reset(sec_prot_keys_t *sec_keys);
00383 
00384 /**
00385  * sec_prot_keys_fresh_gtkl_get gets GTK liveness based on GTK status fields
00386  *
00387  * \param gtks GTK keys
00388  *
00389  * \return bit field indicating GTK liveness
00390  *
00391  */
00392 uint8_t sec_prot_keys_fresh_gtkl_get(sec_prot_gtk_keys_t *gtks);
00393 
00394 /**
00395  * sec_prot_keys_gtkl_set sets GTK liveness storage
00396  *
00397  * \param sec_keys security keys
00398  * \param gtkl bit field indicating GTK liveness
00399  *
00400  */
00401 void sec_prot_keys_gtkl_set(sec_prot_keys_t *sec_keys, uint8_t gtkl);
00402 
00403 /**
00404  * sec_prot_keys_gtkl_set checks whether GTK is live on GTK liveness storage
00405  *
00406  * \param sec_keys security keys
00407  * \param index index of the GTK which liveness is returned
00408  *
00409  * \return TRUE GTK is live, FALSE GTK is not live
00410  *
00411  */
00412 bool sec_prot_keys_gtkl_gtk_is_live(sec_prot_keys_t *sec_keys, uint8_t index);
00413 
00414 /**
00415  * sec_prot_keys_gtkl_gtk_live_set sets that GTK is live to GTK liveness storage
00416  *
00417  * \param sec_keys security keys
00418  * \param index index of the GTK which is set live
00419  *
00420  * \return < 0 failure
00421  * \return >= 0 success
00422  *
00423  */
00424 int8_t sec_prot_keys_gtkl_gtk_live_set(sec_prot_keys_t *sec_keys, uint8_t index);
00425 
00426 /**
00427  * sec_prot_keys_gtk_insert_index_set sets index of GTK to be inserted
00428  *
00429  * \param sec_keys security keys
00430  * \param index GTK index
00431  *
00432  * \return < 0 failure
00433  * \return >= 0 success
00434  *
00435  */
00436 int8_t sec_prot_keys_gtk_insert_index_set(sec_prot_keys_t *sec_keys, uint8_t index);
00437 
00438 /**
00439  * sec_prot_keys_gtk_insert_index_get gets index of GTK to be inserted
00440  *
00441  * \param sec_keys security keys
00442  *
00443  * \return >= 0 GTK index
00444  * \return < 0 no GTK to be inserted
00445  *
00446  */
00447 int8_t sec_prot_keys_gtk_insert_index_get(sec_prot_keys_t *sec_keys);
00448 
00449 /**
00450  * sec_prot_keys_gtk_insert_index_clear clears the index of GTK to be inserted
00451  *
00452  * \param sec_keys security keys
00453  *
00454  */
00455 void sec_prot_keys_gtk_insert_index_clear(sec_prot_keys_t *sec_keys);
00456 
00457 /**
00458  * sec_prot_keys_gtkl_from_gtk_insert_index_set sets inserted GTK as live to GTK liveness storage
00459  *
00460  * \param sec_keys security keys
00461  *
00462  */
00463 void sec_prot_keys_gtkl_from_gtk_insert_index_set(sec_prot_keys_t *sec_keys);
00464 
00465 /**
00466  * sec_prot_keys_gtk_insert_index_from_gtkl_get gets inserted GTK based on GTK liveness storage
00467  *
00468  * \param sec_keys security keys
00469  *
00470  * \return >= 0 GTK index
00471  * \return < 0 no GTK to be inserted
00472  *
00473  */
00474 int8_t sec_prot_keys_gtk_insert_index_from_gtkl_get(sec_prot_keys_t *sec_keys);
00475 
00476 /**
00477  * sec_prot_keys_get_gtk_to_insert gets GTK that is marked to be inserted
00478  *
00479  * \param sec_keys security keys
00480  * \param index index of the returned GTK
00481  *
00482  * \return GTK or NULL
00483  *
00484  */
00485 uint8_t *sec_prot_keys_get_gtk_to_insert(sec_prot_keys_t *sec_keys, uint8_t *index);
00486 
00487 /**
00488  * sec_prot_keys_gtk_set sets Group Transient Key
00489  *
00490  * \param gtks GTK keys
00491  * \param index index
00492  * \param gtk gtk value
00493  * \param lifetime GTK lifetime
00494  *
00495  * \return < 0 failure
00496  * \return >= 0 success
00497  *
00498  */
00499 int8_t sec_prot_keys_gtk_set(sec_prot_gtk_keys_t *gtks, uint8_t index, uint8_t *gtk, uint32_t lifetime);
00500 
00501 /**
00502  * sec_prot_keys_gtk_clear clears Group Transient Key
00503  *
00504  * \param gtks GTK keys
00505  * \param index index
00506  *
00507  * \return < 0 failure
00508  * \return >= 0 success
00509  *
00510  */
00511 int8_t sec_prot_keys_gtk_clear(sec_prot_gtk_keys_t *gtks, uint8_t index);
00512 
00513 /**
00514  * sec_prot_keys_gtk_is_set checks if Group Transient Key is set
00515  *
00516  * \param gtks GTK keys
00517  * \param index index
00518  *
00519  * \return TRUE GTK is set, FALSE GTK is not set
00520  *
00521  */
00522 bool sec_prot_keys_gtk_is_set(sec_prot_gtk_keys_t *gtks, uint8_t index);
00523 
00524 /**
00525  * sec_prot_keys_gtk_gets gets Group Transient Key
00526  *
00527  * \param gtks GTK keys
00528  * \param index index
00529  *
00530  * \return GTK or NULL
00531  *
00532  */
00533 uint8_t *sec_prot_keys_gtk_get(sec_prot_gtk_keys_t *gtks, uint8_t index);
00534 
00535 /**
00536  * sec_prot_keys_gtk_lifetime_get gets GTK lifetime
00537  *
00538  * \param gtks GTK keys
00539  * \param index index
00540  *
00541  * \return GTK lifetime
00542  *
00543  */
00544 uint32_t sec_prot_keys_gtk_lifetime_get(sec_prot_gtk_keys_t *gtks, uint8_t index);
00545 
00546 /**
00547  * sec_prot_keys_gtk_lifetime_decrement decrements GTK lifetime
00548  *
00549  * \param gtks GTK keys
00550  * \param index index for GTK
00551  * \param seconds elapsed seconds
00552  *
00553  * \return new GTK lifetime
00554  *
00555  */
00556 uint32_t sec_prot_keys_gtk_lifetime_decrement(sec_prot_gtk_keys_t *gtks, uint8_t index, uint16_t seconds);
00557 
00558 /**
00559  * sec_prot_keys_gtks_are_updated returns GTKs have been updated flag
00560  *
00561  * \param gtks GTK keys
00562  *
00563  * \return TRUE GTKs have been updated, FALSE GTKs have not been updated
00564  *
00565  */
00566 bool sec_prot_keys_gtks_are_updated(sec_prot_gtk_keys_t *gtks);
00567 
00568 /**
00569  * sec_prot_keys_gtks_updated_set sets GTKs have been updated flag
00570  *
00571  * \param gtks GTK keys
00572  *
00573  *
00574  */
00575 void sec_prot_keys_gtks_updated_set(sec_prot_gtk_keys_t *gtks);
00576 
00577 /**
00578  * sec_prot_keys_gtks_updated_set resets GTKs have been updated flag
00579  *
00580  * \param gtks GTK keys
00581  *
00582  *
00583  */
00584 void sec_prot_keys_gtks_updated_reset(sec_prot_gtk_keys_t *gtks);
00585 
00586 /**
00587  * sec_prot_keys_gtk_status_fresh_set sets GTK as status fresh (if GTK status new)
00588  *
00589  * \param gtks GTK keys
00590  * \param index index
00591  *
00592  */
00593 void sec_prot_keys_gtk_status_fresh_set(sec_prot_gtk_keys_t *gtks, uint8_t index);
00594 
00595 /**
00596  * sec_prot_keys_gtk_status_fresh_set sets all GTK statuses fresh (if GTK status new)
00597  *
00598  * \param gtks GTK keys
00599  *
00600  */
00601 void sec_prot_keys_gtk_status_all_fresh_set(sec_prot_gtk_keys_t *gtks);
00602 
00603 /**
00604  * sec_prot_keys_gtk_status_active_set sets fresh GTK to active, and currently active as old
00605  *
00606  * \param gtks GTK keys
00607  * \param index index
00608  *
00609  * \return < 0 failure
00610  * \return >= 0 success
00611  *
00612  */
00613 int8_t sec_prot_keys_gtk_status_active_set(sec_prot_gtk_keys_t *gtks, uint8_t index);
00614 
00615 /**
00616  * sec_prot_keys_gtk_status_active_get gets active GTK
00617  *
00618  * \param gtks GTK keys
00619  *
00620  * \return >= 0 GTK index
00621  * \return < 0 no active GTK
00622  *
00623  */
00624 int8_t sec_prot_keys_gtk_status_active_get(sec_prot_gtk_keys_t *gtks);
00625 
00626 /**
00627  * sec_prot_keys_gtk_status_is_live checks whether GTK is active
00628  *
00629  * \param gtks GTK keys
00630  * \param index index
00631  *
00632  * \return TRUE active, FALSE non active
00633  *
00634  */
00635 bool sec_prot_keys_gtk_status_is_live(sec_prot_gtk_keys_t *gtks, uint8_t index);
00636 
00637 /**
00638  * sec_prot_keys_gtks_hash_generate generate GTK hash based on all GTKs
00639  *
00640  * \param gtks GTK keys
00641  * \param gtk_hash GTK hash
00642  *
00643  */
00644 void sec_prot_keys_gtks_hash_generate(sec_prot_gtk_keys_t *gtks, uint8_t *gtk_hash);
00645 
00646 /**
00647  * sec_prot_keys_gtk_hash_generate generate GTK hash for a GTK
00648  *
00649  * \param gtk GTK key
00650  * \param gtk_hash GTK hash for a GTK
00651  *
00652  */
00653 void sec_prot_keys_gtk_hash_generate(uint8_t *gtk, uint8_t *gtk_hash);
00654 
00655 /**
00656  * sec_prot_keys_gtks_hash_update update GTKs based on GTK hash
00657  *
00658  * \param gtks GTK keys
00659  * \param gtk_hash GTK hash
00660  *
00661  * \return GTK mismatch type or no mismatch
00662  *
00663  */
00664 gtk_mismatch_e sec_prot_keys_gtks_hash_update(sec_prot_gtk_keys_t *gtks, uint8_t *gtkhash);
00665 
00666 /**
00667  * sec_prot_keys_gtk_hash_empty checks if GTK hash field is empty
00668  *
00669  * \param gtk_hash GTK hash
00670  *
00671  * \return TRUE GTK hash is empty, FALSE GTK hash is set
00672  *
00673  */
00674 bool sec_prot_keys_gtk_hash_empty(uint8_t *gtkhash);
00675 
00676 /**
00677  * sec_prot_keys_gtk_install_order_last_get gets install order of the last GTK to be installd
00678  *
00679  * \param gtks GTK keys
00680  *
00681  * \return install order
00682  *
00683  */
00684 int8_t sec_prot_keys_gtk_install_order_last_get(sec_prot_gtk_keys_t *gtks);
00685 
00686 /**
00687  * sec_prot_keys_gtk_install_order_last_get gets GTK that is to be installed last
00688  *
00689  * \param gtks GTK keys
00690  *
00691  * \return GTK index
00692  *
00693  */
00694 int8_t sec_prot_keys_gtk_install_order_last_index_get(sec_prot_gtk_keys_t *gtks);
00695 
00696 /**
00697  * sec_prot_keys_gtk_install_order_last_lifetime_get gets lifetime of the GTK that is to be installed last
00698  *
00699  * \param gtks GTK keys
00700  *
00701  * \return lifetime
00702  *
00703  */
00704 uint32_t sec_prot_keys_gtk_install_order_last_lifetime_get(sec_prot_gtk_keys_t *gtks);
00705 
00706 /**
00707  * sec_prot_keys_gtk_install_order_first_index_get gets index of the GTK that is to be installed first
00708  *
00709  * \param gtks GTK keys
00710  *
00711  * \return GTK index
00712  *
00713  */
00714 int8_t sec_prot_keys_gtk_install_order_first_index_get(sec_prot_gtk_keys_t *gtks);
00715 
00716 /**
00717  * sec_prot_keys_gtk_install_order_second_index_get gets index of the GTK that is to be installed second first
00718  *
00719  * \param gtks GTK keys
00720  *
00721  * \return GTK index
00722  *
00723  */
00724 int8_t sec_prot_keys_gtk_install_order_second_index_get(sec_prot_gtk_keys_t *gtks);
00725 
00726 /**
00727  * sec_prot_keys_gtk_install_order_update updates install order (if GTKs are removed set the order back)
00728  *
00729  * \param gtks GTK keys
00730  *
00731  */
00732 void sec_prot_keys_gtk_install_order_update(sec_prot_gtk_keys_t *gtks);
00733 
00734 /**
00735  * sec_prot_keys_gtk_install_index_get gets a free index for GTK to be installed
00736  *
00737  * \param gtks GTK keys
00738  *
00739  * \return GTK index
00740  *
00741  */
00742 int8_t sec_prot_keys_gtk_install_index_get(sec_prot_gtk_keys_t *gtks);
00743 
00744 /**
00745  * sec_prot_keys_gtk_count counts GTK keys
00746  *
00747  * \param gtks GTK keys
00748  *
00749  * \return count of keys, 0 for no keys
00750  *
00751  */
00752 uint8_t sec_prot_keys_gtk_count(sec_prot_gtk_keys_t *gtks);
00753 
00754 #endif /* SEC_PROT_KEYS_H_ */