curve25519.h

/*!
    \ingroup Curve25519

    \brief This function generates a Curve25519 key using the given random
    number generator, rng, of the size given (keysize), and stores it in
    the given curve25519_key structure. It should be called after the key
    structure has been initialized through wc_curve25519_init().

    \return 0 Returned on successfully generating the key and and storing
    it in the given curve25519_key structure.
    \return ECC_BAD_ARG_E Returned if the input keysize does not correspond to
    the keysize for a curve25519 key (32 bytes).
    \return RNG_FAILURE_E Returned if the rng internal status is not
    DRBG_OK or if there is in generating the next random block with rng.
    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
    are NULL.

    \param [in] rng Pointer to the RNG object used to generate the ecc key.
    \param [in] keysize Size of the key to generate. Must be 32 bytes for
    curve25519.
    \param [in,out] key Pointer to the curve25519_key structure in which to
    store the generated key.

    _Example_
    \code
    int ret;

    curve25519_key key;
    wc_curve25519_init(&key); // initialize key
    WC_RNG rng;
    wc_InitRng(&rng); // initialize random number generator

    ret = wc_curve25519_make_key(&rng, 32, &key);
    if (ret != 0) {
        // error making Curve25519 key
    }
    \endcode

    \sa wc_curve25519_init
*/

int wc_curve25519_make_key(WC_RNG* rng, int keysize, curve25519_key* key);

/*!
    \ingroup Curve25519

    \brief This function computes a shared secret key given a secret private
    key and a received public key. It stores the generated secret key in the
    buffer out and assigns the length of the secret key to outlen. Only
    supports big endian.

    \return 0 Returned on successfully computing a shared secret key.
    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
    are NULL.
    \return ECC_BAD_ARG_E Returned if the first bit of the public key is
    set, to avoid implementation fingerprinting.

    \param [in] private_key Pointer to the curve25519_key structure initialized
    with the user’s private key.
    \param [in] public_key Pointer to the  curve25519_key structure containing
    the received public key.
    \param [out] out Pointer to a buffer in which to store the 32 byte computed
    secret key.
    \param [in,out] outlen Pointer in which to store the length written to the
    output buffer.

    _Example_
    \code
    int ret;

    byte sharedKey[32];
    word32 keySz;
    curve25519_key privKey, pubKey;
    // initialize both keys

    ret = wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey, &keySz);
    if (ret != 0) {
        // error generating shared key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
    \sa wc_curve25519_shared_secret_ex
*/

int wc_curve25519_shared_secret(curve25519_key* private_key,
                                curve25519_key* public_key,
                                byte* out, word32* outlen);

/*!
    \ingroup Curve25519

    \brief This function computes a shared secret key given a secret private
    key and a received public key. It stores the generated secret key in the
    buffer out and assigns the length of the secret key to outlen. Supports
    both big and little endian.

    \return 0 Returned on successfully computing a shared secret key.
    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
    are NULL.
    \return ECC_BAD_ARG_E Returned if the first bit of the public key is set,
    to avoid implementation fingerprinting.

    \param [in] private_key Pointer to the curve25519_key structure initialized
    with the user’s private key.
    \param [in] public_key Pointer to the  curve25519_key structure containing
    the received public key.
    \param [out] out Pointer to a buffer in which to store the 32 byte computed
    secret key.
    \param [in,out] outlen Pointer in which to store the length written to the
    output buffer.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
    form to use.

    _Example_
    \code
    int ret;

    byte sharedKey[32];
    word32 keySz;

    curve25519_key privKey, pubKey;
    // initialize both keys

    ret = wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz,
             EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error generating shared key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
    \sa wc_curve25519_shared_secret
*/

int wc_curve25519_shared_secret_ex(curve25519_key* private_key,
                                   curve25519_key* public_key,
                                   byte* out, word32* outlen, int endian);

/*!
    \ingroup Curve25519

    \brief This function initializes a Curve25519 key. It should be called
    before generating a key for the structure.

    \return 0 Returned on successfully initializing the curve25519_key
    structure.
    \return BAD_FUNC_ARG Returned when key is NULL.

    \param [in,out] key Pointer to the curve25519_key structure to initialize.

    _Example_
    \code
    curve25519_key key;
    wc_curve25519_init(&key); // initialize key
    // make key and proceed to encryption
    \endcode

    \sa wc_curve25519_make_key
*/

