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_ecies 9 @{ 10 */ 11 12 /*! 13 @file mbedtls_cc_ecies.h 14 15 @brief This file contains the CryptoCell Elliptic Curve Integrated Encryption Scheme (ECIES) APIs. 16 */ 17 18 #ifndef _MBEDTLS_CC_ECIES_H 19 #define _MBEDTLS_CC_ECIES_H 20 21 22 #include "cc_ecpki_types.h" 23 #include "cc_pal_types_plat.h" 24 #include "cc_kdf.h" 25 #include "mbedtls_cc_hkdf.h" 26 #include "mbedtls/ecp.h" 27 28 #ifdef __cplusplus 29 extern "C" 30 { 31 #endif 32 /*! The maximal length of the ECIES cipher in bytes. */ 33 #define MBEDTLS_ECIES_MAX_CIPHER_LEN_BYTES ((2*CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS + 1) * sizeof(int)) 34 /*! The minimal length of the ECIES buffer in bytes. */ 35 #define MBEDTLS_ECIES_MIN_BUFF_LEN_BYTES (sizeof(CCEciesTempData_t)) 36 37 /*! 38 @brief A macro for creating and encrypting a secret key. 39 40 For a description of the parameters see ::mbedtls_ecies_kem_encrypt_full. 41 */ 42 #define mbedtls_ecies_kem_encrypt(pGrp, pRecipPublKey, kdfDerivMode, kdfHashMode, \ 43 isSingleHashMode, pSecrKey, secrKeySize, \ 44 pCipherData, pCipherDataSize, pBuff, buffLen, \ 45 f_rng, p_rng) \ 46 mbedtls_ecies_kem_encrypt_full((pGrp), (pRecipPublKey), (kdfDerivMode), (kdfHashMode), \ 47 (isSingleHashMode), NULL, NULL, (pSecrKey), (secrKeySize), \ 48 (pCipherData), (pCipherDataSize), (pBuff), (buffLen), \ 49 f_rng, p_rng) 50 51 /*! 52 @brief This function creates and encrypts (encapsulates) the secret key of 53 required size, according to <em>ISO/IEC 18033-2:2006: Information technology 54 -- Security techniques -- Encryption algorithms -- Part 2: Asymmetric 55 ciphers</em>, ECIES-KEM Encryption. 56 57 To call this function in applications, the ::mbedtls_ecies_kem_encrypt macro 58 definition must be used. The function itself has the additional input of the 59 external ephemeral key pair, used only for testing purposes. 60 61 @note Use KDF2 function mode for compliance with <em>X9.63-2011: Public Key 62 Cryptography for the Financial Services Industry – Key Agreement and Key 63 Transport Using Elliptic Curve Cryptography</em>. \par 64 65 @note The term "sender" indicates an entity that creates and 66 encapsulates the secret key using this function. The term "recipient" 67 indicates another entity which receives and decrypts the secret key. \par 68 69 @note All public and private keys that are used must relate to the same EC 70 Domain. \par 71 72 @note The user must verify that the public key of the recipient is 73 on the elliptic curve before it is used in this function. 74 75 @return CCError_t \c 0 on success. 76 */ 77 CCError_t mbedtls_ecies_kem_encrypt_full( 78 /*! [in] The ECP group to use. */ 79 mbedtls_ecp_group *pGrp, 80 /*! [in] A pointer to the public key of the recipient. */ 81 mbedtls_ecp_point *pRecipUzPublKey, 82 /*! [in] The KDF function mode to use: KDF1 or KDF2. For more 83 information, see CCKdfDerivFuncMode_t() in cc_kdf.h. */ 84 CCKdfDerivFuncMode_t kdfDerivMode, 85 /*! [in] The used hash function. */ 86 mbedtls_hkdf_hashmode_t kdfHashMode, 87 /*! [in] The specific ECIES mode, according to <em>ISO/IEC 18033-2:2006: 88 Information technology -- Security techniques -- Encryption algorithms 89 -- Part 2: Asymmetric ciphers</em> - section 10.2: 0: Not-single hash, 90 or 1: Single hash. */ 91 uint32_t isSingleHashMode, 92 /*! [in] A pointer to the ephemeral public key related to the private 93 key. Must be set to NULL if \p pExtEphUzPrivateKey = NULL. */ 94 mbedtls_ecp_point *pExtEphUzPublicKey, 95 /*! [in] The pointer to the external ephemeral private key. This key 96 is used only for testing the function. In regular use, the pointer 97 should be set to NULL and then the random key-pair should be generated 98 internally. */ 99 mbedtls_mpi *pExtEphUzPrivateKey, 100 /*! [in] A pointer to the buffer for the secret-key data to be 101 generated. */ 102 uint8_t *pSecrKey, 103 /*! [in] The size of the secret-key data in bytes. */ 104 size_t secrKeySize, 105 /*! [in] A pointer to the encrypted cipher text. */ 106 uint8_t *pCipherData, 107 /*! [in/out] In: A pointer to the size of the buffer for CipherData 108 output, or Out: The size of the buffer for CipherData output in 109 bytes. */ 110 size_t *pCipherDataSize, 111 /*! [in] A pointer to the temporary buffer. */ 112 void *pBuff, 113 /*! [in] The size of the buffer pointed by \p pBuff. Must not be less 114 than #MBEDTLS_ECIES_MIN_BUFF_LEN_BYTES. */ 115 size_t buffLen, 116 /*! [in] The RNG function required for generating a key pair when 117 \p pExtEphUzPublicKey and \p pExtEphUzPrivateKey are NULL */ 118 int (*f_rng)(void *, unsigned char *, size_t), 119 /*! [in] The RNG parameter. */ 120 void *p_rng 121 ); 122 123 /*! 124 @brief This function decrypts the encapsulated secret key passed by the 125 sender, according to <em>ISO/IEC 18033-2:2006: Information technology -- 126 Security techniques -- Encryption algorithms -- Part 2: Asymmetric 127 ciphers</em>, sec. 10.2.4 - ECIES-KEM Decryption. 128 129 @note The KDF2 function mode must be used for compliance with <em>X9.63-2011: 130 Public Key Cryptography for the Financial Services Industry – Key Agreement 131 and Key Transport Using Elliptic Curve Cryptograph</em>. \par 132 133 @note The term "sender" indicates an entity that creates and 134 encapsulates the secret key using this function. The term "recipient" 135 indicates another entity which receives and decrypts the secret key. \par 136 137 @note All public and private keys that are used must relate to the same EC 138 Domain. \par 139 140 @return CCError_t \c 0 on success. 141 */ 142 CCError_t mbedtls_ecies_kem_decrypt( 143 /*! [in] The ECP group to use. */ 144 mbedtls_ecp_group *pGrp, 145 /*! [in] A pointer to the private key of the recipient. */ 146 mbedtls_mpi *pRecipUzPrivKey, 147 /*! [in] The KDF function mode to use: KDF1 or KDF2. For more 148 information, see CCKdfDerivFuncMode_t() in cc_kdf.h. */ 149 CCKdfDerivFuncMode_t kdfDerivMode, 150 /*! [in] The used hash function. */ 151 mbedtls_hkdf_hashmode_t kdfHashMode, 152 /*! [in] The specific ECIES mode definition: 0,1, according to 153 <em>ISO/IEC 18033-2:2006: Information technology -- Security techniques 154 -- Encryption algorithms -- Part 2: Asymmetric ciphers</em> - 155 section 10.2. */ 156 uint32_t isSingleHashMode, 157 /*! [in] A pointer to the received encrypted cipher data. */ 158 uint8_t *pCipherData, 159 /*! [in] The size of the cipher data in bytes. */ 160 size_t cipherDataSize, 161 /*! [in] A pointer to the buffer for the secret-key data to be 162 generated. */ 163 uint8_t *pSecrKey, 164 /*! [in] The size of the secret-key data in bytes. */ 165 size_t secrKeySize, 166 /*! [in] A pointer to the temporary buffer. */ 167 void *pBuff, 168 /*! [in] The size of the buffer pointed by \p pBuff. Must not be 169 less than #MBEDTLS_ECIES_MIN_BUFF_LEN_BYTES. */ 170 size_t buffLen 171 ); 172 173 174 #ifdef __cplusplus 175 } 176 #endif 177 178 /*! 179 @} 180 */ 181 #endif 182 183 184
