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_srp 9 @{ 10 */ 11 12 /*! 13 @file 14 @brief This file contains all of the CryptoCell SRP APIs, their enums and 15 definitions. 16 */ 17 18 #ifndef _MBEDTLS_CC_SRP_H 19 #define _MBEDTLS_CC_SRP_H 20 21 #include "cc_pal_types.h" 22 #include "cc_error.h" 23 #include "cc_pka_defs_hw.h" 24 #include "cc_hash_defs.h" 25 #include "cc_rnd_common.h" 26 27 28 #ifdef __cplusplus 29 extern "C" 30 { 31 #endif 32 33 /*!\internal The following describes the SRP APIs usage for the Device and the Accessory :* 34 35 Device (User) Accessory (Host) 36 * -------------- ----------------- 37 38 1. CC_SRP_HK_INIT(CC_SRP_USER, .......) CC_SRP_HK_INIT(CC_SRP_HOST, .....) 39 40 2. CC_SrpPwdVerCreate(..) 41 42 3. CC_SrpUserPubKeyCreate(..) CC_SrpHostPubKeyCreate(..) 43 44 4. CC_SrpUserProofCalc(..) 45 46 5. CC_SrpHostProofVerifyAndCalc(..) 47 48 6. CC_SrpUserProofVerify(..) 49 50 7. CC_SrpClear(..) CC_SrpClear(..) 51 52 */ 53 54 /************************ Defines ******************************/ 55 /* The SRP modulus sizes. */ 56 /*! SRP modulus size of 1024 bits. */ 57 #define CC_SRP_MODULUS_SIZE_1024_BITS 1024 58 /*! SRP modulus size of 1536 bits. */ 59 #define CC_SRP_MODULUS_SIZE_1536_BITS 1536 60 /*! SRP modulus size of 2048 bits. */ 61 #define CC_SRP_MODULUS_SIZE_2048_BITS 2048 62 /*! SRP modulus size of 3072 bits. */ 63 #define CC_SRP_MODULUS_SIZE_3072_BITS 3072 64 65 /*! The maximal size of the SRP modulus in bits. */ 66 #define CC_SRP_MAX_MODULUS_IN_BITS CC_SRP_MODULUS_SIZE_3072_BITS 67 /*! The maximal size of the SRP modulus in bytes. */ 68 #define CC_SRP_MAX_MODULUS (CC_SRP_MAX_MODULUS_IN_BITS/CC_BITS_IN_BYTE) 69 /*! The maximal size of the SRP modulus in words. */ 70 #define CC_SRP_MAX_MODULUS_IN_WORDS (CC_SRP_MAX_MODULUS_IN_BITS/CC_BITS_IN_32BIT_WORD) 71 72 /* SRP private number size range. */ 73 /*! The minimal size of the SRP private number in bits. */ 74 #define CC_SRP_PRIV_NUM_MIN_SIZE_IN_BITS (256) 75 /*! The minimal size of the SRP private number in bytes. */ 76 #define CC_SRP_PRIV_NUM_MIN_SIZE (CC_SRP_PRIV_NUM_MIN_SIZE_IN_BITS/CC_BITS_IN_BYTE) 77 /*! The minimal size of the SRP private number in words. */ 78 #define CC_SRP_PRIV_NUM_MIN_SIZE_IN_WORDS (CC_SRP_PRIV_NUM_MIN_SIZE_IN_BITS/CC_BITS_IN_32BIT_WORD) 79 /*! The maximal size of the SRP private number in bits. */ 80 #define CC_SRP_PRIV_NUM_MAX_SIZE_IN_BITS (CC_SRP_MAX_MODULUS_IN_BITS) 81 /*! The maximal size of the SRP private number in bytes. */ 82 #define CC_SRP_PRIV_NUM_MAX_SIZE (CC_SRP_PRIV_NUM_MAX_SIZE_IN_BITS/CC_BITS_IN_BYTE) 83 /*! The maximal size of the SRP private number in words. */ 84 #define CC_SRP_PRIV_NUM_MAX_SIZE_IN_WORDS (CC_SRP_PRIV_NUM_MAX_SIZE_IN_BITS/CC_BITS_IN_32BIT_WORD) 85 86 /*! The maximal size of the SRP hash digest in words. */ 87 #define CC_SRP_MAX_DIGEST_IN_WORDS CC_HASH_RESULT_SIZE_IN_WORDS 88 /*! The maximal size of the SRP hash digest in bytes. */ 89 #define CC_SRP_MAX_DIGEST (CC_SRP_MAX_DIGEST_IN_WORDS*CC_32BIT_WORD_SIZE) 90 91 /*! The minimal size of the salt in bytes. */ 92 #define CC_SRP_MIN_SALT_SIZE (8) 93 /*! The minimal size of the salt in words. */ 94 #define CC_SRP_MIN_SALT_SIZE_IN_WORDS (CC_SRP_MIN_SALT_SIZE/CC_32BIT_WORD_SIZE) 95 /*! The maximal size of the salt in bytes. */ 96 #define CC_SRP_MAX_SALT_SIZE (64) 97 /*! The maximal size of the salt in words. */ 98 #define CC_SRP_MAX_SALT_SIZE_IN_WORDS (CC_SRP_MAX_SALT_SIZE/CC_32BIT_WORD_SIZE) 99 100 /************************ Typedefs ****************************/ 101 /*! The definition of the SRP modulus buffer. */ 102 typedef uint8_t mbedtls_srp_modulus[CC_SRP_MAX_MODULUS]; 103 104 /*! The definition of the SRP digest buffer. */ 105 typedef uint8_t mbedtls_srp_digest[CC_SRP_MAX_DIGEST]; 106 107 /*! The definition of the SRP session key. */ 108 typedef uint8_t mbedtls_srp_sessionKey[2*CC_SRP_MAX_DIGEST]; 109 110 /************************ Enums ********************************/ 111 112 /*! Supported SRP versions. */ 113 typedef enum { 114 /*! SRP version 3. */ 115 CC_SRP_VER_3 = 0, 116 /*! SRP version 6. */ 117 CC_SRP_VER_6 = 1, 118 /*! SRP version 6A. */ 119 CC_SRP_VER_6A = 2, 120 /*! SRP version HK. */ 121 CC_SRP_VER_HK = 3, 122 /*! The maximal number of supported versions. */ 123 CC_SRP_NumOfVersions, 124 /*! Reserved.*/ 125 CC_SRP_VersionLast= 0x7FFFFFFF, 126 }mbedtls_srp_version_t; 127 128 /*! SRP entity types. */ 129 typedef enum { 130 /*! The host entity, also known as server, verifier, or accessory. */ 131 CC_SRP_HOST = 1, 132 /*! The user entity, also known as client, or device. */ 133 CC_SRP_USER = 2, 134 /*! The maximal number of entities types. */ 135 CC_SRP_NumOfEntityType, 136 /*! Reserved. */ 137 CC_SRP_EntityLast= 0x7FFFFFFF, 138 }mbedtls_srp_entity_t; 139 140 /************************ Structs ******************************/ 141 142 /*! 143 @brief Group parameters for the SRP. 144 145 Defines the modulus and the generator used. 146 */ 147 typedef struct mbedtls_srp_group_param { 148 /*! The SRP modulus. */ 149 mbedtls_srp_modulus modulus; 150 /*! The SRP generator. */ 151 uint8_t gen; 152 /*! The size of the SRP modulus in bits. */ 153 size_t modSizeInBits; 154 /*! The valid SRP Np. */ 155 uint32_t validNp; 156 /*! The SRP Np buffer. */ 157 uint32_t Np[CC_PKA_BARRETT_MOD_TAG_BUFF_SIZE_IN_WORDS]; 158 }mbedtls_srp_group_param; 159 160 /************************ context Structs ******************************/ 161 /*! The SRP context prototype */ 162 typedef struct mbedtls_srp_context { 163 /*! The SRP entitiy type. */ 164 mbedtls_srp_entity_t srpType; 165 /*! The SRP version. */ 166 mbedtls_srp_version_t srpVer; 167 /*! The group parameter including the modulus information. */// N, g, Np 168 mbedtls_srp_group_param groupParam; 169 /*! The hash mode. */ 170 CCHashOperationMode_t hashMode; 171 /*! The hash digest size. */ 172 size_t hashDigestSize; 173 /*! The session key size. */ 174 size_t sessionKeySize; 175 /*! A pointer to the RND context. */ 176 CCRndContext_t *pRndCtx; 177 /*! The modulus. */ // a or b 178 mbedtls_srp_modulus ephemPriv; 179 /*! The modulus size. */ 180 size_t ephemPrivSize; 181 /*! The user-name digest. */// M 182 mbedtls_srp_digest userNameDigest; 183 /*! The cred digest. */ // p 184 mbedtls_srp_digest credDigest; 185 /*! The SRP K multiplier. */ // k multiplier 186 mbedtls_srp_digest kMult; 187 }mbedtls_srp_context; 188 189 190 /************************ SRP common Functions **********************/ 191 /*****************************************************************************/ 192 /*! 193 @brief This function initiates the SRP context. 194 195 @return \c CC_OK on success. 196 @return A non-zero value on failure as defined in mbedtls_cc_srp_error.h. 197 */ 198 CIMPORT_C CCError_t mbedtls_srp_init( 199 /*! [in] The SRP entity type. */ 200 mbedtls_srp_entity_t srpType, 201 /*! [in] The SRP version. */ 202 mbedtls_srp_version_t srpVer, 203 /*! [in] A pointer to the SRP modulus, BE Byte buffer. */ 204 mbedtls_srp_modulus srpModulus, 205 /*! [in] The SRP generator param. */ 206 uint8_t srpGen, 207 /*! [in] The size of the SRP modulus in bits. Valid values are: 1024 208 bits, 1536 bits, 2048 bits, or 3072 bits. */ 209 size_t modSizeInBits, 210 /*! [in] The hash mode. */ 211 CCHashOperationMode_t hashMode, 212 /*! [in] A pointer to the username. */ 213 uint8_t *pUserName, 214 /*! [in] The size of the username buffer. Must be larger than 0. */ 215 size_t userNameSize, 216 /*! [in] A pointer to the user password. */ 217 uint8_t *pPwd, 218 /*! [in] The size of the user-password buffer. Must be larger than 0 219 if \p pPwd is valid. */ 220 size_t pwdSize, 221 /*! [in] A pointer to the RND context. */ 222 CCRndContext_t *pRndCtx, 223 /*! [out] A pointer to the SRP host context. */ 224 mbedtls_srp_context *pCtx 225 ); 226 227 /*! Macro definition for a specific SRP-initialization function. */ 228 #define CC_SRP_HK_INIT(srpType, srpModulus, srpGen, modSizeInBits, pUserName, userNameSize, pPwd, pwdSize, pRndCtx, pCtx) \ 229 mbedtls_srp_init(srpType, CC_SRP_VER_HK, srpModulus, srpGen, modSizeInBits, CC_HASH_SHA512_mode, pUserName, userNameSize, pPwd, pwdSize, pRndCtx, pCtx) 230 231 232 /*****************************************************************************/ 233 /*! 234 @brief This function calculates \p pSalt and \p pwdVerifier. 235 236 @return \c CC_OK on success. 237 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h, 238 cc_rnd_error.h. 239 */ 240 CIMPORT_C CCError_t mbedtls_srp_pwd_ver_create( 241 /*! [in] The size of the random salt to generate. The range is between 242 #CC_SRP_MIN_SALT_SIZE and #CC_SRP_MAX_SALT_SIZE. */ 243 size_t saltSize, 244 /*! [out] A pointer to the \p pSalt number (s). */ 245 uint8_t *pSalt, 246 /*! [out] A pointer to the password verifier (v). */ 247 mbedtls_srp_modulus pwdVerifier, 248 /*! [out] A pointer to the SRP context. */ 249 mbedtls_srp_context *pCtx 250 ); 251 252 253 /*****************************************************************************/ 254 /*! 255 @brief This function clears the SRP context. 256 257 @return \c CC_OK on success. 258 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h. 259 */ 260 CIMPORT_C CCError_t mbedtls_srp_clear( 261 /*! [in/out] A pointer to the SRP context. */ 262 mbedtls_srp_context *pCtx 263 ); 264 265 266 /************************ SRP Host Functions **********************/ 267 /*****************************************************************************/ 268 /*! 269 @brief This function generates the public and private host ephemeral keys, 270 known as B and b in <em>RFC 5054 Using the Secure Remote Password (SRP) 271 Protocol for TLS Authentication</em>. 272 273 @return \c CC_OK on success. 274 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h or 275 cc_rnd_error.h. 276 */ 277 CIMPORT_C CCError_t mbedtls_srp_host_pub_key_create( 278 /*! [in] The size of the generated ephemeral private key (b). The range 279 is between #CC_SRP_PRIV_NUM_MIN_SIZE and #CC_SRP_PRIV_NUM_MAX_SIZE */ 280 size_t ephemPrivSize, 281 /*! [in] A pointer to the verifier (v). */ 282 mbedtls_srp_modulus pwdVerifier, 283 /*! [out] A pointer to the host ephemeral public key (B). */ 284 mbedtls_srp_modulus hostPubKeyB, 285 /*! [in/out] A pointer to the SRP context. */ 286 mbedtls_srp_context *pCtx 287 ); 288 289 290 /*! 291 @brief This function verifies the user proof, and calculates the host-message 292 proof. 293 294 @return \c CC_OK on success. 295 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h. 296 */ 297 CIMPORT_C CCError_t mbedtls_srp_host_proof_verify_and_calc( 298 /*! [in] The size of the random salt. The range is between 299 #CC_SRP_MIN_SALT_SIZE and #CC_SRP_MAX_SALT_SIZE. */ 300 size_t saltSize, 301 /*! [in] A pointer to the pSalt number. */ 302 uint8_t *pSalt, 303 /*! [in] A pointer to the password verifier (v). */ 304 mbedtls_srp_modulus pwdVerifier, 305 /*! [in] A pointer to the ephemeral public key of the user (A). */ 306 mbedtls_srp_modulus userPubKeyA, 307 /*! [in] A pointer to the ephemeral public key of the host (B). */ 308 mbedtls_srp_modulus hostPubKeyB, 309 /*! [in] A pointer to the SRP user-proof buffer (M1). */ 310 mbedtls_srp_digest userProof, 311 /*! [out] A pointer to the SRP host-proof buffer (M2). */ 312 mbedtls_srp_digest hostProof, 313 /*! [out] A pointer to the SRP session key (K). */ 314 mbedtls_srp_sessionKey sessionKey, 315 /*! [in] A pointer to the SRP context. */ 316 mbedtls_srp_context *pCtx 317 ); 318 319 320 321 /************************ SRP User Functions **********************/ 322 /*****************************************************************************/ 323 /*! 324 @brief This function generates public and private user ephemeral keys, known 325 as A and a in <em>RFC 5054 Using the Secure Remote Password (SRP) Protocol 326 for TLS Authentication</em>. 327 328 @return \c CC_OK on success. 329 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h or 330 cc_rnd_error.h. 331 */ 332 CIMPORT_C CCError_t mbedtls_srp_user_pub_key_create( 333 /*! [in] The size of the generated ephemeral private key (a). The range 334 is between #CC_SRP_PRIV_NUM_MIN_SIZE and #CC_SRP_PRIV_NUM_MAX_SIZE. 335 The size must be 32 bit aligned */ 336 size_t ephemPrivSize, 337 /*! [out] A pointer to the user ephemeral public key (A). */ 338 mbedtls_srp_modulus userPubKeyA, 339 /*! [in/out] A pointer to the SRP context. */ 340 mbedtls_srp_context *pCtx 341 ); 342 343 344 /*****************************************************************************/ 345 /*! 346 @brief This function calculates the user proof. 347 348 @return \c CC_OK on success. 349 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h. 350 */ 351 CIMPORT_C CCError_t mbedtls_srp_user_proof_calc( 352 /*! [in] The size of the random salt. The range is between 353 #CC_SRP_MIN_SALT_SIZE and #CC_SRP_MAX_SALT_SIZE. */ 354 size_t saltSize, 355 /*! [in] A pointer to the pSalt number. */ 356 uint8_t *pSalt, 357 /*! [in] A pointer to the public ephmeral key of the user (A). */ 358 mbedtls_srp_modulus userPubKeyA, 359 /*! [in] A pointer to the public ephmeral key of the host (B). */ 360 mbedtls_srp_modulus hostPubKeyB, 361 /*! [out] A pointer to the SRP user proof buffer (M1). */ 362 mbedtls_srp_digest userProof, 363 /*! [out] A pointer to the SRP session key (K). */ 364 mbedtls_srp_sessionKey sessionKey, 365 /*! [out] A pointer to the SRP context. */ 366 mbedtls_srp_context *pCtx 367 ); 368 369 /*****************************************************************************/ 370 /*! 371 @brief This function verifies the host proof. 372 373 @return \c CC_OK on success. 374 @return A non-zero value on failure, as defined in mbedtls_cc_srp_error.h. 375 */ 376 CIMPORT_C CCError_t mbedtls_srp_user_proof_verify( 377 /*! [in] A pointer to the SRP session key (K). */ 378 mbedtls_srp_sessionKey sessionKey, 379 /*! [in] A pointer to the public ephmeral key of the user (A). */ 380 mbedtls_srp_modulus userPubKeyA, 381 /*! [in] A pointer to the SRP user proof buffer (M1). */ 382 mbedtls_srp_digest userProof, 383 /*! [in] A pointer to the SRP host proof buffer (M2). */ 384 mbedtls_srp_digest hostProof, 385 /*! [out] A pointer to the SRP user context. */ 386 mbedtls_srp_context *pCtx 387 ); 388 389 390 #ifdef __cplusplus 391 } 392 #endif 393 394 /*! 395 @} 396 */ 397 #endif /* #ifndef _MBEDTLS_CC_SRP_H */ 398
