SharkSslPSAConsumerECDH.h File Reference

#include "SharkSSL.h"
#include "SharkSslPSAConsumerCurves.h"

Go to the source code of this file.

Data Structures
struct	SharkSslPSAEcdhKey
	Standalone ECDH private key owned by the external PSA provider. More...

Typedefs
typedef struct SharkSslPSAEcdhKey	SharkSslPSAEcdhKey
	Standalone ECDH private key owned by the external PSA provider. More...

Functions
SHARKSSL_API int	SharkSslPSAEcdhKey_generate (SharkSslPSAEcdhKey *o, U16 curveID)
	Generate a volatile ECDH private key for a supported standalone curve. More...
SHARKSSL_API int	SharkSslPSAEcdhKey_import (SharkSslPSAEcdhKey *o, U16 curveID, const U8 *privateKey, U16 privateKeyLen)
	Import a private scalar: big-endian for Weierstrass, little-endian for X25519/X448. More...
SHARKSSL_API int	SharkSslPSAEcdhKey_exportPublic (const SharkSslPSAEcdhKey *o, U8 *publicKey, U16 publicKeySize, U16 *publicKeyLen)
	Export the public key as SEC1 uncompressed or RFC 7748. More...
SHARKSSL_API int	SharkSslPSAEcdhKey_agree (const SharkSslPSAEcdhKey *o, const U8 *peerPublicKey, U16 peerPublicKeyLen, U8 *sharedSecret, U16 sharedSecretSize, U16 *sharedSecretLen)
	Derive a raw shared secret; clear it on any failure, including all-zero Montgomery output. More...
SHARKSSL_API int	SharkSslPSAEcdhKey_destructor (SharkSslPSAEcdhKey *o)
	Destroy the volatile PSA key and clear this context. More...

Detailed Description

See Choose a SharkSSL API for build scope and the owning API layer.

Typedef Documentation

SharkSslPSAEcdhKey

typedef struct SharkSslPSAEcdhKey SharkSslPSAEcdhKey

Standalone ECDH private key owned by the external PSA provider.

Initialize once, then call destructor before reusing this context.

Function Documentation

SharkSslPSAEcdhKey_agree()

int SharkSslPSAEcdhKey_agree	(	const SharkSslPSAEcdhKey *	o,
		const U8 *	peerPublicKey,
		U16	peerPublicKeyLen,
		U8 *	sharedSecret,
		U16	sharedSecretSize,
		U16 *	sharedSecretLen
	)

Derive a raw shared secret; clear it on any failure, including all-zero Montgomery output.

Rejects an all-zero agreement result.

With a valid length pointer and output buffer, failure clears the supplied output capacity. Apply the protocol's key derivation to the shared secret; this API performs raw agreement.

Parameters

o	const SharkSslPSAEcdhKey *; required live private-key context.
peerPublicKey	const U8 *; required peer public key in the same curve encoding as exportPublic.
peerPublicKeyLen	U16; exact curve-specific public-key length in bytes.
sharedSecret	U8 *; required caller-owned secret output buffer.
sharedSecretSize	U16; output capacity in bytes, at least the curve's scalar width.
sharedSecretLen	U16 *; required result byte count; initialized to zero.

Returns

int: 0 on success; -1 for invalid arguments, unsupported algorithms/policies, or provider failure.

SharkSslPSAEcdhKey_destructor()

int SharkSslPSAEcdhKey_destructor

(

SharkSslPSAEcdhKey *

o

)

Destroy the volatile PSA key and clear this context.

Parameters

o	SharkSslPSAEcdhKey *; required initialized context. An empty handle is accepted; successful destruction clears the object.

Returns

int: 0 on success; -1 for NULL or provider destruction failure. Failure retains the handle for a later cleanup attempt.

SharkSslPSAEcdhKey_exportPublic()

int SharkSslPSAEcdhKey_exportPublic	(	const SharkSslPSAEcdhKey *	o,
		U8 *	publicKey,
		U16	publicKeySize,
		U16 *	publicKeyLen
	)

Export the public key as SEC1 uncompressed or RFC 7748.

Parameters

o	const SharkSslPSAEcdhKey *; required live key context.
publicKey	U8 *; required output buffer. Weierstrass output is 0x04 followed by fixed-width X and Y; Montgomery output is the raw public value.
publicKeySize	U16; capacity in bytes, sufficient for the curve encoding.
publicKeyLen	U16 *; required result length in bytes; set to zero on failure.

Returns

int: 0 on success; -1 for invalid arguments, unsupported algorithms/policies, or provider failure.

SharkSslPSAEcdhKey_generate()

int SharkSslPSAEcdhKey_generate	(	SharkSslPSAEcdhKey *	o,
		U16	curveID
	)

Generate a volatile ECDH private key for a supported standalone curve.

On success the context owns a volatile key with ECDH derivation policy.

Use SharkSslPSAEcdhKey_destructor to release it.

Parameters

o	SharkSslPSAEcdhKey *; required caller-owned empty context. Destroy its existing key successfully before reuse; creation initializes the storage.
curveID	U16; supported curve identifier from SharkSslPSAConsumerCurves.h or SharkSSL.h; the provider must support that curve.

Returns

int: 0 on success; -1 for invalid arguments, unsupported algorithms/policies, or provider failure.

SharkSslPSAEcdhKey_import()

int SharkSslPSAEcdhKey_import	(	SharkSslPSAEcdhKey *	o,
		U16	curveID,
		const U8 *	privateKey,
		U16	privateKeyLen
	)

Import a private scalar: big-endian for Weierstrass, little-endian for X25519/X448.

On success the context owns a volatile key with ECDH derivation policy.

Use SharkSslPSAEcdhKey_destructor to release it.

Parameters

o	SharkSslPSAEcdhKey *; required caller-owned empty context. Destroy its existing key successfully before reuse; creation initializes the storage.
curveID	U16; supported curve identifier from SharkSslPSAConsumerCurves.h or SharkSSL.h; the provider must support that curve.
privateKey	const U8 *; required private scalar in the selected provider's PSA encoding; borrowed for this call.
privateKeyLen	U16; exact curve-specific private-key length in bytes (28/32/40/48/64/66 for supported Weierstrass curves, 32 for X25519, 56 for X448).

Returns

int: 0 on success; -1 for invalid arguments, unsupported algorithms/policies, or provider failure.