/**
 * @file se050_x25519_sw.h
 * @brief Software X25519 ECDH Implementation Header
 * 
 * Pure software implementation for WireGuard ephemeral key generation.
 * Fallback when SE050 hardware is unavailable.
 * 
 * License: MIT (Clean-room implementation)
 */

#ifndef SE050_X25519_SW_H
#define SE050_X25519_SW_H

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

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================================
 * Constants
 * ============================================================================ */

#define X25519_SECRET_KEY_SIZE  32
#define X25519_PUBLIC_KEY_SIZE  32
#define X25519_SHARED_SECRET_SIZE  32

/* ============================================================================
 * Type Definitions
 * ============================================================================ */

/**
 * @brief X25519 keypair structure
 */
typedef struct {
    uint8_t private_key[X25519_SECRET_KEY_SIZE];
    uint8_t public_key[X25519_PUBLIC_KEY_SIZE];
} se050_x25519_sw_keypair_t;

/* ============================================================================
 * API Functions
 * ============================================================================ */

/**
 * @brief Generate X25519 keypair
 * 
 * @param keypair Output keypair structure
 * @param rng_func Random number generator function
 * @param rng_ctx RNG context
 * @return 0 on success, -1 on error
 */
typedef int (*x25519_rng_func)(uint8_t *dst, size_t len, void *rng_ctx);

int se050_x25519_sw_generate_keypair(
    se050_x25519_sw_keypair_t *keypair,
    x25519_rng_func rng_func,
    void *rng_ctx
);

/**
 * @brief Compute X25519 shared secret
 * 
 * @param shared_secret Output shared secret (32 bytes)
 * @param private_key Private key (32 bytes, will be clamped)
 * @param peer_public Peer's public key (32 bytes)
 * @return 0 on success, -1 on error
 */
int se050_x25519_sw_compute_shared_secret(
    uint8_t *shared_secret,
    const uint8_t *private_key,
    const uint8_t *peer_public
);

/**
 * @brief Compute X25519 public key from private key
 * 
 * @param public_key Output public key (32 bytes)
 * @param private_key Private key (32 bytes, will be clamped)
 * @return 0 on success, -1 on error
 */
int se050_x25519_sw_derive_public_key(
    uint8_t *public_key,
    const uint8_t *private_key
);

/**
 * @brief Clamp X25519 private key
 * 
 * Applies X25519 scalar clamping:
 * - Clear bits 0, 1, 2 of first byte
 * - Clear bit 254 of last byte
 * - Set bit 255 of last byte
 * 
 * @param scalar Private key to clamp (modified in place)
 */
void se050_x25519_sw_clamp(uint8_t *scalar);

/**
 * @brief Securely zeroize key material
 * 
 * @param key Key material to zeroize
 * @param len Length in bytes
 */
void se050_x25519_sw_zeroize(uint8_t *key, size_t len);

#ifdef __cplusplus
}
#endif

#endif /* SE050_X25519_SW_H */