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 @addtogroup cc_lib 9 10 @{ 11 */ 12 13 /*! 14 @file 15 @brief This file contains all of the basic APIs of the CryptoCell library, 16 their enums and definitions. 17 */ 18 19 20 #ifndef __CC_LIB_H__ 21 #define __CC_LIB_H__ 22 23 #include "cc_pal_types.h" 24 #include "cc_rnd_common.h" 25 26 #ifdef __cplusplus 27 extern "C" 28 { 29 #endif 30 31 32 /*! Definitions for error returns from ::CC_LibInit or ::CC_LibFini functions. */ 33 typedef enum { 34 /*! Success.*/ 35 CC_LIB_RET_OK = 0, 36 /*! Illegal context pointer.*/ 37 CC_LIB_RET_EINVAL_CTX_PTR, 38 /*! Illegal work-buffer pointer.*/ 39 CC_LIB_RET_EINVAL_WORK_BUF_PTR, 40 /*! Error returned from the HAL layer.*/ 41 CC_LIB_RET_HAL, 42 /*! Error returned from the PAL layer.*/ 43 CC_LIB_RET_PAL, 44 /*! RND instantiation failed.*/ 45 CC_LIB_RET_RND_INST_ERR, 46 /*! Invalid peripheral ID. */ 47 CC_LIB_RET_EINVAL_PIDR, 48 /*! Invalid component ID. */ 49 CC_LIB_RET_EINVAL_CIDR, 50 /*! Error returned from AO write operation. */ 51 CC_LIB_AO_WRITE_FAILED_ERR, 52 /*! Reserved.*/ 53 CC_LIB_RESERVE32B = 0x7FFFFFFFL 54 } CClibRetCode_t; 55 56 57 /*! Internal definition for the product register. */ 58 #define DX_VERSION_PRODUCT_BIT_SHIFT 0x18UL 59 /*! Internal definition for the product register size. */ 60 #define DX_VERSION_PRODUCT_BIT_SIZE 0x8UL 61 62 63 64 /*! 65 @brief This function performs global initialization of the CryptoCell runtime 66 library. 67 68 It must be called once per CryptoCell cold-boot cycle. 69 Among other initializations, this function initializes the CTR-DRBG context, 70 including the TRNG seeding. An initialized DRBG context is required for 71 calling DRBG APIs, as well as asymmetric-cryptography key-generation and 72 signatures.\n 73 The primary context returned by this function can be used as a single global 74 context for all DRBG needs. Alternatively, other contexts may be initialized 75 and used with a more limited scope, for specific applications or specific 76 threads. 77 78 @note If used, the Mutexes are initialized by this API. Therefore, unlike 79 other APIs in the library, this API is not thread-safe. \par 80 @note The \p rndWorkBuff_ptr parameter can be NULL in case full entropy mode 81 is used. \par 82 83 @return \c CC_LIB_RET_OK on success. 84 @return A non-zero value on failure. 85 */ 86 CClibRetCode_t CC_LibInit( 87 /*! [in/out] A pointer to the RND context buffer allocated by the user. 88 The context is used to maintain the RND state as well as 89 pointers to a function used for random vector generation. 90 This context must be saved and provided as a parameter to 91 any API that uses the RND module.*/ 92 CCRndContext_t *rndContext_ptr, 93 /*! [in] A scratchpad for the work of the RND module. */ 94 CCRndWorkBuff_t *rndWorkBuff_ptr 95 ); 96 97 /*! 98 @brief This function finalizes library operations. 99 100 It performs the following operations: 101 <ul><li>Frees the associated resources (mutexes).</li> 102 <li>Calls the HAL and PAL terminate functions.</li> 103 <li>Cleans the DRBG context.</li></ul> 104 105 @return \c CC_LIB_RET_OK on success. 106 @return A non-zero value on failure. 107 */ 108 CClibRetCode_t CC_LibFini( 109 /*! [in/out] A pointer to the RND context buffer that was initialized 110 in #CC_LibInit.*/ 111 CCRndContext_t *rndContext_ptr 112 ); 113 114 #ifdef __cplusplus 115 } 116 #endif 117 118 /*! 119 @} 120 */ 121 122 #endif /*__CC_LIB_H__*/ 123
