se050_scp03.hpp File Reference

GlobalPlatform SCP03 session over an existing T=1 I²C link. More...

#include "se050_apdu.hpp"
#include "se050_scp03_crypto.hpp"
#include "se050_t1_session.hpp"
#include "se050_types.hpp"
#include <cstddef>
#include <cstdint>
#include <cstring>

Go to the source code of this file.

Classes
struct	se050::scp03::StaticKeys
	Runtime static keys (never compiled-in NXP defaults). More...
struct	se050::scp03::ChannelState
	Live SCP03 session state after a successful handshake. More...
struct	se050::scp03::CommandFields
	A C-APDU split into its ISO/IEC 7816-4 section 5.1 fields. More...
class	se050::scp03::Session< TransportT >
	SCP03 session bound to a T=1 transport. More...

Namespaces
namespace	se050
namespace	se050::scp03

Functions
Error	se050::scp03::ParseCommand (const std::uint8_t *capdu, std::size_t len, CommandFields *f) noexcept
	Split a serialized C-APDU into data and Le (ISO/IEC 7816-4 section 5.1, cases 1, 2S/E, 3S/E, 4S/E).
Error	se050::scp03::WrapCommand (ChannelState &st, const std::uint8_t *capdu, std::size_t capdu_len, std::uint8_t *out, std::size_t out_cap, std::size_t *out_len) noexcept
	C-MAC + C-ENC wrap of a C-APDU in any ISO/IEC 7816-4 case, short or extended.
void	se050::scp03::WipeChannel (ChannelState &st) noexcept
	End a session: wipe the session keys, MAC chaining value and counter, mark it closed.
Error	se050::scp03::UnwrapResponse (ChannelState &st, const std::uint8_t *rapdu, std::size_t rapdu_len, std::uint8_t *out, std::size_t out_cap, std::size_t *out_len) noexcept
	R-MAC check and R-ENC decryption of one response. Increments the counter on success.
bool	se050::scp03::FillPutKeyBlock (std::uint8_t *block, const std::uint8_t current_dek[crypto::kAes128KeyLen], const std::uint8_t plain[crypto::kAes128KeyLen], std::uint8_t kcv3[kPutKeyKcvLen]) noexcept
	One AES key field inside GP PUT KEY (encrypted with the current DEK).
Error	se050::scp03::BuildPutKey (std::uint8_t key_version, const std::uint8_t current_dek[crypto::kAes128KeyLen], const std::uint8_t new_enc[crypto::kAes128KeyLen], const std::uint8_t new_mac[crypto::kAes128KeyLen], const std::uint8_t new_dek[crypto::kAes128KeyLen], std::uint8_t *capdu, std::size_t capdu_cap, std::size_t *capdu_len, std::uint8_t *expect_rsp, std::size_t expect_cap, std::size_t *expect_len) noexcept
	Build GP PUT KEY (CLA 0x80, INS 0xD8, P1 = key version, P2 0x81).

Variables
constexpr std::uint8_t	se050::scp03::kClaGp = 0x80U
constexpr std::uint8_t	se050::scp03::kClaGpSecure = 0x84U
constexpr std::uint8_t	se050::scp03::kInsInitializeUpdate = 0x50U
constexpr std::uint8_t	se050::scp03::kInsExternalAuthenticate = 0x82U
constexpr std::uint8_t	se050::scp03::kDefaultKeyVersion = 0x0BU
constexpr std::uint8_t	se050::scp03::kSecLevelCmacCencRmacRenc = 0x33U
constexpr std::size_t	se050::scp03::kInitUpdateRspMin = 10U + 3U + 8U + 8U + 2U
constexpr std::uint8_t	se050::scp03::kClaSmBit = 0x04U
constexpr std::size_t	se050::scp03::kMacFieldLen = 8U
constexpr std::size_t	se050::scp03::kWrapScratchBytes = 320U
	Minimum wrap workspace, enough for short APDUs (CM4: D2 .se_apdu_scratch, not task stack).
constexpr std::size_t	se050::scp03::kWrapScratchBytesExtended = kMaxApduCommandBytes + 7U + 16U + kMacFieldLen + 2U
	Wrap workspace for any command up to kMaxApduCommandBytes (extended header, padding, MAC, Le).
constexpr std::uint8_t	se050::scp03::kInsPutKey = 0xD8U
constexpr std::uint8_t	se050::scp03::kPutKeyTypeAes = 0x88U
constexpr std::uint8_t	se050::scp03::kPutKeyP2Multiple = 0x81U
constexpr std::uint8_t	se050::scp03::kPutKeyKcvLen = 0x03U
constexpr std::size_t	se050::scp03::kPutKeyBlockBytes = 23U
	type + lens + enc key + KCV
constexpr std::size_t	se050::scp03::kPutKeyDataBytes = 1U + 3U * kPutKeyBlockBytes
	version + ENC/MAC/DEK
constexpr std::size_t	se050::scp03::kPutKeyExpectRspBytes = 1U + 3U * kPutKeyKcvLen
	version + 3 KCVs

Detailed Description

GlobalPlatform SCP03 session over an existing T=1 I²C link.

Protects on-board APDUs against an I²C probe (the MitM that can forge "signature valid"). This is not the HMI channel — HMI trust remains SE-backed TLS 1.3. Host crypto is in se050_scp03_crypto.hpp (AES-CMAC / CBC). Compiled-in NXP default ENC/MAC/DEK values are forbidden; OpenSecureChannel returns Error::NotSupported when static keys are absent.

Wrap/unwrap uses caller-owned buffers (CM4: D2 .se_apdu_scratch). Live T=1 exchanges stay plaintext until unique ENC/MAC keys exist.

Copyright

Copyright (c) 2026 HardFOC. All rights reserved.