int wc_curve25519_init(curve25519_key* key);

/*!
    \ingroup Curve25519

    \brief This function frees a Curve25519 object.

    \param [in,out] key Pointer to the key object to free.

    _Example_
    \code
    curve25519_key privKey;
    // initialize key, use it to generate shared secret key
    wc_curve25519_free(&privKey);
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
*/

void wc_curve25519_free(curve25519_key* key);

/*!
    \ingroup Curve25519

    \brief This function imports a curve25519 private key only. (Big endian).

    \return 0 Returned on successfully importing private key.
    \return BAD_FUNC_ARG Returns if key or priv is null.
    \return ECC_BAD_ARG_E Returns if privSz is not equal to CURVE25519_KEY_SIZE.

    \param [in] priv Pointer to a buffer containing the private key to import.
    \param [in] privSz Length of the private key to import.
    \param [in,out] key Pointer to the structure in which to store the imported
    key.

    _Example_
    \code
    int ret;

    byte priv[] = { Contents of private key };
    curve25519_key key;
    wc_curve25519_init(&key);

    ret = wc_curve25519_import_private(priv, sizeof(priv), &key);
    if (ret != 0) {
        // error importing keys
    }
    \endcode

    \sa wc_curve25519_import_private_ex
    \sa wc_curve25519_size
*/

int wc_curve25519_import_private(const byte* priv, word32 privSz,
                                 curve25519_key* key);

/*!
    \ingroup Curve25519

    \brief curve25519 private key import only. (Big or Little endian).

    \return 0 Returned on successfully importing private key.
    \return BAD_FUNC_ARG Returns if key or priv is null.
    \return ECC_BAD_ARG_E Returns if privSz is not equal to CURVE25519_KEY_SIZE.

    \param [in] priv Pointer to a buffer containing the private key to import.
    \param [in] privSz Length of the private key to import.
    \param [in,out] key Pointer to the structure in which to store the imported
    key.
    \param [in]  endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to
    set which form to use.

    _Example_
    \code
    int ret;

    byte priv[] = { // Contents of private key };
    curve25519_key key;
    wc_curve25519_init(&key);

    ret = wc_curve25519_import_private_ex(priv, sizeof(priv), &key,
            EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error importing keys
    }

    \endcode

    \sa wc_curve25519_import_private
    \sa wc_curve25519_size
*/

int wc_curve25519_import_private_ex(const byte* priv, word32 privSz,
                                    curve25519_key* key, int endian);

/*!
    \ingroup Curve25519

    \brief This function imports a public-private key pair into a
    curve25519_key structure.  Big endian only.

    \return 0 Returned on importing into the curve25519_key structure
    \return BAD_FUNC_ARG Returns if any of the input parameters are null.
    \return ECC_BAD_ARG_E Returned if the input key’s key size does not match
    the public or private key sizes.

    \param [in] priv Pointer to a buffer containing the private key to import.
    \param [in] privSz Length of the private key to import.
    \param [in] pub Pointer to a buffer containing the public key to import.
    \param [in] pubSz Length of the public key to import.
    \param [in,out] key Pointer to the structure in which to store the imported
    keys.

    _Example_
    \code
    int ret;

    byte priv[32];
    byte pub[32];
    // initialize with public and private keys
    curve25519_key key;

    wc_curve25519_init(&key);
    // initialize key

    ret = wc_curve25519_import_private_raw(&priv, sizeof(priv), pub,
            sizeof(pub), &key);
    if (ret != 0) {
        // error importing keys
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
    \sa wc_curve25519_import_public
    \sa wc_curve25519_export_private_raw
*/

int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
                            const byte* pub, word32 pubSz, curve25519_key* key);

