feat(tbor): implement RSA-AES key unwrap (GetUnwrappingKey + UnwrapKey)

[vsonims]

Summary

Implements the TBOR key-import pair that lets a host RSA-AES-wrap a
key to a partition and re-import it as a masked (unmask-on-use) blob
— the TBOR analogue of MBOR RsaUnwrap, but re-masking the recovered
key under a scope's masking key instead of vaulting it under a key
handle.

Reordered stack: this now sits below the HMAC keygen+mac PR
(#580), so the RSA/AES/ECC key-import path is independent of the HMAC
command work. As the first general crypto command in the stack, it
also introduces the shared session/masking helpers and the shared
HashAlgo wire enum (relocated into key_props). (Replaces the
auto-merged #581, which was closed as a side effect of the branch
reorder.)

GetUnwrappingKey (opcode 0x13)

Returns the partition's RSA-2048 unwrapping public key in HSM wire
format (n_le(256) ‖ e_le(4)). The private half never leaves the
device; UnwrapKey resolves it internally by the partition's
RSA_UNWRAPPING_KEY_ID property. Materialised lazily (std/emulator PAL)
or generated in the background from partition init (hardware); an absent
key surfaces as PendingKeyGeneration so the host retries. Both CO/CU.

UnwrapKey (opcode 0x14)

Within an open CO/CU session, unwrap a host-supplied
RSA-OAEP(KEK) ‖ AES-KWP(key) blob with the partition unwrapping key and
return the recovered key masked (AEAD-GCM-256) under the requested
scope's masking key. Supports the AES, RSA (plain/CRT), ECC, and HMAC
key classes via the shared azihsm_fw_hsm_key_unwrap /
azihsm_fw_hsm_key_decode crates; the decode crate gains an HMAC path
(32/48/64 B → _HmacShaN). The re-derived wire public key is returned
for the asymmetric (RSA/ECC) classes; symmetric classes return an empty
pub_key. Persists nothing. Both CO/CU.

Shared helpers introduced here

• validate_active_session and resolve_masking_key(scope, sess_id)
  (Session → per-session key; Ephemeral/Local/SecurityDomain → scope
  vault key).
• The HashAlgo wire enum, moved into the shared key_props module (it
  selects the OAEP hash here and, in feat(tbor): implement HmacGenerateKey + Hmac (masked-key HMAC crypto) #580, the HMAC SHA variant).

Tests / validation

• Emu round-trips: GetUnwrappingKey; UnwrapKey AES (masked, no
  pubkey) and HMAC key-class (recovered kind = _HmacSha256). The full
  unwrap→MAC round-trip lives in feat(tbor): implement HmacGenerateKey + Hmac (masked-key HMAC crypto) #580, which builds on this command.
• Full TBOR emu suite green (114 tests at this layer); clippy clean;
  nightly fmt + copyright clean; Uno (thumbv7em) build passes.
• Docs: docs/tbor-ddi/commands/{get_unwrapping_key,unwrap_key}.md +
  README rows (0x13, 0x14).

Endianness note (host wrap)

GetUnwrappingKey returns the modulus/exponent little-endian, and the
device expects the OAEP ciphertext in wire-LE (it flips to big-endian
internally for OpenSSL). The emu test's host-side wrap reverses the
pubkey components (LE→BE for from_hsm_bytes) and the RSA-OAEP
ciphertext (BE→LE) accordingly.

[Copilot]

Pull request overview

This PR adds the TBOR RSA‑AES key import command pair (GetUnwrappingKey / UnwrapKey) to allow a host to wrap key material to a partition and re-import it as a masked (unmask-on-use) blob, plus supporting plumbing (shared session/masking helpers, HashAlgo wire enum) and tests/docs. It also updates the SessionEx schedule to use a 32‑byte AES‑GCM masking key (TBOR) while keeping legacy MBOR’s 80‑byte CBC masking key schedule.

Changes:

• Introduces TBOR opcodes 0x13 (GetUnwrappingKey) and 0x14 (UnwrapKey) end-to-end: wire types, dispatcher routing, handlers, host wrappers, and docs.
• Adds shared TBOR helper(s) for active-session validation and resolving per-scope masking keys; moves/introduces HashAlgo in shared key_props.
• Extends key decode to support HMAC key material (32/48/64 B → _HmacSha*) and adds TBOR derive support for “reserve + fill later” for mutable buffer fields.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
fw/plat/uno/fw/pal/src/session.rs	Updates SessionEx blob sizing/validation to use 32-byte masking key for TBOR.
fw/plat/std/pal/src/session.rs	Updates SessionEx blob sizing and makes session masking-key extraction length-aware (legacy vs SessionEx).
fw/pal/traits/src/lib.rs	Changes SESSION_MASKING_KEY_LEN to 32 and clarifies it’s for TBOR SessionEx masking.
fw/core/lib/src/op.rs	Classifies new TBOR opcodes as InSession for session-flag validation.
fw/core/lib/src/ddi/tbor/unwrap_key.rs	New TBOR UnwrapKey handler: unwrap, decode, scope-mask, and respond (incl. pubkey for RSA/ECC).
fw/core/lib/src/ddi/tbor/session_open_finish.rs	Updates SessionEx schedule documentation to 32-byte AES-GCM masking key.
fw/core/lib/src/ddi/tbor/mod.rs	Adds opcode constants, dispatch routing, active-session validation helper, and masking-key resolver helper.
fw/core/lib/src/ddi/tbor/get_unwrapping_key.rs	New TBOR GetUnwrappingKey handler: derives and returns partition RSA unwrapping public key.
fw/core/lib/src/ddi/mod.rs	Adds a shared hmac_hash helper at the command level for both codecs.
fw/core/lib/src/ddi/mbor/hmac.rs	Switches to shared crate::ddi::hmac_hash.
fw/core/lib/src/ddi/mbor/from_pal.rs	Removes the duplicated MBOR-only hmac_hash mapping helper.
fw/core/key-decode/src/lib.rs	Adds HMAC as a decode class and wires it into decode().
fw/core/key-decode/src/hmac.rs	New HMAC decode path (length-based classification).
fw/core/ddi/tbor/types/src/unwrap_key.rs	New TBOR wire schema for UnwrapKey.
fw/core/ddi/tbor/types/src/lib.rs	Exposes new TBOR type modules (get_unwrapping_key, unwrap_key).
fw/core/ddi/tbor/types/src/key_props.rs	Expands key-props to include shared HashAlgo wire enum.
fw/core/ddi/tbor/types/src/get_unwrapping_key.rs	New TBOR wire schema for GetUnwrappingKey.
fw/core/ddi/tbor/derive/src/schema.rs	Documents semantics of mutable fields and the reserve+fill pattern.
fw/core/ddi/tbor/derive/src/codegen_enc.rs	Implements encoder generation for <field>_reserve(len) for mutable buffers.
docs/tbor-ddi/README.md	Adds 0x13/0x14 to the TBOR command table.
docs/tbor-ddi/commands/unwrap_key.md	New documentation page for UnwrapKey.
docs/tbor-ddi/commands/get_unwrapping_key.md	New documentation page for GetUnwrappingKey.
ddi/tbor/types/tests/commands/unwrap_key.rs	New emu integration tests for UnwrapKey (AES + HMAC).
ddi/tbor/types/tests/commands/mod.rs	Registers new TBOR command tests.
ddi/tbor/types/tests/commands/get_unwrapping_key.rs	New emu integration tests for GetUnwrappingKey (length/non-zero/stability).
ddi/tbor/types/src/unwrap_key.rs	New host-side TBOR request/response wrappers for UnwrapKey.
ddi/tbor/types/src/lib.rs	Re-exports new host-side command wrappers.
ddi/tbor/types/src/get_unwrapping_key.rs	New host-side TBOR request/response wrappers for GetUnwrappingKey.

[vsonims]

Update: this PR now also introduces encoder "reserve + fill" support in the TBOR derive. For any #[tbor(mutable)] buffer / sealed_key field, the encoder emits a <field>_reserve(len) setter that reserves the data slot without copying, so a response can be built with reserved slots and filled in place via decode_mut (zero-copy — the TBOR analogue of MBOR's reserve/from_layout). GetUnwrappingKey now uses it: the PAL derives the wire public key straight into the reserved response slot (no scratch buffer, no copy). This infrastructure is reused by the stacked HMAC (#580) and AES key-generate commands.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

fw/core/ddi/tbor/types/src/get_unwrapping_key.rs:9

• The rustdoc link for UnwrapKey points to crate::hmac, which is unrelated and breaks navigation for readers of the wire schema docs.

//! `GetUnwrappingKey` is an in-session command that returns the
//! partition's RSA-2048 **unwrapping** public key, which the host uses to
//! RSA-AES key-wrap a payload for [`UnwrapKey`](crate::hmac).  The
//! unwrapping key is a device-provisioned partition-internal key; only its

fw/core/ddi/tbor/types/src/unwrap_key.rs:59

• The constants are described as being "pinned" into #[tbor(... max_len = ...)] literals, but there are no compile-time assertions to prevent them from drifting out of sync (a pattern used in other TBOR type schemas).

pub const UNWRAP_PUB_KEY_MAX_LEN: usize = 520;

fw/core/lib/src/ddi/tbor/mod.rs:229

• resolve_masking_key uses pal.session_masking_key() for KeyScope::Session, but the Uno PAL currently returns UnsupportedCmd from session_masking_key (fw/plat/uno/fw/pal/src/session.rs:333-335). This makes Session-scoped masking fail on Uno/hardware even though the docs and handler comments indicate it should work for any Active session.

) -> HsmResult<&'p DmaBuf> {
    match scope {
        HsmKeyScope::Session => pal.session_masking_key(io, sess_id),
        _ => {
            let mk_key_id = masking_key_id_for_scope(pal, io, scope)?;
            pal.vault_key(io, mk_key_id)
        }

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

fw/core/ddi/tbor/types/src/get_unwrapping_key.rs:9

• Rustdoc link target is incorrect: crate::hmac doesn’t exist in this module and will produce a broken intra-doc link. This should point to the unwrap_key schema/module.

//! `GetUnwrappingKey` is an in-session command that returns the
//! partition's RSA-2048 **unwrapping** public key, which the host uses to
//! RSA-AES key-wrap a payload for [`UnwrapKey`](crate::hmac).  The
//! unwrapping key is a device-provisioned partition-internal key; only its

fw/core/ddi/tbor/types/src/unwrap_key.rs:59

• The max-len constants are described as “pinned” to #[tbor(... max_len = ...)] literals, but there are no const _: () = assert!(...) tripwires to keep them in sync. Other TBOR schemas use these asserts to prevent silent drift (e.g. get_unwrapping_key.rs).

/// Max recovered public-key length (RSA-4096 `n_le(512) ‖ e_le(4)`).
/// Pinned into the `#[tbor(buffer, max_len = 520)]` literal on
/// [`TborUnwrapKeyResp::pub_key`].
pub const UNWRAP_PUB_KEY_MAX_LEN: usize = 520;

fw/core/lib/src/ddi/tbor/mod.rs:239

• resolve_masking_key assumes HsmKeyScope::Session can always be satisfied via pal.session_masking_key(...), but on the Uno PAL this method currently returns UnsupportedCmd (see fw/plat/uno/fw/pal/src/session.rs:333-335). This means Session-scoped masking (documented as supported) will fail on hardware unless the Uno PAL implements session_masking_key for SessionEx blobs (32-byte AES-GCM key).

/// Resolve the 32-byte AES-256-GCM masking key material for `scope`,
/// returning a borrow of the on-device key.
///
/// `Session` scope resolves to the per-session masking key
/// ([`HsmSessionManager::session_masking_key`](azihsm_fw_hsm_pal_traits::HsmSessionManager::session_masking_key));
/// every other scope resolves via [`masking_key_id_for_scope`] and reads
/// the vault key.  All scopes yield a 32-byte key suitable for the
/// `key_masking::aead` (AES-GCM-256) masked-key system.
fn resolve_masking_key<'p, P: HsmPal>(
    pal: &'p P,
    io: &impl HsmIo,
    scope: HsmKeyScope,
    sess_id: HsmSessId,
) -> HsmResult<&'p DmaBuf> {
    match scope {
        HsmKeyScope::Session => pal.session_masking_key(io, sess_id),
        _ => {
            let mk_key_id = masking_key_id_for_scope(pal, io, scope)?;
            pal.vault_key(io, mk_key_id)
        }
    }