14.2 VSS Keystore Module

Complete VSS page overlay (first 160 fixed bytes).

typedef struct {
    VSS_NvmWrappedFlashKey_t  flashKey;      /* offset 0x000 (64 bytes) */
    VSS_NvmPageHeader_t       pageHeader;    /* offset 0x040 (96 bytes) */
} VSS_Page_t;

96-byte page header at offset 0x040.

typedef struct {
    uint16_t                pageSeqNumber;
    uint8_t                 lifecycleState;
    uint8_t                 secBootConfig;
    VSS_SegmentDescriptor_t unencryptedSeg;
    VSS_SegmentDescriptor_t flashKeyEncSeg;
    VSS_SegmentDescriptor_t tamperKeyEncSeg;
    VSS_SegmentDescriptor_t tamperLogSeg;
    uint32_t                reservedA;
    uint32_t                fwRollbackMeta;
    uint32_t                fwVersion;
    uint8_t                 reservedB[32];
    uint8_t                 headerHash[32];
} VSS_NvmPageHeader_t;  /* 96 bytes at offset 0x040 */

4-byte segment locator within the page.

typedef struct {
    uint16_t offset;    /* Byte offset from page start */
    uint16_t size;      /* Segment size in bytes */
} VSS_SegmentDescriptor_t;  /* 4 bytes */

Header of the Variable Slot Meta Data Segment (at start of unencrypted segment).

typedef struct {
    uint16_t segmentSize;   /* Total size of this segment (including this field) */
    uint8_t  numSlots;      /* Number of slot metadata entries */
    uint8_t  reservedVSM;   /* Alignment padding */
} VSS_SlotMetaSegHeader_t;  /* 4 bytes */

16-byte metadata entry for one variable slot.

typedef struct {
    VSS_SlotHeader_t header;              /* Slot header (4 bytes) */
    uint32_t         validAfter;          /* Valid-after UNIX timestamp */
    uint32_t         validBefore;         /* Valid-before UNIX timestamp */
    uint32_t         dataSpecificMetaData; /* Type-specific metadata */
} VSS_SlotMetaData_t;  /* 16 bytes */

4-byte packed slot header.

typedef union {
    struct {
        uint8_t variableSlotIndex;   /* Slot index (e.g. 2, 3, 0x82) */
        uint8_t storageIndex;        /* Position in offset table */
        VSS_StorageData_t storageData; /* Storage attributes (bitfield) */
        uint8_t vsType : 3;          /* VSS_SlotType_t value */
    };
    uint32_t v;
} VSS_SlotHeader_t;  /* 4 bytes */

Interpretation of dataSpecificMetaData for ECC Weierstrass Prime keys.

typedef union {
    struct {
        uint32_t size        : 8;   /* Key size in bytes (32=P-256, 48=P-384) */
        uint32_t usage       : 1;   /* 0=key exchange, 1=signature */
        uint32_t algoUsed    : 1;   /* ECDSA algorithm flag */
        uint32_t paramA      : 2;   /* Curve parameter A type */
        uint32_t domainInc   : 1;   /* 1=domain parameters included */
        uint32_t publicKeyInc: 1;   /* 1=public key included */
        uint32_t privateKeyInc:1;   /* 1=private key included */
    };
    uint32_t v;
} VSS_EccWcPrimeKeyMeta_t;  /* 4 bytes (bitfield) */

const VSS_Page_t * VSS_GetPage ( uint8_t pageIndex );

Returns a memory-mapped pointer to the full VSS page.

Returns: const VSS_Page_t * or NULL if invalid.

Example:

const VSS_Page_t *pPage = VSS_GetPage(0);
if (pPage != NULL) {
    uint8_t lcs = pPage->pageHeader.lifecycleState;
    printf("Lifecycle: 0x%02X\n", lcs);
}

const VSS_NvmPageHeader_t * VSS_GetPageHeader ( uint8_t pageIndex );

Returns a pointer to the 96-byte page header.

Returns: const VSS_NvmPageHeader_t * or NULL.

Example:

const VSS_NvmPageHeader_t *pHdr = VSS_GetPageHeader(0);
if (pHdr != NULL) {
    printf("Seq: %u, FW Ver: 0x%08X\n",
           pHdr->pageSeqNumber, pHdr->fwVersion);
}

uint8_t VSS_GetActivePageIndex ( void );

Determines which page (0 or 1) is the most recent by comparing sequence numbers with 16-bit wrap-around handling.

