ISecureElement.h

Go to the documentation of this file.

#pragma once
 
#include "cdc_core/IService.h"
#include <cstdint>
#include <cstddef>
 
namespace cdc::hal {

enum class EccCurve : uint8_t {
    P256,       // NIST P-256 (secp256r1)
    ED25519     // Ed25519
};

inline uint8_t curveByte(EccCurve c) {
    return (c == EccCurve::ED25519) ? 0 : 1;
}

inline EccCurve curveFromByte(uint8_t b) {
    return (b == 0) ? EccCurve::ED25519 : EccCurve::P256;
}

enum class SeResult : uint8_t {
    OK,                 // Success
    ERROR,              // Generic error
    SESSION_REQUIRED,   // No active session
    SLOT_EMPTY,         // Key slot is empty
    SLOT_OCCUPIED,      // Slot already has a key
    INVALID_PARAM,      // Invalid parameter
    ALARM_MODE,         // Chip in alarm mode (tamper detected)
    NOT_SUPPORTED       // Operation not supported
};

class ISecureElement : public core::IService {
public:
    // Slot limits
    static constexpr uint8_t ECC_SLOT_COUNT = 32;
    static constexpr uint16_t RMEM_SLOT_COUNT = 512;
    // Minimum guaranteed slot size across all supported TROPIC01 Application
    // FW versions. Use for static layouts that must remain stable when the
    // chip is reflashed with older FW; query getRmemSlotSize() for the actual
    // runtime capability.
    static constexpr uint16_t RMEM_SLOT_SIZE = 444;
    // Stack-buffer ceiling sized for the largest known FW (>= 2.0 reports 475).
    static constexpr uint16_t RMEM_SLOT_SIZE_MAX = 475;
    static constexpr uint8_t RMEM_NAME_LEN = 16;
 
    virtual ~ISecureElement() = default;
 
    // === Session Management ===

    virtual bool sessionStart() = 0;

    virtual void sessionEnd() = 0;

    virtual bool isSessionActive() const = 0;

    virtual void sleep() = 0;
 
    // === ECC Key Operations ===

    virtual SeResult eccGenerate(uint8_t slot, EccCurve curve) = 0;

    virtual SeResult eccImport(uint8_t slot, const uint8_t* privKey, EccCurve curve) = 0;

    virtual SeResult eccGetPublicKey(uint8_t slot, uint8_t* pubKey, EccCurve* curve = nullptr) = 0;

    virtual SeResult eccDelete(uint8_t slot) = 0;

    virtual bool eccSlotUsed(uint8_t slot) const = 0;
 
    // === Signing Operations ===

    virtual SeResult ecdsaSign(uint8_t slot, const uint8_t* msg, size_t msgLen,
                               uint8_t* sig, size_t* sigLen) = 0;

    virtual SeResult eddsaSign(uint8_t slot, const uint8_t* msg, size_t msgLen,
                               uint8_t* sig) = 0;
 
    // === R-Memory Operations ===

    virtual SeResult rmemRead(uint16_t slot, uint8_t* data, uint16_t maxLen,
                              uint16_t* actualLen) = 0;

    virtual SeResult rmemWrite(uint16_t slot, const uint8_t* data, uint16_t len) = 0;

    virtual SeResult rmemErase(uint16_t slot) = 0;

    virtual bool rmemSlotUsed(uint16_t slot) const = 0;
 
    // === R-Memory Header Helpers ===
 
    struct __attribute__((packed)) RMemHeader {
        uint8_t magic;
        uint8_t checksum;
        uint8_t moduleId;
        uint8_t flags;
        char name[RMEM_NAME_LEN];
        uint16_t payloadLen;
    };

    virtual SeResult rmemWriteWithHeader(uint16_t slot, uint8_t moduleId,
                                         const char* name, uint8_t flags,
                                         const uint8_t* payload, uint16_t payloadLen) = 0;

    virtual SeResult rmemReadWithHeader(uint16_t slot, RMemHeader* headerOut,
                                        uint8_t* payloadOut, uint16_t payloadMax,
                                        uint16_t* payloadLenOut) = 0;
 
    // === Random Number Generator ===

    virtual bool getRandom(uint8_t* buffer, uint16_t size) = 0;

    virtual bool getRandomStrict(uint8_t* buffer, uint16_t size) = 0;
 
    // === Diagnostics ===

    virtual bool getChipId(uint8_t* serialNum, uint8_t size) = 0;

    virtual bool getFwVersion(uint8_t riscvVer[4], uint8_t spectVer[4]) = 0;

    virtual uint16_t getRmemSlotSize() const = 0;
};
 
// Factory function to get secure element instance
ISecureElement* getSecureElementInstance();
 
} // namespace cdc::hal