1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 8 #ifndef RSA_PKI_PKA_H 9 #define RSA_PKI_PKA_H 10 11 /* 12 * All the includes that are needed for code using this module to 13 * compile correctly should be #included here. 14 */ 15 16 #include "secureboot_basetypes.h" 17 #include "secureboot_stage_defs.h" 18 19 20 #ifdef __cplusplus 21 extern "C" 22 { 23 #endif 24 25 /************************ Defines ******************************/ 26 27 28 /* values for defining, that PKA entry is not in use */ 29 #define PKA_SIZE_ENTRY_NOT_USED 0xFFFFFFFF 30 #define PKA_ADDRESS_ENTRY_NOT_USED 0xFFC 31 32 /* define NpCreateFlag values */ 33 #define PKA_CreateNP 1 34 #define PKA_SetNP 0 35 36 /* define "discard result" value */ 37 #define RES_DISCARD 0x3F 38 39 40 /* default LenID-s definitions. Last 3 names used in RSA KG. 41 Note: extended sizes are in the entries LenID+1 (i.e. 1,3) accordingly */ 42 #define LenIDn 0 /* for operation or modulus size*/ 43 #define LenIDpq 2 /* for P, Q size */ 44 #define LenID101 4 /* for P1,P2,Q1,Q2 101 bit size */ 45 #define LenIDmin 6 /* for min allowed operation size (now 128 bit) */ 46 #define LenIDmax 7 /* for max allowed operation size (now 2112 bit) */ 47 48 /* define of PKA Tag for debug printing of PKA operations result 49 into tempRes global buffer */ 50 #define PKA_TAG_DebugPtint 1 51 52 53 /************************ Enums ********************************/ 54 55 /* defines enumerator for all allowed PKA operations */ 56 typedef enum 57 { 58 PKA_Terminate_ID = 0, 59 PKA_Add_ID = 1, 60 PKA_AddIm_ID = 2, 61 PKA_Sub_ID = 3, 62 PKA_SubIm_ID = 4, 63 PKA_Neg_ID = 5, 64 65 PKA_ModAdd_ID = 6, 66 PKA_ModAddIm_ID = 7, 67 PKA_ModSub_ID = 8, 68 PKA_ModSubIm_ID = 9, 69 PKA_ModNeg_ID = 10, 70 71 PKA_And_ID = 11, 72 PKA_Tst0_ID = 12, 73 PKA_Clr0_ID = 13, 74 PKA_Clr_ID = 14, 75 76 PKA_OR_ID = 15, 77 PKA_Copy_ID = 16, 78 PKA_SetBit0_ID = 17, 79 80 PKA_XOR_ID = 18, 81 PKA_Flip0_ID = 19, 82 PKA_InvBits_ID = 20, 83 PKA_Compare_ID = 21, 84 85 PKA_SHR0_ID = 22, 86 PKA_SHR1_ID = 23, 87 PKA_SHL0_ID = 24, 88 PKA_SHL1_ID = 25, 89 90 PKA_LMul_ID = 26, 91 PKA_HMul_ID = 27, 92 PKA_ModMul_ID = 28, 93 PKA_ModMulNR_ID = 29, 94 PKA_ModExp_ID = 30, 95 96 PKA_Div_ID = 31, 97 PKA_ModInv_ID = 32, 98 99 PKA_OpOffMode 100 101 } RSA_HW_PKI_PKA_OpID_t; 102 103 104 /* Enumerator, defining whether the functions performs default settings 105 of PKI registers, or takes they from user passed arguments */ 106 typedef enum 107 { 108 DefaultRegs = 0, 109 SetRegs = 1, 110 RegsSetOffMode 111 112 } RSA_HW_PKI_PKA_SetRegs_t; 113 114 115 /************************ Typedefs ****************************/ 116 117 /************************ Typedefs ****************************/ 118 119 /************************ Structs ******************************/ 120 121 /* definition of the Registers sizes array type, used for initialisation 122 of the PKA sizes table */ 123 typedef uint32_t RSA_HW_PKI_PKA_RegsSizes_t[RSA_PKA_MAX_COUNT_OF_REGS_SIZES]; 124 125 /* This structure contains virtual pointers (numbers in range 0-31) of 126 PKI registers RegsNum[] and registers physical addresses RegsAddr[]. 127 For example: RegsNum[3] = 5 and RegsAddr[3] = 0x400 means, that address of 128 register 5 is 0x400. The user may set into this structure only needed registers, 129 used in planned PKA operations. */ 130 131 typedef struct 132 { 133 uint32_t RegsNum[RSA_HW_PKI_PKA_MAX_COUNT_OF_PHYS_MEM_REGS] ; 134 uint32_t RegsAddr[RSA_HW_PKI_PKA_MAX_COUNT_OF_PHYS_MEM_REGS] ; 135 }RSA_HW_PKI_PKA_RegsMap_t; 136 137 /************************ Public Variables **********************/ 138 139 /************************ Public Functions ******************************/ 140 141 142 /***********************************************************************************************/ 143 /***********************************************************************************************/ 144 /* */ 145 /* RSA PKI FUNCTIONS, PERFORMING PKA OPERATIONS */ 146 /* */ 147 /***********************************************************************************************/ 148 /***********************************************************************************************/ 149 150 151 152 /*******************************************************************************/ 153 /********** RSA PKI PKA initialisation functions and macros **********/ 154 /*******************************************************************************/ 155 156 /*********** PkaSetRegsSizesTab function **********************/ 157 /** 158 * @brief This function initializes the PKA registers sizes table. 159 * 160 * The function sets sizes table as follows: 161 * - tab[0] = MaxSizeBits; //maximal size, usually this is exact modulus size in bits 162 * - tab[1] = Extended size with extra bits, aligned to big words. 163 * - other entrie, 164 uint32_t Xs = PKA_SIZE_ENTRY_NOT_USED, means - not used. 165 * 166 * @param[in] opSizeInBits - Size of PKA operations (modulus) in bits. The value must be in interval 167 * from defined Min. to Max. size bits. 168 * @param[in] regSizeInPkaWords - Sise of registers in PKA big words (e.g. 128-bit words). 169 * 170 * @return - no return value 171 * 172 */ 173 void RSA_PKA_SetRegsSizesTab( uint32_t opSizeInBits, 174 int32_t regSizeInPkaWords, 175 unsigned long VirtualHwBaseAddr); 176 177 178 /*********** PkaSetRegsMapTab function **********************/ 179 /** 180 * @brief This function initializes the PKA registers sizes table. 181 * 182 * The function checks input parameters and sets the physical memory registers mapping-table 183 * according to parameters, passed by the user: 184 * - start address of register 0 is the start address of PKA data registers memory 185 * PKA_SRAM_REGS_MEM_OFFSET_WORDS (defined in pka_hw_defs.h file); 186 * - special registers are set as follows: N=0,NP=1,T0=30,T1=31; 187 * - all registers have the same size, equalled to given size; 188 * 189 * @param[in] countOfRegs - The count of registeres, requirred by the user. 190 * @param[in] regSizeInPkaWords - Sise of registers in PKA big words (e.g. 128-bit words). 191 * @param[in] VirtualHwBaseAddr - ARM CryptoCell base address 192 * 193 * @return - no return value 194 * 195 */ 196 void RSA_PKA_SetRegsMapTab(int32_t countOfRegs, 197 int32_t regSizeInPkaWords, 198 unsigned long VirtualHwBaseAddr); 199 200 201 202 /*********** PkaInitPka function **********************/ 203 /** 204 * @brief This function initializes the PKA engine. 205 * 206 * The function performs the following: 207 * - initializes the PKA_SizesTable, PKA_MappingTable and special register 208 * N_NP_T0_T1 according to user passed register sizes, registers mapping 209 * and default N_NP_T0_T1 value. 210 * 211 * The function calls the PkaSetRegsSizesTab and PkaSetRegsMapTab 212 * functions and sets N_NP_T0_T1 value into N_NP_T0_T1 register. 213 * Notes: 214 * - See remarks to PkaSetRegsSizesTab and PkaSetRegsMapTab functions. 215 * - The function allocates one additional word for each register if it is needed for extra bits. 216 * 217 * 218 * @return void 219 * 220 */ 221 void RSA_PKA_InitPka(uint32_t opSizeInBits, /*in*/ 222 uint32_t regsCount, /*in*/ 223 unsigned long virtualHwBaseAddr) /*out*/; 224 225 226 /*********** RSA_HW_PKI_PKA_FinishPKA function **********************/ 227 /** 228 * @brief This function ends the PKA engine session and disables PKA clocks. 229 * 230 * @param[in] VirtualHwBaseAddr - Virtual HW base address, passed by user. 231 * 232 * @return - no return parameters. 233 * 234 */ 235 void RSA_HW_PKI_PKA_FinishPKA( unsigned long VirtualHwBaseAddr /*in*/ ); 236 237 238 239 /*******************************************************************************/ 240 /************ RSA PKI PKA mathmatic functions and macros ****************/ 241 /*******************************************************************************/ 242 243 /*********** PkaDbgExecOperation (with virtual pointers) ******************/ 244 /** 245 * @brief This function executes any allowed PKA mathematic operation according to 246 * user passed Opcode. 247 * 248 * The function receives code of operation, virtual pointers to PKI registers 249 * (sequence number), for arguments and result, and operates PKA machine by writing 250 * full operation code into OPCODE register. Then the function calls macros for 251 * waiting the PKA pipe ready signal. 252 * If opcode is illegal or one of operands is illegal, the function returns an 253 * error code defined in llf_pki_error.h file. 254 * 255 * The user don't call this function directly. For user convenience, in llf_pki.h file are 256 * given some macros for calling this function according to each performed operation. 257 * 258 * NOTES: 259 * - Before executing modular operations, the modulus must be set into N=r0 register of PKA. 260 * - Before modular multiplication and exponentiation must be calculated and set into NP=r1 261 * register the Barrett modulus tag NP = 2**(sizeN+132) / N. 262 * - In operations with immediate operands (IsImmediate bit = 1), the operand value (5-bit) 263 * is treated as sign-extended. That means: low 4 bits are treated as unsigned operand 264 * value in range 0-15 and bit 5 is a sign (with extension to all high bits of register, 265 * in which the full operand shall be set). 266 * - In shift operations the 5-bits shift operand is treated as unsigned value in range 0-31 267 * (count of shifts is equaled to shift operand value + 1). 268 * - The LMul operation gives the low half of multiplication result of length equaled to 269 * operation size. The leading not significant bits of the operands and result (including 270 * the the extra word) must be zeroed. 271 * - The HMul operation gives the high half of multiplication result plus one high word of low 272 * half of full multiplication result. Therefore this result is by one word large, than 273 * operation size. The leading not significant bits of the operands and result, 274 * including extra word must be zeroed. 275 * - The ModInv operation calculates Res = 1/OpB mod N for odd modulus. Operand A is ignored. 276 * In case of even modulus the function returns an error. Therefore in this case 277 * (also for odd modulus) the user may call the PkaExecFullModInv function. 278 * 279 * @param[in] Opcode - The operation code according HW PKA definitions. Valid values: 0 - max Opcode. 280 * @param[in] LenID - ID of the length of operands according to register sizes table 281 * (means the number of entry in the table). Valid values: 0...7. 282 * @param[in] IsAImmed - If IsAImmed = 1, then operand A treated as immediate value, else - 283 * as virtual register pointer. Valid values: 0,1. 284 * @param[in] OpA - Operand A: an immediate value or virtual register pointer, according to IsAImmed 285 * IsAImmed parameter. Valid values: 0 <= OpA <= 31. 286 * @param[in] IsBImmed - If IsBImmed = 1, then operand B treated as immediate value, else - 287 * as virtual register pointer. Valid values: 0,1. 288 * @param[in] OpB - Operand B: an immediate value or virtual register pointer, according to IsAImmed 289 * IsBImmed parameter. Valid values: 0 <= OpA <= 31. 290 * @param[in] ResDiscard - If ResDiscard = 1, then result is discarded. 291 * @param[in] Res - Virtual register pointer for result data. 292 * Valid values: 0 <= Res <= 31. Value Res = RES_DISCARD means result must be discarded. 293 * @param[in] Tag - The user defined value (Tag <= 31), used for indication goals. 294 * 295 * 296 * @return CCError_t - On success CC_OK is returned, on failure an error code: 297 * PKA_ILLEGAL_OPCODE_ERROR 298 * PKA_ILLEGAL_OPERAND_LEN_ERROR 299 * PKA_ILLEGAL_OPERAND_TYPE_ERROR 300 * PKA_ILLEGAL_OPERAND_ERROR 301 * PKA_INVERSION_NOT_EXISTS_ERROR 302 */ 303 304 305 CCError_t _RSA_PKA_ExecOperation( uint32_t Opcode, /*in*/ 306 uint8_t LenID, /*in*/ 307 uint8_t IsAImmed, /*in*/ 308 int8_t OpA, /*in*/ 309 uint8_t IsBImmed, /*in*/ 310 int8_t OpB, /*in*/ 311 uint8_t ResDiscard, /*in*/ 312 int8_t Res, /*in*/ 313 uint8_t Tag, /*in*/ 314 unsigned long VirtualHwBaseAddr); 315 316 /*************************************************************************/ 317 /* Macros for calling PKA operations (names according to operation issue */ 318 /*************************************************************************/ 319 320 /*----------------------------------*/ 321 /* 1. ADD - SUBTRACT operations */ 322 /*----------------------------------*/ 323 324 /* Add: Res = OpA + OpB */ 325 #define RSA_PKA_Add(LenID, OpA, OpB, Res, Tag, VirtualHwBaseAddr) \ 326 _RSA_PKA_ExecOperation( PkaAdd,(LenID), 0, (OpA), 0, (OpB), 0, (Res), (Tag), (VirtualHwBaseAddr) ) 327 /* AddIm: Res = OpA + OpBIm */ 328 #define RSA_PKA_Add_IM(LenID, OpA, OpBIm, Res, Tag, VirtualHwBaseAddr) \ 329 _RSA_PKA_ExecOperation( PkaAddIm,(LenID), 0, (OpA), 1, (OpBIm), 0, (Res), (Tag), (VirtualHwBaseAddr) ) 330 /* SubIm: Res = OpA - OpBIm */ 331 #define RSA_PKA_SUB_IM(LenID, OpA, OpBIm, Res, Tag, VirtualHwBaseAddr) \ 332 _RSA_PKA_ExecOperation( PkaSubIm,(LenID), 0, (OpA), 1, (OpBIm), 0, (Res), (Tag), (VirtualHwBaseAddr) ) 333 334 /*----------------------------------*/ 335 /* 2. Logical operations */ 336 /*----------------------------------*/ 337 338 /* Clr: Res = OpA & 0 - clears the operand A. */ 339 #define RSA_PKA_Clr(LenID, OpA, Tag, VirtualHwBaseAddr) \ 340 _RSA_PKA_ExecOperation( PkaAND, (LenID), 0, (OpA), 1, 0x00, 0, (OpA), (Tag), (VirtualHwBaseAddr)) 341 342 /* Clear: for full clearing the actual register opA, this macro calls Clr operation twice. */ 343 #define RSA_PKA_Clear(LenID, OpA, Tag, VirtualHwBaseAddr) \ 344 RSA_PKA_Clr(LenID, OpA, Tag, VirtualHwBaseAddr); \ 345 RSA_PKA_Clr(LenID, OpA, Tag, VirtualHwBaseAddr) 346 347 /* Set0: Res = OpA || 1 : set bit0 = 1, other bits are not changed */ 348 #define RSA_PKA_Set0(LenID, OpA, Res, Tag, VirtualHwBaseAddr) \ 349 _RSA_PKA_ExecOperation(PkaOR, (LenID), 0, (OpA), 1, 0x01, 0, (Res), (Tag), (VirtualHwBaseAddr)) 350 351 /*-----------------------------------------------------*/ 352 /* 2. Multiplication and other operations */ 353 /* Note: See notes to PKA_ExecOperation */ 354 /*-----------------------------------------------------*/ 355 #define RSA_PKA_Add(LenID, OpA, OpB, Res, Tag, VirtualHwBaseAddr) \ 356 _RSA_PKA_ExecOperation( PkaAdd,(LenID), 0, (OpA), 0, (OpB), 0, (Res), (Tag), (VirtualHwBaseAddr) ) 357 358 /* ModExp: Res = OpA ** OpB mod N - modular exponentiation */ 359 #define RSA_HW_PKI_PKA_ModExp(LenID, OpA, OpB, Res, Tag, VirtualHwBaseAddr) \ 360 _RSA_PKA_ExecOperation( PkaModExp, (LenID), 0, (OpA), 0, (OpB), 0, (Res), (Tag), (VirtualHwBaseAddr)) 361 362 /* Copy: OpDest = OpSrc || 0 */ 363 #define RSA_PKA_Copy(LenID, OpDest, OpSrc, Tag, VirtualHwBaseAddr) \ 364 _RSA_PKA_ExecOperation(PkaOR, (LenID), 0, (OpSrc), 1, 0x00, 0, (OpDest), (Tag), (VirtualHwBaseAddr)) 365 366 /* SHR0: Res = OpA >> (S+1) : shifts right operand A by S+1 bits, insert 0 to left most bits */ 367 #define RSA_PKA_SHR0(LenID, OpA, S, Res, Tag, VirtualHwBaseAddr) \ 368 _RSA_PKA_ExecOperation( PkaSHR0, (LenID), 0, (OpA), 0, (S), 0, (Res), (Tag), (VirtualHwBaseAddr)) 369 370 /* SHL0: Res = OpA << (S+1) : shifts left operand A by S+1 bits, insert 0 to right most bits */ 371 #define RSA_PKA_SHL0(LenID, OpA, S, Res, Tag, VirtualHwBaseAddr) \ 372 _RSA_PKA_ExecOperation(PkaSHL0, (LenID), 0, (OpA), 0, (S), 0, (Res), (Tag), (VirtualHwBaseAddr)) 373 374 /* Divide: Res = OpA / OpB , OpA = OpA mod OpB - division, */ 375 #define RSA_PKA_Div(LenID, OpA, OpB, Res, Tag, VirtualHwBaseAddr) \ 376 _RSA_PKA_ExecOperation( PkaDiv, (LenID), 0, (OpA), 0, (OpB), 0, (Res), (Tag), (VirtualHwBaseAddr)) 377 378 379 380 #define RSA_PKA_WRITE_WORD_TO_REG(Val,i,VirtReg, VirtualHwBaseAddr) {\ 381 uint32_t currAddr;\ 382 RSA_PKA_WAIT_ON_PKA_DONE(VirtualHwBaseAddr); \ 383 currAddr = RSA_PKA_GetRegAddress(VirtReg, VirtualHwBaseAddr);\ 384 RSA_HW_PKI_HW_LOAD_VALUE_TO_PKA_MEM(VirtualHwBaseAddr, currAddr+(i), (Val));\ 385 } 386 387 388 /* ***************************************************************************** */ 389 /* ************ Auxiliary functions used in PKA **************** */ 390 /* ***************************************************************************** */ 391 392 393 /*********** RSA_HW_PKI_PKA_ClearBlockOfRegs function **********************/ 394 /** 395 * @brief This function clears block of PKA registers. 396 * 397 * Assumings: - PKA is initialised. 398 * - Length of extended (by word) registers is plased into LenID entry of 399 * sizes table. 400 * 401 * @param[in] firstReg - Virtual address (number) of first register in block. 402 * @param[in] countOfRegs - Count of registers to clear. 403 * @param[in] LenId - ID of entry of regsSizesTable defines registers lengts with word extension. 404 * @param[in] VirtualHwBaseAddr - Virtual HW base address, passed by user. 405 * 406 */ 407 void RSA_HW_PKI_PKA_ClearBlockOfRegs( 408 uint8_t firstReg, /*in*/ 409 uint8_t countOfRegs, /*in*/ 410 uint8_t LenID, /*in*/ 411 unsigned long VirtualHwBaseAddr /*in*/ ); 412 413 414 415 /*********** RSA_HW_PKI_PKA_CopyDataIntoPkaReg function **********************/ 416 /** 417 * @brief This function copies source data into PKA register . 418 * 419 * Assumings: - PKA is initialised. 420 * - Length of extended (by word) registers is plased into LenID entry of 421 * sizes table. 422 * - If the extra word of register must be cleared also the user must 423 * set LenID according to extended register size 424 * 425 * @param[in] dstReg - Virtual address (number) of destination register. 426 * @param[in] LenId - ID of entry of regsSizesTable defines registers lengts with word extension. 427 * @param[in] src_ptr - Pointer to source buffer. 428 * @param[in] sizeBytes - Data size in bytes. 429 * @param[in] VirtualHwBaseAddr - Virtual HW base address, passed by user. 430 * 431 * @return - no return parameters. 432 * 433 */ 434 void RSA_HW_PKI_PKA_CopyDataIntoPkaReg(uint32_t dstReg, /*out*/ 435 uint32_t LenID, /*in*/ 436 const uint32_t *src_ptr, /*in*/ 437 uint32_t sizeWords, /*in*/ 438 unsigned long VirtualHwBaseAddr); 439 440 441 442 443 /*********** RSA_HW_PKI_PKA_CopyDataFromPkaReg **********************/ 444 /** 445 * @brief This function copies data from PKA register into output buffer . 446 * 447 * Assumings: - PKA is initialised. 448 * - Length of extended (by word) registers is plased into LenID entry of 449 * sizes table. 450 * - If the extra word of register must be cleared also the user must 451 * set LenID according to extended register size 452 * 453 * @param[in] srcReg - Virtual address (number) of source PKA register. 454 * @param[in] dst_ptr - Pointer to destination buffer. 455 * @param[in] sizeBytes - Source size in bytes. 456 * @param[in] VirtualHwBaseAddr - Virtual HW base address, passed by user. 457 * 458 * @return - no return parameters. 459 * 460 */ 461 void RSA_HW_PKI_PKA_CopyDataFromPkaReg(uint32_t *dst_ptr, /*out*/ 462 uint32_t sizeWords, /*in*/ 463 uint32_t srcReg, /*in*/ 464 unsigned long VirtualHwBaseAddr); 465 466 467 /*********** RSA_HW_PKI_SET_MSB_ADDR **********************/ 468 /** 469 * @brief This function sets the PKI MSB register according ot the SRAM address . 470 * 471 * Assumings: - PKA registers are accessable. 472 * - SRAM address is multiple of 4KB. 473 * 474 * @param[in] pkaAdrress - base address of the SRAM for PKA. 475 * 476 * @return - no return parameters. 477 * 478 */ 479 void RSA_HW_PKI_SET_MSB_ADDR(unsigned long virtualAddress, uint32_t pkaAdrress); 480 481 /** 482 * The function uses physical data pointers to calculate 483 * the Barrett tag Np. Np is saved into Register indexed by regNp. 484 * 485 * For RSA it uses truncated sizes: 486 * Np = truncated(2^(3*A+3*X-1) / ceiling(n/(2^(N-2*A-2*X))); 487 * 488 * function assumes modulus in PKA reg 0, and output is to PKA reg 1 489 * 490 */ 491 uint32_t RSA_HW_PKA_CalcNpIntoPkaReg(uint32_t lenId, 492 uint32_t sizeNbits, 493 int8_t regN, 494 int8_t regNp, // out 495 int8_t regTemp1, 496 int8_t regTempN, 497 unsigned long VirtualHwBaseAddr) ; 498 499 #ifdef __cplusplus 500 } 501 #endif 502 503 #endif 504
