ECJPAKE.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2020, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 * @file ECJPAKE.h
 *
 * @brief   TI Driver for Elliptic Curve Password Authenticated Key Exchange
 *          by Juggling.
 *
 * @anchor ti_drivers_ECJPAKE_Overview
 * # Overview #
 * Elliptic Curve Password Authenticated Key Exchange by Juggling (EC-JPAKE)
 * is a key agreement scheme that establishes a secure channel over an insecure
 * network. It only requires sharing a password offline and does not require
 * public key infrastructure or trusted third parties such as certificate
 * authorities.
 *
 * At the end of the EC-JPAKE scheme, both parties derive a shared secret
 * from which a session key is derived.
 *
 * The scheme is symmetric. Both parties perform the exact same operations
 * to end up with the shared secret.
 *
 * # Steps involved #
 * Since the scheme is symmetric, the steps involved will be illustrated
 * using Alice and Bob as relevant parties.
 *
 *  -# Alice and Bob decide on some pre-shared secret, the password, and
 *     negotiate this through some offline means such as during commissioning.
 *
 *  -# Alice generates private keys x1, x2, v1, and v2 uniformly at random from [1, n - 1],
 *     where n is the order of the curve.
 *  -# Alice generates public keys X1 = x1 * G, X2 = x2 * G, V1 = v1 * G, and V2 = v2 * G.
 *  -# Alice generates Zero-Knowledge Proofs (ZKPs) for (X1, x1) and (X2, x2).
 *     The required hash is computed by concatenating G, V, the public key
 *     the ZKP authenticates, and the UserID of the authenticator and hashing
 *     the new bitstring. The exact order and formatting of all parameters and
 *     any extra information such as length words must be agreed upon by both
 *     parties to yield the same result.
 *  -# Alice sends X1, X2, V1, V2, r1, r2, and her UserID to Bob.
 *
 *  -# Bob generates private keys x3, x4, v3, and v4 uniformly at random from [1, n - 1],
 *     where n is the order of the curve.
 *  -# Bob generates public keys X3 = x3 * G, X4 = x4 * G, V3 = v3 * G, and V4 = v4 * G.
 *  -# Bob generates Zero-Knowledge Proofs (ZKPs) for (X3, x3) and (X4, x4).
 *  -# Bob sends X3, X4, V3, V4, r3, r4, and his UserID to Bob.
 *
 *  -# Alice and Bob verify the other parties ZKPs and break off the scheme if they
 *     do not check out.
 *
 *  -# Alice computes the new generator point G2 = (X1 + X3 + X4).
 *  -# Alice computes the combined private key x5 = x2 * s, where s is the pre-shared
 *     secret.
 *  -# Alice computes the combined public key X5 = x5 * G2.
 *  -# Alice computes a ZKP for (X5, x5) using G2 as the generator point of the ZKP.
 *  -# Alice sends X5, V5, r5, and her UserID to Bob.
 *
 *  -# Bob computes the new generator point G3 = (X3 + X1 + X2).
 *  -# Bob computes the combined private key x6 = x4 * s, where s is the pre-shared
 *     secret.
 *  -# Bob computes the combined public key X6 = x6 * G3.
 *  -# Bob computes a ZKP for (X6, x6) using G3 as the generator point of the ZKP.
 *  -# Bob sends X6, V6, r6, and his UserID to Alice.
 *
 *  -# Alice and Bob verify the other parties ZKPs and break off the scheme if they
 *     do not check out. This involves computing the other parties generator point.
 *
 *  -# Alice computes shared secret K = (X6 - (X4 * x5)) * x2.
 *
 *  -# Bob computes shared secret K = (X5 - (X2 * x6)) * x4.
 *
 *  -# Alice and Bob each run K through a mutually agreed upon key derivation
 *    function to compute the symmetric session key.
 *
 * @anchor ti_drivers_ECJPAKE_Usage
 * # Usage #
 *
 * ## Before starting an ECJPAKE operation #
 *
 * Before starting an ECJPAKE operation, the application must do the following:
 * -# Call ECJPAKE_init() to initialize the driver
 * -# Call ECJPAKE_Params_init() to initialize the ECJPAKE_Params to default values.
 * -# Modify the ECJPAKE_Params as desired
 * -# Call ECJPAKE_open() to open an instance of the driver
 *
 * ## Round one #
 * -# Initialize the following private key CryptoKeys.
 *    Seed them with keying material uniformly drawn from [1, n - 1]
 *      - myPrivateKey1
 *      - myPrivateKey2
 *      - myPrivateV1
 *      - myPrivateV2
 * -# Initialize the following blank public key CryptoKeys:
 *      - myPublicKey1
 *      - myPublicKey2
 *      - myPublicV1
 *      - myPublicV2
 *      - theirPublicKey1
 *      - theirPublicKey2
 *      - theirPublicV1
 *      - theirPublicV2
 * -# Call ECJPAKE_roundOneGenerateKeys() to generate all round one keys as needed.
 * -# Generate the hashes for the ZKPs using previously agreed upon formatting.
 *    Use the default generator point of the curve in the first round.
 * -# Generate your two ZKPs by calling ECJPAKE_generateZKP() once per ZKP.
 * -# Exchange public keys, UserIDs, and ZKP signatures. Write the received keying
 *    material into the relevant buffers or load them into key stores as specified
 *    by the CryptoKeys initialised earlier.
 * -# Verify the other party's ZKPs after computing their ZKP hash by calling
 *    ECJPAKE_verifyZKP() once per ZKP.
 * -# You can now let all V keys, myPrivateKey1, and all ZKP signatures go out of scope
 *    and re-use their memory.
 *
 * ## Round two #
 *  -# Initialize the following private key CryptoKeys.
 *     Seed myPrivateV with keying material uniformly drawn from [1, n - 1].
 *     Initialise the preSharedSecret with the common keying material previously
 *     shared between you and the other party.
 *      - preSharedSecret
 *      - myCombinedPrivateKey
 *  -# Initialize the following blank public key CryptoKeys:
 *      - theirNewGenerator
 *      - myNewGenerator
 *      - myCombinedPublicKey
 *      - myPublicV
 *  -# Call ECJPAKE_roundTwoGenerateKeys() to generate the remaining round two keys.
 *  -# Generate the hash for your ZKP use myNewGenerator as your generator point.
 *  -# Exchange public keys, UserIDs, and ZKP signatures. Write the received keying
 *     material into the relevant buffers or load them into key stores as specified
 *     by the CryptoKeys initialised earlier.
 *  -# Verify the other party's ZKP after computing their ZKP hash b calling
 *     ECJPAKE_verifyZKP(). Use theirNewGenerator as the generator point for this
 *     ZKP.
 *  -# You can now let all keys and keying material but myCombinedPrivateKey,
 *     theirCombinedPublicKey, theirPublicKey2, and myPrivateKey2 go out of scope.
 *
 * ## Computing the shared secret #
 *  -#  Initialize the following blank public key CryptoKey:
 *      - sharedSecret
 *  -#  Call ECJPAKE_computeSharedSecret().
 *  -#  Run sharedSecret through a key derivation function to compute the shared
 *     symmetric session key.
 *
 * ## Key Formatting
 * The ECJPAKE API expects the private and public keys to be formatted in octet
 * string format. The details of octet string formatting can be found in
 * SEC 1: Elliptic Curve Cryptography.
 *
 * Private keys and V's are formatted as big-endian integers of the same length
 * as the curve length.
 *
 * Public keys, public V's, generator points, and shared secrets are points on
 * an elliptic curve. These points can be expressed in several ways.
 * This API uses points expressed in uncompressed affine coordinates by default.
 * The octet string format requires a formatting byte in the first byte of the
 * public key. When using uncompressed affine coordinates, this is the value
 * 0x04.
 * The point itself is stored as a concatenated array of X followed by Y.
 * X and Y are big-endian. Some implementations do not require or yield
 * the Y coordinate for ECJPAKE on certain curves. It is recommended that the full
 * keying material buffer of twice the curve param length is used to facilitate
 * code-reuse. Implementations that do not use the Y coordinate will zero-out
 * the Y-coordinate whenever they write a point to the CryptoKey.
 *
 * This API accepts and returns the keying material of public keys according
 * to the following table:
 *
 * | Curve Type         | Keying Material Array | Array Length               |
 * |--------------------|-----------------------|----------------------------|
 * | Short Weierstrass  | [0x04, X, Y]          | 1 + 2 * Curve Param Length |
 * | Montgomery         | [0x04, X, Y]          | 1 + 2 * Curve Param Length |
 * | Edwards            | [0x04, X, Y]          | 1 + 2 * Curve Param Length |
 *
 * The r component of the ZKP signature, hash, and preSharedSecret also all
 * use the octet string format. They are interpreted as big-endian integers.
 *
 * @anchor ti_drivers_ECJPAKE_Synopsis
 * ## Synopsis
 *
 * @anchor ti_drivers_ECJPAKE_Synopsis_Code
 * @code
 * // Import ECJPAKE Driver definitions
 * #include <ti/drivers/ECJPAKE.h>
 *
 * ECJPAKE_init();
 *
 * // Since we are using default ECJPAKE_Params, we just pass in NULL for that parameter.
 * ecjpakeHandle = ECJPAKE_open(0, NULL);

 * ECJPAKE_Handle handle = ECJPAKE_open(0, &params);
 *
 * ECJPAKE_OperationRoundOneGenerateKeys   operationRoundOneGenerateKeys;
 * ECJPAKE_OperationRoundTwoGenerateKeys   operationRoundTwoGenerateKeys;
 * ECJPAKE_OperationGenerateZKP            operationGenerateZKP;
 * ECJPAKE_OperationVerifyZKP              operationVerifyZKP;
 * ECJPAKE_OperationComputeSharedSecret    operationComputeSharedSecret;
 *
 * // Generate my round one keys
 * ECJPAKE_OperationRoundOneGenerateKeys_init(&operationRoundOneGenerateKeys);
 * operationRoundOneGenerateKeys.curve             = &ECCParams_NISTP256;
 * operationRoundOneGenerateKeys.myPrivateKey1     = &myPrivateCryptoKey1;
 * operationRoundOneGenerateKeys.myPrivateKey2     = &myPrivateCryptoKey2;
 * operationRoundOneGenerateKeys.myPublicKey1      = &myPublicCryptoKey1;
 * operationRoundOneGenerateKeys.myPublicKey2      = &myPublicCryptoKey2;
 * operationRoundOneGenerateKeys.myPrivateV1       = &myPrivateCryptoV1;
 * operationRoundOneGenerateKeys.myPrivateV2       = &myPrivateCryptoV2;
 * operationRoundOneGenerateKeys.myPublicV1        = &myPublicCryptoV1;
 * operationRoundOneGenerateKeys.myPublicV2        = &myPublicCryptoV2;
 *
 * result = ECJPAKE_roundOneGenerateKeys(handle, &operationRoundOneGenerateKeys);
 *
 * // Generate hashes here
 *
 * // generate my round one ZKPs
 * ECJPAKE_OperationGenerateZKP_init(&operationGenerateZKP);
 * operationGenerateZKP.curve              = &ECCParams_NISTP256;
 * operationGenerateZKP.myPrivateKey       = &myPrivateCryptoKey1;
 * operationGenerateZKP.myPrivateV         = &myPrivateCryptoV1;
 * operationGenerateZKP.hash               = myHash1;
 * operationGenerateZKP.r                  = myR1;
 *
 * result = ECJPAKE_generateZKP(handle, &operationGenerateZKP);
 *
 * ECJPAKE_OperationGenerateZKP_init(&operationGenerateZKP);
 * operationGenerateZKP.curve              = &ECCParams_NISTP256;
 * operationGenerateZKP.myPrivateKey       = &myPrivateCryptoKey2;
 * operationGenerateZKP.myPrivateV         = &myPrivateCryptoV2;
 * operationGenerateZKP.hash               = myHash2;
 * operationGenerateZKP.r                  = myR2;
 *
 * result = ECJPAKE_generateZKP(handle, &operationGenerateZKP);
 *
 * // Do ZKP and key transmission here
 *
 * // Verify their round one ZKPs
 * // Generate their hashes here
 *
 * ECJPAKE_OperationVerifyZKP_init(&operationVerifyZKP);
 * operationVerifyZKP.curve                = &ECCParams_NISTP256;
 * operationVerifyZKP.theirGenerator       = NULL;
 * operationVerifyZKP.theirPublicKey       = &theirPublicCryptoKey1;
 * operationVerifyZKP.theirPublicV         = &theirPublicCryptoV1;
 * operationVerifyZKP.hash                 = theirHash1;
 * operationVerifyZKP.r                    = theirR1;
 *
 * result = ECJPAKE_verifyZKP(handle, &operationVerifyZKP);
 *
 * ECJPAKE_OperationVerifyZKP_init(&operationVerifyZKP);
 * operationVerifyZKP.curve                = &ECCParams_NISTP256;
 * operationVerifyZKP.theirGenerator       = NULL;
 * operationVerifyZKP.theirPublicKey       = &theirPublicCryptoKey2;
 * operationVerifyZKP.theirPublicV         = &theirPublicCryptoV2;
 * operationVerifyZKP.hash                 = theirHash2;
 * operationVerifyZKP.r                    = theirR2;
 *
 * result = ECJPAKE_verifyZKP(handle,&operationVerifyZKP);
 *
 * // Round two starts now
 *
 * // Generate my round two keys
 * ECJPAKE_OperationRoundTwoGenerateKeys_init(&operationRoundTwoGenerateKeys);
 * operationRoundTwoGenerateKeys.curve                 = &ECCParams_NISTP256;
 * operationRoundTwoGenerateKeys.myPrivateKey2         = &myPrivateCryptoKey2;
 * operationRoundTwoGenerateKeys.myPublicKey1          = &myPublicCryptoKey1;
 * operationRoundTwoGenerateKeys.myPublicKey2          = &myPublicCryptoKey2;
 * operationRoundTwoGenerateKeys.theirPublicKey1       = &theirPublicCryptoKey1;
 * operationRoundTwoGenerateKeys.theirPublicKey2       = &theirPublicCryptoKey2;
 * operationRoundTwoGenerateKeys.preSharedSecret       = &preSharedSecretCryptoKey;
 * operationRoundTwoGenerateKeys.theirNewGenerator     = &theirGeneratorKey;
 * operationRoundTwoGenerateKeys.myNewGenerator        = &myGeneratorKey;
 * operationRoundTwoGenerateKeys.myCombinedPrivateKey  = &myCombinedPrivateKey;
 * operationRoundTwoGenerateKeys.myCombinedPublicKey   = &myCombinedPublicKey;
 * operationRoundTwoGenerateKeys.myPrivateV            = &myPrivateCryptoV3;
 * operationRoundTwoGenerateKeys.myPublicV             = &myPublicCryptoV3;
 *
 * result = ECJPAKE_roundTwoGenerateKeys(handle, &operationRoundTwoGenerateKeys);
 *
 * // Generate my round  two ZKP
 * // Generate the round two hash here
 *
 * ECJPAKE_OperationGenerateZKP_init(&operationGenerateZKP);
 * operationGenerateZKP.curve              = &ECCParams_NISTP256;
 * operationGenerateZKP.myPrivateKey       = &myCombinedPrivateKey;
 * operationGenerateZKP.myPrivateV         = &myPrivateCryptoV3;
 * operationGenerateZKP.hash               = myHash3;
 * operationGenerateZKP.r                  = myR3;
 *
 * result = ECJPAKE_generateZKP(handle, &operationGenerateZKP);
 *
 * // Exchange keys and ZKPs again
 *
 * // Verify their second round ZKP
 * // Generate their round two hash here
 *
 * ECJPAKE_OperationVerifyZKP_init(&operationVerifyZKP);
 * operationVerifyZKP.curve                = &ECCParams_NISTP256;
 * operationVerifyZKP.theirGenerator       = &theirGeneratorKey;
 * operationVerifyZKP.theirPublicKey       = &theirCombinedPublicKey;
 * operationVerifyZKP.theirPublicV         = &theirPublicCryptoV3;
 * operationVerifyZKP.hash                 = theirHash3;
 * operationVerifyZKP.r                    = theirR3;
 *
 * result = ECJPAKE_verifyZKP(handle, &operationVerifyZKP);
 *
 * // Generate shared secret
 * ECJPAKE_OperationComputeSharedSecret_init(&operationComputeSharedSecret);
 * operationComputeSharedSecret.curve                      = &ECCParams_NISTP256;
 * operationComputeSharedSecret.myCombinedPrivateKey       = &myCombinedPrivateKey;
 * operationComputeSharedSecret.theirCombinedPublicKey     = &theirCombinedPublicKey;
 * operationComputeSharedSecret.theirPublicKey2            = &theirPublicCryptoKey2;
 * operationComputeSharedSecret.myPrivateKey2              = &myPrivateCryptoKey2;
 * operationComputeSharedSecret.sharedSecret               = &sharedSecretCryptoKey;
 *
 * result =  ECJPAKE_computeSharedSecret(handle, &operationComputeSharedSecret);
 *
 * // Close the driver
 * ECJPAKE_close(handle);
 * @endcode
 *
 * @anchor ti_drivers_ECJPAKE_Examples
 * # Examples #
 *
 * ## Basic ECJPAKE exchange #
 *
 * @code
 *
 * #define NISTP256_CURVE_LENGTH_BYTES 32
 * #define OCTET_STRING_OFFSET 1
 * #define NISTP256_PRIVATE_KEY_LENGTH_BYTES NISTP256_CURVE_LENGTH_BYTES
 * #define NISTP256_PUBLIC_KEY_LENGTH_BYTES (NISTP256_CURVE_LENGTH_BYTES * 2 + OCTET_STRING_OFFSET)
 *
 * // My fixed keying material
 * uint8_t myPrivateKeyMaterial1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myPrivateKeyMaterial2[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myPrivateVMaterial1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myPrivateVMaterial2[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myPrivateVMaterial3[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myHash1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myHash2[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myHash3[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * // My derived keying material
 * uint8_t myR1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myR2[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myR3[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myPublicKeyMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t myPublicKeyMaterial2[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t myPublicVMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t myPublicVMaterial2[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t myPublicVMaterial3[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t myCombinedPublicKeyMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t myCombinedPrivateKeyMaterial1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t myGenerator[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 *
 * // Their fixed keying material
 * uint8_t theirHash1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t theirHash2[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t theirHash3[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 *
 * // Their derived keying material
 * uint8_t theirR1[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t theirR2[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t theirR3[NISTP256_PRIVATE_KEY_LENGTH_BYTES];
 * uint8_t theirPublicKeyMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t theirPublicKeyMaterial2[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t theirPublicVMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t theirPublicVMaterial2[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t theirPublicVMaterial3[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t theirCombinedPublicKeyMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 * uint8_t theirGenerator[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 *
 * //  Shared secrets
 * uint8_t preSharedSecretKeyingMaterial[NISTP256_PRIVATE_KEY_LENGTH_BYTES] = "This is our password";
 * uint8_t sharedSecretKeyingMaterial1[NISTP256_PUBLIC_KEY_LENGTH_BYTES];
 *
 * // Pre-Shared Secret Key
 * CryptoKey preSharedSecretCryptoKey;
 *
 * // Final shared secret keys
 * CryptoKey sharedSecretCryptoKey;
 *
 * // My's keys
 * CryptoKey myPrivateCryptoKey1;
 * CryptoKey myPrivateCryptoKey2;
 * CryptoKey myPrivateCryptoV1;
 * CryptoKey myPrivateCryptoV2;
 * CryptoKey myPrivateCryptoV3;
 * CryptoKey myCombinedPrivateKey;
 *
 * CryptoKey myPublicCryptoKey1;
 * CryptoKey myPublicCryptoKey2;
 * CryptoKey myPublicCryptoV1;
 * CryptoKey myPublicCryptoV2;
 * CryptoKey myPublicCryptoV3;
 * CryptoKey myCombinedPublicKey;
 * CryptoKey myGeneratorKey;
 *
 * // Their's Keys
 * CryptoKey theirPublicCryptoKey1;
 * CryptoKey theirPublicCryptoKey2;
 * CryptoKey theirPublicCryptoV1;
 * CryptoKey theirPublicCryptoV2;
 * CryptoKey theirPublicCryptoV3;
 * CryptoKey theirCombinedPublicKey;
 * CryptoKey theirGeneratorKey;
 *
 * // NISTP256 generator
 * CryptoKeyPlaintext_initKey(NULL, ECCParams_NISTP256.generatorX, sizeof(ECCParams_NISTP256.length * 2));
 *
 * // Pre-shared secret
 * CryptoKeyPlaintext_initKey(&preSharedSecretCryptoKey, preSharedSecretKeyingMaterial,
 sizeof(preSharedSecretKeyingMaterial));
 *
 * // Final shared secret key
 * CryptoKeyPlaintext_initKey(&sharedSecretCryptoKey, sharedSecretKeyingMaterial1, sizeof(sharedSecretKeyingMaterial1));
 * CryptoKeyPlaintext_initKey(&sharedSecretCryptoKey2, sharedSecretKeyingMaterial2,
 sizeof(sharedSecretKeyingMaterial2));
 *
 *
 * // My keys
 *
 * // This example assumes that the private keying material buffers already
 * // contains random bytes. Otherwise, we need to use a TRNG or DRBG to fill
 * // them after initialising the CryptoKeys.
 * CryptoKeyPlaintext_initKey(&myPrivateCryptoKey1, myPrivateKeyMaterial1, sizeof(myPrivateKeyMaterial1));
 * CryptoKeyPlaintext_initKey(&myPrivateCryptoKey2, myPrivateKeyMaterial2, sizeof(myPrivateKeyMaterial2));
 * CryptoKeyPlaintext_initKey(&myPrivateCryptoV1, myPrivateVMaterial1, sizeof(myPrivateVMaterial1));
 * CryptoKeyPlaintext_initKey(&myPrivateCryptoV2, myPrivateVMaterial2, sizeof(myPrivateVMaterial2));
 * CryptoKeyPlaintext_initKey(&myPrivateCryptoV3, myPrivateVMaterial3, sizeof(myPrivateVMaterial3));
 *
 * CryptoKeyPlaintext_initBlankKey(&myPublicCryptoKey1, myPublicKeyMaterial1, sizeof(myPublicKeyMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&myPublicCryptoKey2, myPublicKeyMaterial2, sizeof(myPublicKeyMaterial2));
 * CryptoKeyPlaintext_initBlankKey(&myPublicCryptoV1, myPublicVMaterial1, sizeof(myPublicVMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&myPublicCryptoV2, myPublicVMaterial2, sizeof(myPublicVMaterial2));
 * CryptoKeyPlaintext_initBlankKey(&myPublicCryptoV3, myPublicVMaterial3, sizeof(myPublicVMaterial3));
 * CryptoKeyPlaintext_initBlankKey(&myCombinedPrivateKey, myCombinedPrivateKeyMaterial1,
 sizeof(myCombinedPrivateKeyMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&myCombinedPublicKey, myCombinedPublicKeyMaterial1,
 sizeof(myCombinedPublicKeyMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&myGeneratorKey, myGenerator, sizeof(myGenerator));
 *
 * // Their keys
 * CryptoKeyPlaintext_initBlankKey(&theirPublicCryptoKey1, theirPublicKeyMaterial1, sizeof(theirPublicKeyMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&theirPublicCryptoKey2, theirPublicKeyMaterial2, sizeof(theirPublicKeyMaterial2));
 * CryptoKeyPlaintext_initBlankKey(&theirPublicCryptoV1, theirPublicVMaterial1, sizeof(theirPublicVMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&theirPublicCryptoV2, theirPublicVMaterial2, sizeof(theirPublicVMaterial2));
 * CryptoKeyPlaintext_initBlankKey(&theirPublicCryptoV3, theirPublicVMaterial3, sizeof(theirPublicVMaterial3));
 * CryptoKeyPlaintext_initBlankKey(&theirCombinedPublicKey, theirCombinedPublicKeyMaterial1,
 sizeof(theirCombinedPublicKeyMaterial1));
 * CryptoKeyPlaintext_initBlankKey(&theirGeneratorKey, theirGenerator, sizeof(theirGenerator));
 *
 * // Initial driver setup
 * ECJPAKE_Params params;
 * ECJPAKE_Params_init(&params);
 *
 *
 * ECJPAKE_Handle handle = ECJPAKE_open(0, &params);
 *
 * ECJPAKE_OperationRoundOneGenerateKeys   operationRoundOneGenerateKeys;
 * ECJPAKE_OperationRoundTwoGenerateKeys   operationRoundTwoGenerateKeys;
 * ECJPAKE_OperationGenerateZKP            operationGenerateZKP;
 * ECJPAKE_OperationVerifyZKP              operationVerifyZKP;
 * ECJPAKE_OperationComputeSharedSecret    operationComputeSharedSecret;
 *
 * // Generate my round one keys
 * ECJPAKE_OperationRoundOneGenerateKeys_init(&operationRoundOneGenerateKeys);
 * operationRoundOneGenerateKeys.curve             = &ECCParams_NISTP256;
 * operationRoundOneGenerateKeys.myPrivateKey1     = &myPrivateCryptoKey1;
 * operationRoundOneGenerateKeys.myPrivateKey2     = &myPrivateCryptoKey2;
 * operationRoundOneGenerateKeys.myPublicKey1      = &myPublicCryptoKey1;
 * operationRoundOneGenerateKeys.myPublicKey2      = &myPublicCryptoKey2;
 * operationRoundOneGenerateKeys.myPrivateV1       = &myPrivateCryptoV1;
 * operationRoundOneGenerateKeys.myPrivateV2       = &myPrivateCryptoV2;
 * operationRoundOneGenerateKeys.myPublicV1        = &myPublicCryptoV1;
 * operationRoundOneGenerateKeys.myPublicV2        = &myPublicCryptoV2;
 *
 * int_fast16_t result = ECJPAKE_roundOneGenerateKeys(handle, &operationRoundOneGenerateKeys);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * // Generate hashes here
 *
 * // generate my round one ZKPs
 * ECJPAKE_OperationGenerateZKP_init(&operationGenerateZKP);
 * operationGenerateZKP.curve              = &ECCParams_NISTP256;
 * operationGenerateZKP.myPrivateKey       = &myPrivateCryptoKey1;
 * operationGenerateZKP.myPrivateV         = &myPrivateCryptoV1;
 * operationGenerateZKP.hash               = myHash1;
 * operationGenerateZKP.r                  = myR1;
 *
 * result = ECJPAKE_generateZKP(handle, &operationGenerateZKP);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * ECJPAKE_OperationGenerateZKP_init(&operationGenerateZKP);
 * operationGenerateZKP.curve              = &ECCParams_NISTP256;
 * operationGenerateZKP.myPrivateKey       = &myPrivateCryptoKey2;
 * operationGenerateZKP.myPrivateV         = &myPrivateCryptoV2;
 * operationGenerateZKP.hash               = myHash2;
 * operationGenerateZKP.r                  = myR2;
 *
 * result = ECJPAKE_generateZKP(handle, &operationGenerateZKP);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * // Do ZKP and key transmission here
 *
 * // Verify their round one ZKPs
 * // Generate their hashes here
 *
 * ECJPAKE_OperationVerifyZKP_init(&operationVerifyZKP);
 * operationVerifyZKP.curve                = &ECCParams_NISTP256;
 * operationVerifyZKP.theirGenerator       = NULL;
 * operationVerifyZKP.theirPublicKey       = &theirPublicCryptoKey1;
 * operationVerifyZKP.theirPublicV         = &theirPublicCryptoV1;
 * operationVerifyZKP.hash                 = theirHash1;
 * operationVerifyZKP.r                    = theirR1;
 *
 * result = ECJPAKE_verifyZKP(handle, &operationVerifyZKP);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * ECJPAKE_OperationVerifyZKP_init(&operationVerifyZKP);
 * operationVerifyZKP.curve                = &ECCParams_NISTP256;
 * operationVerifyZKP.theirGenerator       = NULL;
 * operationVerifyZKP.theirPublicKey       = &theirPublicCryptoKey2;
 * operationVerifyZKP.theirPublicV         = &theirPublicCryptoV2;
 * operationVerifyZKP.hash                 = theirHash2;
 * operationVerifyZKP.r                    = theirR2;
 *
 * result = ECJPAKE_verifyZKP(handle,&operationVerifyZKP);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * // Round two starts now
 *
 * // Generate my round two keys
 * ECJPAKE_OperationRoundTwoGenerateKeys_init(&operationRoundTwoGenerateKeys);
 * operationRoundTwoGenerateKeys.curve                 = &ECCParams_NISTP256;
 * operationRoundTwoGenerateKeys.myPrivateKey2         = &myPrivateCryptoKey2;
 * operationRoundTwoGenerateKeys.myPublicKey1          = &myPublicCryptoKey1;
 * operationRoundTwoGenerateKeys.myPublicKey2          = &myPublicCryptoKey2;
 * operationRoundTwoGenerateKeys.theirPublicKey1       = &theirPublicCryptoKey1;
 * operationRoundTwoGenerateKeys.theirPublicKey2       = &theirPublicCryptoKey2;
 * operationRoundTwoGenerateKeys.preSharedSecret       = &preSharedSecretCryptoKey;
 * operationRoundTwoGenerateKeys.theirNewGenerator     = &theirGeneratorKey;
 * operationRoundTwoGenerateKeys.myNewGenerator        = &myGeneratorKey;
 * operationRoundTwoGenerateKeys.myCombinedPrivateKey  = &myCombinedPrivateKey;
 * operationRoundTwoGenerateKeys.myCombinedPublicKey   = &myCombinedPublicKey;
 * operationRoundTwoGenerateKeys.myPrivateV            = &myPrivateCryptoV3;
 * operationRoundTwoGenerateKeys.myPublicV             = &myPublicCryptoV3;
 *
 * result = ECJPAKE_roundTwoGenerateKeys(handle, &operationRoundTwoGenerateKeys);
 *
 * // Generate my round  two ZKP
 * // Generate the round two hash here
 *
 * ECJPAKE_OperationGenerateZKP_init(&operationGenerateZKP);
 * operationGenerateZKP.curve              = &ECCParams_NISTP256;
 * operationGenerateZKP.myPrivateKey       = &myCombinedPrivateKey;
 * operationGenerateZKP.myPrivateV         = &myPrivateCryptoV3;
 * operationGenerateZKP.hash               = myHash3;
 * operationGenerateZKP.r                  = myR3;
 *
 * result = ECJPAKE_generateZKP(handle, &operationGenerateZKP);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * // Exchange keys and ZKPs again
 *
 * // Verify their second round ZKP
 * // Generate their round two hash here
 *
 * ECJPAKE_OperationVerifyZKP_init(&operationVerifyZKP);
 * operationVerifyZKP.curve                = &ECCParams_NISTP256;
 * operationVerifyZKP.theirGenerator       = &theirGeneratorKey;
 * operationVerifyZKP.theirPublicKey       = &theirCombinedPublicKey;
 * operationVerifyZKP.theirPublicV         = &theirPublicCryptoV3;
 * operationVerifyZKP.hash                 = theirHash3;
 * operationVerifyZKP.r                    = theirR3;
 *
 * result = ECJPAKE_verifyZKP(handle, &operationVerifyZKP);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 *
 * // Generate shared secret
 * ECJPAKE_OperationComputeSharedSecret_init(&operationComputeSharedSecret);
 * operationComputeSharedSecret.curve                      = &ECCParams_NISTP256;
 * operationComputeSharedSecret.myCombinedPrivateKey       = &myCombinedPrivateKey;
 * operationComputeSharedSecret.theirCombinedPublicKey     = &theirCombinedPublicKey;
 * operationComputeSharedSecret.theirPublicKey2            = &theirPublicCryptoKey2;
 * operationComputeSharedSecret.myPrivateKey2              = &myPrivateCryptoKey2;
 * operationComputeSharedSecret.sharedSecret               = &sharedSecretCryptoKey;
 *
 * result =  ECJPAKE_computeSharedSecret(handle, &operationComputeSharedSecret);
 *
 * if (result != ECJPAKE_STATUS_SUCCESS) {
 *     while(1);
 * }
 *
 * // Run sharedSecretCryptoKey through a key derivation function and
 * // confirm to the other party that we have derived the same key
 *
 *
 * @endcode
 *
 *
 */

#ifndef ti_drivers_ECJPAKE__include
#define ti_drivers_ECJPAKE__include

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>

#ifdef __cplusplus
extern "C" {
#endif

#define ECJPAKE_STATUS_RESERVED (-32)

#define ECJPAKE_STATUS_SUCCESS (0)

#define ECJPAKE_STATUS_ERROR (-1)

#define ECJPAKE_STATUS_RESOURCE_UNAVAILABLE (-2)

#define ECJPAKE_STATUS_INVALID_PUBLIC_KEY (-3)

#define ECJPAKE_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-4)

#define ECJPAKE_STATUS_PUBLIC_KEY_LARGER_THAN_PRIME (-5)

#define ECJPAKE_STATUS_POINT_AT_INFINITY (-6)

#define ECJPAKE_STATUS_INVALID_PRIVATE_KEY (-7)

#define ECJPAKE_STATUS_INVALID_PRIVATE_V (-8)

#define ECJPAKE_STATUS_CANCELED (-9)

typedef struct
{
    void *object;

    void const *hwAttrs;
} ECJPAKE_Config;

typedef ECJPAKE_Config *ECJPAKE_Handle;

typedef enum
{
    ECJPAKE_RETURN_BEHAVIOR_CALLBACK = 1, 
    ECJPAKE_RETURN_BEHAVIOR_BLOCKING = 2, 
    ECJPAKE_RETURN_BEHAVIOR_POLLING  = 4, 
} ECJPAKE_ReturnBehavior;

typedef struct
{
    const ECCParams_CurveParams *curve; 
    CryptoKey *myPrivateKey1;           
    CryptoKey *myPrivateKey2;           
    CryptoKey *myPublicKey1;            
    CryptoKey *myPublicKey2;            
    CryptoKey *myPrivateV1;             
    CryptoKey *myPrivateV2;             
    CryptoKey *myPublicV1;              
    CryptoKey *myPublicV2;              
} ECJPAKE_OperationRoundOneGenerateKeys;

typedef struct
{
    const ECCParams_CurveParams *curve; 
    const CryptoKey *myPrivateKey;      
    const CryptoKey *myPrivateV;        
    const uint8_t *hash;                
    uint8_t *r;                         
} ECJPAKE_OperationGenerateZKP;

typedef struct
{
    const ECCParams_CurveParams *curve; 
    const CryptoKey *theirGenerator;    
    const CryptoKey *theirPublicKey;    
    const CryptoKey *theirPublicV;      
    const uint8_t *hash;                
    const uint8_t *r;                   
} ECJPAKE_OperationVerifyZKP;

typedef struct
{
    const ECCParams_CurveParams *curve; 
    const CryptoKey *myPrivateKey2;     
    const CryptoKey *myPublicKey1;      
    const CryptoKey *myPublicKey2;      
    const CryptoKey *theirPublicKey1;   
    const CryptoKey *theirPublicKey2;   
    const CryptoKey *preSharedSecret;   
    CryptoKey *theirNewGenerator;       
    CryptoKey *myNewGenerator;          
    CryptoKey *myCombinedPrivateKey;    
    CryptoKey *myCombinedPublicKey;     
    CryptoKey *myPrivateV;              
    CryptoKey *myPublicV;               
} ECJPAKE_OperationRoundTwoGenerateKeys;

typedef struct
{
    const ECCParams_CurveParams *curve;      
    const CryptoKey *myCombinedPrivateKey;   
    const CryptoKey *theirCombinedPublicKey; 
    const CryptoKey *theirPublicKey2;        
    const CryptoKey *myPrivateKey2;          
    CryptoKey *sharedSecret;                 
} ECJPAKE_OperationComputeSharedSecret;

typedef union
{
    ECJPAKE_OperationRoundOneGenerateKeys *generateRoundOneKeys; 
    ECJPAKE_OperationGenerateZKP *generateZKP; 
    ECJPAKE_OperationVerifyZKP *verifyZKP;     
    ECJPAKE_OperationRoundTwoGenerateKeys *generateRoundTwoKeys; 
    ECJPAKE_OperationComputeSharedSecret *computeSharedSecret; 
} ECJPAKE_Operation;

typedef enum
{
    ECJPAKE_OPERATION_TYPE_ROUND_ONE_GENERATE_KEYS = 1,
    ECJPAKE_OPERATION_TYPE_GENERATE_ZKP            = 2,
    ECJPAKE_OPERATION_TYPE_VERIFY_ZKP              = 3,
    ECJPAKE_OPERATION_TYPE_ROUND_TWO_GENERATE_KEYS = 4,
    ECJPAKE_OPERATION_TYPE_COMPUTE_SHARED_SECRET   = 5,
} ECJPAKE_OperationType;

typedef void (*ECJPAKE_CallbackFxn)(ECJPAKE_Handle handle,
                                    int_fast16_t returnStatus,
                                    ECJPAKE_Operation operation,
                                    ECJPAKE_OperationType operationType);

typedef struct
{
    ECJPAKE_ReturnBehavior returnBehavior; 
    ECJPAKE_CallbackFxn callbackFxn;       
    uint32_t timeout;                      
    void *custom;                          
} ECJPAKE_Params;

void ECJPAKE_init(void);

void ECJPAKE_OperationRoundOneGenerateKeys_init(ECJPAKE_OperationRoundOneGenerateKeys *operation);

void ECJPAKE_OperationGenerateZKP_init(ECJPAKE_OperationGenerateZKP *operation);

void ECJPAKE_OperationVerifyZKP_init(ECJPAKE_OperationVerifyZKP *operation);

void ECJPAKE_OperationRoundTwoGenerateKeys_init(ECJPAKE_OperationRoundTwoGenerateKeys *operation);

void ECJPAKE_OperationComputeSharedSecret_init(ECJPAKE_OperationComputeSharedSecret *operation);

void ECJPAKE_close(ECJPAKE_Handle handle);

ECJPAKE_Handle ECJPAKE_open(uint_least8_t index, ECJPAKE_Params *params);

void ECJPAKE_Params_init(ECJPAKE_Params *params);

int_fast16_t ECJPAKE_roundOneGenerateKeys(ECJPAKE_Handle handle, ECJPAKE_OperationRoundOneGenerateKeys *operation);

int_fast16_t ECJPAKE_generateZKP(ECJPAKE_Handle handle, ECJPAKE_OperationGenerateZKP *operation);

int_fast16_t ECJPAKE_verifyZKP(ECJPAKE_Handle handle, ECJPAKE_OperationVerifyZKP *operation);

int_fast16_t ECJPAKE_roundTwoGenerateKeys(ECJPAKE_Handle handle, ECJPAKE_OperationRoundTwoGenerateKeys *operation);

int_fast16_t ECJPAKE_computeSharedSecret(ECJPAKE_Handle handle, ECJPAKE_OperationComputeSharedSecret *operation);

int_fast16_t ECJPAKE_cancelOperation(ECJPAKE_Handle handle);

ECJPAKE_Handle ECJPAKE_construct(ECJPAKE_Config *config, const ECJPAKE_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ECJPAKE__include */