pkcs12 file parser use mbedTLS

README.md

@@ -5,9 +5,11 @@
 1. [Introduction](#introduction)
 2. [Terms and Definitions](#terms-and-definitions)
 3. [SecAPI Overview](#secapi-overview)
-4. [Sample Use Cases](#sample-use-cases)
-5. [Robustness Rules](#robustness-rules)
-6. [References](#references)
+4. [Build](#build)
+5. [Source Structure](#source-structure)
+6. [Sample Use Cases](#sample-use-cases)
+7. [Robustness Rules](#robustness-rules)
+8. [References](#references)
 
 ## Introduction
 
@@ -140,14 +142,16 @@ container as well as authenticate the container.
 
 The API provides the following cryptographic capabilities:
 
-* AES cipher algorithm using ECB, CBC, and CTR mode.
-* AES GCM authenticated encryption and decryption.
-* RSA decryption using PKCS and OAEP padding.
-* RSA signature generation using PKCS and PSS padding.
-* ECDSA signature generation.
-* HMAC calculation using SHA1, SHA-256, SHA-384, and SHA-512.
-* AES CMAC calculation.
-* Random number generation.
+| Category | Operations |
+|---|---|
+| Symmetric | AES-CBC, AES-ECB, AES-CTR, AES-GCM (128/256-bit) |
+| Asymmetric | RSA (sign/verify, encrypt/decrypt, PKCS/OAEP padding, 1024–4096 bit), ECDSA (P-256, P-384, P-521), ECDH |
+| Hashing | SHA-1, SHA-256, SHA-384, SHA-512 |
+| MAC | HMAC (SHA-1, SHA-256, SHA-384, SHA-512), CMAC |
+| KDF | HKDF, Concat KDF, multi-round KDF |
+| Key Exchange | DH, ECDH (NIST curves), X25519, X448 |
+| Signature | RSA-PSS, RSA-PKCS1v15, ECDSA, Ed25519, Ed448 |
+| RNG | Random number generation |
 
 Public key operations are out of scope for the API. Digest operations are also out of scope for the
 API since digest operations do not require access to keys.
@@ -175,6 +179,81 @@ This reference implementation is implemented with simple examples of how to perf
 operations using OpenSSL. It has not been optimized to provide the fastest possible cryptographic
 operations.
 
+## Build
+
+### Prerequisites
+
+- macOS (ARM64 or Intel) or Linux
+- CMake 3.16+
+
+All dependencies are automatically resolved during the build:
+- **OpenSSL** — TLS Engine/Provider integration, test harness crypto verification; found on system if available, otherwise fetched from GitHub and built from source
+- **mbedTLS** — primary cryptographic backend for the TA implementation (AES, RSA, ECC, hashing, HMAC, CMAC)
+- **yajl** — JSON parsing for key containers and provisioning data
+- **libdecaf** — Ed448/X448 elliptic curve operations (EdDSA signatures, ECDH key exchange)
+- **ed25519-donna** — Ed25519 EdDSA signature operations
+- **curve25519-donna** — X25519 ECDH key exchange operations
+
+All library versions are defined in `reference/cmake/deps.cmake`.
+
+### Native Build (macOS / Linux)
+
+```bash
+mkdir build && cd build
+cmake .. -DENABLE_SVP=OFF -DCMAKE_BUILD_TYPE=Debug
+make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)
+```
+
+> **Note:** If OpenSSL is not installed on the system, CMake will fetch and build
+> it from source. In this case you **must** use `make -j1` for the first build —
+> parallel builds will fail because the OpenSSL build must complete before
+> dependent targets can compile. Subsequent rebuilds can use `-j` normally.
+
+### Build Flow (macOS / Linux)
+
+```mermaid
+flowchart TD
+    subgraph "Native Build (macOS / Linux)"
+        A[cmake ..] --> B{System OpenSSL found?}
+        B -->|Yes| C[Use system OpenSSL]
+        B -->|No| D[Fetch OpenSSL 3.x from GitHub & build]
+        C --> E[Fetch deps via deps.cmake]
+        D --> E
+        E --> F["mbedTLS, yajl, libdecaf, ed25519-donna, curve25519-donna"]
+        F --> G[make -j]
+        G --> H[saclienttest / taimpltest / util_*_test]
+    end
+```
+
+## Source Structure
+
+All source code lives under `reference/src/`. The directory is organized into layered modules:
+
+| Directory | Description |
+|---|---|
+| `client/` | Public API headers (`sa.h`, `sa_crypto.h`, `sa_key.h`, `sa_svp.h`, `sa_cenc.h`, etc.) and the client library. This is what applications include to use SecAPI. |
+| `clientimpl/` | Client implementation that bridges the public API to the Trusted Application layer. Marshals/unmarshals data between REE client code and the TA. |
+| `taimpl/` | Core Trusted Application implementation containing all cryptographic logic, key management, cipher/MAC/digest stores, and protocol-specific encryption (Netflix, CENC). Crypto backends live under `taimpl/src/internal/providers/` — mbedTLS, libdecaf, ed25519-donna, and curve25519-donna. An `openssl/` directory also exists under providers for build management purposes (OpenSSL auto-fetch); it is used only by taimpltest, not by the TA itself. |
+| `util/` | Shared utility library with **no crypto dependency**. Provides logging, digest helpers, and key-rights management used by all other modules. |
+| `util_mbedtls/` | mbedTLS-specific utilities: PKCS8/PKCS12 key format parsing, digest wrappers, hardware RNG abstraction, and mbedTLS test helpers. Built when the mbedTLS backend is selected. |
+| `util_openssl/` | OpenSSL-specific utilities: PKCS8/PKCS12 key format parsing, digest mechanism abstraction, and OpenSSL test helpers. Built when the OpenSSL backend is selected. |
+
+```
+reference/src/
+├── client/          # Public API (sa.h, sa_crypto.h, sa_key.h, …)
+├── clientimpl/      # REE ↔ TA bridge
+├── taimpl/          # TA core + crypto providers
+│   ├── include/     #   TA interface headers
+│   ├── src/
+│   │   ├── internal/        # Crypto logic (symmetric, rsa, ec, kdf, cenc, …)
+│   │   │   └── providers/   # mbedtls/, openssl/, decaf/, ed25519-donna/, curve25519-donna/
+│   │   └── porting/         # Platform-specific (init, rand, svp, transport)
+│   └── test/        #   taimpltest
+├── util/            # Logging, digest helpers (no crypto dep)
+├── util_mbedtls/    # mbedTLS utilities + util_mbedtls_test
+└── util_openssl/    # OpenSSL utilities + util_openssl_test
+```
+
 ## Sample Use Cases
 
 ### In-Field Key Provisioning

rdk_build/README.md

@@ -0,0 +1,116 @@
+# RDK Build — tasecureapi with mbedTLS
+
+## Overview
+
+This directory contains the BitBake recipe (`tasecureapi-mbedtls_1.0.bb`) for
+cross-compiling tasecureapi on an RDK (Yocto) build server targeting ARM32.
+
+`ENABLE_SVP` is **ON by default** in the recipe.
+
+## Build Instructions
+
+### Prerequisites
+
+- RDK Yocto build environment (oe-init-build-env sourced)
+- Recipe placed under your Yocto layer, e.g.:
+  `meta-rdk-vendor-test-utils/recipes-extend/mbedtls2.6.1/`
+- Source tree placed under `files/tasecureapi/` alongside the recipe
+
+### Build
+
+```bash
+# Source the build environment
+source ~/sharp-mtk/rdke/common/poky/oe-init-build-env ~/sharp-mtk/scripts/build-sharp-m120-32
+
+# Full build
+bitbake lib32-tasecureapi-mbedtls
+
+# Clean rebuild (after source changes)
+bitbake lib32-tasecureapi-mbedtls -c cleansstate && bitbake lib32-tasecureapi-mbedtls
+```
+
+### Build with SVP OFF
+
+To disable SVP, edit the recipe and change `-DENABLE_SVP=ON` to `-DENABLE_SVP=OFF`
+in the `EXTRA_OECMAKE` block, then do a clean rebuild.
+
+Alternatively, override via `local.conf` without modifying the recipe:
+
+```bash
+# In conf/local.conf — override SVP to OFF
+EXTRA_OECMAKE:remove:pn-lib32-tasecureapi-mbedtls = "-DENABLE_SVP=ON"
+EXTRA_OECMAKE:append:pn-lib32-tasecureapi-mbedtls = " -DENABLE_SVP=OFF"
+```
+
+## Expected Test Results (ARM32)
+
+### saclienttest
+
+| Configuration | Total Tests | Passed | Failed | Skipped | Notes |
+|---|---|---|---|---|---|
+| SVP=ON  | 6670 | 6454 | **216** | — | 216 CENC timing failures |
+| SVP=ON + DISABLE_CENC_TIMING | 6670 | **6670** | **0** | — | All pass (757393 ms) |
+| SVP=OFF | 6635 | ~5352 | **72**  | ~1211 | 72 CENC timing failures  |
+
+### taimpltest
+
+| Configuration | Total Tests | Passed | Failed | Skipped | Notes |
+|---|---|---|---|---|---|
+| SVP=ON  | 707 | **635** | **72** | 0 | 72 CENC timing failures (`TaProcessCommonEncryptionTests_1000000`) |
+| SVP=ON + DISABLE_CENC_TIMING | 707 | **707** | **0** | 0 | All pass (18666 ms) |
+| SVP=OFF | 143 | **43** | 0 | 100 | — |
+
+### util_mbedtls_test
+
+| Configuration | Total Tests | Passed | Failed |
+|---|---|---|---|
+| SVP=ON  | 13 | **13** | 0 |
+| SVP=OFF | 13 | **13** | 0 |
+
+### util_openssl_test
+
+| Configuration | Total Tests | Passed | Failed |
+|---|---|---|---|
+| SVP=ON  | 2 | **2** | 0 |
+| SVP=OFF | 2 | **2** | 0 |
+
+All util tests require `root_keystore.p12` in the working directory.
+Deploy it alongside the test binaries:
+
+```bash
+scp root_keystore.p12 root@<target>:/opt/mbedtls261/
+```
+
+### Known Failures — CENC Timing
+
+All CENC timing failures are in the `*ProcessCommonEncryptionTests_1000000` test suites
+(both `SaProcessCommonEncryptionTests_1000000` in saclienttest and
+`TaProcessCommonEncryptionTests_1000000` in taimpltest).
+These tests decrypt **1 MB of CENC data** and assert that decryption completes
+within a timing threshold (`ASSERT_LE(duration.count(), sample_time)`).
+
+On ARM32 hardware the decryption is functionally correct but exceeds the
+timing threshold, causing assertion failures:
+
+**saclienttest:**
+- SVP=OFF: 72 failures (72 parameter combinations)
+- SVP=ON: 216 failures (72 combinations × 3 SVP offset variants: `(0,0)`, `(1,0)`, `(1,1)`)
+
+**taimpltest:**
+- SVP=ON: 72 failures (72 parameter combinations, single SVP offset variant)
+
+These are **not correctness bugs** — the decryption output is verified via
+SHA-256 digest check (`ta_sa_svp_buffer_check`) and is correct. The timing
+threshold (10 ms for 1 MB) was calibrated for faster hardware.
+
+To eliminate all CENC timing failures, add `-DDISABLE_CENC_TIMING=ON` to
+`EXTRA_OECMAKE` in the recipe and do a clean rebuild. This skips the timing
+assertions entirely — all 216 (SVP=ON) or 72 (SVP=OFF) failures will be gone,
+bringing the failure count to **0**.
+
+## Dependency Management
+
+The recipe's `do_fetch_deps` task parses `cmake/deps.cmake` (single source of
+truth) and clones all 5 dependencies on the build server:
+
+- mbedtls, yajl, libdecaf, ed25519-donna, curve25519-donna