/*!
    \ingroup Curve25519

    \brief This function imports a public-private key pair into a curve25519_key structure.  Supports both big and little endian.

    \return 0 Returned on importing into the curve25519_key structure
    \return BAD_FUNC_ARG Returns if any of the input parameters are null.
    \return ECC_BAD_ARG_E Returned if or the input key’s key size does not match
    the public or private key sizes

    \param [in] priv Pointer to a buffer containing the private key to import.
    \param [in] privSz Length of the private key to import.
    \param [in] pub Pointer to a buffer containing the public key to import.
    \param [in] pubSz Length of the public key to import.
    \param [in,out] key Pointer to the structure in which to store the imported
    keys.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set
    which form to use.

    _Example_
    \code
    int ret;
    byte priv[32];
    byte pub[32];
    // initialize with public and private keys
    curve25519_key key;

    wc_curve25519_init(&key);
    // initialize key

    ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub,
            sizeof(pub), &key, EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error importing keys
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
    \sa wc_curve25519_import_public
    \sa wc_curve25519_export_private_raw
    \sa wc_curve25519_import_private_raw
*/

int wc_curve25519_import_private_raw_ex(const byte* priv, word32 privSz,
                                        const byte* pub, word32 pubSz,
                                        curve25519_key* key, int endian);

/*!
    \ingroup Curve25519

    \brief This function exports a private key from a curve25519_key structure
    and stores it in the given out buffer. It also sets outLen to be the size
    of the exported key. Big Endian only.

    \return 0 Returned on successfully exporting the private key from the
    curve25519_key structure.
    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
    \return ECC_BAD_ARG_E Returned if *outLen is less than wc_curve25519_size().

    \param [in] key Pointer to the structure from which to export the key.
    \param [out] out Pointer to the buffer in which to store the exported key.
    \param [in,out] outLen On in, is the size of the out in bytes.
    On out, will store the bytes written to the output buffer.

    _Example_
    \code
    int ret;
    byte priv[32];
    word32 privSz;

    curve25519_key key;
    // initialize and make key

    ret = wc_curve25519_export_private_raw(&key, priv, &privSz);
    if (ret != 0) {
        // error exporting key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
    \sa wc_curve25519_import_private_raw
    \sa wc_curve25519_export_private_raw_ex
*/

int wc_curve25519_export_private_raw(curve25519_key* key, byte* out,
                                     word32* outLen);

/*!
    \ingroup Curve25519

    \brief This function exports a private key from a curve25519_key structure
    and stores it in the given out buffer. It also sets outLen to be the size
    of the exported key.  Can specify whether it's big or little endian.

    \return 0 Returned on successfully exporting the private key from the
    curve25519_key structure.
    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
    \return ECC_BAD_ARG_E Returned if *outLen is less than wc_curve25519_size().

    \param [in] key Pointer to the structure from which to export the key.
    \param [out] out Pointer to the buffer in which to store the exported key.
    \param [in,out] outLen On in, is the size of the out in bytes.
    On out, will store the bytes written to the output buffer.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
    form to use.

    _Example_
    \code
    int ret;

    byte priv[32];
    word32 privSz;
    curve25519_key key;
    // initialize and make key
    ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz,
            EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error exporting key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
    \sa wc_curve25519_import_private_raw
    \sa wc_curve25519_export_private_raw
    \sa wc_curve25519_size
*/

int wc_curve25519_export_private_raw_ex(curve25519_key* key, byte* out,
                                        word32* outLen, int endian);

/*!
    \ingroup Curve25519

    \brief This function imports a public key from the given in buffer and
    stores it in the  curve25519_key structure.

    \return 0 Returned on successfully importing the public key into the
    curve25519_key structure.
    \return ECC_BAD_ARG_E Returned if the inLen parameter does not match the key
    size of the key structure.
    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.

    \param [in] in Pointer to the buffer containing the public key to import.
    \param [in] inLen Length of the public key to import.
    \param [in,out] key Pointer to the curve25519_key structure in which to
    store the key.

    _Example_
    \code
    int ret;

    byte pub[32];
    // initialize pub with public key

    curve25519_key key;
    // initialize key

    ret = wc_curve25519_import_public(pub,sizeof(pub), &key);
    if (ret != 0) {
        // error importing key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_export_public
    \sa wc_curve25519_import_private_raw
    \sa wc_curve25519_import_public_ex
    \sa wc_curve25519_check_public
    \sa wc_curve25519_size
*/

int wc_curve25519_import_public(const byte* in, word32 inLen,
                                curve25519_key* key);

