1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup TeeTrusted 18 * @{ 19 * 20 * @brief TEE(Trusted Excution Environment) API. 21 * Provides security capability APIs such as trusted storage, encryption and decryption, 22 * and trusted time for trusted application development. 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file tee_arith_api.h 29 * 30 * @brief Provides APIs for operating big integers. 31 * 32 * @library NA 33 * @kit TEEKit 34 * @syscap SystemCapability.Tee.TeeClient 35 * @since 20 36 */ 37 38 #ifndef TEE_ARITH_API_H 39 #define TEE_ARITH_API_H 40 41 #include <tee_defines.h> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Defines the handle type representing a big integer. 49 * 50 * @since 20 51 */ 52 typedef uint32_t TEE_BigInt; 53 54 /** 55 * @brief Defines the handle of a big integer for Fast Modular Multiplication (FMM). 56 * 57 * @since 20 58 */ 59 typedef uint32_t TEE_BigIntFMM; 60 61 /** 62 * @brief Defines the handle of a context container for FMM operations. 63 * 64 * @since 20 65 */ 66 typedef uint32_t TEE_BigIntFMMContext; 67 68 /** 69 * @brief Obtains the size of the array of uint32_t values required to represent a <b>BigInt</b>. 70 * 71 * @param n Indicates the <b>TEE_BigInt</b> type. 72 * 73 * @return Returns the <b>BigInt</b> size obtained. 74 * 75 * @since 20 76 */ 77 #define TEE_BigIntSizeInU32(n) ((((n) + 31) / 32) + 2) 78 79 /** 80 * @brief Obtains the size of the array of uint32_t values. 81 * 82 * @param modulusSizeInBits Indicates the modulus size, in bits. 83 * 84 * @return Returns the number of bytes required to store a <b>TEE_BigIntFMM</b>, 85 * given a modulus of length <b>modSizeInBits</b>. 86 * 87 * @since 20 88 */ 89 size_t TEE_BigIntFMMSizeInU32(size_t modulusSizeInBits); 90 91 /** 92 * @brief Obtains the size of an array of uint32_t values required to represent a fast modular context. 93 * 94 * @param modulusSizeInBits Indicates the modulus size, in bits. 95 * 96 * @return Returns the number of bytes required to store a <b>TEE_BigIntFMMContext</b>, 97 * given a modulus of length <b>modSizeInBits</b>. 98 * 99 * @since 20 100 */ 101 size_t TEE_BigIntFMMContextSizeInU32(size_t modulusSizeInBits); 102 103 /** 104 * @brief Initializes a <b>TEE_BigInt</b>. 105 * 106 * @param bigInt Indicates the pointer to the <b>TEE_BigInt</b> to initialize. 107 * @param len Indicates the size of the memory pointed to by <b>TEE_BigInt</b>, in uint32_t. 108 * 109 * @since 20 110 */ 111 void TEE_BigIntInit(TEE_BigInt *bigInt, size_t len); 112 113 /** 114 * @brief Calculates the necessary prerequisites for fast modular multiplication and stores them in a context. 115 * 116 * @param context Indicates the pointer to the <b>TEE_BigIntFMMContext</b> to initialize. 117 * @param len Indicates the size of the memory pointed to by <b>context</b>, in uint32_t. 118 * @param modulus Indicates the pointer to the modulus. 119 * 120 * @since 20 121 */ 122 void TEE_BigIntInitFMMContext(TEE_BigIntFMMContext *context, size_t len, const TEE_BigInt *modulus); 123 124 /** 125 * @brief Calculates the necessary prerequisites for fast modular multiplication and stores them in a context. 126 * 127 * @param context Indicates the pointer to the <b>TEE_BigIntFMMContext</b> to initialize. 128 * @param len Indicates the size of the memory pointed to by <b>context</b>, in uint32_t. 129 * @param modulus Indicates the pointer to the modulus. 130 * 131 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 132 * Returns other values if the operation fails. 133 * 134 * @since 20 135 */ 136 TEE_Result TEE_BigIntInitFMMContext1(TEE_BigIntFMMContext *context, size_t len, const TEE_BigInt *modulus); 137 138 /** 139 * @brief Initializes a <b>TEE_BigIntFMM</b> and sets its represented value to zero. 140 * 141 * @param bigIntFMM Indicates the pointer to the <b>TEE_BigIntFMM</b> to initialize. 142 * @param len Indicates the size of the memory pointed to by <b>bigIntFMM</b>, in uint32_t. 143 * 144 * @since 20 145 */ 146 void TEE_BigIntInitFMM(TEE_BigIntFMM *bigIntFMM, size_t len); 147 148 /** 149 * @brief Converts an octet string buffer into the <b>TEE_BigInt</b> format. 150 * 151 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result. 152 * @param buffer Indicates the pointer to the buffer that holds the octet string representation of the integer. 153 * @param bufferLen Indicates the buffer length, in bytes. 154 * @param sign Indicates the sign of <b>dest</b>, which is set to the sign of <b>sign</b>. 155 * 156 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 157 * Returns <b>TEE_ERROR_OVERFLOW</b> if the memory allocated for <b>dest</b> is too small. 158 * 159 * @since 20 160 */ 161 TEE_Result TEE_BigIntConvertFromOctetString(TEE_BigInt *dest, const uint8_t *buffer, size_t bufferLen, int32_t sign); 162 163 /** 164 * @brief Converts the absolute value of an integer in <b>TEE_BigInt</b> format into an octet string. 165 * 166 * @param buffer Indicates the pointer to the output buffer that holds the converted octet string representation 167 * of the integer. 168 * @param bufferLen Indicates the pointer to the buffer length, in bytes. 169 * @param bigInt Indicates the pointer to the integer to convert. 170 * 171 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 172 * Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the output buffer is too small to hold the octet string. 173 * 174 * @since 20 175 */ 176 TEE_Result TEE_BigIntConvertToOctetString(void *buffer, size_t *bufferLen, const TEE_BigInt *bigInt); 177 178 /** 179 * @brief Sets <b>dest</b> to the value <b>shortVal</b>. 180 * 181 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result. 182 * @param shortVal Indicates the value to set. 183 * 184 * @since 20 185 */ 186 void TEE_BigIntConvertFromS32(TEE_BigInt *dest, int32_t shortVal); 187 188 /** 189 * @brief Sets <b>dest</b> to the value of <b>src</b>, including the sign of <b>src</b>. 190 * 191 * @param dest Indicates the pointer to the <b> int32_t</b> that holds the result. 192 * @param src Indicates the pointer to the value to set. 193 * 194 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 195 * Returns <b>TEE_ERROR_OVERFLOW</b> if <b>src</b> does not fit within an <b> int32_t</b>. 196 * 197 * @since 20 198 */ 199 TEE_Result TEE_BigIntConvertToS32(int32_t *dest, const TEE_BigInt *src); 200 201 /** 202 * @brief Checks whether op1 > op2, op1 == op2, or op1 < op2. 203 * 204 * @param op1 Indicates the pointer to the first operand. 205 * @param op2 Indicates the pointer to the second operand. 206 * 207 * @return Returns <b>0</b> if op1 == op2. 208 * Returns a positive number if op1 > op2. 209 * 210 * @since 20 211 */ 212 int32_t TEE_BigIntCmp(const TEE_BigInt *op1, const TEE_BigInt *op2); 213 214 /** 215 * @brief Checks whether op > shortVal, op == shortVal, or op < shortVal. 216 * 217 * @param op Indicates the pointer to the first operand. 218 * @param shortVal Indicates the pointer to the second operand. 219 * 220 * @return Returns <b>0</b> if op1 == shortVal. 221 * Returns a positive number if op1 > shortVal. 222 * 223 * @since 20 224 */ 225 int32_t TEE_BigIntCmpS32(const TEE_BigInt *op, int32_t shortVal); 226 227 /** 228 * @brief Computes |dest| = |op| >> bits. 229 * 230 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the shifted result. 231 * @param op Indicates the pointer to the operand to be shifted. 232 * @param bits Indicates the number of bits to shift. 233 * 234 * @since 20 235 */ 236 void TEE_BigIntShiftRight(TEE_BigInt *dest, const TEE_BigInt *op, size_t bits); 237 238 /** 239 * @brief Obtains the <b>bitIndex</b> bit of the natural binary representation of |src|. 240 * 241 * @param src Indicates the pointer to the integer. 242 * @param bitIndex Indicates the offset of the bit to read, starting from offset <b>0</b> of the least significant bit. 243 * 244 * @return Returns the Boolean value of <b>bitIndexth</b> in |src|. The value <b>true</b> represents a <b>1</b>, 245 * and <b>false</b> represents a <b>0</b>. 246 * 247 * @since 20 248 */ 249 bool TEE_BigIntGetBit(const TEE_BigInt *src, uint32_t bitIndex); 250 251 /** 252 * @brief Obtains the number of bits in the natural binary representation of |src|, 253 * that is, the magnitude of <b>src</b>. 254 * 255 * @param src Indicates the pointer to the integer. 256 * 257 * @return Returns <b>0</b> if <b>src</b> is <b>0</b>. 258 * Returns the number of bits in the natural binary representation of <b>src</b>. 259 * 260 * @since 20 261 */ 262 uint32_t TEE_BigIntGetBitCount(const TEE_BigInt *src); 263 264 /** 265 * @brief Sets the first bit of <b>bitIndex</b> in the natural binary representation of <b>op</b> to 266 * <b>1</b> or <b>0</b>. 267 * 268 * @param op Indicates the pointer to the integer. 269 * @param bitIndex Indicates the offset of the bit to set, starting from offset <b>0</b> of the least significant bit. 270 * @param value Indicates the bit value to set. The value <b>true</b> represents a <b>1</b>, and the value <b>false</b> 271 * represents a <b>0</b>. 272 * 273 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 274 * Returns <b>TEE_ERROR_OVERFLOW bitIndexth</b> if the <b>bitIndexth</b> bit is larger than the allocated bit 275 * length of <b>op</b>. 276 * 277 * @since 20 278 */ 279 TEE_Result TEE_BigIntSetBit(TEE_BigInt *op, uint32_t bitIndex, bool value); 280 281 /** 282 * @brief Assigns the value of <b>src</b> to <b>dest</b>. 283 * 284 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> to be assigned. 285 * @param src Indicates the pointer to the source operand. 286 * 287 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 288 * Returns <b>TEE_ERROR_OVERFLOW</b> if the <b>dest</b> operand cannot hold the value of <b>src</b>. 289 * 290 * @since 20 291 */ 292 TEE_Result TEE_BigIntAssign(TEE_BigInt *dest, const TEE_BigInt *src); 293 294 /** 295 * @brief Assigns the value of <b>src</b> to <b>dest</b>. 296 * 297 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> to be assigned. 298 * @param src Indicates the pointer to the source operand. 299 * 300 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 301 * Returns <b>TEE_ERROR_OVERFLOW</b> if the <b>dest</b> operand cannot hold the value of <b>src</b>. 302 * 303 * @since 20 304 */ 305 TEE_Result TEE_BigIntAbs(TEE_BigInt *dest, const TEE_BigInt *src); 306 307 /** 308 * @brief Computes dest = op1 + op2. 309 * 310 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the sum of <b>op1</b> and <b>op2</b>. 311 * @param op1 Indicates the pointer to the first operand. 312 * @param op2 Indicates the pointer to the second operand. 313 * 314 * @since 20 315 */ 316 void TEE_BigIntAdd(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); 317 318 /** 319 * @brief Computes dest = op1 – op2. 320 * 321 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the difference between <b>op1</b> 322 * and <b>op2</b>. 323 * @param op1 Indicates the pointer to the first operand. 324 * @param op2 Indicates the pointer to the second operand. 325 * 326 * @since 20 327 */ 328 void TEE_BigIntSub(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); 329 330 /** 331 * @brief Negates an operand: dest = –op. 332 * 333 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result –op. 334 * @param op Indicates the pointer to the operand to be negated. 335 * 336 * @since 20 337 */ 338 void TEE_BigIntNeg(TEE_BigInt *dest, const TEE_BigInt *op); 339 340 /** 341 * @brief Computes dest = op1 * op2. 342 * 343 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the product of <b>op1</b> and <b>op2</b>. 344 * @param op1 Indicates the pointer to the first operand. 345 * @param op2 Indicates the pointer to the second operand. 346 * 347 * @since 20 348 */ 349 void TEE_BigIntMul(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); 350 351 /** 352 * @brief Computes dest = op * op. 353 * 354 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result op * op. 355 * @param op Indicates the pointer to the operand to be squared. 356 * 357 * @since 20 358 */ 359 void TEE_BigIntSquare(TEE_BigInt *dest, const TEE_BigInt *op); 360 361 /** 362 * @brief Computes <b>dest_r</b> and <b>dest_q</b> to make op1 = dest_q* op2 + dest_r. 363 * 364 * @param dest_q Indicates the pointer to the <b>TEE_BigInt</b> that holds the quotient. 365 * @param dest_r Indicates the pointer to the <b>TEE_BigInt</b> that holds the remainder. 366 * @param op1 Indicates the pointer to the first operand, which is the dividend. 367 * @param op2 Indicates the pointer to the second operand, which is the divisor. 368 * 369 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 370 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if at least one parameter is null. 371 * 372 * @since 20 373 */ 374 void TEE_BigIntDiv(TEE_BigInt *dest_q, TEE_BigInt *dest_r, const TEE_BigInt *op1, const TEE_BigInt *op2); 375 376 /** 377 * @brief Computes dest = op (mod n) to make 0 <= dest < n. 378 * 379 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result op (mod n). 380 * @param op Indicates the pointer to the operand to be reduced mod n. 381 * @param n [IN] Indicates the pointer to the modulus, which must be greater than 1. 382 * 383 * @since 20 384 */ 385 void TEE_BigIntMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); 386 387 /** 388 * @brief Computes dest = (op1 + op2) (mod n). 389 * 390 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result op (op1 + op2)(mod n). 391 * @param op1 Indicates the pointer to the first operand. 392 * @param op2 Indicates the pointer to the second operand. 393 * @param n Indicates the pointer to the modulus, which must be greater than 1. 394 * 395 * @since 20 396 */ 397 void TEE_BigIntAddMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); 398 399 /** 400 * @brief Computes dest = (op1 – op2) (mod n). 401 * 402 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result op (op1 – op2)(mod n). 403 * @param op1 Indicates the pointer to the first operand. 404 * @param op2 Indicates the pointer to the second operand. 405 * @param n Indicates the pointer to the modulus, which must be greater than 1. 406 * 407 * @since 20 408 */ 409 void TEE_BigIntSubMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); 410 411 /** 412 * @brief Computes dest = (op1* op2)(mod n). 413 * 414 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result op (op1 * op2)(mod n). 415 * @param op1 Indicates the pointer to the first operand. 416 * @param op2 Indicates the pointer to the second operand. 417 * @param n Indicates the pointer to the modulus, which must be greater than 1. 418 * 419 * @since 20 420 */ 421 void TEE_BigIntMulMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); 422 423 /** 424 * @brief Computes dest = (op * op) (mod n). 425 * 426 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result op (op * op)(mod n). 427 * @param op Indicates the pointer to the operand. 428 * @param n [IN] Indicates the pointer to the modulus, which must be greater than 1. 429 * 430 * @since 20 431 */ 432 void TEE_BigIntSquareMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); 433 434 /** 435 * @brief Computes <b>dest</b> to make dest* op = 1 (mod n). 436 * 437 * @param dest Indicates the pointer to the <b>TEE_BigInt</b> that holds the result (op^–1)(mod n). 438 * @param op Indicates the pointer to the operand. 439 * @param n [IN] Indicates the pointer to the modulus, which must be greater than 1. 440 * 441 * @since 20 442 */ 443 void TEE_BigIntInvMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); 444 445 /** 446 * @brief Checks whether gcd(op1, op2) == 1. 447 * 448 * @param op1 Indicates the pointer to the first operand. 449 * @param op2 Indicates the pointer to the second operand. 450 * 451 * @return Returns <b>true</b> if gcd(op1, op2) == 1. 452 * Returns <b>false</b> if gcd(op1, op2) != 1. 453 * 454 * @since 20 455 */ 456 bool TEE_BigIntRelativePrime(const TEE_BigInt *op1, const TEE_BigInt *op2); 457 458 /** 459 * @brief Computes the greatest common divisor of <b>op1</b> and <b>op2</b>. 460 * 461 * @param gcd Indicates the pointer to the <b>TEE_BigInt</b> that holds the greatest common divisor of <b>op1</b> 462 * and <b>op2</b>. 463 * @param u Indicates the pointer to the <b>TEE_BigInt</b> that holds the first coefficient. 464 * @param v Indicates the pointer to the <b>TEE_BigInt</b> that holds the second coefficient. 465 * @param op1 Indicates the pointer to the first operand. 466 * @param op2 Indicates the pointer to the second operand. 467 * 468 * @since 20 469 */ 470 void TEE_BigIntComputeExtendedGcd(TEE_BigInt *gcd, TEE_BigInt *u, TEE_BigInt *v, const TEE_BigInt *op1, 471 const TEE_BigInt *op2); 472 /** 473 * @brief Performs a probabilistic primality test on <b>op</b>. 474 * 475 * @param op Indicates the pointer to the candidate number that is tested for primality. 476 * @param confidenceLevel Indicates the expected confidence level for a non-conclusive test. 477 * 478 * @return Returns <b>0</b> if <b>op</b> is a composite number. 479 * Returns <b>1</b> if <b>op</b> is a prime number. 480 * Returns <b>–1</b> if the test is non-conclusive but the probability that <b>op</b> is composite is 481 * less than 2^(-confidenceLevel). 482 * 483 * @since 20 484 */ 485 int32_t TEE_BigIntIsProbablePrime(const TEE_BigInt *op, uint32_t confidenceLevel); 486 487 /** 488 * @brief Converts <b>src</b> into a representation suitable for doing fast modular multiplication. 489 * 490 * @param dest Indicates the pointer to an initialized <b>TEE_BigIntFMM</b> memory area. 491 * @param src Indicates the pointer to the <b>TEE_BigInt</b> to convert. 492 * @param n Indicates the pointer to the modulus. 493 * @param context Indicates the pointer to the context that is previously initialized using 494 * {@link TEE_BigIntInitFMMContext1}. 495 * 496 * @since 20 497 */ 498 void TEE_BigIntConvertToFMM(TEE_BigIntFMM *dest, const TEE_BigInt *src, const TEE_BigInt *n, 499 const TEE_BigIntFMMContext *context); 500 501 /** 502 * @brief Converts <b>src</b> in the fast modular multiplication representation back to a 503 * <b>TEE_BigInt</b> representation. 504 * 505 * @param dest Indicates the pointer to an initialized <b>TEE_BigIntFMM</b> memory area to store the converted result. 506 * @param src Indicates the pointer to a <b>TEE_BigIntFMM</b> holding the value in the fast modular multiplication 507 * representation. 508 * @param n Indicates the pointer to the modulus. 509 * @param context Indicates the pointer to the context that is previously initialized using 510 * {@link TEE_BigIntInitFMMContext1}. 511 * 512 * @since 20 513 */ 514 void TEE_BigIntConvertFromFMM(TEE_BigInt *dest, const TEE_BigIntFMM *src, const TEE_BigInt *n, 515 const TEE_BigIntFMMContext *context); 516 517 /** 518 * @brief Computes dest = op1* op2 in the fast modular multiplication representation. 519 * 520 * @param dest Indicates the pointer to the <b>TEE_BigIntFMM</b> that holds the result op1* op2. 521 * @param op1 Indicates the pointer to the first operand. 522 * @param op2 Indicates the pointer to the second operand. 523 * @param n Indicates the pointer to the modulus. 524 * @param context Indicates the pointer to the context that is previously initialized using 525 * {@link TEE_BigIntInitFMMContext1}. 526 * 527 * @since 20 528 */ 529 void TEE_BigIntComputeFMM(TEE_BigIntFMM *dest, const TEE_BigIntFMM *op1, const TEE_BigIntFMM *op2, const TEE_BigInt *n, 530 const TEE_BigIntFMMContext *context); 531 532 /** 533 * @brief Computes dest = (op1 ^ op2)(mod n). 534 * 535 * @param des Indicates the pointer to the <b>TEE_BigInt</b> that holds the result (op1 ^ op2)(mod n). 536 * @param op1 Indicates the pointer to the first operand. 537 * @param op2 Indicates the pointer to the second operand. 538 * @param n Indicates the pointer to the modulus. 539 * @param context Indicates the pointer to the context that is previously initialized using 540 * {@link TEE_BigIntInitFMMContext1} or initialized to null. 541 * 542 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 543 * Returns <b>TEE_ERROR_NOT_SUPPORTED</b> if the value of <b>n</b> is not supported. 544 * 545 * @since 20 546 */ 547 TEE_Result TEE_BigIntExpMod(TEE_BigInt *des, TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n, 548 TEE_BigIntFMMContext *context); 549 550 #ifdef __cplusplus 551 } 552 #endif 553 554 #endif 555 /** @} */