Returns: 0 or 1.

Example:

uint8_t active = VSS_GetActivePageIndex();
const VSS_NvmPageHeader_t *pHdr = VSS_GetPageHeader(active);

uint8_t VSS_GetLifecycleState ( uint8_t pageIndex );

Returns the lifecycle state byte from the page header.

Returns: VSS_LifecycleState_t value. Returns 0xFF on error.

Example:

uint8_t lcs = VSS_GetLifecycleState(VSS_GetActivePageIndex());
if (lcs == (uint8_t)VSS_LIFECYCLE_SECURE) {
    printf("Device is in SECURE lifecycle\n");
}

const VSS_SlotMetaSegHeader_t * VSS_GetUnencryptedMetaSegment ( uint8_t pageIndex );

Returns a pointer to the Variable Slot Meta Data Segment header within the unencrypted segment. Uses the unencryptedSeg descriptor from the page header.

Returns: const VSS_SlotMetaSegHeader_t * or NULL.

Example:

uint8_t active = VSS_GetActivePageIndex();
const VSS_SlotMetaSegHeader_t *pMeta = VSS_GetUnencryptedMetaSegment(active);
if (pMeta != NULL) {
    printf("Segment size: %u, Num slots: %u\n",
           pMeta->segmentSize, pMeta->numSlots);
}

const VSS_SlotMetaData_t * VSS_GetSlotMetaData (
    uint8_t pageIndex,
    uint8_t slotIndex );

Returns a pointer to a specific 16-byte slot metadata entry.

Returns: const VSS_SlotMetaData_t * or NULL.

Example:

uint8_t active = VSS_GetActivePageIndex();
uint8_t count = VSS_GetSlotCount(active);

for (uint8_t i = 0; i < count; i++) {
    const VSS_SlotMetaData_t *pSlot = VSS_GetSlotMetaData(active, i);
    if (pSlot != NULL) {
        printf("Slot[%u]: vsIndex=%u, type=%u\n",
               i, pSlot->header.variableSlotIndex,
               pSlot->header.slotType);
    }
}

uint8_t VSS_GetSlotCount ( uint8_t pageIndex );

Returns the number of variable slot entries in the unencrypted segment.

Returns: Count (0..255), or 0 on error.

Example:

uint8_t n = VSS_GetSlotCount(VSS_GetActivePageIndex());
printf("Total slots in VSS: %u\n", n);

VSS_SlotType_t VSS_GetSlotType ( uint8_t pageIndex, uint8_t slotIndex );

Returns the type of the specified slot.

Returns: VSS_SlotType_t value. Returns VSS_SLOT_RAW (0) on error.

Example:

VSS_SlotType_t st = VSS_GetSlotType(active, 0);
if (st == VSS_SLOT_ASYMMETRICAL_KEY) {
    /* Parse ECC metadata from dataSpecificMetaData */
}

const uint8_t * VSS_GetFlashKey ( uint8_t pageIndex );

Returns a pointer to the 32-byte AES-256 Flash key.

Returns: const uint8_t * (32 bytes) or NULL.

#include "vss_keystore.h"
#include <stdio.h>

void print_vss_status(void)
{
    uint8_t active = VSS_GetActivePageIndex();
    const VSS_NvmPageHeader_t *pHdr = VSS_GetPageHeader(active);

    if (pHdr == NULL) {
        printf("ERROR: Cannot read VSS page %u\n", active);
        return;
    }

    printf("Active VSS page: %u\n", active);
    printf("Sequence number: 0x%04X\n", pHdr->pageSeqNumber);
    printf("Lifecycle state: 0x%02X\n", pHdr->lifecycleState);
    printf("Secure boot cfg: 0x%02X\n", pHdr->secBootConfig);
    printf("FW version:      0x%08X\n", pHdr->fwVersion);
    printf("Num slots:       %u\n", VSS_GetSlotCount(active));
}

void enumerate_vss_slots(void)
{
    uint8_t active = VSS_GetActivePageIndex();
    uint8_t count = VSS_GetSlotCount(active);

    static const char *typeNames[] = {
        "RAW", "SYMMETRIC", "ASYMMETRIC", "HASH", "HASH_IV", "VER_INFO"
    };

    for (uint8_t i = 0; i < count; i++) {
        const VSS_SlotMetaData_t *pMeta = VSS_GetSlotMetaData(active, i);
        if (pMeta == NULL) continue;

        uint8_t vsIdx = pMeta->header.variableSlotIndex;
        uint8_t st = pMeta->header.slotType;

        printf("  Slot 0x%02X: %s\n", vsIdx,
               (st < 6) ? typeNames[st] : "UNKNOWN");
    }
}

