SNIP_CLASSIC_CRYIF_SECTION_8_3_8_7_Key_Exchange_Interface

8.3.8.7 Key Exchange Interface Two users that each have a private secret can use a key exchange protocol to obtain a common secret, e.g. a key for a symmetric-key algorithm, without telling each other their private secret and without any listener being able to obtain the common secret or their private secrets. The functions Csm_KeyExchangeCalcPubVal / Csm_JobKeyExchangeCalcPubVal and Csm_KeyExchangeCalcSecret / Csm_JobKeyExchangeCalcSecret are used to support Diffie-Hellman (DH) key exchange. This allows two partners, Alice and Bob, to generate private and public key material, to exchange public parts so that both parties can generate at the end a common shared secret. This shared secret can further be used, e.g. for symmetric data operation such as data encryption or MAC generation. The public and private key material can either be based on prime based large number as it is used with RSA or on elliptic curve (so-called elliptic-curve diffie-hellman). The CSM key exchange functions require a key with key elements according to [SWS_Csm_01022], in the line of Crypto Service "Key Exchange". The key elements CRYPTO_KE_KEYEXCHANGE_BASE, CRYPTO_KE_KEYEXCHANGE_PRIVKEY and CRYPTO_KE_KEYEXCHANGE_OWNPUBKEY are used to hold the public/private key material. These values can either be pre-defined and set by Csm_KeyElementSet followed by Csm_KeySetValid or generated. For example, these key values can be generated by Csm_KeyGenerate and then copied with Csm_KeyElementCopy to the corresponding key elements, followed by a call to Csm_KeySetValid. In a first step, Alice will call Csm_KeyExchangeCalcPubVal / Csm_JobKeyExchangeCalcPubVal and send the results to Bob (exchanged data may need to be signed and/or encrypted depending on the protocol). It should be noted, that if Csm_KeyExchangeCalcPubVal is called but no valid key material exists (key is not valid or essential key elements have length=0), the function shall generate the necessary key material and continue as normal. If needed, Bob will put received key material from Alice into the corresponding key elements. He will also call Csm_KeyExchangeCalcPubVal to generate his shared value that needs to be sent to Alice. Afterwards, Bob can call Csm_KeyExchangeCalcSecret to generate the common secret. This value will be placed into the key element CRYPTO_KE_KEYEXCHANGE_SHAREDVALUE. When Alice receives the public value from Bob, it will call Csm_KeyExchangeCalcSecret and provides the value from Bob in the parameter of the function. The common shared secret will be generated by this function into the key element CRYPTO_KE_ KEYEXCHANGE_SHAREDVALUE. Depending on the algorithm, Bob needs to send key material to Alice to allow her to generate the common shared secret. The key element CRYPTO_KE_KEYEXCHANGE_ALGORITHM specifies the Diffie-Hellman algorithm. The key element value is of type Crypto_AlgorithmFamilyType, for example CRYPTO_ALGOFAM_DH (for modulo based DH) or CRYPTO_ALGOFAM_ED25519 (for ECDH(E)). Additional elliptic curve parameter can be specified with the additional key element CRYPTO_KE_KEYEXCHANGE_CURVETYPE. The other key elements have the following meaning: DH(E) ECDH(E) CRYPTO_KE_KEYEXCHANGE_BASE Modulo Generator point CRYPTO_KE_KEYEXCHANGE_PRIVKEY Local exponent Private key CRYPTO_KE_KEYEXCHANGE_OWNPUBKEY Generator Public key [SWS_Csm_00966] Definition of API function Csm_KeyExchangeCalcPubVal Upstream requirements: SRS_CryptoStack_00028 ⌈ Service Name Csm_KeyExchangeCalcPubVal Syntax Std_ReturnType Csm_KeyExchangeCalcPubVal ( uint32 keyId, uint8* publicValuePtr, uint32* publicValueLengthPtr ) Service ID [hex] 0x6c Sync/Async Synchronous Reentrancy Reentrant but not for same keyId Parameters (in) keyId Holds the identifier of the key which shall be used for the key exchange protocol. Parameters (inout) publicValueLengthPtr Holds a pointer to the memory location in which the public value length information is stored. On calling this function, this parameter shall contain the size of the buffer provided by public ValuePtr. When the request has finished, the actual length of the returned value shall be stored. Parameters (out) publicValuePtr Contains the pointer to the data where the public value shall be stored. Return value Std_ReturnType E_OK: Request successful E_NOT_OK: Request failed CRYPTO_E_BUSY: Request failed, Crypto Driver Object is busy CRYPTO_E_KEY_NOT_VALID: Request failed, the key’s state is "invalid" CRYPTO_E_KEY_EMPTY: Request failed because of uninitialized source key element Description Calculates the public value of the current user for the key exchange and stores the public key in the memory location pointed by the public value pointer. Available via Csm.h ⌋ [SWS_Csm_01020] ⌈If no errors are detected by Csm, the service Csm_KeyExchangeCalcPubVal shall call CryIf_KeyExchangeCalcPubVal.⌋ [SWS_Csm_00967] Definition of API function Csm_KeyExchangeCalcSecret Upstream requirements: SRS_CryptoStack_00028 ⌈ Service Name Csm_KeyExchangeCalcSecret Syntax Std_ReturnType Csm_KeyExchangeCalcSecret ( uint32 keyId, const uint8* partnerPublicValuePtr, uint32 partnerPublicValueLength ) Service ID [hex] 0x6d Sync/Async Synchronous Reentrancy Reentrant but not for same keyId keyId Holds the identifier of the key which shall be used for the key exchange protocol. partnerPublicValuePtr Holds the pointer to the memory location which contains the partner’s public value. Parameters (in) partnerPublicValueLength Contains the length of the partner’s public value in bytes. Parameters (inout) None Parameters (out) None Return value Std_ReturnType E_OK: Request successful E_NOT_OK: Request failed CRYPTO_E_BUSY: Request failed, Crypto Driver Object is busy CRYPTO_E_KEY_NOT_VALID: Request failed, the key’s state is "invalid" CRYPTO_E_KEY_EMPTY: Request failed because of uninitialized source key element Description Calculates the shared secret key for the key exchange with the key material of the key identified by the keyId and the partner public key. The shared secret key is stored as a key element in the same key. Available via Csm.h ⌋ [SWS_Csm_01006] ⌈If no errors are detected by Csm, the service Csm_KeyExchangeCalcSecret shall call CryIf_KeyExchangeCalcSecret.⌋