ssi_util_key_derivation.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107
  1. /**************************************************************************************
  2. * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
  3. * *
  4. * This file and the related binary are licensed under the following license: *
  5. * *
  6. * ARM Object Code and Header Files License, v1.0 Redistribution. *
  7. * *
  8. * Redistribution and use of object code, header files, and documentation, without *
  9. * modification, are permitted provided that the following conditions are met: *
  10. * *
  11. * 1) Redistributions must reproduce the above copyright notice and the *
  12. * following disclaimer in the documentation and/or other materials *
  13. * provided with the distribution. *
  14. * *
  15. * 2) Unless to the extent explicitly permitted by law, no reverse *
  16. * engineering, decompilation, or disassembly of is permitted. *
  17. * *
  18. * 3) Redistribution and use is permitted solely for the purpose of *
  19. * developing or executing applications that are targeted for use *
  20. * on an ARM-based product. *
  21. * *
  22. * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
  23. * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
  24. * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
  25. * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
  26. * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
  27. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
  28. * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
  29. * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
  30. * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
  31. * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
  32. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
  33. **************************************************************************************/
  34. #ifndef _SSI_UTIL_KEY_DERIVATION_H
  35. #define _SSI_UTIL_KEY_DERIVATION_H
  36. /*!
  37. @file
  38. @brief This module defines the API that supports Key derivation function as specified
  39. in [SP800-108] in section "KDF in Counter Mode".
  40. @defgroup ssi_utils_key_derivation CryptoCell utility key derivation APIs
  41. @{
  42. @ingroup ssi_utils
  43. */
  44. #ifdef __cplusplus
  45. extern "C"
  46. {
  47. #endif
  48. #include "ssi_util_defs.h"
  49. #include "ssi_util_key_derivation_defs.h"
  50. #include "ssi_aes.h"
  51. /******************************************************************************
  52. * DEFINITIONS
  53. ******************************************************************************/
  54. /*! Input key derivation type. */
  55. typedef enum {
  56. /*! User's key.*/
  57. SASI_UTIL_USER_KEY = 0,
  58. /*! Root key (Kdr).*/
  59. SASI_UTIL_ROOT_KEY = 1,
  60. /*! Reserved.*/
  61. SASI_UTIL_END_OF_KEY_TYPE = 0x7FFFFFFF
  62. }SaSiUtilKeyType_t;
  63. /*!
  64. @brief The key derivation function is as specified in [SP800-108] in section "KDF in Counter Mode".
  65. The derivation is based on length l, label L, context C and derivation key Ki.
  66. AES-CMAC is used as the pseudorandom function (PRF).
  67. @return SASI_UTIL_OK on success.
  68. @return A non-zero value from ssi_util_error.h on failure.
  69. */
  70. /* A key derivation functions can iterates n times until l bits of keying material are generated.
  71. For each of the iteration of the PRF, i=1 to n, do:
  72. result(0) = 0;
  73. K(i) = PRF (Ki, [i] || Label || 0x00 || Context || length);
  74. results(i) = result(i-1) || K(i);
  75. concisely, result(i) = K(i) || k(i-1) || .... || k(0)*/
  76. SaSiUtilError_t SaSi_UtilKeyDerivation(
  77. SaSiUtilKeyType_t keyType, /*!< [in] The key type that is used as an input to a key derivation function.
  78. Can be one of: SASI_UTIL_USER_KEY or SASI_UTIL_ROOT_KEY. */
  79. SaSiAesUserKeyData_t *pUserKey, /*!< [in] A pointer to the user's key buffer (in case of SASI_UTIL_USER_KEY). */
  80. const uint8_t *pLabel, /*!< [in] A string that identifies the purpose for the derived keying material.*/
  81. size_t labelSize, /*!< [in] The label size should be in range of 1 to 64 bytes length. */
  82. const uint8_t *pContextData, /*!< [in] A binary string containing the information related to the derived keying material. */
  83. size_t contextSize, /*!< [in] The context size should be in range of 1 to 64 bytes length. */
  84. uint8_t *pDerivedKey, /*!< [out] Keying material output (MUST be atleast the size of derivedKeySize). */
  85. size_t derivedKeySize /*!< [in] Size of the derived keying material in bytes (limited to 4080 bytes). */
  86. );
  87. #ifdef __cplusplus
  88. }
  89. #endif
  90. /**
  91. @}
  92. */
  93. #endif /*_SSI_UTIL_KEY_DERIVATION_H*/