#include "vss_keystore.h"
#include <string.h>

/* Extract ECC public key coordinates (X, Y) from a VSS slot.
 * pXout and pYout must point to buffers of at least 48 bytes
 * (maximum for P-384). Actual size returned via *pKeySize. */
bool get_ecc_public_key(uint8_t pageIndex, uint8_t iterIdx,
                        uint8_t *pXout, uint8_t *pYout, uint16_t *pKeySize)
{
    if ((pXout == NULL) || (pYout == NULL) || (pKeySize == NULL))
    {
        return false;
    }

    const VSS_SlotMetaData_t *pMeta = VSS_GetSlotMetaData(pageIndex, iterIdx);
    if (pMeta == NULL)
    {
        return false;
    }
    
    if (pMeta->header.slotType != (uint8_t)VSS_SLOT_ASYMMETRICAL_KEY)
    {
        return false;
    }

    /* Parse key size and flags from dataSpecificMetaData */
    const VSS_EccWcPrimeKeyMeta_t *pEcc =
        (const VSS_EccWcPrimeKeyMeta_t *)&pMeta->dataSpecificMetaData;

    uint16_t keySize = (uint16_t)pEcc->size;  /* 32 for P-256, 48 for P-384 */
    *pKeySize = keySize;

    /* Check that public key is included in this slot */
    if (pEcc->publicKeyInc == 0U)
    {
        return false;  /* No public key in this slot */
    }

    /* Read the full slot data into a local buffer */
    static uint8_t slotBuf[256];
    uint16_t dataLen = VSS_ReadSlotData(iterIdx, slotBuf, (uint16_t)sizeof(slotBuf));
    if (dataLen == 0U)
    {
        return false;
    }

    /* Slot data layout for ECC Weierstrass Prime:
     *   [domain params if domainInc=1] (variable, typically not included)
     *   [public key X || Y]            (keySize * 2 bytes, if publicKeyInc=1)
     *   [private key]                  (keySize bytes, if privateKeyInc=1)
     */
    uint16_t offset = 0U;

    /* Skip domain parameters if present (rare) */
    if (pEcc->domainInc != 0U)
    {
        /* Domain params: p, a, b, Gx, Gy, n, h = 7 * keySize bytes */
        offset += (uint16_t)(7U * keySize);
    }

    /* Verify we have enough data for the public key */
    if ((offset + (2U * keySize)) > dataLen)
    {
        return false;
    }

    /* Copy X coordinate */
    memcpy(pXout, &slotBuf[offset], keySize);
    offset += keySize;

    /* Copy Y coordinate */
    memcpy(pYout, &slotBuf[offset], keySize);

    return true;
}

/* Usage example */
void print_slot2_public_key(void)
{
    uint8_t x[48], y[48];
    uint16_t keySize = 0;
    uint8_t active = VSS_GetActivePageIndex();

    if (get_ecc_public_key(active, 0, x, y, &keySize))
    {
        printf("Public Key (P-%u):\r\n", (unsigned)(keySize * 8U));
        printf("  X: ");
        for (uint16_t i = 0; i < keySize; i++) printf("%02X ", x[i]);
        printf("\r\n  Y: ");
        for (uint16_t i = 0; i < keySize; i++) printf("%02X ", y[i]);
        printf("\r\n");
    }
}

#include "vss_keystore.h"
#include "crypto/puf04891_pic32cmsg/drv_puf.h"

/* Check if a slot contains a PUF key code and return its actual size */
uint16_t get_keycode_actual_size(const uint8_t *pData, uint16_t rawLen)
{
    /* PUF key code magic: 0x37 0x10 */
    if (rawLen < 4) return rawLen;
    if (pData[0] != 0x37 || pData[1] != 0x10) return rawLen;

    /* keyLenBits at bytes 2-3 (little-endian) */
    uint16_t keyLenBits = (uint16_t)pData[2] | ((uint16_t)pData[3] << 8);
    if (keyLenBits == 0) return rawLen;

    uint16_t kcSize = (uint16_t)DRV_PUF_KEY_CODE_SIZE(keyLenBits);
    return (kcSize <= rawLen) ? kcSize : rawLen;
}