refactor(esp_tee): Update TEE secure storage examples and test-apps

Author: laukik-hase

components/esp_tee/scripts/esp_tee_sec_stg_keygen/README.md

@@ -0,0 +1,95 @@
+# TEE Secure Storage: Image Generation
+
+
+## A. Generate Secure Key Blobs
+
+### `esp_tee_sec_stg_keygen` tool
+
+```
+$ python esp_tee_sec_stg_keygen.py --help
+usage: esp_tee_sec_stg_keygen.py [-h] -k {aes256,ecdsa_p256,ecdsa_p192} -o OUTPUT [-i INPUT] [--write-once]
+
+Generate or import a cryptographic key structure for secure storage
+
+options:
+  -h, --help            show this help message and exit
+  -k, --key-type {aes256,ecdsa_p256,ecdsa_p192}
+                        key type to be processed
+  -o, --output OUTPUT   output binary file name
+  -i, --input INPUT     input key file (.pem for ecdsa, .bin for aes)
+  --write-once          make key persistent - cannot be modified or deleted once written
+```
+
+### ECDSA Keys
+
+```bash
+python esp_tee_sec_stg_keygen.py -k ecdsa_p256 -o ecdsa_p256_k0.bin
+python esp_tee_sec_stg_keygen.py -k ecdsa_p192 -o ecdsa_p192_k0.bin
+```
+
+#### With custom PEM:
+
+```bash
+openssl ecparam -name prime256v1 -genkey -noout -out ecdsa_p256.pem
+python esp_tee_sec_stg_keygen.py -k ecdsa_p256 -o ecdsa_p256_k1.bin -i ecdsa_p256.pem --write-once
+```
+
+### AES-256 Key
+
+```bash
+python esp_tee_sec_stg_keygen.py -k aes256 -o aes256_gcm_k0.bin --write-once
+```
+
+#### With custom key and IV
+
+```bash
+# Generate 32 bytes AES key
+openssl rand 32 > aes_key.bin
+
+# Generate 12 bytes IV (optional)
+openssl rand 12 >> aes_key.bin
+
+# Generate AES key blob using custom key + IV
+python esp_tee_sec_stg_keygen.py -k aes256 -o aes256_gcm_k1.bin -i aes_key.bin
+```
+
+## B. NVS Partition Image Generation
+
+### Create the TEE Secure Storage CSV
+
+Prepare a CSV file that defines the data to be used as input for the NVS Partition Generator utility.
+
+```csv
+key,type,encoding,value
+tee_sec_stg_ns,namespace,,
+aes256_key0,file,binary,aes256_gcm_k0.bin
+p256_key0,file,binary,ecdsa_p256_k0.bin
+p192_key0,file,binary,ecdsa_p192_k0.bin
+attest_key0,file,binary,ecdsa_p256_k1.bin
+```
+> [!IMPORTANT]
+> As per the current implementation, all data objects in the TEE Secure Storage are to be stored in the `tee_sec_stg_ns` namespace.
+
+### Generate NVS Encryption Keys
+
+```bash
+python nvs_partition_gen.py generate-key --key_protect_hmac --kp_hmac_inputkey hmac_key.bin --keyfile nvs_keys.bin
+```
+
+> [!IMPORTANT]
+> `hmac_key.bin` must match the HMAC key programmed into the eFuse block specified by `CONFIG_SECURE_TEE_SEC_STG_EFUSE_HMAC_KEY_ID`.
+
+### Generate encrypted NVS partition
+
+```bash
+python nvs_partition_gen.py encrypt tee_sec_stg_val.csv tee_sec_stg_nvs.bin 0x8000 --inputkey nvs_keys.bin
+```
+
+> [!NOTE]
+> Replace `0x8000` with the actual size of the TEE Secure Storage partition as configured in your project's partition table.
+
+## (Optional) Decrypt for Verification
+
+```bash
+python nvs_partition_gen.py decrypt tee_sec_stg_nvs.bin nvs_keys.bin tee_sec_stg_nvs_decr.bin
+```

components/esp_tee/scripts/esp_tee_sec_stg_keygen/esp_tee_sec_stg_keygen.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import argparse
+import os
+import struct
+from enum import Enum
+from enum import IntFlag
+from typing import Any
+from typing import Optional
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+# === Constants ===
+SEC_STG_KEY_DATA_SZ = 256
+AES_KEY_LEN = 32
+AES_DEFAULT_IV_LEN = 16
+AES_GCM_IV_LEN = 12
+ECDSA_P256_LEN = 32
+ECDSA_P192_LEN = 24
+
+
+# === Key Type Enum ===
+class KeyType(Enum):
+    AES256 = 0
+    ECDSA_P256 = 1
+    ECDSA_P192 = 2
+
+
+# === Bitwise Flags Enum ===
+class Flags(IntFlag):
+    NONE = 0x00000000
+    WRITE_ONCE = 0x00000001
+
+
+# === Key Generators ===
+
+
+def generate_aes256_key(flags: Flags, key_file: Optional[str] = None) -> bytes:
+    if key_file:
+        with open(key_file, 'rb') as f:
+            key_data = f.read()
+
+        if len(key_data) < AES_KEY_LEN:
+            raise ValueError('AES key file must be at least 32 bytes long')
+
+        key = key_data[:AES_KEY_LEN]
+        iv_data = key_data[AES_KEY_LEN:]
+
+        iv_len = len(iv_data)
+        if iv_len == 0:
+            iv = os.urandom(AES_DEFAULT_IV_LEN)
+        elif iv_len == AES_GCM_IV_LEN:
+            iv = iv_data + b'\x00' * (AES_DEFAULT_IV_LEN - AES_GCM_IV_LEN)
+        elif iv_len == AES_DEFAULT_IV_LEN:
+            iv = iv_data
+        else:
+            raise ValueError('IV length must be exactly 12 or 16 bytes, or omitted to generate one')
+    else:
+        key = os.urandom(AES_KEY_LEN)
+        iv = os.urandom(AES_DEFAULT_IV_LEN)
+
+    packed = struct.pack('<II32s16s', KeyType.AES256.value, flags.value, key, iv)
+    return packed + b'\x00' * (SEC_STG_KEY_DATA_SZ - len(packed))
+
+
+def generate_ecdsa_key(
+    curve: ec.EllipticCurve, key_type_enum: KeyType, key_len: int, flags: Flags, pem_file: Optional[str] = None
+) -> bytes:
+    if pem_file:
+        with open(pem_file, 'rb') as f:
+            private_key = serialization.load_pem_private_key(f.read(), password=None, backend=default_backend())
+        if not isinstance(private_key, ec.EllipticCurvePrivateKey):
+            raise ValueError('Provided PEM does not contain an EC private key')
+    else:
+        private_key = ec.generate_private_key(curve, default_backend())
+
+    priv = private_key.private_numbers().private_value.to_bytes(key_len, 'big')
+    pub = private_key.public_key().public_numbers()
+    x = pub.x.to_bytes(key_len, 'big')
+    y = pub.y.to_bytes(key_len, 'big')
+
+    packed = struct.pack(f'<II{key_len}s{key_len}s{key_len}s', key_type_enum.value, flags.value, priv, x, y)
+    return packed + b'\x00' * (SEC_STG_KEY_DATA_SZ - len(packed))
+
+
+def generate_key_data(key_type: KeyType, flags: Flags, input_file: Optional[str]) -> bytes:
+    if key_type == KeyType.AES256:
+        return generate_aes256_key(flags, input_file)
+    elif key_type == KeyType.ECDSA_P256:
+        return generate_ecdsa_key(ec.SECP256R1(), key_type, ECDSA_P256_LEN, flags, input_file)
+    elif key_type == KeyType.ECDSA_P192:
+        return generate_ecdsa_key(ec.SECP192R1(), key_type, ECDSA_P192_LEN, flags, input_file)
+    else:
+        raise ValueError(f'Unsupported key type: {key_type}')
+
+
+# === CLI ===
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description='Generate or import a cryptographic key structure for secure storage')
+    parser.add_argument(
+        '-k',
+        '--key-type',
+        type=str,
+        choices=[e.name.lower() for e in KeyType],
+        required=True,
+        help='key type to be processed',
+    )
+    parser.add_argument(
+        '-o',
+        '--output',
+        required=True,
+        help='output binary file name',
+    )
+    parser.add_argument(
+        '-i',
+        '--input',
+        help='input key file (.pem for ecdsa, .bin for aes)',
+    )
+    parser.add_argument(
+        '--write-once',
+        action='store_true',
+        help='make key persistent - cannot be modified or deleted once written',
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args: Any = parse_args()
+
+    key_type = KeyType[args.key_type.upper()]
+    flags = Flags.NONE
+    if args.write_once:
+        flags |= Flags.WRITE_ONCE
+
+    print(f'[+] Generating key of type: {key_type.name} (value: {key_type.value})')
+    if args.input:
+        print(f'[+] Using user-provided key file: {args.input}')
+    if args.write_once:
+        print('[+] WRITE_ONCE flag is set')
+
+    key_data = generate_key_data(key_type, flags, args.input)
+
+    with open(args.output, 'wb') as f:
+        f.write(key_data)
+
+    print(f'[✓] Key written to {args.output}')
+
+
+if __name__ == '__main__':
+    main()

components/esp_tee/test_apps/tee_cli_app/README.md

@@ -78,39 +78,41 @@ get_msg_sha256  "<msg>"
   Get the SHA256 digest for the given message
        "<msg>"  Message for SHA256 digest calculation
 
-tee_sec_stg_gen_key  <slot_id> <key_type>
-  Generate and store a new key of the specified type in the given TEE secure
-  storage slot
-     <slot_id>  TEE Secure storage slot for storing the key
-    <key_type>  Key type (0: ECDSA_SECP256R1, 1: AES256)
-
-tee_sec_stg_sign  <slot_id> <msg_sha256>
-  Sign a message using the ECDSA keypair stored in the given slot ID and verify
-  the signature
-     <slot_id>  TEE Secure storage slot storing the ecdsa-secp256r1 keypair
+tee_sec_stg_gen_key  <key_id> <key_type>
+  Generate and store a new key of the specified type with the given ID
+      <key_id>  TEE Secure storage key ID
+    <key_type>  Key type (0: AES256, 1: ECDSA_SECP256R1)
+
+tee_sec_stg_sign  <key_id> <msg_sha256>
+  Sign a message using the ECDSA keypair stored with the given key ID and
+  verify the signature
+      <key_id>  TEE Secure storage key ID
   <msg_sha256>  SHA256 digest of the message to be signed and verified
 
-tee_sec_stg_encrypt  <slot_id> <plaintext>
-  Encrypt data using AES-GCM with a key from secure storage
-     <slot_id>  TEE Secure storage slot storing the AES key
+tee_sec_stg_encrypt  <key_id> <plaintext>
+  Encrypt data using AES-GCM key with the given ID from secure storage
+      <key_id>  TEE Secure storage key ID
    <plaintext>  Plaintext to be encrypted
 
-tee_sec_stg_decrypt  <slot_id> <ciphertext> <tag>
-  Decrypt data using AES-GCM with a key from secure storage
-     <slot_id>  TEE Secure storage slot storing the AES key
+tee_sec_stg_decrypt  <key_id> <ciphertext> <tag>
+  Decrypt data using AES-GCM key with the given ID from secure storage
+      <key_id>  TEE Secure storage key ID
   <ciphertext>  Ciphertext to be decrypted
          <tag>  AES-GCM authentication tag
 
-help
-  Print the list of registered commands
+help  [<string>] [-v <0|1>]
+  Print the summary of all registered commands if no arguments are given,
+  otherwise print summary of given command.
+      <string>  Name of command
+  -v, --verbose=<0|1>  If specified, list console commands with given verbose level
 ```
 
 ## Secure Services
 
 ### Attestation
 
 - The `tee_att_info` command provided by the attestation service generates and dumps an Entity Attestation Token (EAT) signed by the TEE.
-- The token is signed using the ECDSA key (`secp256r1` curve) stored in the configured slot ID of the TEE Secure Storage.
+- The token is signed using the ECDSA key (`secp256r1` curve) stored in the TEE Secure Storage with the configured key ID.
 
 <details>
   <summary><b>Sample output:</b> <i>tee_att_info</i></summary>
@@ -128,22 +130,22 @@ I (8180) tee_attest: Attestation token - Data:
 ### Secure Storage
 
 - The TEE secure storage service provides the following commands:
-    - `tee_sec_stg_gen_key`: Generate and store a new key (ECDSA or AES) in a specified TEE secure storage slot
-    - `tee_sec_stg_sign`: Sign a message using an ECDSA `secp256r1` key pair stored in a specified slot and verify the signature
-    - `tee_sec_stg_encrypt`: Encrypt data with AES256-GCM using the key from the specified slot and outputs the ciphertext and tag
-    - `tee_sec_stg_decrypt`: Decrypt ciphertext using key from the specified slot and tag for integrity verification
+    - `tee_sec_stg_gen_key`: Generate and store a new key (ECDSA or AES) in the TEE secure storage with the specified ID
+    - `tee_sec_stg_sign`: Sign a message using an ECDSA `secp256r1` key pair with the specified ID and verify the signature
+    - `tee_sec_stg_encrypt`: Encrypt data with AES256-GCM using the key with the specified ID and outputs the ciphertext and tag
+    - `tee_sec_stg_decrypt`: Decrypt ciphertext using key with the specified ID and tag for integrity verification
 - The `get_msg_sha256` command computes the SHA256 hash of a given message, which can be used as input for the `tee_sec_stg_sign` command.
 
 <details>
   <summary><b>Sample output:</b> <i>tee_sec_stg_gen_key + get_msg_sha256 + tee_sec_stg_sign</i></summary>
 
 ```log
-esp32c6> tee_sec_stg_gen_key 7 0
-I (2964) tee_sec_stg: Generated ECDSA_SECP256R1 key in slot 7
+esp32c6> tee_sec_stg_gen_key ecdsa_p256_k0 1
+I (2964) tee_sec_stg: Generated ECDSA_SECP256R1 key with ID ecdsa_p256_k0
 esp32c6> get_msg_sha256 "hello world"
 I (3984) tee_sec_stg: Message digest (SHA256) -
 b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
-esp32c6> tee_sec_stg_sign 7 b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+esp32c6> tee_sec_stg_sign ecdsa_p256_k0 b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
 I (5384) tee_sec_stg: Generated signature -
 944684f6ddcf4c268ac6b65e34ccb8d95bd2849567a87867101bc1f09208f0885d935d7b3ba9d46014f28e4c7c988d68c775431fcb2cb2d4ca5c6862db771088
 I (6404) tee_sec_stg: Public key (Uncompressed) -
@@ -157,14 +159,14 @@ I (6444) tee_sec_stg: Signature verified successfully!
   <summary><b>Sample output:</b> <i>tee_sec_stg_gen_key + tee_sec_stg_encrypt + tee_sec_stg_decrypt</i></summary>
 
 ```log
-esp32c6> tee_sec_stg_gen_key 8 1
-I (2784) tee_sec_stg: Generated AES256 key in slot 8
-esp32c6> tee_sec_stg_encrypt 8 b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+esp32c6> tee_sec_stg_gen_key aes256_k0 0
+I (2784) tee_sec_stg: Generated AES256 key with ID key0
+esp32c6> tee_sec_stg_encrypt aes256_k0 b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
 I (3084) tee_sec_stg: Ciphertext -
 58054310a96d48c2dccdf2e34005aa63b40817723d3ec3d597ab362efea084c1
 I (3594) tee_sec_stg: Tag -
 caeedb43e08dc3b4e35a58b2412908cc
-esp32c6> tee_sec_stg_decrypt 8 58054310a96d48c2dccdf2e34005aa63b40817723d3ec3d597ab362efea084c1 caeedb43e08dc3b4e35a58b2412908cc
+esp32c6> tee_sec_stg_decrypt aes256_k0 58054310a96d48c2dccdf2e34005aa63b40817723d3ec3d597ab362efea084c1 caeedb43e08dc3b4e35a58b2412908cc
 I (4314) tee_sec_stg: Decrypted plaintext -
 b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
 ```

components/esp_tee/test_apps/tee_cli_app/main/app_main.c

@@ -18,6 +18,7 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 
+#include "esp_tee_sec_storage.h"
 #include "example_tee_srv.h"
 
 #define PROMPT_STR CONFIG_IDF_TARGET