/*!
    \ingroup Curve25519

    \brief This function imports a public key from the given in buffer and
    stores it in the  curve25519_key structure.

    \return 0 Returned on successfully importing the public key into the
    curve25519_key structure.
    \return ECC_BAD_ARG_E Returned if the inLen parameter does not match the
    key size of the key structure.
    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.

    \param [in] in Pointer to the buffer containing the public key to import.
    \param [in] inLen Length of the public key to import.
    \param [in,out] key Pointer to the curve25519_key structure in which to
    store the key.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
    form to use.

    _Example_
    \code
    int ret;

    byte pub[32];
    // initialize pub with public key
    curve25519_key key;
    // initialize key

    ret = wc_curve25519_import_public_ex(pub, sizeof(pub), &key,
            EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error importing key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_export_public
    \sa wc_curve25519_import_private_raw
    \sa wc_curve25519_import_public
    \sa wc_curve25519_check_public
    \sa wc_curve25519_size
*/

int wc_curve25519_import_public_ex(const byte* in, word32 inLen,
                                   curve25519_key* key, int endian);

/*!
    \ingroup Curve25519

    \brief This function checks that a public key buffer holds a valid
    Curve25519 key value given the endian ordering.

    \return 0 Returned when the public key value is valid.
    \return ECC_BAD_ARG_E Returned if the public key value is not valid.
    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.

    \param [in] pub Pointer to the buffer containing the public key to check.
    \param [in] pubSz Length of the public key to check.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
    form to use.

    _Example_
    \code
    int ret;

    byte pub[] = { Contents of public key };

    ret = wc_curve25519_check_public_ex(pub, sizeof(pub), EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error importing key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_import_public
    \sa wc_curve25519_import_public_ex
    \sa wc_curve25519_size
*/

int wc_curve25519_check_public(const byte* pub, word32 pubSz, int endian);

/*!
    \ingroup Curve25519

    \brief This function exports a public key from the given key structure and
    stores the result in the out buffer. Big endian only.

    \return 0 Returned on successfully exporting the public key from the
    curve25519_key structure.
    \return ECC_BAD_ARG_E Returned if outLen is less than
    CURVE25519_PUB_KEY_SIZE.
    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.

    \param [in] key Pointer to the curve25519_key structure in from which to
    export the key.
    \param [out] out Pointer to the buffer in which to store the public key.
    \param [in,out] outLen On in, is the size of the out in bytes.
    On out, will store the bytes written to the output buffer.

    _Example_
    \code
    int ret;

    byte pub[32];
    int pubSz;

    curve25519_key key;
    // initialize and make key
    ret = wc_curve25519_export_public(&key, pub, &pubSz);
    if (ret != 0) {
        // error exporting key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_export_private_raw
    \sa wc_curve25519_import_public
*/

int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen);

/*!
    \ingroup Curve25519

    \brief This function exports a public key from the given key structure and
    stores the result in the out buffer. Supports both big and little endian.

    \return 0 Returned on successfully exporting the public key from the
    curve25519_key structure.
    \return ECC_BAD_ARG_E Returned if outLen is less than
    CURVE25519_PUB_KEY_SIZE.
    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.

    \param [in] key Pointer to the curve25519_key structure in from which to
    export the key.
    \param [out] out Pointer to the buffer in which to store the public key.
    \param [in,out] outLen On in, is the size of the out in bytes.
    On out, will store the bytes written to the output buffer.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
    form to use.

    _Example_
    \code
    int ret;

    byte pub[32];
    int pubSz;

    curve25519_key key;
    // initialize and make key

    ret = wc_curve25519_export_public_ex(&key, pub, &pubSz, EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error exporting key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_export_private_raw
    \sa wc_curve25519_import_public
*/

int wc_curve25519_export_public_ex(curve25519_key* key, byte* out,
                                   word32* outLen, int endian);

/*!
    \ingroup Curve25519

    \brief Export Curve25519 key pair.  Big endian only.

    \return 0 Returned on successfully exporting the key pair from the
    curve25519_key structure.
    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
    \return ECC_BAD_ARG_E Returned if privSz is less than CURVE25519_KEY_SIZE or
    pubSz is less than CURVE25519_PUB_KEY_SIZE.

    \param [in] key Pointer to the curve25519_key structure in from which to
    export the key pair.
    \param [out] priv Pointer to the buffer in which to store the private key.
    \param [in,out] privSz On in, is the size of the priv buffer in bytes.
    On out, will store the bytes written to the priv buffer.
    \param [out] pub Pointer to the buffer in which to store the public key.
    \param [in,out] pubSz On in, is the size of the pub buffer in bytes.
    On out, will store the bytes written to the pub buffer.

    _Example_
    \code
    int ret;

    byte pub[32];
    byte priv[32];
    int pubSz;
    int privSz;

    curve25519_key key;
    // initialize and make key

    ret = wc_curve25519_export_key_raw(&key, priv, &privSz, pub, &pubSz);
    if (ret != 0) {
        // error exporting key
    }
    \endcode

    \sa wc_curve25519_export_key_raw_ex
    \sa wc_curve25519_export_private_raw
*/

int wc_curve25519_export_key_raw(curve25519_key* key,
                                 byte* priv, word32 *privSz,
                                 byte* pub, word32 *pubSz);

/*!
    \ingroup Curve25519

    \brief Export curve25519 key pair.  Big or little endian.

    \return 0 Returned on successfully exporting the key pair from the
    curve25519_key structure.
    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
    \return ECC_BAD_ARG_E Returned if privSz is less than CURVE25519_KEY_SIZE or
    pubSz is less than CURVE25519_PUB_KEY_SIZE.

    \param [in] key Pointer to the curve25519_key structure in from which to
    export the key pair.
    \param [out] priv Pointer to the buffer in which to store the private key.
    \param [in,out] privSz On in, is the size of the priv buffer in bytes.
    On out, will store the bytes written to the priv buffer.
    \param [out] pub Pointer to the buffer in which to store the public key.
    \param [in,out] pubSz On in, is the size of the pub buffer in bytes.
    On out, will store the bytes written to the pub buffer.
    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
    form to use.

    _Example_
    \code
    int ret;

    byte pub[32];
    byte priv[32];
    int pubSz;
    int privSz;

    curve25519_key key;
    // initialize and make key

    ret = wc_curve25519_export_key_raw_ex(&key, priv, &privSz, pub, &pubSz,
            EC25519_BIG_ENDIAN);
    if (ret != 0) {
        // error exporting key
    }
    \endcode

    \sa wc_curve25519_export_key_raw
    \sa wc_curve25519_export_private_raw_ex
    \sa wc_curve25519_export_public_ex
*/

int wc_curve25519_export_key_raw_ex(curve25519_key* key,
                                    byte* priv, word32 *privSz,
                                    byte* pub, word32 *pubSz,
                                    int endian);

/*!
    \ingroup Curve25519

    \brief This function returns the key size of the given key structure.

    \return Success Given a valid, initialized curve25519_key structure,
    returns the size of the key.
    \return 0 Returned if key is NULL

    \param [in] key Pointer to the curve25519_key structure in for which to
    determine the key size.

    _Example_
    \code
    int keySz;

    curve25519_key key;
    // initialize and make key

    keySz = wc_curve25519_size(&key);
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
*/

int wc_curve25519_size(curve25519_key* key);

/*!
    \ingroup Curve25519
    \brief This function generates a Curve25519 public key from a given
    private key. This is a lower-level function that operates directly
    on byte buffers rather than curve25519_key structures.

    \return 0 On successfully generating the public key
    \return ECC_BAD_ARG_E If the key sizes are invalid
    \return BAD_FUNC_ARG If any input parameters are NULL

    \param private_size Size of the private key (must be 32)
    \param priv Pointer to buffer containing the private key
    \param public_size Size of the public key buffer (must be 32)
    \param pub Pointer to buffer to store the public key

    _Example_
    \code
    byte priv[CURVE25519_KEYSIZE];
    byte pub[CURVE25519_KEYSIZE];

    // initialize priv with private key
    int ret = wc_curve25519_make_pub(sizeof(priv), priv, sizeof(pub),
                                     pub);
    if (ret != 0) {
        // error generating public key
    }
    \endcode

    \sa wc_curve25519_make_key
    \sa wc_curve25519_make_pub_blind
*/
int wc_curve25519_make_pub(int private_size, const byte* priv,
                           int public_size, byte* pub);

/*!
    \ingroup Curve25519
    \brief This function generates a Curve25519 public key from a given
    private key with blinding to resist side-channel attacks. This adds
    randomization to the scalar multiplication operation.

    \return 0 On successfully generating the public key
    \return ECC_BAD_ARG_E If the key sizes are invalid
    \return BAD_FUNC_ARG If any input parameters are NULL

    \param private_size Size of the private key (must be 32)
    \param priv Pointer to buffer containing the private key
    \param public_size Size of the public key buffer (must be 32)
    \param pub Pointer to buffer to store the public key
    \param rng Pointer to initialized RNG for blinding

    _Example_
    \code
    WC_RNG rng;
    byte priv[CURVE25519_KEYSIZE];
    byte pub[CURVE25519_KEYSIZE];

    wc_InitRng(&rng);
    // initialize priv with private key
    int ret = wc_curve25519_make_pub_blind(sizeof(priv), priv,
                                           sizeof(pub), pub, &rng);
    if (ret != 0) {
        // error generating public key
    }
    \endcode

    \sa wc_curve25519_make_pub
    \sa wc_curve25519_generic_blind
*/
int wc_curve25519_make_pub_blind(int private_size, const byte* priv,
                                 int public_size, byte* pub,
                                 WC_RNG* rng);

/*!
    \ingroup Curve25519
    \brief This function performs a generic Curve25519 scalar
    multiplication with a custom basepoint. This allows computing
    scalar * basepoint for any basepoint, not just the standard
    generator.

    \return 0 On successfully computing the result
    \return ECC_BAD_ARG_E If the sizes are invalid
    \return BAD_FUNC_ARG If any input parameters are NULL

    \param private_size Size of the scalar (must be 32)
    \param priv Pointer to buffer containing the scalar
    \param public_size Size of the output buffer (must be 32)
    \param pub Pointer to buffer to store the result
    \param basepoint_size Size of the basepoint (must be 32)
    \param basepoint Pointer to buffer containing the basepoint

    _Example_
    \code
    byte scalar[CURVE25519_KEYSIZE];
    byte basepoint[CURVE25519_KEYSIZE];
    byte result[CURVE25519_KEYSIZE];

    // initialize scalar and basepoint
    int ret = wc_curve25519_generic(sizeof(scalar), scalar,
                                    sizeof(result), result,
                                    sizeof(basepoint), basepoint);
    if (ret != 0) {
        // error computing result
    }
    \endcode

    \sa wc_curve25519_shared_secret
    \sa wc_curve25519_generic_blind
*/
int wc_curve25519_generic(int private_size, const byte* priv,
                         int public_size, byte* pub,
                         int basepoint_size, const byte* basepoint);

/*!
    \ingroup Curve25519
    \brief This function performs a generic Curve25519 scalar
    multiplication with a custom basepoint and blinding to resist
    side-channel attacks.

    \return 0 On successfully computing the result
    \return ECC_BAD_ARG_E If the sizes are invalid
    \return BAD_FUNC_ARG If any input parameters are NULL

    \param private_size Size of the scalar (must be 32)
    \param priv Pointer to buffer containing the scalar
    \param public_size Size of the output buffer (must be 32)
    \param pub Pointer to buffer to store the result
    \param basepoint_size Size of the basepoint (must be 32)
    \param basepoint Pointer to buffer containing the basepoint
    \param rng Pointer to initialized RNG for blinding

    _Example_
    \code
    WC_RNG rng;
    byte scalar[CURVE25519_KEYSIZE];
    byte basepoint[CURVE25519_KEYSIZE];
    byte result[CURVE25519_KEYSIZE];

    wc_InitRng(&rng);
    // initialize scalar and basepoint
    int ret = wc_curve25519_generic_blind(sizeof(scalar), scalar,
                                          sizeof(result), result,
                                          sizeof(basepoint), basepoint,
                                          &rng);
    \endcode

    \sa wc_curve25519_generic
    \sa wc_curve25519_make_pub_blind
*/
int wc_curve25519_generic_blind(int private_size, const byte* priv,
                                int public_size, byte* pub,
                                int basepoint_size, const byte* basepoint,
                                WC_RNG* rng);

/*!
    \ingroup Curve25519
    \brief This function generates a Curve25519 private key using the
    given random number generator. This is a lower-level function that
    generates only the private key bytes.

    \return 0 On successfully generating the private key
    \return ECC_BAD_ARG_E If keysize is invalid
    \return BAD_FUNC_ARG If any input parameters are NULL
    \return RNG_FAILURE_E If random number generation fails

    \param rng Pointer to initialized RNG
    \param keysize Size of the key to generate (must be 32)
    \param priv Pointer to buffer to store the private key

    _Example_
    \code
    WC_RNG rng;
    byte priv[CURVE25519_KEYSIZE];

    wc_InitRng(&rng);
    int ret = wc_curve25519_make_priv(&rng, sizeof(priv), priv);
    if (ret != 0) {
        // error generating private key
    }
    \endcode

    \sa wc_curve25519_make_key
    \sa wc_curve25519_make_pub
*/
int wc_curve25519_make_priv(WC_RNG* rng, int keysize, byte* priv);

/*!
    \ingroup Curve25519
    \brief This function initializes a Curve25519 key with extended
    parameters, allowing specification of custom heap and device ID
    for hardware acceleration.

    \return 0 On successfully initializing the key
    \return BAD_FUNC_ARG If key is NULL

    \param key Pointer to the curve25519_key structure to initialize
    \param heap Pointer to heap hint for memory allocation (can be
    NULL)
    \param devId Device ID for hardware acceleration (use
    INVALID_DEVID for software only)

    _Example_
    \code
    curve25519_key key;
    void* heap = NULL;
    int devId = INVALID_DEVID;

    int ret = wc_curve25519_init_ex(&key, heap, devId);
    if (ret != 0) {
        // error initializing key
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_free
*/
int wc_curve25519_init_ex(curve25519_key* key, void* heap, int devId);

/*!
    \ingroup Curve25519
    \brief This function sets the RNG to be used with a Curve25519
    key. This is useful for operations that require randomness such
    as blinded scalar multiplication.

    \return 0 On successfully setting the RNG
    \return BAD_FUNC_ARG If key or rng is NULL

    \param key Pointer to the curve25519_key structure
    \param rng Pointer to initialized RNG

    _Example_
    \code
    WC_RNG rng;
    curve25519_key key;

    wc_InitRng(&rng);
    wc_curve25519_init(&key);
    int ret = wc_curve25519_set_rng(&key, &rng);
    if (ret != 0) {
        // error setting RNG
    }
    \endcode

    \sa wc_curve25519_init
    \sa wc_curve25519_make_key
*/
int wc_curve25519_set_rng(curve25519_key* key, WC_RNG* rng);

/*!
    \ingroup Curve25519
    \brief This function allocates and initializes a new Curve25519
    key structure with extended parameters. The caller is responsible
    for freeing the key with wc_curve25519_delete. These New/Delete
    functions are exposed to support allocation of the structure using
    dynamic memory to provide better ABI compatibility.

    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
    defined.

    \return Pointer to newly allocated curve25519_key on success
    \return NULL on failure

    \param heap Pointer to heap hint for memory allocation (can be
    NULL)
    \param devId Device ID for hardware acceleration (use
    INVALID_DEVID for software only)
    \param result_code Pointer to store result code (0 on success)

    _Example_
    \code
    int ret;
    curve25519_key* key;

    key = wc_curve25519_new(NULL, INVALID_DEVID, &ret);
    if (key == NULL || ret != 0) {
        // error allocating key
    }
    // use key
    wc_curve25519_delete(key, &key);
    \endcode

    \sa wc_curve25519_delete
    \sa wc_curve25519_init_ex
*/
curve25519_key* wc_curve25519_new(void* heap, int devId,
                                  int *result_code);

/*!
    \ingroup Curve25519
    \brief This function frees a Curve25519 key structure that was
    allocated with wc_curve25519_new and sets the pointer to NULL.
    These New/Delete functions are exposed to support allocation of the
    structure using dynamic memory to provide better ABI compatibility.

    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
    defined.

    \return 0 On successfully freeing the key
    \return BAD_FUNC_ARG If key or key_p is NULL

    \param key Pointer to the curve25519_key structure to free
    \param key_p Pointer to the key pointer (will be set to NULL)

    _Example_
    \code
    int ret;
    curve25519_key* key;

    key = wc_curve25519_new(NULL, INVALID_DEVID, &ret);
    // use key
    ret = wc_curve25519_delete(key, &key);
    if (ret != 0) {
        // error freeing key
    }
    // key is now NULL
    \endcode

    \sa wc_curve25519_new
    \sa wc_curve25519_free
*/
int wc_curve25519_delete(curve25519_key* key, curve25519_key** key_p);