HSMLPF3Utility.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2024-2025, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 /*!****************************************************************************
34  * @file HSMLPF3Utility.h
35  *
36  * @brief Interface for helper functions for HSM-related operations
37  *
38  */
39 
42 #include <stdint.h>
43 
44 #include <ti/devices/DeviceFamily.h>
45 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
46  #include DeviceFamily_constructPath(driverlib/aes.h)
47 #endif
48 
49 /* Defines */
50 #define HSM_ASYM_DATA_VHEADER (4U)
51 #define HSM_WORD_LENGTH (4U)
52 #define HSM_SIGNATURE_VCOUNT (2U)
53 #define HSM_ASYM_ECC_PUB_KEY_VCOUNT (2U)
54 #define HSM_ASYM_CURVE25519_PUB_KEY_VCOUNT (1U)
55 #define HSM_ASYM_ECC_PUB_KEY_UNCOMP_ENC_LENG (1U)
56 #define HSM_ASYM_ECC_UNCOMP_ENC_VALUE (0x04U)
57 #define HSM_ASYM_ECC_SRD_SCRT_ENC_VALUE (0U)
58 #define HSM_DRBG_RNG_BLOCK_SIZE HSM_WORD_LENGTH
59 #define HSM_RAW_RNG_BLOCK_SIZE (256U)
60 #define HSM_RAW_RNG_MAX_LENGTH (65536U)
61 #define HSM_MAC_MAX_LENGTH (AES_BLOCK_SIZE)
62 #define HSM_AEAD_MIN_MAC_LENGTH (2U)
63 #define HSM_AEAD_TEMP_ASSET_SIZE (48U)
64 #define HSM_AES_128_KEY_LENGTH (AES_128_KEY_LENGTH_BYTES)
65 #define HSM_AES_192_KEY_LENGTH (AES_128_KEY_LENGTH_BYTES + 8)
66 #define HSM_AES_256_KEY_LENGTH (2 * AES_128_KEY_LENGTH_BYTES)
67 
68 #define BITS_TO_BYTES(bits) (((size_t)(bits) + 7U) / 8U)
69 /* Left-shift by 3 to multiply by 8, to convert from bytes to bits */
70 #define BYTES_TO_BITS(bytes) ((bytes) << 3)
71 
72 #define HSM_IS_SIZE_MULTIPLE_OF_WORD(x) (((x) & (HSM_WORD_LENGTH - 1U)) == 0U)
73 #define HSM_IS_SIZE_MULTIPLE_OF_AES_BLOCK_SIZE(x) (((x) & (AES_BLOCK_SIZE - 1U)) == 0U)
74 #define HSM_IS_SIZE_MULTIPLE_OF_RAW_BLOCK(x) (((x) & (HSM_RAW_RNG_BLOCK_SIZE - 1U)) == 0U)
75 
76 /* HSM token-related Defines */
77 
78 /* Asset Policy Codes */
79 #define HSM_ASSET_POLICY_NONMODIFIABLE 0x00000001
80 #define HSM_ASSET_POLICY_TEMPORARY 0x00000002
81 
82 #define HSM_ASSET_POLICY_SYM_HASH 0x00002800
83 #define HSM_ASSET_POLICY_SYM_HASH_MAC 0x00012800
84 #define HSM_ASSET_POLICY_SYM_AES_MAC 0x00022800
85 #define HSM_ASSET_POLICY_SYM_AES_BULK 0x00032800
86 #define HSM_ASSET_POLICY_SYM_AES_AUTH 0x00042800
87 #define HSM_ASSET_POLICY_SYM_WRAP 0x00052800
88 #define HSM_ASSET_POLICY_ASYM_SIGNVRFY 0x00004000
89 #define HSM_ASSET_POLICY_ASYM_KEYEXCH 0x00014000
90 #define HSM_ASSET_POLICY_ASYM_KEYPARAMS 0x000F4400
91 #define HSM_ASSET_POLICY_GENERIC_DATA 0x00000400
92 
93 #define HSM_ASSET_POLICY_PRIVATEDATA 0x00000800
94 #define HSM_ASSET_POLICY_ST_ANY 0x04000000
95 
96 #define HSM_ASSET_POLICY_DIR_ENC_GEN 0x00100000
97 #define HSM_ASSET_POLICY_DIR_DEC_VRFY 0x00200000
98 #define HSM_ASSET_POLICY_DIR_ENC_DEC 0x00300000
99 
100 #define HSM_ASSET_POLICY_SYM_AIH_SHA2_224 0x01000000
101 #define HSM_ASSET_POLICY_SYM_AIH_SHA2_256 0x01400000
102 #define HSM_ASSET_POLICY_SYM_AIH_SHA2_384 0x01800000
103 #define HSM_ASSET_POLICY_SYM_AIH_SHA2_512 0x01C00000
104 
105 #define HSM_ASSET_POLICY_SYM_MODE_ECB 0X00000000
106 #define HSM_ASSET_POLICY_SYM_MODE_CBC 0X08000000
107 #define HSM_ASSET_POLICY_SYM_MODE_CTR 0X18000000
108 #define HSM_ASSET_POLICY_SYM_MODE_CCM 0X00000000
109 #define HSM_ASSET_POLICY_SYM_MODE_GCM 0X08000000
110 #define HSM_ASSET_POLICY_SYM_MODE_CMAC 0X00000000
111 #define HSM_ASSET_POLICY_SYM_MODE_CBC_MAC 0X08000000
112 
113 #define HSM_ASSET_POLICY_ASYM_ECDH 0x00200000
114 #define HSM_ASSET_POLICY_ASYM_ECDSA 0x00300000
115 #define HSM_ASSET_POLICY_ASYM_CURVE25519 0x00400000
116 #define HSM_ASSET_POLICY_ASYM_ED25519 0x00500000
117 
118 #define HSM_ASSET_POLICY_ASYM_SHA2_224 0x20000000
119 #define HSM_ASSET_POLICY_ASYM_SHA2_256 0x28000000
120 #define HSM_ASSET_POLICY_ASYM_SHA2_384 0x30000000
121 #define HSM_ASSET_POLICY_ASYM_SHA2_512 0x38000000
122 
123 /* Encryption Defines */
124 #define HSM_ENCRYPTION_TOKEN_WORD0 0x01000000
125 #define HSM_ENCRYPTION_TOKEN_WORD11 0x00004000
126 #define HSM_ENCRYPTION_TOKEN_WORD11_ENC 0x00008000
127 #define HSM_ENCRYPTION_TOKEN_WORD11_KEY128 0x00010000
128 #define HSM_ENCRYPTION_TOKEN_WORD11_KEY192 0x00020000
129 #define HSM_ENCRYPTION_TOKEN_WORD11_KEY256 0x00030000
130 
131 #define HSM_ENCRYPTION_TOKEN_WORD11_CCM 0x00000050
132 #define HSM_ENCRYPTION_TOKEN_WORD11_GCM 0x00000070
133 
134 #define HSM_ENCRYPTION_TOKEN_WORD11_SAVEIV 0x00001000
135 #define HSM_ENCRYPTION_TOKEN_WORD11_LOADIV 0X00000200
136 
137 #define HSM_ENCRYPTION_TOKEN_WORD16_GCM_IV 0x01000000
138 
139 /* MAC Defines */
140 #define HSM_MAC_TOKEN_WORD0 0x13000000
141 
142 #define HSM_MAC_TOKEN_WORD6_CMAC 0x00000008
143 #define HSM_MAC_TOKEN_WORD6_CBC_MAC 0x00000009
144 
145 #define HSM_MAC_TOKEN_WORD6_INIT2FINAL 0X00000000
146 #define HSM_MAC_TOKEN_WORD6_CONT2FINAL 0X00000010
147 #define HSM_MAC_TOKEN_WORD6_INIT2CONT 0X00000020
148 #define HSM_MAC_TOKEN_WORD6_CONT2CONT 0X00000030
149 
150 /* ECC Defines */
151 #define HSM_PK_TOKEN_WORD0 0x19000000
152 #define HSM_PK_TOKEN_WORD2_CMD_ECC_KEYS_CHECK 0x00000001
153 #define HSM_PK_TOKEN_WORD2_CMD_ECDSA_SIGN 0x00000006
154 #define HSM_PK_TOKEN_WORD2_CMD_ECDSA_VRFY 0x00000007
155 #define HSM_PK_TOKEN_WORD2_CMD_ECC_GEN_PUBKEY 0x00000014
156 #define HSM_PK_TOKEN_WORD2_CMD_ECDH_GEN_SHRD_SCRT 0x00000016
157 #define HSM_PK_TOKEN_WORD2_CMD_25519_GEN_PUBKEY 0x00000028
158 #define HSM_PK_TOKEN_WORD2_CMD_25519_GEN_SHRD_SCRT 0x0000002A
159 #define HSM_PK_TOKEN_WORD2_CMD_EDDSA_GEN_PUBKEY 0x0000002B
160 #define HSM_PK_TOKEN_WORD2_CMD_EDDSA_SIGN_INITIAL 0x0000002D
161 #define HSM_PK_TOKEN_WORD2_CMD_EDDSA_SIGN_UPDATE 0x0000002E
162 #define HSM_PK_TOKEN_WORD2_CMD_EDDSA_SIGN_FINAL 0x0000002F
163 #define HSM_PK_TOKEN_WORD2_CMD_EDDSA_VRFY_INITIAL 0x00000030
164 #define HSM_PK_TOKEN_WORD2_CMD_EDDSA_VRFY_FINAL 0x00000031
165 
166 typedef enum
167 {
168  HSMLPF3_BIG_ENDIAN_KEY = 0,
169  HSMLPF3_LITTLE_ENDIAN_KEY = 1,
170 } HSMLPF3_KeyMaterialEndianness;
171 
177 static inline uint32_t HSM_ASYM_DATA_SIZE_B2W(const size_t x)
178 {
179  return (uint32_t)((x + 31U) / 32U);
180 }
181 
187 static inline uint32_t HSM_ASYM_DATA_SIZE_B2WB(const size_t x)
188 {
189  return (uint32_t)(HSM_WORD_LENGTH * (HSM_ASYM_DATA_SIZE_B2W(x)));
190 }
191 
197 static inline uint32_t HSM_ASYM_DATA_SIZE_VWB(const size_t x)
198 {
199  return (uint32_t)(HSM_ASYM_DATA_VHEADER + HSM_ASYM_DATA_SIZE_B2WB(x));
200 }
201 
207 static inline uint32_t HSMLPF3_getOutputBufferLength(const uint32_t inputLength)
208 {
209 #ifdef VEX_CHECK_DMA_WITH_TOKEN_ID
210  /* 32-bit alignment + extra size for the TokenID */
211  return (((inputLength + 3U) & (size_t)~3UL) + sizeof(size_t));
212 #else
213  /* 32-bit alignment */
214  return ((inputLength + 3U) & (size_t)~3UL);
215 #endif
216 }
217 
225 void *HSMLPF3_reverseMemCpy(void *dest, const void *src, size_t size);
226 
236 void HSMLPF3_asymVectorHeaderFormat(const size_t modulusSizeBits,
237  const uint8_t itemsLength,
238  const uint8_t itemIdx,
239  const uint8_t domainId,
240  uint32_t *blob);
241 
251 void HSMLPF3_asymDHPriKeyToHW(uint8_t *in,
252  const size_t modulusSizeBits,
253  const uint8_t domainId,
254  HSMLPF3_KeyMaterialEndianness endianness,
255  uint8_t *blob);
256 
267 void HSMLPF3_asymDHPubKeyToHW(uint8_t *in,
268  const size_t modulusSizeBits,
269  const uint8_t itemsLength,
270  const uint8_t domainId,
271  HSMLPF3_KeyMaterialEndianness endianness,
272  uint8_t *blob);
273 
284 void HSMLPF3_asymDHPubKeyFromHW(const uint8_t *const in,
285  const size_t modulusSizeBits,
286  const uint8_t itemsLength,
287  HSMLPF3_KeyMaterialEndianness endianness,
288  uint8_t *out_pubKey);
289 
299 void HSMLPF3_asymDsaSignatureFromHW(const uint8_t *const in,
300  const size_t modulusSizeBits,
301  HSMLPF3_KeyMaterialEndianness endianness,
302  uint8_t *out_r,
303  uint8_t *out_s);
304 
314 void HSMLPF3_asymDsaSignatureToHW(const uint8_t *const Signature_r,
315  const uint8_t *const Signature_s,
316  HSMLPF3_KeyMaterialEndianness endianness,
317  const size_t modulusSizeBits,
318  uint8_t *const blob);
319 
328 void HSMLPF3_asymDsaPubKeyToHW(const uint8_t *const pubKey,
329  const size_t modulusSizeBits,
330  const uint8_t domainId,
331  uint8_t *const blob);
332 
341 void HSMLPF3_asymDsaPriKeyToHW(const uint8_t *const pubKey,
342  const size_t modulusSizeBits,
343  const uint8_t domainId,
344  uint8_t *const blob);
345 
© Copyright 1995-2025, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale