iqr_ecdh.h File Reference

ISARA Radiate Security Solution Suite's Elliptic Curve Diffie-Hellman. More...

Typedefs
typedef struct iqr_ECDHParams_struct	iqr_ECDHParams
typedef struct iqr_ECDHPrivateKey_struct	iqr_ECDHPrivateKey
typedef struct iqr_ECDHCurve_struct	iqr_ECDHCurve

Functions
IQR_API iqr_retval	iqr_ECDHCreateParams (const iqr_Context *ctx, const iqr_ECDHCurve *curve, iqr_ECDHParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_ECDHDestroyParams (iqr_ECDHParams **params)
IQR_API iqr_retval	iqr_ECDHGetPublicKeySize (const iqr_ECDHParams *params, size_t *public_key_size)
IQR_API iqr_retval	iqr_ECDHGetSecretSize (const iqr_ECDHParams *params, size_t *secret_size)
IQR_API iqr_retval	iqr_ECDHCreatePrivateKey (const iqr_ECDHParams *params, const iqr_RNG *rng, iqr_ECDHPrivateKey **private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_ECDHDestroyPrivateKey (iqr_ECDHPrivateKey **private_key)
IQR_API iqr_retval	iqr_ECDHGetPublicKey (const iqr_ECDHPrivateKey *private_key, uint8_t *public_key, size_t public_key_size)
IQR_API iqr_retval	iqr_ECDHGetSecret (const iqr_ECDHPrivateKey *private_key, const uint8_t *public_key, size_t public_key_size, uint8_t *secret, size_t secret_size)

Variables
IQR_EXTERN const iqr_ECDHCurve	IQR_ECDH_NISTP256
IQR_EXTERN const iqr_ECDHCurve	IQR_ECDH_NISTP384
IQR_EXTERN const iqr_ECDHCurve	IQR_ECDH_NISTP521
IQR_EXTERN const iqr_ECDHCurve	IQR_ECDH_X25519

Typedef Documentation

iqr_ECDHCurve

typedef struct iqr_ECDHCurve_struct iqr_ECDHCurve

Which curve to use.

iqr_ECDHParams

typedef struct iqr_ECDHParams_struct iqr_ECDHParams

The ECDH domain parameters.

iqr_ECDHPrivateKey

typedef struct iqr_ECDHPrivateKey_struct iqr_ECDHPrivateKey

The private key.

Function Documentation

iqr_ECDHCreateParams()

IQR_API iqr_retval iqr_ECDHCreateParams	(	const iqr_Context *	ctx,
		const iqr_ECDHCurve *	curve,
		iqr_ECDHParams **	params
	)

Create an ECDH Parameters object that encapsulates the domain parameters.

It's up to the user to manage domain parameters; the parameter data is not exposed in stored keys or secrets.

*params must be set to NULL before calling iqr_ECDHCreateParams().

Parameters

[in]	ctx	A Context object.
[in]	curve	iqr_ECDHCurve to use.
[out]	params	The iqr_ECDHParams output.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHCreatePrivateKey()

IQR_API iqr_retval iqr_ECDHCreatePrivateKey	(	const iqr_ECDHParams *	params,
		const iqr_RNG *	rng,
		iqr_ECDHPrivateKey **	private_key
	)

Create an ECDH private key to be used during shared secret generation.

The rng must be initialized before being passed to iqr_ECDHCreatePrivateKey().

*private_key must be set to NULL before calling iqr_ECDHCreatePrivateKey().

Note

If iqr_ECDHCreatePrivateKey() repeatedly returns IQR_ERESEED, your random number generator isn't producing uniformly random values. Use a cryptographically strong RNG (such as HMAC-DRBG, found in iqr_rng.h) with sufficient entropy.

Parameters

[in]	params	The iqr_ECDHParams to use.
[in]	rng	A seeded random number generator.
[out]	private_key	Used to store the private key.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_ECDHDestroyParams

(

iqr_ECDHParams **

params

)

Clear and deallocate an ECDH Parameter object.

params will be set to NULL prior to returning.

All internal iqr_ECDHParams buffers are cleared and deallocated during the call to iqr_ECDHDestroyParams(). The iqr_ECDHParams object does not store any cryptographic material.

Parameters

[in,out]

params

The iqr_ECDHParams instance to destroy.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_ECDHDestroyPrivateKey

(

iqr_ECDHPrivateKey **

private_key

)

Clear and deallocate an ECDH private key.

private_key will be set to NULL prior to returning.

The private key's data is cleared before its internal buffers are deallocated.

Parameters

[in,out]

private_key

The private key to destroy.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHGetPublicKey()

IQR_API iqr_retval iqr_ECDHGetPublicKey	(	const iqr_ECDHPrivateKey *	private_key,
		uint8_t *	public_key,
		size_t	public_key_size
	)

Create the public key needed for ECDH key agreement.

The public keys are output as an octet string as defined in SEC 1 Elliptic Curve Cryptography, seciton 2.3.

Parameters

[in]	private_key	The private key.
[out]	public_key	A buffer to retrieve the public key.
[in]	public_key_size	The size of public_key in bytes. This must be exactly the size returned by iqr_ECDHGetPublicKeySize().

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHGetPublicKeySize()

IQR_API iqr_retval iqr_ECDHGetPublicKeySize	(	const iqr_ECDHParams *	params,
		size_t *	public_key_size
	)

Get the size of an ECDH public key, in bytes.

Parameters

[in]	params	The iqr_ECDHParams to use.
[out]	public_key_size	The size of a public key, in bytes.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHGetSecret()

IQR_API iqr_retval iqr_ECDHGetSecret	(	const iqr_ECDHPrivateKey *	private_key,
		const uint8_t *	public_key,
		size_t	public_key_size,
		uint8_t *	secret,
		size_t	secret_size
	)

Get the ECDH shared secret.

Note

The output secret is a shared secret, not a key. This output must be passed through a KDF or hash function before being used. Do not use this secret directly.

Be sure to safely wipe and discard the secret after it's been used.

Parameters

[in]	private_key	The private key.
[in]	public_key	The public key.
[in]	public_key_size	The size of public_key in bytes. This must be exactly the size returned by iqr_ECDHGetPublicKeySize().
[out]	secret	A buffer to retrieve the shared secret.
[in]	secret_size	The size of secret in bytes. This must be exactly the size returned by iqr_ECDHGetSecretSize().

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_ECDHGetSecretSize()

IQR_API iqr_retval iqr_ECDHGetSecretSize	(	const iqr_ECDHParams *	params,
		size_t *	secret_size
	)

Get the size of an ECDH secret, in bytes.

Parameters

[in]	params	The iqr_ECDHParams to use.
[out]	secret_size	The size of a secret, in bytes.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

Variable Documentation

IQR_ECDH_NISTP256

IQR_EXTERN const iqr_ECDHCurve IQR_ECDH_NISTP256

NIST curve P-256, defined in FIPS 186-4 Appendix D.

IQR_ECDH_NISTP384

IQR_EXTERN const iqr_ECDHCurve IQR_ECDH_NISTP384

NIST curve P-384, defined in FIPS 186-4 Appendix D.

IQR_ECDH_NISTP521

IQR_EXTERN const iqr_ECDHCurve IQR_ECDH_NISTP521

NIST curve P-251, defined in FIPS 186-4 Appendix D.

IQR_ECDH_X25519

IQR_EXTERN const iqr_ECDHCurve IQR_ECDH_X25519

Curve25519, defined by Daniel Bernstein.

Detailed Description

ISARA Radiate Security Solution Suite's Elliptic Curve Diffie-Hellman.

Copyright

Copyright 2017-2018, ISARA Corporation, All Rights Reserved.

License

The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@.nosp@m.isar.nosp@m.a.com for more information.