crys_srp.h

00001 /**************************************************************************************
00002 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved         *
00003 *                                                                                     *
00004 * This file and the related binary are licensed under the following license:          *
00005 *                                                                                     *
00006 * ARM Object Code and Header Files License, v1.0 Redistribution.                      *
00007 *                                                                                     *
00008 * Redistribution and use of object code, header files, and documentation, without     *
00009 * modification, are permitted provided that the following conditions are met:         *
00010 *                                                                                     *
00011 * 1) Redistributions must reproduce the above copyright notice and the                *
00012 *    following disclaimer in the documentation and/or other materials                 *
00013 *    provided with the distribution.                                                  *
00014 *                                                                                     *
00015 * 2) Unless to the extent explicitly permitted by law, no reverse                     *
00016 *    engineering, decompilation, or disassembly of is permitted.                      *
00017 *                                                                                     *
00018 * 3) Redistribution and use is permitted solely for the purpose of                    *
00019 *    developing or executing applications that are targeted for use                   *
00020 *    on an ARM-based product.                                                         *
00021 *                                                                                     *
00022 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND                  *
00023 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT             *
00024 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,        *
00025 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
00026 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
00027 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED            *
00028 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR              *
00029 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF              *
00030 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING                *
00031 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS                  *
00032 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                        *
00033 **************************************************************************************/
00034 
00035 
00036 /*!
00037 @file
00038 @brief This file contains all of the enums and definitions that are used for the
00039        CRYS SRP APIs, as well as the APIs themselves.
00040 @defgroup crys_srp CryptoCell SRP APIs
00041 @{
00042 @ingroup cryptocell_api
00043 
00044 */
00045 #ifndef CRYS_SRP_H
00046 #define CRYS_SRP_H
00047 
00048 
00049 #include "ssi_pal_types.h"
00050 #include "crys_error.h"
00051 #include "crys_pka_defs_hw.h"
00052 #include "crys_hash.h"
00053 #include "crys_rnd.h"
00054 
00055 
00056 #ifdef __cplusplus
00057 extern "C"
00058 {
00059 #endif
00060 
00061 /*!\internal The following describes the SRP APIs usage for the Device and the Accessory :*
00062 
00063         Device (User)                       Accessory (Host)
00064 *      --------------                       -----------------
00065 
00066   1.    CRYS_SRP_HK_INIT(CRYS_SRP_USER, .......)        CRYS_SRP_HK_INIT(CRYS_SRP_HOST, .....)
00067 
00068   2.                                CRYS_SRP_PwdVerCreate(..)
00069 
00070   3.    CRYS_SRP_UserPubKeyCreate(..)               CRYS_SRP_HostPubKeyCreate(..)
00071 
00072   4.    CRYS_SRP_UserProofCalc(..)
00073 
00074   5.                                CRYS_SRP_HostProofVerifyAndCalc(..)
00075 
00076   6.    CRYS_SRP_UserProofVerify(..)
00077 
00078   7.    CRYS_SRP_Clear(..)                  CRYS_SRP_Clear(..)
00079 
00080  */
00081 
00082 /************************ Defines ******************************/
00083 /*! The SRP modulus sizes. */
00084 /*! 1024 bits modulus size. */
00085 #define CRYS_SRP_MODULUS_SIZE_1024_BITS   1024
00086 /*! 1536 bits modulus size. */
00087 #define CRYS_SRP_MODULUS_SIZE_1536_BITS   1536
00088 /*! 2048 bits modulus size. */
00089 #define CRYS_SRP_MODULUS_SIZE_2048_BITS   2048
00090 /*! 3072 bits modulus size. */
00091 #define CRYS_SRP_MODULUS_SIZE_3072_BITS   3072
00092 
00093 /*! Maximal modulus size in bits. */
00094 #define CRYS_SRP_MAX_MODULUS_IN_BITS        CRYS_SRP_MODULUS_SIZE_3072_BITS
00095 /*! Maximal modulus size in bytes. */
00096 #define CRYS_SRP_MAX_MODULUS            (CRYS_SRP_MAX_MODULUS_IN_BITS/SASI_BITS_IN_BYTE)
00097 /*! Maximal modulus size in words. */
00098 #define CRYS_SRP_MAX_MODULUS_IN_WORDS       (CRYS_SRP_MAX_MODULUS_IN_BITS/SASI_BITS_IN_32BIT_WORD)
00099 
00100 /*! The SRP private number size range. */
00101 /*! Minimal private number size in bits. */
00102 #define CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_BITS      (256)
00103 /*! Minimal private number size in bytes. */
00104 #define CRYS_SRP_PRIV_NUM_MIN_SIZE          (CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_BITS/SASI_BITS_IN_BYTE)
00105 /*! Minimal private number size in words. */
00106 #define CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_WORDS         (CRYS_SRP_PRIV_NUM_MIN_SIZE_IN_BITS/SASI_BITS_IN_32BIT_WORD)
00107 /*! Maximal private number size in bits. */
00108 #define CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_BITS      (CRYS_SRP_MAX_MODULUS_IN_BITS)
00109 /*! Maximal private number size in bytes. */
00110 #define CRYS_SRP_PRIV_NUM_MAX_SIZE          (CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_BITS/SASI_BITS_IN_BYTE)
00111 /*! Maximal private number size in words. */
00112 #define CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_WORDS         (CRYS_SRP_PRIV_NUM_MAX_SIZE_IN_BITS/SASI_BITS_IN_32BIT_WORD)
00113 
00114 /*! Maximal SRP HASH digest size in words. */
00115 #define CRYS_SRP_MAX_DIGEST_IN_WORDS        CRYS_HASH_RESULT_SIZE_IN_WORDS
00116 /*! Maximal SRP HASH digest size in bytes. */
00117 #define CRYS_SRP_MAX_DIGEST         (CRYS_SRP_MAX_DIGEST_IN_WORDS*SASI_32BIT_WORD_SIZE)
00118 
00119 /*! Minimal salt size in bytes. */
00120 #define CRYS_SRP_MIN_SALT_SIZE          (8)
00121 /*! Minimal salt size in words. */
00122 #define CRYS_SRP_MIN_SALT_SIZE_IN_WORDS     (CRYS_SRP_MIN_SALT_SIZE/SASI_32BIT_WORD_SIZE)
00123 /*! Maximal salt size in bytes. */
00124 #define CRYS_SRP_MAX_SALT_SIZE          (64)
00125 /*! Maximal salt size in words. */
00126 #define CRYS_SRP_MAX_SALT_SIZE_IN_WORDS     (CRYS_SRP_MAX_SALT_SIZE/SASI_32BIT_WORD_SIZE)
00127 
00128 /************************ Typedefs  ****************************/
00129 /*! SRP modulus buffer definition. */
00130 typedef uint8_t CRYS_SRP_Modulus_t [CRYS_SRP_MAX_MODULUS];
00131 
00132 /*! SRP digest buffer definition. */
00133 typedef uint8_t CRYS_SRP_Digest_t [CRYS_SRP_MAX_DIGEST];
00134 
00135 /*! SRP secret buffer definition. */
00136 typedef uint8_t CRYS_SRP_Secret_t [2*CRYS_SRP_MAX_DIGEST];
00137 
00138 /************************ Enums ********************************/
00139 
00140 /*!
00141 SRP supported versions
00142 */
00143 typedef enum {
00144     CRYS_SRP_VER_3   = 0,    /*!< VER 3. */
00145     CRYS_SRP_VER_6    = 1,    /*!< VER 6. */
00146     CRYS_SRP_VER_6A   = 2,    /*!< VER 6A. */
00147     CRYS_SRP_VER_HK   = 3,    /*!< VER 6A. */
00148     /*! Maximal number of supported versions.*/
00149     CRYS_SRP_NumOfVersions ,
00150     /*! Reserved.*/
00151     CRYS_SRP_VersionLast = 0x7FFFFFFF,
00152 
00153 }CRYS_SRP_Version_t ;
00154 
00155 /*!
00156 SRP entity type
00157 */
00158 typedef enum {
00159     CRYS_SRP_HOST    = 1,    /*!< Host entity, called also server, verifier, or Accessory in Home-Kit */
00160     CRYS_SRP_USER    = 2,    /*!< User entity, called also client, or Device in Home-Kit */
00161     /*! Maximal number of entities types.*/
00162     CRYS_SRP_NumOfEntityType ,
00163     /*! Reserved.*/
00164     CRYS_SRP_EntityLast = 0x7FFFFFFF,
00165 
00166 }CRYS_SRP_Entity_t ;
00167 
00168 /************************ Structs  ******************************/
00169 
00170 /*! Group parameters for the SRP - defines the modulus and the generator used */
00171 typedef struct CRYS_SRP_GroupParam_t  {
00172     /*! SRP modulus.*/
00173     CRYS_SRP_Modulus_t  modulus ;
00174     /*! SRP generator.*/
00175     uint8_t         gen ;
00176     /*! SRP modulus size in bits .*/
00177     size_t          modSizeInBits ;
00178     /*! SRP valid Np.*/
00179     uint32_t        validNp ;
00180     /*! SRP Np buffer.*/
00181     uint32_t        Np [CRYS_PKA_BARRETT_MOD_TAG_BUFF_SIZE_IN_WORDS];
00182 }CRYS_SRP_GroupParam_t ;
00183 
00184 /************************ context Structs  ******************************/
00185 /*! The SRP context prototype */
00186 typedef struct CRYS_SRP_Context_t  {
00187     /*! SRP entitiy type.*/
00188     CRYS_SRP_Entity_t        srpType ;
00189     /*! SRP version.*/
00190     CRYS_SRP_Version_t       srpVer ;
00191     /*! Group parameter including the modulus information.*/
00192     CRYS_SRP_GroupParam_t        groupParam ; // N, g, Np
00193     /*! Hash mode.*/
00194     CRYS_HASH_OperationMode_t    hashMode ;
00195     /*! Hash digest size.*/
00196     size_t              hashDigestSize ;
00197     /*! Pointer to RND state.*/
00198     CRYS_RND_State_t         *pRndState ;
00199     /*! Pointer to random vector generation function.*/
00200     SaSiRndGenerateVectWorkFunc_t    rndGenerateVectFunc ;
00201     /*! Modulus.*/
00202     CRYS_SRP_Modulus_t      ephemPriv ;  // a or b
00203     /*! Modulus size.*/
00204     size_t              ephemPrivSize ;
00205     /*! User name digest.*/
00206     CRYS_SRP_Digest_t       userNameDigest ; // M
00207     /*! Cred digest.*/
00208     CRYS_SRP_Digest_t       credDigest ; // p
00209     /*! SRP K multiplier. */                        //
00210     CRYS_SRP_Digest_t       kMult ;      // k multiplier
00211 }CRYS_SRP_Context_t ;
00212 
00213 
00214 /************************ SRP common Functions **********************/
00215 /****************************************************************************************************/
00216 /*!
00217 @brief This function initiates the SRP context.
00218 
00219 @return CRYS_OK on success.
00220 @return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
00221 */
00222 CIMPORT_C CRYSError_t   CRYS_SRP_Init(
00223                 CRYS_SRP_Entity_t    srpType,    /*!< [in] SRP entity type. */
00224                 CRYS_SRP_Version_t   srpVer,     /*!< [in] SRP version. */
00225                 CRYS_SRP_Modulus_t  srpModulus, /*!< [in] A pointer to the SRP modulus, BE byte buffer. */
00226                 uint8_t         srpGen,     /*!< [in] The SRP generator param. */
00227                 size_t          modSizeInBits,  /*!< [in] The SRP modulus size in bits:1024, 1536, 2048 & 3072 */
00228                 CRYS_HASH_OperationMode_t    hashMode,       /*!< [in] Enumerator defining the HASH mode. */
00229                 uint8_t         *pUserName, /*!< [in] A Pointer to user name. */
00230                 size_t                  userNameSize,   /*!< [in] The user name buffer size > 0. */
00231                 uint8_t         *pPwd,      /*!< [in] A Pointer to user password. */
00232                 size_t                  pwdSize,    /*!< [in] The user password buffer size > 0 if pPwd is valid. */
00233                 void    *pRndState, /*!< [in] A Pointer to RND context.*/
00234                 SaSiRndGenerateVectWorkFunc_t    rndGenerateVectFunc, /*!< [in] Pointer to random vector generation function.*/
00235                 CRYS_SRP_Context_t   *pCtx       /*!< [out] A Pointer to the SRP host context.*/
00236 );
00237 
00238 /*! MACRO definition for a specific SRP initialization function.*/
00239 #define CRYS_SRP_HK_INIT(srpType, srpModulus, srpGen, modSizeInBits, pUserName, userNameSize, pPwd, pwdSize, pRndState, rndGenerateVectFunc, pCtx) \
00240     CRYS_SRP_Init(srpType, CRYS_SRP_VER_HK, srpModulus, srpGen, modSizeInBits, CRYS_HASH_SHA512_mode, pUserName, userNameSize, pPwd, pwdSize, pRndState, rndGenerateVectFunc, pCtx)
00241 
00242 
00243 /****************************************************************************************************/
00244 /*!
00245 @brief This function calculates pSalt &  password verifier
00246 
00247 @return CRYS_OK on success.
00248 @return A non-zero value on failure as defined crys_srp_error.h, crys_rnd_error.h or crys_hash_error.h.
00249 */
00250 CIMPORT_C CRYSError_t   CRYS_SRP_PwdVerCreate(
00251                 size_t                  saltSize,   /*!< [in] The size of the random salt to generate,
00252                                         The range is between CRYS_SRP_MIN_SALT_SIZE
00253                                         to CRYS_SRP_MAX_SALT_SIZE. */
00254                 uint8_t         *pSalt,     /*!< [out] A Pointer to the pSalt number (s).*/
00255                 CRYS_SRP_Modulus_t      pwdVerifier,    /*!< [out] A Pointer to the password verifier (v). */
00256                 CRYS_SRP_Context_t   *pCtx       /*!< [out] A Pointer to the SRP context.*/
00257 );
00258 
00259 
00260 /****************************************************************************************************/
00261 /*!
00262 @brief Clears the SRP context.
00263 
00264 @return CRYS_OK on success.
00265 @return A non-zero value on failure as defined crys_srp_error.h.
00266 */
00267 CIMPORT_C CRYSError_t   CRYS_SRP_Clear(
00268                 CRYS_SRP_Context_t   *pCtx       /*!< [in/out] A Pointer to the SRP context.*/
00269 );
00270 
00271 
00272 /************************ SRP Host Functions **********************/
00273 /****************************************************************************************************/
00274 /*!
00275 @brief This function generates host public & private ephemeral key, known as B & b in RFC
00276 
00277 @return CRYS_OK on success.
00278 @return A non-zero value on failure as defined crys_srp_error.h or crys_rnd_error.h.
00279 */
00280 CIMPORT_C CRYSError_t   CRYS_SRP_HostPubKeyCreate(
00281                 size_t                  ephemPrivSize,  /*!< [in] The size of the generated ephemeral private key (b).
00282                                         The range is between CRYS_SRP_PRIV_NUM_MIN_SIZE to
00283                                         CRYS_SRP_PRIV_NUM_MAX_SIZE */
00284                 CRYS_SRP_Modulus_t      pwdVerifier,    /*!< [in] A Pointer to the verifier (v). */
00285                 CRYS_SRP_Modulus_t      hostPubKeyB,    /*!< [out] A Pointer to the host ephemeral public key (B). */
00286                 CRYS_SRP_Context_t   *pCtx       /*!< [in/out] A Pointer to the SRP context.*/
00287 );
00288 
00289 
00290 /*!
00291 @brief Verifies the user Proof and calculates the Host message proof.
00292 
00293 @return CRYS_OK on success.
00294 @return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
00295 */
00296 CIMPORT_C CRYSError_t   CRYS_SRP_HostProofVerifyAndCalc(
00297                 size_t                  saltSize,   /*!< [in] The size of the random salt,
00298                                         The range is between CRYS_SRP_MIN_SALT_SIZE
00299                                         to CRYS_SRP_MAX_SALT_SIZE. */
00300                 uint8_t         *pSalt,     /*!< [in] A Pointer to the pSalt number.*/
00301                 CRYS_SRP_Modulus_t      pwdVerifier,    /*!< [in] A Pointer to the password verifier (v). */
00302                 CRYS_SRP_Modulus_t      userPubKeyA,    /*!< [in] A Pointer to the user ephemeral public key (A). */
00303                 CRYS_SRP_Modulus_t      hostPubKeyB,    /*!< [in] A Pointer to the host ephemeral public key (B). */
00304                 CRYS_SRP_Digest_t   userProof,      /*!< [in] A Pointer to the SRP user proof buffer (M1).*/
00305                 CRYS_SRP_Digest_t   hostProof,      /*!< [out] A Pointer to the SRP host proof buffer (M2).*/
00306                 CRYS_SRP_Secret_t   sharedSecret,   /*!< [out] A Pointer to the SRP shared secret (K).*/
00307                 CRYS_SRP_Context_t   *pCtx       /*!< [in] A Pointer to the SRP context.*/
00308 );
00309 
00310 
00311 
00312 /************************ SRP User Functions **********************/
00313 /****************************************************************************************************/
00314 /*!
00315 @brief This function generates user public & private ephemeral key, known as A & a in RFC
00316 
00317 @return CRYS_OK on success.
00318 @return A non-zero value on failure as defined crys_srp_error.h or crys_rnd_error.h.
00319 */
00320 CIMPORT_C CRYSError_t   CRYS_SRP_UserPubKeyCreate(
00321                 size_t                  ephemPrivSize,  /*!< [in] The size of the generated ephemeral private key (a).
00322                                         The range is between CRYS_SRP_PRIV_NUM_MIN_SIZE to
00323                                         CRYS_SRP_PRIV_NUM_MAX_SIZE */
00324                 CRYS_SRP_Modulus_t      userPubKeyA,    /*!< [out] A Pointer to the user ephemeral public key (A). */
00325                 CRYS_SRP_Context_t   *pCtx       /*!< [in/out] A Pointer to the SRP context.*/
00326 );
00327 
00328 
00329 /****************************************************************************************************/
00330 /*!
00331 @brief This function calculates the user proof.
00332 
00333 @return CRYS_OK on success.
00334 @return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
00335 */
00336 CIMPORT_C CRYSError_t   CRYS_SRP_UserProofCalc(
00337                 size_t                  saltSize,   /*!< [in] The size of the random salt,
00338                                         The range is between CRYS_SRP_MIN_SALT_SIZE
00339                                         to CRYS_SRP_MAX_SALT_SIZE. */
00340                 uint8_t         *pSalt,     /*!< [in] A Pointer to the pSalt number.*/
00341                 CRYS_SRP_Modulus_t  userPubKeyA,  /*!< [in] A Pointer to the user public ephmeral key (A).*/
00342                 CRYS_SRP_Modulus_t  hostPubKeyB,  /*!< [in] A Pointer to the host public ephmeral key (B).*/
00343                 CRYS_SRP_Digest_t   userProof,      /*!< [out] A Pointer to the SRP user proof buffer (M1).*/
00344                 CRYS_SRP_Secret_t   sharedSecret,   /*!< [out] A Pointer to the SRP shared secret (K).*/
00345                 CRYS_SRP_Context_t   *pCtx       /*!< [out] A Pointer to the SRP context.*/
00346 );
00347 
00348 /****************************************************************************************************/
00349 /*!
00350 @brief This function verifies the host proof
00351 
00352 @return CRYS_OK on success.
00353 @return A non-zero value on failure as defined crys_srp_error.h or crys_hash_error.h.
00354 */
00355 CIMPORT_C CRYSError_t   CRYS_SRP_UserProofVerify(
00356                 CRYS_SRP_Secret_t   sharedSecret,   /*!< [in] A Pointer to the SRP shared secret (K).*/
00357                 CRYS_SRP_Modulus_t  userPubKeyA,  /*!< [in] A Pointer to the user public ephmeral key (A).*/
00358                 CRYS_SRP_Digest_t   userProof,      /*!< [in] A Pointer to the SRP user proof buffer (M1).*/
00359                 CRYS_SRP_Digest_t   hostProof,     /*!< [in] A Pointer to the SRP host proof buffer (M2).*/
00360                 CRYS_SRP_Context_t   *pCtx       /*!< [out] A Pointer to the SRP user context.*/
00361 );
00362 
00363 
00364 #ifdef __cplusplus
00365 }
00366 #endif
00367 /**
00368 @}
00369  */
00370 #endif /* #ifndef CRYS_SRP_H */
00371 
00372 
00373 
00374 
00375