Unprivileged Architecture: Instructions and Architectural States

Introduction

KLE lets software perform high-performance cryptographic operations without direct access to the keys or other critical derived values. KLE achieves this through the concepts explained next.

Foundational Principles and Definitions

Principles are labeled Pn, where n is a sequential number. The most important ones define what the KLE architecture is about:

P1	KLE allows software to use keys that are not exposed to software. It hides the confidential parts of the internal state of the cryptographic algorithms it performs.
P2	KLE associates each key with an algorithm, and with policies that limit its use to certain privilege modes and bind it to software and hardware environments.
P3	Every cryptographic operation is atomic. When an instruction performs a well-defined sequence of similar cryptographic operations, it reports prefix-complete progress of that sequence.
P4	Multiple keys can be in use at the same time, and their algorithms composed.

These four Principles prompt the definition of a Cryptographic Context:

Definition: Cryptographic Context.: Most KLE instructions run within the constraints set by a Cryptographic Context (CC). A CC is an indivisible structure consisting of a Metadata Header (MDH), with a fixed format and length, and a Content, whose size depends on the MDH. The Content holds the secrets, such as keys, and other sensitive material, as well as public material derived from the secrets, such as public keys. The MDH binds the use of the information in the Content to one set of cryptographic algorithms, and, optionally, to a process, VM, security state, boot cycle, expiration date, or other policies. The MDH requires integrity, except for ADSDropped, an unauthenticated format hint (AuxDataLen and ADSDropped Fields); the Content requires integrity, as well as confidentiality for all the information that is not supposed to be public (such as public keys). KLE and the algorithms it implements enforce these requirements architecturally.

P5	Cryptographic Contexts are stateful, and record and manage the progress of the algorithm.

Multiple CCs can be active at the same time; a caller must be able to configure them as needed. This requires an architectural place for them.

P6	Resource management is architectural: resources are managed by software, and their exhaustion is reported by the architecture so that software can take the necessary actions.

KLE realizes this Principle by defining Cryptographic Lockers and the means by which the architecture manages them.

Definition: Cryptographic Locker.: Cryptographic Lockers (lockers for short) are per-hart architectural containers that safeguard their contents. CCs are created by writing Metadata and Content into a locker, a process called Provisioning, which also binds them to each other. A CC is usable only while in a locker, where only the KLE unit accesses or modifies it, under the rules of the architecture and of the algorithm; no instruction returns its secrets in clear, except where the algorithm allows it.

A KLE implementation supports 32 lockers.

P7	KLE is scalable: it works on small and larger cores, with and without vector registers.
P8	Instructions perform tasks that are as simple as possible, in accord with the RISC-V philosophy, while code sequences stay short. An instruction performs a complex task only if it is necessary for security reasons, i.e., when breaking it up further would lead to a violation of a security-related Principle, such as P1, P2, P12, P15 and P16.
P9	Minimize the pressure on the instruction encoding space.

Embedding the algorithm’s encoding in the MDH is the main mechanism implementing P9.

P10	Architectural state beyond the lockers is minimal, and exists once per hart.

Algorithms are implemented by KLE Machines:

Definition: KLE Machine.: A KLE Machine (short: Machine) is a state machine that implements one or more cryptographic functions (primitives, modes, protocols) through the interface of this specification. Fields in the MDH fully identify it. A small set of KLE instructions operates all Machines: their inputs and outputs come from vector registers, GPRs, and memory, and their semantics depend on the Machine.

Encapsulating Machine-specific behavior in the MDH rather than the instructions lets different primitives (e.g., AES-128, AES-256 and SM4) be used in the same modes (e.g., ECB, GCM-SIV and XTS) without changing the compiled code, and supports side-channel-resistant variants transparently.

P11	Besides the operations that are always allowed by the architecture, a Machine admits only the sequences of operations that its specification defines.

Machines use the state of Principle P5 to enforce this Principle.

P12	Inside a locker, a CC is accessed only through its Machine and the instructions managing it.
P13	Software can always configure a new CC, after clearing other lockers if necessary.
P14	A CC can be saved and restored, also into a different locker or on a different implementation, to support features such as context switching, sleep, hibernation and VM migration.
P15	Outside a locker, a CC is sealed: it reveals nothing beyond what its format leaves in clear, and cannot be altered undetected.

CCs are saved and restored by generating Sealed Cryptographic Contexts:

Definition: Sealed Cryptographic Context.: For context switching, a CC can be exported from a locker as a Sealed Cryptographic Context (SCC), an authenticated representation, encrypted except for its public values, that can later be imported into a locker. Export and import use a Context Sealing Key (CSK), which M-mode may be able to program. An SCC sealed under one CSK cannot be imported under another, which separates spatial and temporal domains cryptographically. An SCC leaves in clear only its MDH and its clear blocks (Rule GR9), all authenticated except the ADSDropped bit of the MDH; the image of a locker in an Error State is an unauthenticated MDH and carries no Content (Export and Import of a Locker in an Error State).

P16	No operation yields a key or widens a policy: secrets flow only downhill.

P16 is the same principle behind NIST’s key-management recommendations on the associations of a key with its usage and related information (NIST SP 800-57 Part 1 Rev. 5 cite:[nist-SP-800-57-p1-r5], §§6.2.1.4 and 6.2.1.6) and on the cryptographic strength, separation and context binding of derived keys (NIST SP 800-108 Rev. 1, Update 1 cite:[nist-SP-800-108-r1], “Security Considerations”).

Finally, KLE instructions are subdivided into classes, each usable only in certain contexts. Instructions that use the secrets in CCs are bounded by usage policies, whereas those that, for instance, save and restore SCCs can be used at any time. Principles P13 and P14 prevent denial of service on the resources of the KLE implementation.

Definition: Instruction Classes and Usage Control.: KLE distinguishes between management operations and usage operations on CCs and lockers. The management operations are provisioning, SCC import, and export of a locker as an SCC; clearing a locker, i.e., freeing it and deleting any secret it contains, is a separate configuration instruction. None of these uses the secrets of a locker for the operations of its Machine. None changes the Machine or the Usage Control policies of a Valid locker, except through the narrowing, provisioning and import defined for it. Usage operations are cryptographic operations and state changes. To prevent denial of service, management operations and clearing are less restricted than usage operations: Usage Control policies restrict only usage operations.
Definition: Localities.: KLE can bind a CC to Localities, which restrict where its exported SCCs can be imported and so where it can be restored and used: specific devices or device classes, hardware configurations, physical or virtual boot cycles, and process domains at various privilege modes.

The entire architecture follows from these Principles and Definitions.

Architectural Model

KLE is architected as an interface to an attached unit: its instructions behave like messages over a tightly coupled coprocessor interface, and the KLE unit executes them independently of the issuing hart and returns the results.

This keeps the hart side simple: software implements the locker-configuration logic, the KLE unit the cryptography, and several cores may share one KLE unit.

The specification defines only architectural behavior, not implementation: KLE may be integrated into a CPU core or be a distinct hardware unit; either way each client hart has separate KLE architectural state, and the same code runs on both.

KLE may be emulated, partly or completely, in M-mode firmware: an implementation may, for example, perform symmetric operations (Symmetric Cryptography) in the KLE unit and emulate public-key cryptography (Elliptic Curve Cryptography, Post-Quantum Public-Key Cryptography), whose very large states then reside in secure memory that meets the requirements of The Cryptographic Locker File and Authentication Information, such as on-chip SRAM reserved for M-mode.

No instruction may make key material or other locker state that the KLE holds accessible in the clear to any privileged mode except M-mode and authenticated Debug mode, which is Debug mode while the External Debug Security extension (Prerequisites) authorizes external debugging of M-mode. The only locker state exported in the clear is what the software that opened the operation supplied: the Content of a partial provisioning (Management States and Formats), and the data loaded by an unfinished system-specific import (Rule GR50); since any mode can export it, that software clears or completes the operation before another software context runs (Rule SR1). A misuse that Rule MR15 leaves to the caller, such as the reuse of an IV, can still reveal locker state derived from the key, such as the GHASH key of GCM (Accepted Risks). KLE implementations in S/VS-mode or HS-mode are forbidden: instructions and Machines may be emulated only in M-mode. Trap-and-emulate and on-demand (lazy) SCC import rely on the *llockerstatus CSRs (mllockerstatus, sllockerstatus, and vsllockerstatus for Dirtiness Tracking).

Prerequisites

A conformant KLE implementation requires the RISC-V External Debug Security extension cite:[riscvExternalDebugSecurity].

It requires the KLE exceptions of Exceptions Raised by KLE to be implemented and raised as the unprivileged architecture mandates, whether or not the other parts of the KLE Privileged Architecture are implemented.

Where the KLE unit or its Machines need an RBG, they must use an entropy source that meets the requirements of the Zkr extension (chapter “Cryptography Extensions: Scalar & Entropy Source Instructions”, section “Entropy Source” cite:[RISCV-ISA-Unpriv]), used to seed a DRBG compliant with NIST SP 800-90A cite:[nist-SP-800-90-r1] or with another standard that the implementation documents. The DRBG must be instantiated with a security strength of at least 256 bits and reseeded from that entropy source at the interval its standard prescribes; another standard may replace SP 800-90A only if it provides at least this strength. Rule GR45 covers RBG failure.

Endianness

As defined in Values, Bits, and Byte Strings, a PI, an SCC and a PCCC (cf. Management States and Formats) are byte strings: a value V of 8n bits in them, the MDH (cf. Metadata) included, occupies n consecutive bytes, byte i holding V[8i+7:8i], whatever the data endianness (mstatus.MBE, SBE and UBE, and with the H extension hstatus.VSBE and vsstatus.UBE) of the hart. KLE memory instructions follow this mapping, and those bits do not affect them. Software on a hart with big-endian data accesses that moves an MDH between memory and GPRs, or vector elements wider than 8 bits, converts its byte order, for instance with rev8, or uses byte accesses. This convention lets CCs migrate between harts of different endianness.

Extensions Overview

The principal KLE instructions, defined in full in Instructions, are:

kl.setst moves the CC in a locker between the states of its Machine.
kl.mgmt moves a locker through its management lifecycle, and, with the management transfer instructions kl.load, kl.store, kl.mvin, and kl.mvout performs the management operations (Provisioning, Import, and Export), each in several instructions, except on a locker in an Error State (Export and Import of a Locker in an Error State):
- provisioning loads metadata and clear Content into a locker, binding them;
- export writes a locker to memory as an SCC;
- import loads an SCC into a locker.
kl.clear unconfigures and clears a locker. It is a pseudo-instruction of kl.setst, and never part of a management operation.
kl.exec performs the cryptographic operations that the Machine configured in a locker defines for the locker’s current state.
kl.getmd* reads the metadata of a locker. The pseudo-instruction kl.getst, built on kl.getmdl, extracts the state of a locker from its MDH and reports errors.

KLE comprises several sub-extensions. Those that define ISA features are given in Table 1; those that define cryptographic algorithms are listed in Machine Type and Mode Encodings, corresponding Extensions.

Table 1. Extensions defining KLE ISA features
Extension	Features	Defined in:
`Zklv`	Support for vector registers.	Instructions
`Zklio`	Support for streaming instructions and the KLIOBUF.	KLIOBUF, Zklio
`Zklmem`	Dedicated memory instructions.	KLE Memory Instructions
`Zklmv`	Dedicated move instructions.	kl.mvin and kl.mvout
`Zklexpire`	Support for the ExpirationDate metadata field.	ExpirationDate Field

Zkl conformance requires:

at least one of Zklv and Zklio;
AES-128, AES-192 and AES-256 in ECB and GCM modes, AES-128 and AES-256 in GCM-SIV mode, and SHA2-224, SHA2-256, SHA2-384, SHA2-512, SHA2-512/224 and SHA2-512/256, as defined in Unprivileged Architecture: Machines; and
Zklmem, in hardware or by trap-and-emulate (KLE Emulation Control in mstatus); in the latter case Zklmv in hardware.

KLE instructions may raise the standard RISC-V exceptions and a few KLE-specific exception types, listed in Exception causes in decreasing priority order.

Zklv requires the KLV subset of the vector extension (RVV/KLV) with VLEN ≥ 128, that is, Zvl128b or a larger Zvl*b, which every vector Form that carries an MDH or a 128-bit block needs.

With trap-and-emulate, the hardware raises an illegal-instruction exception for instructions it does not implement, which the platform must deliver to M-mode (medeleg bit 2 zero). The emulating code moves data between memory and the locker with Zklmv. kl.load and kl.store are always present; Zklmv and Zklexpire are otherwise optional.

Table 2 gives, for each instruction and for each CSR that software below M-mode accesses through KLE instructions, the extension that defines it and its Forms or availability with Zklv and with Zklio.

Table 2. Instruction/CSR–extension matrix
Instruction / CSR	Defined by	With `Zklv`	With `Zklio`
`kl.size` / `kl.avail`	`Zkl` common	Forms A–C	Forms A and B
`kl.exec`	`Zkl` common	Forms A–D	Form D, natively or as the substitution (Rule GR10) of a Form A–C
`kl.mvin`, `kl.mvout`	`Zklmv`	GPR and vector variants	GPR and KLIOBUF variants; each only when `Zklmv` is implemented, which is mandatory in hardware if `Zklmem` is emulated
`kl.setst`, `kl.setstq` (and the pseudo-instructions `kl.clear`, `kl.clearall`, `kl.clearads`)	`Zkl` common	Forms A–D	Forms A, B and D
`kl.setste`	`Zkl` common	Available
`kl.mgmt`	`Zkl` common	Forms A, C and D	Forms A and D
`kl.getmdl`, `kl.getmd` (and the pseudo-instructions `kl.getst`, `kl.getstx`)	`Zkl` common	Available
`kl.getmdv`	`Zklv`	Available	—
`kl.getnl`, `kl.setnl`, `kl.setnli`, `kl.getks`, `kl.setks`, `kl.setksi`	`Zkl` common	Available
`kl.getbl`, `kl.getbt`, `kl.setbl`, `kl.setbt`, `kl.setbli`, `kl.setbti`	`Zklio`	—	Available
`kl.rstrl`, `kl.rstrh`	`Zkl` common	Available
`kl.rstrv`	`Zklv`	Available	—
`kl.clone`, `kl.rename`, `kl.swap`	`Zkl` common	Available
`kl.derive`	`Zkl` common	Available
`kl.load`, `kl.store`	`Zklmem`	Always present, in hardware or by trap-and-emulate, per the conformance requirements above
`kl.input`, `kl.output`	`Zklio`	—	Available
`kliobuflen`, `kliobuftop`, `mklmaxiobuflen`	`Zklio`	—	Available
`klstart`	`Zkl` common	Always present
`klnamedlocker`	`Zkl` common	Always present

Architectural State and Operand Sources

Cryptographic Lockers

KLE defines 32 Cryptographic Lockers, K0–K31: per-hart architectural state that, like GPRs and vector registers, is the same in every privilege mode. Unlike a register, a locker can be unconfigured, holding no CC. Instructions address a locker by a 5-bit immediate; some may instead name the named locker, KLNL, whose number a CSR holds.

A configured locker K(i) holds a CC: its Metadata Header K(i).MDH and its K(i).Content (Foundational Principles and Definitions). During import and export, and in an SCC, the content is two consecutive arrays of 128-bit blocks: Content1, the architected content that Unprivileged Architecture: Machines specifies for each Machine, and Content2, any implementation-specific content.

The Cryptographic Locker File and Authentication Information

Lockers reside in a per-hart cryptographic locker file (KLF), a memory that only the KLE implementation can access; where the implementation is emulated, in part or in full, only M-mode firmware accesses it, through an implementation-defined mechanism that the implementation must provide.

The KLF protects the confidentiality and integrity of its contents, also against rollback through any access that this specification does not define. Every path that handles a locker’s secrets, emulated ones included, must resist timing, other side-channel and fault-injection attacks at least as well as the locker’s Machine at its SCProtection level (SCProtection Field), and a path that serves several levels, at the highest of them. These paths are reconstruction, re-sharing, KLF access, SCC_KeyDeriv, SCC_Encrypt and SCC_Decrypt in export and import (SCC Export and Import Algorithms), system-specific import (Rules for the Import of a System-Specific Format), and every use of the CSK and its derived keys. Only the implementer’s certifications, if any, establish what an implementation achieves.

The KLE unit computes the functions SCC_KeyDeriv, SCC_Encrypt and SCC_Decrypt with the AES and POLYVAL hardware of its Machines, and for the import and export of lockers implementing a Machine at a certain SCProtection level, these functions must offer the same or higher level of side-channel and fault-injection attack protection. One risk is accepted: these keys seal every SCC, so with several levels, each SCC resists differential side-channel and fault-injection attacks only as well as the least-protected engine that uses them (Discussion Points).

Unlike the KLF, an SCC does not resist rollback: while it exists, any party that holds it, such as the software that stores it or any mode that could export the locker, can import it again under the same CSK and Localities and so replay an earlier CC state. This may enable multi-time-pad or nonce-reuse attacks on the Machines that rely on a fresh IV, nonce or counter: CBC, CFB, OFB, CTR, XCTR, GCM, OCB, Ascon-AEAD128 and, for message equality only, GCM-SIV. A CC owner must trust the party that stores its SCCs for freshness, clear its lockers before another software context runs (Rule SR1), use a Machine whose security survives replay, or accept the risk; policies cannot readily tell misuse from legitimate re-import, such as a retry after payload corruption.

Architecturally, whatever the implementation, the KLF has two parts:

32 128-bit blocks, the i-th holding the MDH of K(i), so that every locker holds its MDH, if only to show that it is unconfigured; and
an implementation-defined amount of dynamically allocated memory that holds the Content of every configured locker.

“KLF capacity” refers only to the second part: a locker that holds only its MDH consumes none, and what a configured locker consumes depends on its MDH (Length of External Formats and KLF Capacity Usage of a Locker). Insufficient capacity may prevent a configuration instruction from executing; unconfiguring other lockers frees capacity. The number of lockers, 32, comes from the 5-bit register fields of the encoding, not from the capacity, and an implementation need not hold 32 configured lockers at once. The capacity must suffice for two fully configured CCs of the largest Machine that the implementation supports, each with the largest ADS that the implementation keeps for it, together with any state that the implementation needs while it operates on them. If system-specific formats, that is, formats other than those of KLE, are supported, it must also cover the largest amount by which the import of a system-specific format needs more memory than the import of a KLE format of the same Machine. Further capacity is desirable, but not required.

Corruption of a hart’s KLF is unrecoverable: it resets the hart’s KLE architectural state (KLE Unit Reset and M-mode-only Harts) and raises a KLE fatal-error exception (Exceptions Raised by KLE).

The KLE unit holds three 128-bit authentication registers, SIV, IMPQUAL and SIV2, with the authentication and identification data of a locker whose import or export is open, without recording which locker that is (Ownership of Authentication Registers); kl.load, kl.store, kl.mvin and kl.mvout access them as the leading bytes of the image (kl.mvin and kl.mvout). The export-opening kl.mgmt of a Valid locker writes SIV, and also IMPQUAL and SIV2 if the AuxDataLen of the locker’s MDH is at least 2. An import-opening kl.mgmt, other than the short import of an Error-State locker (Export and Import of a Locker in an Error State), zeroizes all three before the kl.load or kl.mvin that writes them.

To save hardware, the authentication registers exist once per hart, not per locker, so a second management operation may overwrite those of a first one still in flight; Rules SR7 and SR8 state what software must do.

RVV/KLV

KLE takes its inputs and outputs from vector registers, from an architectural input/output buffer (KLIOBUF) loaded from and stored to memory, or from both.

Vector registers need only a minimal subset of the V extension, KLV (KLE-subset of V). KLV must be fully opcode-compatible with RVV: code written for KLV behaves identically under V with Zvbc, for the vector configurations that KLV supports. KLV comprises:

vector registers of at least 128 bits;
the CSRs vstart, vl, vtype and vlenb, with their RVV 1.0 semantics;
the configuration-setting instructions vsetvli, vsetivli and vsetvl, with:
- tail-agnostic and mask-agnostic configurations only, since KLE neither uses vector masking nor defines masked instructions, and always applies a tail-agnostic policy (bit 25 of the kl.exec encoding is reserved for masked operations, should a compelling use case arise);
- SEW values 8, 16, 32 and 64, with ELEN = 64;
- LMUL values 1, 2, 4 and 8; and
- for a configuration that KLV does not support, vtype.vill is set and vl = 0, as in RVV; a KLE instruction with a vector operand raises an illegal-instruction exception if vtype.vill is set;
the unit-stride loads and stores vle<eew>.v and vse<eew>.v of element widths 8, 16, 32 and 64 whose EMUL is 1, 2, 4 or 8; an implementation that provides KLV without V raises an illegal-instruction exception for such an access whose EMUL is fractional;
the whole-register loads, stores and moves vl<n>re<eew>.v, vs<n>r.v and vmv<n>r.v, for context switches;
vmv.x.s, vmv.s.x, and the slides vslideup.v[xi], vslidedown.v[xi], vslide1up.vx and vslide1down.vx, to move data into and out of vector registers;
the logical operations vand.v[vxi], vor.v[vxi] and vxor.v[vxi] (the immediate forms give, for instance, a bitwise NOT); and
vclmul.v[vx] and vclmulh.v[vx] of Zvbc, for SEW = 64 only, as in Zvbc; they may be trap-and-emulated.

KLV requires the listed instructions only with vm = 1; their masked encodings are reserved.

Floating-point, fixed-point and general arithmetic vector operations are not required.

KLE has no concept of an element, and it is not part of the vector unit: it sees a vector register (including a vector register group if LMUL > 1) as a bit string of length KLLEN = VL × SEW, where VL is the vector length in effect (vl).

KLE takes the length of a vector operand from VL × SEW alone (VL = 2 with SEW = 64 and VL = 4 with SEW = 32, for example, both give 128 bits): the CPU decode side uses VL and SEW to determine how much data to send to the KLE unit, which needs only their product.

KLIOBUF

When Zklio is implemented, the architectural input/output buffer KLIOBUF may replace vector registers. The KLIOBUF is per-hart architectural state, not separated by privilege mode, but it is not part of the KLF.

The Zklio instructions kl.input and kl.output transfer data between the KLIOBUF and memory, and the base extension kl.exec then uses Forms whose inputs and outputs are implicitly in the KLIOBUF (Zklio). kliobuftop defines KLLEN for KLIOBUF operands.

Metadata

An SCC carries two kinds of metadata:

the 128-bit MDH, always present, which determines the Machine, the key type and the key’s usage policies; its first 64 bits determine the length of a PI or SCC; and
the optional 128-bit Implementation Qualifier IMPQUAL, which copies the three KLE analogues of the hart’s mvendorid, marchid and mimpid CSRs, namely mklvendorid, mklarchid and mklimpid (AuxDataLen and ADSDropped Fields gives the format of IMPQUAL). It is present when an SCC has AuxDataLen ≥ 2, and lets an implementation determine whether it can use the implementation-specific content of the SCC (AuxDataLen and ADSDropped Fields).

In the rest of the document, “metadata” refers to the first type. The implementation qualifier is always called IMPQUAL.

Table 3 summarizes the MDH fields, which the following subsections describe.

Table 3. Format of the 128-bit Metadata Header
Field	Size	Name	Description
[11:0]	12	Machine	The Machine the key material is bound to. See Machine and MachinePolicy Fields.
[13:12]	2	MachinePolicy	The allowed variants of the Machine, for instance encryption, decryption or both for a symmetric cipher. See Machine and MachinePolicy Fields.
[15:14]	2	MachineExtension	Zero, or a variant of the Machine that the Machine defines. See Machine and MachinePolicy Fields.
[17:16]	2	SCProtection	Side-channel protection level. See SCProtection Field.
[23:18]	6	State	Current state of the locker and its Machine. See State and StateExtension Fields.
[27:24]	4	StateExtension	Additional state information. See State and StateExtension Fields.
[29:28]	2	KeyType	Key given by value, by a system key, or randomly generated. See KeyType Field.
[31:30]	2	Reserved	Reserved.
[45:32]	14	AuxDataLen	Length of the ADS in 128-bit blocks, zero if none; with ADSDropped = 1, the length before `Content2` was dropped; with Version = 3, the length of the system-specific data after the MDH (Rules for the Import of a System-Specific Format).
[46:46]	1	Reserved	Reserved.
[47:47]	1	ADSDropped	Set if `Content2` was discarded. See AuxDataLen and ADSDropped Fields.
[61:48]	14	MachineUse	Machine-specific information, or implementation-specific in the bits and States where the Machine does not use it. See MachineUse and AuxInfo Fields.
[63:62]	2	Version	MDH format version. See Version Field.
[68:64]	5	UsagePolicy	The privilege modes that may use the locker. See UsagePolicy Field.
[77:69]	9	Locality	Zero, or the Locality Secrets the CC is bound to. See Locality Field.
[79:78]	2	Reserved	Reserved.
[95:80]	16	AuxInfo	Machine-specific information, or implementation-specific in the bits and States where the Machine does not use it. See MachineUse and AuxInfo Fields.
[115:96]	20	ExpirationDate	If non-zero, the expiration date of the CC. See ExpirationDate Field.
[127:116]	12	Reserved	Reserved.

Machine and MachinePolicy Fields

Machine is a 12-bit field. Values 0–3071 are architecture-defined, with encodings maintained by RVI (Unprivileged Architecture: Machines); the remaining values are for custom Machines.

The meaning of MachinePolicy depends on the Machine:

For encryption/decryption primitives and modes, bit 0 of MachinePolicy permits encryption and bit 1 decryption.
For asymmetric primitives that support signatures, bit 0 permits their generation and bit 1 verification.
For MACs that generate and verify tags, bit 0 permits generation and bit 1 verification.

MachineExtension is zero unless the Machine defines a non-zero value; the values defined are 1 and 2 for the Elliptic Curve Machines, which select their public-points and sealed variants (Elliptic Curve Cryptography), and 1 for ML-KEM, which selects its sealed variant (ML-KEM). Other values are reserved, and may in the future encode more Machines.

Rule MR1 states how MachinePolicy gates the States of a Machine, and which values are valid.

SCProtection Field

KLE defines three side-channel protection levels, Levels A, B and C, encoded in SCProtection as the values 0, 1 and 2. Value 3 is reserved, and makes the Metadata invalid (Validity of Metadata). cite:[riscvPlatformSecurityModel] gives the threat model and security concepts in which these levels are used.

Table 4. Encoding of Side-Channel Protection levels
Value	Level	Description
0	A	No timing leakage: the same cryptographic operation on the same number of input units takes the same time in the KLE unit, whatever the values of the key, of the internal state, of the input data and of any random value drawn for the operation, except for the dependence that the cryptographic method itself requires (below).
1	B	No timing leakage; differential side-channel protection.
2	C	The protection of Level B; detection of injected faults, followed either by completion with the correct result and no other physical leakage, or by a transition to a fatal error condition (see Error Handling Architecture).

A level applies to the export and import of the locker (The Cryptographic Locker File and Authentication Information) and to the operations that need it for security, such as signature generation but not signature verification, and only as far as the cryptographic method of the Machine needs it: the execution time of ML-DSA, for instance, may depend on the number of iterations of its rejection loops (ML-DSA).

A side-channel-protected Machine is an implementation variant of the unprotected one, distinguished architecturally only by the SCProtection field of the MDH.

An implementation must document, for each level it supports, the standard and edition, assessment profile, security level and test metrics it meets, such as acquisition-time limits and trace sample sizes; Level B, resp. C, must offer at least the guarantees documented for Level A, resp. B.

This specification gives no assurance profiles for these levels. A CC provider that sends its keys to a secure receiver, such as a TEE applet that forwards the CC to the software consuming it, negotiates the protection level and its assessment profile with it by a system-specific mechanism. Relevant references are ISO/IEC 19790:2025 cite:[ISOIEC-19790-2025] for the security requirements of cryptographic modules, ISO/IEC 24759:2025 cite:[ISOIEC-24759-2025] for their testing, ISO/IEC 17825:2024 cite:[ISOIEC-17825-2024] for testing the mitigation of non-invasive attacks, and FIPS 140-3 cite:[nist-fips-140-3], which adopts ISO/IEC 19790:2012 and ISO/IEC 24759:2017 with CMVP modifications; and NIST SP 800-140F cite:[nist-SP-800-140F].

State and StateExtension Fields

State tracks the state of a locker and its Machine: Unconfigured, encrypting or decrypting, initializing, absorbing into or finalizing a hash, computing point multiples, signing or verifying, or in an error state, for instance. StateExtension keeps further state information, usually orthogonal or additional to State. The tables in this section give the values of State and StateExtension common to all Machines, including that of a locker with no Machine, and the States used for CC management.

Table 5. Global CC State Numbers: Inert State
Value	Mnemonic	State Name	Description
0	`kl_state_inert`	Inert	The locker holds no Content: it is Unconfigured or in an Error State (Table 7) (see the definition of Definition: Inert Locker.).

Table 6. Global CC State Numbers: Valid States
Value	Mnemonic	State Name	Description
1	`kl_state_ready`	Ready	Ready for operation; also the state of a newly provisioned CC.
2-53	Defined by the Machine encoded in Machine.
54	`kl_state_success`	Success	The Machine completed successfully. No further cryptographic operation may be performed until the locker is reconfigured or returned to Ready (Rule GR19.3).
55	`kl_state_failure`	Failure	The Machine completed with a negative result; otherwise as in State Success.

The Valid States are States 1–55: State 1 is Ready, States 54 and 55 are Success and Failure, and the Machine defines States 2–53. The Valid States and the Error States are the Complete States.

States 56–63, used during management operations, are the Configuration States; 61–63 are reserved.

With State set to 0, StateExtension encodes Error State as well as the state when a locker holds no CC, i.e., the Unconfigured State.

Table 7. Global *StateExtension* Codes at *State* 0: Unconfigured and Error States
Value	Mnemonic	State Name	Description
0	`kl_stateext_unconfigured`	Unconfigured	Not an Error State: the locker holds no valid CC.
1	`kl_stateext_unsupported`	Unsupported	Unsupported Machine or Machine variant, KeyType, protection level, or a field value that the Machine declares unsupported (Validity of Metadata).
2	`kl_stateext_invalid`	Invalid	The locker has been invalidated by invalid Metadata, by an operation not permitted in its current State, or by another error that the architecture or the Machine reports as Invalid (Error Handling Architecture).
3	`kl_stateext_out_of_memory`	Out of Memory	Insufficient KLF memory for a configuration instruction. A KLE out-of-memory exception handler that cannot free enough memory sets it with `kl.setste` (kl.setste), to return an error.
4	`kl_stateext_mgmt_auth`	Authentication Failed	Authentication failure while completing an SCC import or a locker export, or a failed check that a system-specific format defines, when the format authenticates its data (Rule GR51).
5	`kl_stateext_priv_violation`	Privilege Violation	Narrowing of a policy attempted without sufficient privilege or Locality, or any other failed narrowing, or a transfer to a lower SCProtection (Rules GR30 and GR51).
6	`kl_stateext_expired`	Expired	The locker has expired. Not in effect without `Zklexpire`.
7-15	(Reserved)		Reserved.

Definition: Unconfigured Locker.: A locker is Unconfigured when State and StateExtension are 0: every other field of the MDH then reads zero and has no meaning, and the locker has no Usage Policy, Expiration Date or Key Type. An Unconfigured locker holds no Content beyond the MDH.
Definition: Error State.: A locker is in an Error State, which reports a KLE error, when State is 0 and StateExtension is 1–6: StateExtension holds the code of the Error State (Table 7). A locker in an Error State holds no Content beyond the MDH, whose other fields keep their values except as Rule GR15 states. Entering an Error State overwrites StateExtension with its code, and no Machine defines a StateExtension @ State 0. The Error-State image of such a locker (Export and Import of a Locker in an Error State) consists only of the MDH.
Definition: Inert Locker.: An Inert locker is either Unconfigured or in an Error State, or the named locker KLNL while klnamedlocker = 32.

A locker is said to be invalidated when it transitions to Error State Invalid (i.e., State = 0 and StateExtension = kl_stateext_invalid).

Without Zklexpire, no locker can be in Error State Expired, and a PI, SCC or PCCC whose MDH carries StateExtension 6 at State 0 is invalid.

A locker being provisioned, exported or imported is in one of the following Configuration States:

Table 8. Global CC State Numbers: Configuration States
Value	Mnemonic	Description
56	`kl_cfg_provisioning`	The locker is being configured.
57	`kl_cfg_exporting`	The locker is being exported as an SCC, its contents authenticated and, except for their public values, encrypted.
58	`kl_cfg_importing`	An SCC is being imported into the locker.
59	`kl_cfg_ppi_exporting`	The locker, whose base operation is a provisioning (see Management States and Formats), is being exported; its image has the format of a PI.
60	`kl_cfg_ppi_importing`	Such an image is being re-imported.
61-63	(Reserved)	Reserved.

Rules Governing the State and StateExtension Fields and their Transitions defines the behavior of lockers and SCCs in these States.

Figure 1 shows these States and the default transitions between them, which apply to all Machines. The legend of the graph is:

Double-bordered ellipses: the Unconfigured State, and all Configuration States.
Single-bordered rounded rectangles: the Valid States.
Double-bordered rounded rectangles: the Error States.
Continuous edges: transitions induced by usage instructions.
Dashed edges: transitions induced by reaching the expiration date.
Dotted edges: transitions induced by configuration operations.

Figure 1. Default State Transitions

KeyType Field

KeyType states how the keys of a CC are supplied:

0: by value; the keys are provisioned, exported and imported as values.
1: by a system-specific, 64-bit System Key Identifier (SKID) (System Keys).
2: generated randomly by the kl.mgmt that completes a base (non-nested) provisioning, all keys of the Machine at once unless the Machine states otherwise; an RBG failure follows Rule GR45. The PI has the layout of one with KeyType = 0, and the generated values replace its key values. KeyType then becomes 0, so the keys are exported by value; KeyType = 2 occurs only in a PI, in a PCCC of base type pi and in a locker being provisioned from them (Management States and Formats).
3: reserved; a PI or SCC that carries it is invalid Metadata (Validity of Metadata).

A SKID may refer to keys with unrelated purposes on different devices; the System Key Store (SKS) therefore supplies a Locality for it (Rule GR55.3).

AuxDataLen and ADSDropped Fields

AuxDataLen gives the length, in 128-bit blocks, of the Auxiliary Data Section (ADS), the variable-size, implementation-specific part of the content: 0 means no ADS, and the maximum, 2¹⁴ − 1, is 262,128 bytes. With ADSDropped = 1, it keeps the length from before Content2 was dropped. With Version = 3, it instead gives the length of the data of a system-specific format (Rules for the Import of a System-Specific Format), and no rule that reads it as the length of an ADS applies: such an MDH has no ADS, IMPQUAL or SIV2, and its ADSDropped stays 0.

If AuxDataLen ≥ 2, the SCC includes IMPQUAL, a 128-bit copy of the implementation qualifier of the originating implementation (mklvendorid, mklarchid, and mklimpid):

IMPQUAL := zeros(32) @ mklimpid[31:0] @ mklarchid[31:0] @ mklvendorid[31:0].

The importing implementation uses the ADS only if all 128 bits equal its own IMPQUAL; there is no other compatibility rule. An implementation that produces an ADS must leave KLE unit reset with values of mklvendorid, mklarchid and mklimpid that no implementation with a different ADS format has, and with mklvendorid and mklarchid not both 0. An M-mode handler that emulates a Machine and writes an ADS for the lockers it holds (Emulation of Unsupported Machines) qualifies that ADS itself, for instance with an IMPQUAL of its own, unique per ADS format as for the KLE unit. AuxDataLen counts these 16 bytes and the 16-byte authentication tag of the ADS, so, unless it is the payload length of a system-specific format, it is 0 or at least 2; 1 is invalid. Outside a system-specific format, AuxDataLen is implementation-dependent, but depends only on the other fields of the MDH and on the progress that Rule GR37 allows, never on key material, a secret field, plaintext or ciphertext, or a value drawn for an operation, since kl.getmd* returns it in every mode and State.

ADSDropped, bit 47 of the MDH, is an unauthenticated format hint, ignored in an SCC whose AuxDataLen is 0 and subject to the validity conditions of Validity of Metadata; authentication clears it only in its local copy of the MDH.

Set in an SCC, it tells the import to drop the optional Content2; the import then zeroes the implementation-defined subfields of MachineUse and AuxInfo (MachineUse and AuxInfo Fields). With AuxDataLen ≥ 2, Content2 is then absent, and IMPQUAL and SIV2 remain as non-authoritative padding that keeps the offset of Content1 unchanged.
Clear, it requests second-segment processing; if that fails, the import drops Content2, but still accepts the authenticated Content1 (Decryption and Authentication of a Complete SCC into a Locker).

Toggling it cannot affect Content1 or any policy, make an unauthenticated Content2 usable, or bypass first-segment authentication; dropping Content2 can at most force a restart of an interrupted long-running operation (Rule GR38). After an import, K(i).MDH holds ADSDropped = 0, and an absent or dropped Content2 leaves AuxDataLen = 0 (Decryption and Authentication of a Complete SCC into a Locker); an export uses the AuxDataLen of the MDH, which the implementation keeps up to date (Generation of an SCC from a Fully Configured Locker).

UsagePolicy Field

UsagePolicy determines which modes may use the locker. Usage Control applies only to the usage instructions that Table 13 lists, which use the Machine in a locker to operate on the locker’s internal state, or to expose it, as a kl.exec that produces output does.

Bits 0–4, when set, allow usage in U-mode (VU-mode included), VS-mode, S-mode (HS-mode with the H extension), M-mode, and Debug mode, respectively. A clear bit denies its mode, so a zero UsagePolicy admits no mode: software sets each permission deliberately. mstatus.MPRV is not considered, and the bit of a mode that is unsupported or not enabled has no effect, because it is never checked.

Usage in Debug mode requires bit 4 and, outside authenticated Debug mode (Architectural Model), that bits 0–3 allow the debug access privilege of the External Debug Security extension, that is, the most privileged mode for which that extension allows external debug, and every mode below it: a debugger authorized only for lower privilege modes then gains no usage that those modes lack.

The Debug-mode rule above is based on a draft of the External Debug Security extension (the debug access privilege). It must be revisited when that extension is ratified.

Locality Field

Locality names 128-bit Locality Secrets (LSs), listed in Table 9 and stored in a possibly virtual Locality Secrets Table (LST). Some entries are fixed, or configurable only by an implementation-specific, authenticated hardware process, and shared by all KLE units of an SoC; the others are software-programmable, per-hart architectural state.

At SCC export and import, the Localities named in Locality cryptographically bind the SCC to the current hardware and software environments. The binding ends at import: if a Locality Secret changes later, the next export binds its SCC to the new value.

Eleven LST entries are architected: entries 0–5 form the HW Binding Group, which binds SCCs to the hardware; entries 6–7 the Boot Session Group; and entries 8–10 the SW Filter Group.

Table 9. Architected Localities. Bits refer to the *Locality* field in the MDH.
Idx	Locality	Description	Domain	Config?	Bits	Value
No HW Binding		Independent of chip, OEM and device	—	—	[3:0]	0
0	SiPScrt	Identifies the designer of the SoC. Permanent.	SoC	No	[1:0]	1
1	ChipFamScrt	Identifies the chip (SoC) model. Must also differ when the KLE unit differs, unless the KLE units have the same `mklvendorid`, `mklarchid` and Machine set and differ only in `mklimpid`. Permanent.	SoC	No	[1:0]	2
2	ChipScrt	Unique for each SoC. Permanent.	SoC	No	[1:0]	3
3	OEMScrt	Provisioned by the OEM to differentiate its products. Permanent, or reconfigurable through a custom authenticated hardware mechanism.	Device	HW	[3:2]	1
4	ProdScrt	Identifies the device or system type or model (product). Permanent, or reconfigurable like OEMScrt.	Device	HW	[3:2]	2
5	DevScrt	Unique device (entire system) secret, shared by all harts of an SoC and shareable across the SoCs of a device through an implementation-defined mechanism. Reconfigurable like OEMScrt.	Device	HW	[3:2]	3
No Boot Binding		Independent of physical or virtual boot session	—	—	[5:4]	0
6	PhysBootScrt	Unique per boot session of the host hardware and its firmware stack. Configured by M-mode at the host boot (see mklphysbootscrt).	Device	M	[5:4]	1
7	VirtBootScrt	Unique per boot session of the virtual hardware and its software stack. Regenerated by HS-mode or M-mode at each virtual boot of a VM (see hklvirtbootscrt).	VM	HS/M	[5:4]	2
Binding to Modes			—	—	[8:6]	—
8	MLocality	Configurable at M; separates Supervisor Domains or Security States.	< M	M	6	1
9	HLocality	The hypervisor’s tag on its virtual machines, which separates them; it enters the bindings of a guest’s exports and imports, and of the hypervisor’s handling of the loaded VM’s lockers (see hkllocality). Unconfigured without the H extension.	VM	HS	7	1
10	SLocality	The OS’s Locality: configured via CSR `skllocality` (see skllocality); it always separates U-mode or VU-mode processes, and while V=1 it holds the guest OS’s value, which the hypervisor swaps in.	< (V)S	(V)S	8	1

In the HW Binding Group, ChipFamScrt and DevScrt must be provisioned, and no provisioned secret of the Group may be zeros(128). An unconfigured entry of that Group is transparently replaced by the next configured entry of its chain: SiPScrt → ChipFamScrt → ChipScrt, and OEMScrt → ProdScrt → DevScrt. A Locality Secret is unconfigured if it is not provisioned or holds zeros(128); for the Boot Session and SW Filter Groups, it is not provisioned if its CSR group (Locality Secret CSR groups) is not implemented. A requested Locality may be substituted but never dropped: a PI or SCC whose Locality names an unconfigured entry without a configured substitute, or carries the reserved value 3 in bits [5:4], is invalid Metadata (Validity of Metadata).

Up to six architected Localities may be active at once: up to two of the HW Binding Group, at most one of PhysBootScrt and VirtBootScrt, and up to three of the SW Filter Group. The SCC generation and import algorithms (Management of Cryptographic Contexts) enforce their policies.

ExpirationDate Field

ExpirationDate is in effect only with Zklexpire, which requires the KLE implementation to access a secure clock. Without Zklexpire, a non-zero ExpirationDate in a PI or SCC is invalid Metadata (Validity of Metadata).

A non-zero 20-bit ExpirationDate gives the CC’s expiration in whole hours since 00:00 UTC, 1 January 2027, spanning about 119 years and 7 months, independent of time zones. Software below M-mode must not be able to set the clock. A secure clock always reports monotonically non-decreasing time.

The assurance of the clock, like that of the SCProtection levels (SCProtection Field), is set by security standards and platform profiles, not by this specification. It is strongly recommended that a platform with Zklexpire document its clock, and that the clock:

map to UTC with a documented resolution, maximum error and drift;
keep advancing, or be trustworthily resynchronized, across suspension, reset, power loss and the restore of a saved platform or VM state;
be protected against unauthorized setting, rollback and stoppage, or detect them; and
report itself unavailable, never as zero or a pre-epoch date, while its UTC mapping, progress or error bounds cannot be trusted, until a trusted recovery.

ExpirationDate is evaluated only:

at the issue of any usage instruction, for kl.derive at both endpoints; and
when a usage instruction resumes after a halt, but not between the blocks or component operations of one execution.

Each execution reads the clock at most once, before any component operation, and a passed check covers the rest of it, even if the date passes meanwhile. An unavailable clock on resumption leaves the prefix committed before the halt in place (Rule GR16).

The ExpirationDate of a locker that is not in a Valid State is not evaluated: only an expired locker in active use transitions to Error State Expired, and expired contexts can still be managed cleanly.

The evaluation proceeds as follows:

If ExpirationDate is zero, the instruction proceeds.
If the secure clock cannot be read, the instruction raises a KLE clock-unavailable exception (Exception causes in decreasing priority order) and leaves the State unchanged.
The secure clock’s date is converted to the ExpirationDate format, in whole hours rounded down; a reading before the epoch converts to 0, and one at or after 2²⁰ − 1 hours converts to 2²⁰ − 1.
If the converted value is at least ExpirationDate, the locker transitions to Error State Expired; otherwise the instruction proceeds.

MachineUse and AuxInfo Fields

A Machine may use MachineUse and AuxInfo, or subfields of them, to store additional information, in every State or only in some. Each Machine specification identifies the bits it defines and the States in which it defines them. The other bits, including progress in an implementation-defined format (Rule GR37), are implementation-defined: the implementation may use them in the States in which the Machine does not.

Implementation-defined values are disposable: ignoring them preserves the architected semantics, policies and parameters of the Machine, at the cost of a restart at most.

An implementation that uses them keeps AuxDataLen ≥ 2 in the MDH, exactly 2 when Content2 is empty, so that every SCC it exports includes an ADS (AuxDataLen and ADSDropped Fields).
An import, or an export completion that restores a Valid State, interprets them only if both segments authenticate, even with an empty Content2, and the authenticated IMPQUAL equals that of the importing implementation. Otherwise, if the ADS is absent or discarded (ADSDropped = 1 included), that operation zeroes them after first-segment authentication and before the locker becomes Valid, and the Machine proceeds from the architected fields alone, restarting as Rule GR38 requires.
kl.clearads zeroes them likewise in a resident locker, so that kl.getmd* and a later export observe zeros; later computation may set new values, but never restores the discarded ones.

Neither field may hold a value that depends on key material, a secret field, plaintext or a value drawn for the operation, other than the progress that Rule GR37 allows, since the MDH is not confidential and kl.getmd* returns it in every mode and State.

Validity of Metadata checks these fields only through the unsupported condition on values that a Machine specification declares, and by requiring MachineUse to be zero at a system-specific import (Rule GR47). Otherwise a wrong value causes an error of the Machine that uses it, and a discarded implementation-defined value causes none.

Provisioning ignores and zeroes the MachineUse of a PI and the implementation-defined subfields of its AuxInfo (Locker Management Operations), and the completion of a system-specific import (Rule GR51) zeroes the implementation-defined subfields of AuxInfo that the declared MDH supplies. The rules of the Machine decide what happens to the subfields of AuxInfo that it defines upon provisioning, and to both fields on entering State Ready.

A Machine may use AuxInfo to pass initialization parameters at provisioning. AuxInfo holds, for instance, the modes that an EdDSA CC may use (EdDSA-Specific Rules); the tag length that every verification compares, for GCM, CMAC, HMAC, and Ascon-AEAD128 and its variants (Rule MR12); the segment size u of CFB (Chaining/Feedback Modes (CBC, CFB, and OFB)); and the transfer counter block_base of the Elliptic Curve Machines, which is public (Elliptic Curve Cryptography).

Version Field

Version gives the version of the MDH format:

0: the current format;
1: reserved for newer revisions of the format, whose further version information is encoded in other MDH fields; unsupported in this revision;
2: reserved; and
3: a system-specific format, used only for import (Rules for the Import of a System-Specific Format).

A PI, SCC or PCCC with a Version that the implementation does not support is invalid Metadata (Validity of Metadata). It is invalid, not Unsupported: the version fixes the layout of the MDH, so no other field can be interpreted.

Validity of Metadata

In a PI, software keeps all reserved bits, and all bits that the Machine does not use, zero; elsewhere, software passes unchanged the MDH bits that the implementation wrote.

Valid Metadata is unsupported when any of the following holds:

the combination of Machine, MachinePolicy, MachineExtension and an SCProtection value of 0 to 2 (Levels A to C) is not implemented;
KeyType is 1, resp. 2, and the implementation does not support System Key Identifiers, resp. random key generation, for the Machine (KeyType Field, System Keys); or
it holds a value that a Machine specification declares unsupported if not implemented, such as the AuxInfo of EdDSA (EdDSA-Specific Rules).

A supplied MDH is invalid when any of the following holds:

Version is unsupported, or is 3 in a PI or in a PCCC of base type pi;
Version is 3 at import and any of the following holds: State is not Unconfigured, kl_cfg_importing or kl_cfg_exporting; AuxDataLen is zero; or one of StateExtension, KeyType, ADSDropped and MachineUse is non-zero (Rules for the Import of a System-Specific Format);
KeyType is 1 or 2 for a Machine whose Provisioning Input has no key field, for instance the unkeyed hash functions and XOFs, the ECC, ML-KEM and ML-DSA Machines, and the NIK variants of HMAC;
KeyType is 3, or 2 outside a PI and a PCCC of base type pi;
SCProtection is 3, a reserved value (SCProtection Field);
Locality[5:4] is 3, or Locality names an unconfigured Locality Secret without a configured substitute (Locality Field);
the MDH carries a custom Machine or a system-specific Version, and its Locality includes none of SiPScrt, ChipFamScrt, ChipScrt, OEMScrt, ProdScrt and DevScrt, which bind the CC to its allowed consumers;
State is not 0, or StateExtension is non-zero (an Error State), at provisioning, or State is 0 and StateExtension is 7–15 at import;
State is 61–63 at import, or Unconfigured at an import whose Version is not 3 (Rules Governing the State and StateExtension Fields and their Transitions);
in an SCC or PCCC, StateExtension @ State is a value that the Machine does not support; for this condition, every Machine supports State 0 with a StateExtension of 1–5, and of 6 with Zklexpire, and the Configuration States 56–60 with any StateExtension;
StateExtension is 6 (Expired) at State 0 in an SCC or PCCC when Zklexpire is not implemented;
ExpirationDate is non-zero and Zklexpire is not implemented;
AuxDataLen = 1 and Version is not 3;
AuxDataLen or ADSDropped is non-zero in a PI, or in a PCCC with base type pi (Management States and Formats);
MachinePolicy has a value that Rule MR1 does not admit for the Machine, such as zero for a Machine that requires at least one set bit in it;
MachineExtension has a value that the Machine does not define (Machine and MachinePolicy Fields); or
a Reserved bit is non-zero.

Invalid Metadata takes precedence over unsupported Metadata: the test for unsupported applies only to valid Metadata, as only a valid Version fixes the layout of the fields it reads. The four conditions that depend on the definition of the Machine, those on KeyType for a Machine without a key field, on StateExtension @ State, on MachinePolicy and on MachineExtension, apply only to a Machine that the KLE unit implements, with some MachinePolicy, MachineExtension and SCProtection. For any other Machine, the Metadata is unsupported, and an M-mode handler that emulates the Machine applies those conditions (Emulation of Unsupported Machines).

Narrowing of Metadata

Several operations narrow the policies of a CC by those of another source: the resolution of a SKID (System Keys), a restricted kl.derive (Rule GR30), the import of a system-specific format (Rules for the Import of a System-Specific Format), and kl.rstr*, at the request of software (kl.rstrl, kl.rstrh, and kl.rstrv).

The narrowing of an MDH A by the policies of a source B (an MDH, the policies that the SKS associates with a key, or those that a system-specific format carries) is A with the following fields replaced; a policy field that B does not carry leaves that field of A unchanged, and no other field changes:

MachinePolicy: for kl.rstrl and kl.rstrv only, the AND of both, so that the functions enabled are those that both enable (Rule GR20); every other narrowing leaves it unchanged, even when B is an MDH.
UsagePolicy: the AND of both, so that the modes that may use the CC are those that both allow.
Locality (Table 9): each HW Binding subfield (bits [1:0] and [3:2]) takes the larger value, the stricter entry of its chain, zero meaning no binding; the Boot Session subfield (bits [5:4]) takes the non-zero value if only one is non-zero, and their common value if they are equal; and bits 6–8 are OR-ed.
ExpirationDate, with Zklexpire: the smaller non-zero value, or 0 if both are 0. Without Zklexpire, an expiration among the policies of the SKS or of a system-specific format makes the narrowing fail.

If both Boot Session subfields are non-zero and differ, if either of them is the reserved value 3, or if the resulting Locality names an unconfigured entry without a configured substitute (Locality Field), the policies cannot be met, and the narrowing fails; each operation that narrows states the outcome. Narrowing never changes SCProtection.

CSRs

KLE provides the following unprivileged CSRs. Like vstart and vl, they are unprivileged; the getter and setter instructions are nevertheless the recommended way for software to access them (CSR Getters and Setters: kl.get*, kl.set*, and kl.set*i).

Table 10. KLE Unprivileged CSRs
Address	Privilege	Field	Description
TBD	URW	(`Zklio`) `kliobuflen`	Length of the KLIOBUF, in bytes.
TBD	URW	(`Zklio`) `kliobuftop`	Limit of the KLIOBUF for the current transfers, in bytes.
TBD	URW	`klstart`	Start byte index.
TBD	URW	`klnamedlocker`	Number of the locker named for management transfers and `KLNL`, or 32 if none.

Without Zklio, kliobuflen and kliobuftop do not exist: every access to them raises an illegal-instruction exception, as the corresponding getter and setter instructions are reserved (Rule GR1).

The KLS field in effect controls access to these CSRs: while it is Off, every access, including a read of a CSR that M-mode emulates, raises an illegal-instruction exception (KLE Context Status in mstatus and sstatus). With Smstateen, the KLE bit of the *stateen0 CSRs (CSRs) also gates all of them and the KLE instructions; a denied access raises the exception that Smstateen prescribes for the executing mode and the denying gate.

Context-switch code saves klstart and klnamedlocker first and restores them last, and saves and restores kliobuflen, kliobuftop and the KLIOBUF contents (Software Guidelines, Rule SR3).

The KLE unit does not record which locker the values in the authentication registers belong to: they hold what the last instruction to write them stored (The Cryptographic Locker File and Authentication Information). Their owner is the locker whose import or export is open and that no nested export has saved. Software keeps klnamedlocker at the number of that locker, or at 32, which names no locker, but only while that locker is the only one in State kl_cfg_importing or kl_cfg_exporting (Rules SR7 and SR8). Context-switch code finds the owner this way, exports it before the other lockers and imports it after them, so that its import restores SIV and, if used, IMPQUAL and SIV2 (Context Save Order, Context Restore Order).

A CSR whose description gives a maximum is WARL: writing a larger value sets the maximum, so software must read it back (preferably with the getter instructions of CSR Getters and Setters: kl.get*, kl.set*, and kl.set*i). Writing a reserved value (33 and above) to klnamedlocker leaves it unchanged (klnamedlocker).

kliobuflen

kliobuflen is an XLEN-bit URW CSR that programs the length of the KLIOBUF, in bytes, for kl.input and kl.output; its maximum is the maximum length of the KLIOBUF (mklmaxiobuflen). Every write, even of the current value, zeroes the buffer below the new length before it completes, and sets kliobuftop to that length. Bytes beyond the new length need not be erased, since they stay inaccessible until a later write zeroes them: a write of zero makes the contents inaccessible without erasing them, unless the implementation supports Level C (Destructive Configuration Instructions).

A zero kliobuflen leaves the KLIOBUF unconfigured: an operation that expects an input or an output in it raises an illegal-instruction exception, unless it falls through (Rules GR11, GR13.2 and GR14).

kliobuftop

kliobuftop is an XLEN-bit URW CSR that sets the upper bound, in bytes, of the buffer range that kl.input and kl.output use; its maximum is kliobuflen, and kl.exec never modifies it. It is the KLIOBUF counterpart of VL in the V extension: it defines the operand length KLLEN as kliobuftop × 8 and the transfer window [0, kliobuftop-1].

Writing kliobuftop leaves the buffer unchanged, so software can set the length per operation without writing kliobuflen, which clears the buffer; this mirrors using VL × SEW to supply a partial last block, or a short IV or nonce, to a Machine.

A value invalid for a Machine is detected only when an instruction that uses the KLIOBUF is later issued or restarted, with the outcomes given in Zklio.

klstart

klstart is an XLEN-bit URW CSR that records, in bytes, the progress of the instructions that honor it:

kl.load, kl.store, kl.input and kl.output: the bytes read or written;
kl.exec with a vector or KLIOBUF operand, which may be interrupted at its interruption points (Rule GR33.2): the bytes processed;
kl.derive, which is uninterruptible, requires klstart = 0 (Rule GR29) and leaves it 0; and
kl.mvin and kl.mvout, vector or not: the locker transfer point.

KLE has no intrinsic element length and no counterpart of the Element Group Width (EGW) or Element Group Size (EGS) of the vector crypto extension, or the Effective Element Width (EEW) of the vector extension; its instructions, such as kl.exec, are architecturally decoupled from the operations the KLE unit performs for them. klstart is a byte count; Machines or their implementations record progress that is not byte-structured, such as that of the point multiplications and signature operations of Elliptic Curve Cryptography and Post-Quantum Public-Key Cryptography, in their progress field, in MachineUse (Rule GR37).

Like vstart in the V extension, klstart is the position within the transfer window of kl.exec at which processing starts or resumes: bytes [0, kliobuftop-1] for a KLIOBUF operand, with kliobuflen non-zero, and [0, VL × SEW/8 - 1] for a vector operand. The memory instructions and kl.mvin and kl.mvout define their own windows (KLIOBUF transfer window, serialized image).

Rule GR14 lists the events that change klstart, Rules GR33.2 and GR18 state how kl.exec checks it, and Appendix: Writing Software for KLE provides guidelines for software.

klnamedlocker

klnamedlocker is an XLEN-bit URW CSR; only 6 of its bits are used. It holds the number of the locker named for management transfers and KLNL, or 32 if none. Completing a management operation, even with an error, keeps the number, so that software can inspect the outcome through KLNL before writing 32 or restoring a saved value. Values 33 and above are reserved; writing one leaves klnamedlocker unchanged. While the locker it names is in a Configuration State, that locker is under management; klnamedlocker is also the record from which context-switch code finds the locker that owns the authentication registers SIV, IMPQUAL and SIV2 (Ownership of Authentication Registers).

The named locker serves two purposes:

a single management routine using the named locker can manage any locker, which reduces code size; and
a clear of the named locker sets klnamedlocker to 32 (Rule GR21), which code that does not rewrite klnamedlocker during a management operation detects; other code checks the outcome with kl.getst.

Addressing the named locker when klnamedlocker is 32 causes the instruction to fall through: Rule GR13.2.

Rule GR21 lists the events that change klnamedlocker, Rules GR4 and GR13.2 state how instructions use it, and Appendix: Writing Software for KLE provides guidelines for software writers.

Instructions

This section specifies only the semantics and encodings of the unprivileged KLE instructions, not their behavior in the various States of the Machines, how they respect usage policies, how they use randomness, how they access memory, or whether they are interruptible. The rules governing these aspects are grouped in Rules.

Where an instruction’s behavior depends on a rule, its description states that behavior and references the rule.

Definition: No Operation.: An instruction that performs no operation performs none of the operations of the KLE unit, such as cryptographic operations, but may still have the effects that its description or a rule states, such as writing zeros to its output, writing 0 to klstart, setting klnamedlocker, or raising an exception.

General Rules Governing Encoding and Arguments

The following rules apply to all KLE instructions, unless stated otherwise.

GR1	In every encoding, fields shown with fixed values must hold them. Any other value of such a field, and any unlisted combination of field values, is a reserved encoding and raises an illegal-instruction exception (Second Group of Illegal-Instruction Exception Grounds).
GR2	Use of multiple GPRs for longer inputs: A 64-bit operand is one GPR on RV64 and the pair `(X[s+1],X[s])`, as `X[s+1] @ X[s]`, on RV32. A 128-bit operand is the pair `X[s+1] @ X[s]` on RV64 and the quartet `X[s+3] @ X[s+2] @ X[s+1] @ X[s]` on RV32. This holds for sources and destinations alike. The lowest register number of a pair must be even, and that of a quartet a multiple of four; otherwise an illegal-instruction exception is raised. A pair or quartet is read or written as a whole. Here and in every instruction description, RV32 and RV64 denote an XLEN of 32, resp. 64, in the privilege mode executing the instruction.
GR3	If `X0` is used as a destination or source register, writes to it are discarded, and it reads as zero. When the lowest register of a pair or quartet is `X0`, no register of the group is written, and the group reads as zero.
GR4	Every instruction that can encode a locker number may encode instead the named locker, written `KLNL`: the locker that `klnamedlocker` names when the instruction issues, or no locker if `klnamedlocker` = 32 (Rule GR13.2). The encoding fields `r` and `R` serve only to encode `KLNL`, in place of a locker register field, which must then be zero: `r` = 1 for the single locker operand; in `kl.clone`, `kl.rename`, `kl.swap` and `kl.derive`, `R` = `01` for the first operand, the destination, and `R` = `10` for the second, the source; `R` = `11` is reserved. A non-zero locker register field that `r` or `R` replaces is a reserved encoding. The management transfer instructions, `kl.load`, `kl.store`, `kl.mvin` and `kl.mvout`, have no locker operand: they act on the locker that `klnamedlocker` names.
GR5	Where a KLE instruction carries the whole 128-bit MDH in a vector register or group, such as the MDH-formatted operand of `kl.rstrv` and the destination of `kl.getmdv`, the operand must satisfy `VL` × `SEW` ≥ 128; otherwise an illegal-instruction exception is raised. Extensions Overview lists the vector extensions that provide such a register.
GR6	A vector register operand whose register number is not a multiple of the LMUL in effect is a reserved encoding and raises an illegal-instruction exception, as in RVV 1.0. Every KLE instruction with a vector operand sets `vstart` to 0 when it retires, and on a precise halt sets it as Rules GR33 and GR7 prescribe. An instruction with a vector operand that produces no `vstart` value (`kl.getmdv`, `kl.rstrv`, Form C of `kl.size`, `kl.avail`, `kl.setst` and `kl.mgmt`) raises an illegal-instruction exception if issued with `vstart` ≠ 0, as RVV 1.0 §3.7 permits for a `vstart` value that the instruction can never produce.
GR7	KLE instructions with vector operands that use `klstart` for resumption update `klstart` and `vstart` simultaneously and independently, each by its own semantics; except for `kl.mvin` and `kl.mvout`, both denote the same point of progress, `klstart` in bytes and `vstart` in elements of the width in effect. Issuing a Form A–C `kl.exec` with `klstart` ≠ `vstart` × `SEW`/8 raises an illegal-instruction exception. Each unit keeps its own information, and the two values can still be explicitly desynchronized, as in locker management operations. `kl.mvin` and `kl.mvout` keep the two independent by design: their `klstart` is a locker offset that accumulates across instructions, while `vstart` tracks the vector register.

Provisioning, Import, and Export

Setting aside the handling of lockers in an Error State, a management operation takes three steps: the first and the last are one KLE instruction each, and the second is one or more kl.mvin or kl.mvout (alternatively, kl.load or kl.store) instructions:

An opening kl.mgmt (kl.mgmt) prepares the locker for the management operation.
One or more kl.mvin (kl.mvin and kl.mvout) load the rest of the information into the locker, or one or more kl.mvout move the locker’s information out.
A completing kl.mgmt ends the management operation and makes the locker available to software.

kl.avail and kl.size

kl.avail and kl.size, together with kl.getmd, kl.getmdl, and kl.getmdv (kl.getmd, kl.getmdl, and kl.getmdv), are the inspection instructions, i.e., those that examine the MDH without changing any state.

Synopsis

kl.avail returns 1 if the Machine encoded in the MDH is available in the requested variant, and 0 otherwise. kl.size returns the size in bytes of the memory buffer needed for the data of a PI, an SCC or a system-specific format, or 0 on error, such as an unsupported Machine or an invalid MDH, or raises an illegal-instruction exception for M-mode emulation (item 5).

Mnemonic

kl.avail and kl.size have three Forms:

kl.{avail,size} Xd, Ks - Size from a context.
kl.{avail,size} Xd, Xs - Size from MDH[63:0] in one (RV64) or two (RV32) GPRs.
kl.{avail,size} Xd, Vs - Size from MDH in one vector register.

Encoding

The encoding shares the opcode, funct3 and funct2 (the two msbs of funct7) of kl.exec, with bit 27 set. Bit 25, q, selects kl.size (q = 0) or kl.avail (q = 1).

Field F selects the Form:

F = 0b00 ⇒ Form A, from a context Ks.
F = 0b01 ⇒ Form B, from an MDH in one (RV64) or two (RV32) GPRs.
F = 0b10 ⇒ Form C, from an MDH in a 128-bit vector register.

r must be 0 in Forms B and C; r = 1 there is a reserved encoding.

Description

kl.avail (q = 1) tells whether the KLE unit implements the Machine fields of an MDH: its Machine, MachinePolicy, MachineExtension, KeyType and SCProtection. kl.size (q = 0) gives the size in bytes of the external image that an MDH describes: a PI, an SCC with its tag(s) and ADS, the MDH of a system-specific format followed by its appended data (Rule GR47), or, for an Error State, the MDH alone (Management States and Formats, Length of External Formats and KLF Capacity Usage of a Locker).

The MDH is that of locker Ks in Form A, where Ks may be KLNL (Rule GR4); bits [63:0] in Xs, or X[s+1] @ Xs on RV32, in Form B; and bits [127:0] in Vs in Form C. Form B examines only bits [63:0], since no field in bits [127:64] affects the size of any structure (Length of External Formats and KLF Capacity Usage of a Locker); conditions on those fields, such as the Locality binding of a custom Machine (Validity of Metadata) and the AuxInfo of a Machine, are not applied.

content1_size is the length in bytes of the Content1 of an SCC for the given MDH, and pi_content_size that of the Content of a PI, both determined according to Length of External Formats and KLF Capacity Usage of a Locker. content2_size is 16 * (AuxDataLen - 2) if AuxDataLen ≥ 2 and ADSDropped = 0, and 0 otherwise.

The order in which the conditions are checked is given in Rule GR12. The instruction then writes to Xd the value of the first item of its list that applies.

kl.size returns or raises, evaluated in order:

Form A: 0 if Ks is KLNL while klnamedlocker = 32 or the locker is Unconfigured, 16 if the locker is in an Error State, and otherwise the size of item 7;
Forms B and C: 0 if State is 61–63, or is 0 with a StateExtension of 7–15 (reserved);
16 if State is 0 with a StateExtension of 1–5, or 6 with Zklexpire (an Error State) (Export and Import of a Locker in an Error State);
0 if Version is 1 or 2, or if SCProtection or KeyType holds a reserved value;
if the KLE unit does not natively implement the Machine fields: an illegal-instruction exception if mstatus.kleemulation = 1 (KLE Emulation Control in mstatus), so that M-mode can supply the value, and 0 otherwise;
0 if the MDH is unsupported or invalid Metadata (Validity of Metadata), evaluated as at provisioning when State is 0 and Version is not 3, and as at import otherwise;
the size:
1. 16 + 16 × AuxDataLen if Version is 3, whatever the State;
2. if State is a Valid State or kl_cfg_{importing|exporting}: 32 + content1_size if AuxDataLen = 0, and 64 + content1_size + content2_size if AuxDataLen ≥ 2, the 64-byte fixed part including IMPQUAL and SIV2 even when ADSDropped = 1;
3. 16 + pi_content_size if State is kl_cfg_provisioning, kl_cfg_ppi_importing or kl_cfg_ppi_exporting, or if a supplied MDH has State 0 (the MDH of a PI).

kl.avail returns or raises, evaluated in order:

Form A: 0 if Ks is KLNL while klnamedlocker = 32 or the locker is Unconfigured, and otherwise 1 if the KLE unit implements the Machine fields of the MDH, and 0 if not;
Forms B and C: 0 if Version is 1 or 2, or if SCProtection or KeyType holds a reserved value;
if the KLE unit does not natively implement the Machine fields: same as item 5 of kl.size;
1 otherwise, whatever the other fields hold: a 1 does not exclude a KLE unsupported-Metadata exception that a Machine specification attaches to another field, such as the AuxInfo of EdDSA.

Every item before the lookup is independent of which Machines are implemented, so the lookup traps only when the KLE unit does not natively implement the Machine fields; M-mode then supplies the value of the remaining items.

kl.exec

Synopsis

Perform a cryptographic operation in the KLE unit.

Mnemonic

kl.exec has four Forms:

kl.exec Vd, Kn, Vs2 reads an input vector and writes an output vector.
kl.exec Kn, Vs2 reads an input vector and writes no output vector.
kl.exec Vd, Kn reads no input vector and writes an output vector.
kl.exec Kn reads no input vector and writes no output vector.

Encoding

kl.exec is an R-type instruction.

The encodings of Forms A–D are:

Form = 0b00.
Form = 0b01 and rd = 0b00000.
Form = 0b10 and rs2 = 0b00000.
Form = 0b11 and rd = rs2 = 0b00000.

Except in the encodings that Zklmv assigns (kl.mvin and kl.mvout), the locker operand is in rs1, and an unused register field (rd without an output vector, rs2 without an input vector) must be zero; other non-zero values in it are reserved.

Description

Performs a cryptographic operation defined by the Machine in locker Kn and its state, possibly taking an input and producing an output; Kn may be KLNL (Rule GR4). Rule GR14 describes its output when it performs no operation or transitions the locker to an Error State.

In Form A, each output block has the length of its input block and is written at the same window offset, so Vd and Vs2 may always be the same register group, each block’s output replacing its input; any other overlap of Vd with Vs2 raises an illegal-instruction exception.

A future version of this specification may define the semantics of expanding or narrowing multi-block kl.exec operations, whose output blocks are longer, respectively shorter, than their input blocks. No current Machine defines such operations.

Without Zklv, only Form D is supported: Forms A–C raise an illegal-instruction exception, and kl.input and kl.output supply the inputs of kl.exec and extract its outputs (Zklio).

kl.mvin and kl.mvout

The Zklmv subextension adds dedicated move instructions between scalar/vector registers and a locker. The instructions in this extension are encoded as new forms of kl.exec.

Synopsis

Move content between scalar/vector registers or the KLIOBUF and the named locker, which is in a Configuration State. These instructions do not encode an operand locker (Rule GR4).

Mnemonics

kl.mvin and kl.mvout have three variants each:

kl.mvin Xs2 copies 128 bits from two or four GPRs into the named locker.
kl.mvin Vs2 copies one or more 128-bit blocks from a vector register into the named locker.
kl.mvin KLIOBUF copies one or more 128-bit blocks from the KLIOBUF into the named locker.
kl.mvout Xs1 copies 128 bits from the named locker into two or four GPRs at Xs1.
kl.mvout Vs1 copies one or more 128-bit blocks from the named locker into a vector register Vs1.
kl.mvout KLIOBUF copies one or more 128-bit blocks from the named locker into the KLIOBUF.

Encodings

The encodings are variants of kl.exec Form D (Form = 0b11) in which rd, zero in kl.exec, is non-zero and selects the variant. No locker is encoded, so r = 0; a non-zero r is reserved.

kl.mvin Xs2: rd = 0b00001, rs1 = 0, and rs2 holds the source GPR.
kl.mvin Vs2: rd = 0b00010, rs1 = 0, and rs2 holds the source vector register.
kl.mvin KLIOBUF: rd = 0b00011, rs1 = 0, and rs2 = 0b00000.
kl.mvout Xs1: rd = 0b00101, rs2 = 0, and rs1 names the destination GPR.
kl.mvout Vs1: rd = 0b00110, rs2 = 0, and rs1 names the destination vector register.
kl.mvout KLIOBUF: rd = 0b00111, rs2 = 0, and rs1 = 0b00000.

Any other non-zero value of rd in Form D is reserved and raises an illegal-instruction exception. A non-zero rs1 in variants I–III or VI, or a non-zero rs2 in variants III–VI, is likewise reserved and raises an illegal-instruction exception.

Description

kl.mvin moves the serialized image S into, and kl.mvout out of, the locker that klnamedlocker names, as KLNL does (Rule GR4). Neither transfers the MDH: for a provisioning or an import, the opening kl.mgmt has already loaded it (kl.mgmt), and kl.getmd* reads it.

Transfer

kl.mvin and kl.mvout process the operand window in 16-byte blocks, in order: if klstart < image_end, the block of the serialized image S at offset klstart is transferred and klstart advances by 16; otherwise kl.mvin ignores the block, kl.mvout writes zeros to it, and klstart is unchanged. klstart is kept across instructions; a sequence of them transfers S piecewise. A GPR variant transfers exactly one block and is uninterruptible; a vector variant transfers one block per 128/SEW elements and can be interrupted at a block boundary (Rule GR32). If one management operation combines kl.mvin or kl.mvout with kl.load or kl.store, each byte of S holds the value last written to its offset, by whichever instruction.

Vector variants (II and V)

They also track progress in vstart: each 16-byte block advances it by 128/SEW elements, for instance by 4 for 32-bit and by 2 for 64-bit elements. Element k of the vector operand, for k from vstart to vl − 1, corresponds to byte offset klstart + (k − vstart) × SEW/8 of S. The transfer can halt only at a block boundary: klstart then holds the image offset reached, and vstart the first unprocessed element; if vstart ≥ vl, the instruction, after the checks of Rules GR12 and GR13, transfers nothing and leaves klstart unchanged.

KLIOBUF variants (III and VI)

They use the KLIOBUF in place of a vector register: they transfer bytes 0 to kliobuftop − 1 of the KLIOBUF to or from offsets klstart to klstart + kliobuftop − 1 of S, as a vector variant with vstart = 0 and vl × SEW/8 = kliobuftop does. Like the GPR variants (I and IV), they are architecturally uninterruptible (Rule GR32), although they may transfer several blocks: their length is bounded by the maximum length of the KLIOBUF.

The KLIOBUF variants give an implementation without Zklv multi-block transfers: kl.input fills the KLIOBUF from memory, with klnamedlocker = 32, and kl.mvin KLIOBUF moves it into the locker, with klnamedlocker naming that locker, as kl.input and kl.exec cooperate for the inputs of a Machine (Zklio). Their window is the KLIOBUF up to kliobuftop, so they need no element position, and a transfer of at most that maximum length can be uninterruptible. kl.input and kl.mvin KLIOBUF share klstart: the first reads it as its resume point and writes 0 to it, while the second reads and advances it as the offset in the image. kl.output and kl.mvout KLIOBUF share it likewise, so software saves and restores it around each kl.input or kl.output (Rule SR5).

Exceptions and no-operation cases

A vector variant whose vector extension is not enabled, or whose vl × SEW/8 or vstart × SEW/8 is not a multiple of 16, raises an illegal-instruction exception (Second Group of Illegal-Instruction Exception Grounds), on any locker. So does a KLIOBUF variant if kliobuftop is not a multiple of 16. The other checks are those of Rules GR12 and GR13, Rule GR24 in a Configuration State, and Rule GR14 gives the outcomes.

kl.setst and kl.setstq

Synopsis

Change the state of the Machine encoded in the CC in a locker.

Mnemonic

kl.setst has four Forms:

kl.setst Kd, #immed7 with no auxiliary input.
kl.setst Kd, #immed7, Xs with auxiliary input in one or two GPRs (RV64/RV32).
kl.setst Kd, #immed7, Vs with auxiliary input in a vector register.
kl.setstq Kd, #immed7, Xs with auxiliary input in two or four GPRs (RV64/RV32).

Encoding

kl.setst is an R-type instruction.

The following are separate instructions that share the encoding space of kl.setst:

The encodings with G = 0b01 define the instruction kl.setste (kl.setste).
The encodings with G = 0b10 belong to kl.set* (CSR Getters and Setters: kl.get*, kl.set*, and kl.set*i).
The encodings with G = 0b11 belong to kl.mgmt (kl.mgmt).

#immed7 = kl_cfg_clearall (65) is valid only in Form A, with Kd = 0 and r = 0, where it encodes kl.clearall (kl.clearall); every other encoding with G = 0b00 and #immed7 = 65 is reserved.

The encodings of the four Forms are:

F = 0b00, rs1 = 0b00000: Form A, whose auxiliary operand reads as zero (Rule GR3).
F = 0b00, rs1 ≠ 0b00000: Form B, with a 64-bit auxiliary operand in Xs = rs1 (RV64) or in X[s+1] @ Xs (RV32, Rule GR2).
F = 0b01: Form C.
F = 0b10: Form D, with a 128-bit auxiliary operand in two (RV64) or four (RV32) GPRs starting at Xs = rs1 (Rule GR2).
F = 0b11 is reserved (Rule GR1).

Form A is Form B with X0: where a Machine expects Form B or D, a Form A supplies an operand of zero; where it expects Form A, a Form B or D is a wrong Form (Rule GR19.1). Where a Machine expects Form C, Rule MR5 says which other Forms are admitted.

Description

kl.setst advances the Machine of locker Kd from one stage to another, for instance from initializing a hash function to absorbing data and finalizing the digest. It normally reaches the State that #immed7 names, but some States transition automatically to another State when the instruction completes. Rules Governing the State and StateExtension Fields and their Transitions and each Machine’s specification give the allowed transitions. kl.setst may set state information orthogonal to these stages, possibly as a prerequisite for entering another State.

For all Machines, #immed7 takes these values:

0 (kl_state_inert) encodes kl.clear (kl.clear).
1–53 name the Valid States that Ready and the Machine define (Table 6).
54 and 55 name Success and Failure of the Machine, which cannot be set directly (Rule GR19.5); Failure is an outcome, not an error.
56–63 are reserved encodings (Rule GR1); with G = 0b11 instead of 0b00, the values 56–58 and 63 encode kl.mgmt (kl.mgmt), and 59–62 are reserved encodings.
64 encodes kl_cfg_clear_ads (kl.clearads).
65 encodes kl_cfg_clearall (kl.clearall), in Form A with locker 0 and r = 0 only.
66–127 are Machine-defined, and may change other state information, such as StateExtension.

Rule GR13 gives the outcome of an immediate in 1–55, 64 or 66–127 by the State class of the locker.

Some values require an auxiliary operand, in GPRs (Forms B and D) or in a vector register Vs (Form C).

Kd may be KLNL, except for kl.clearall (Rules GR4 and GR13.2).

kl.setste

Synopsis: Set a locker to an Error State.
Mnemonic: kl.setste Kd, #immed7
Encoding: kl.setste is the encoding of kl.setst (kl.setst and kl.setstq) with G = 0b01, valid only with F = 0b00, rs1 = 0b00000 and #immed7 in 1–6. Every other encoding with G = 0b01 is reserved, and so is #immed7 = 6 without Zklexpire.
Description: kl.setste sets State to 0 (Inert) and StateExtension to #immed7, the code of an Error State (Table 7). The "e" stands for empty and error. It is a configuration instruction, admitted in every State (Rule GR26).

kl.clear

kl.clear Kd is kl.setst (kl.setst and kl.setstq) with #immed7 = kl_state_inert (State and StateExtension Fields), in any Form; it does not read any auxiliary operand, the locker-state-independent checks of Rule GR12 still applying. It sets the locker’s State to Unconfigured and releases its KLF resources. It is a configuration instruction, not a usage instruction: the UsagePolicy does not restrict it, nor can the Machine (Table 13). Rule GR21 also applies.

A kl.clear sets to Dirty every *llockerstatus field in effect for its locker, and every KLS field in effect, if it changes the locker or if any of those *llockerstatus fields is Off (mllockerstatus, sllockerstatus, and vsllockerstatus for Dirtiness Tracking); it also sets every KLS field in effect to Dirty if it changes klnamedlocker.

kl.clearall

kl.clearall is kl.setst with no auxiliary operand, #immed7 = kl_cfg_clearall, locker number 0 and r = 0. The locker field names no locker: kl.clearall acts on every locker whatever the State of K0, and is not a usage instruction.

It unconfigures every locker, as kl.clear on each would. With Zklio, it also unconfigures the KLIOBUF by setting kliobuflen and kliobuftop to 0. The contents become inaccessible and are erased only as Destructive Configuration Instructions requires. In every case it sets klstart to 0, zeroizes the three authentication registers of The Cryptographic Locker File and Authentication Information, and writes 32 to klnamedlocker (Rule GR21). It sets to Dirty the *llockerstatus fields in effect for the current privilege mode, for every locker that it changes or for which any field in effect is Off, as kl.clear does, and the KLS fields in effect if it changes a locker, kliobuflen, kliobuftop, klstart, klnamedlocker or an authentication register, or if any *llockerstatus field in effect is Off.

kl.clearads

kl.clearads Kd deletes any ADS from locker Kd, sets AuxDataLen and ADSDropped to 0, and zeroes the implementation-defined subfields of MachineUse and AuxInfo (MachineUse and AuxInfo Fields). It is encoded as kl.setst (kl.setst and kl.setstq) with no auxiliary operand and #immed7 = kl_cfg_clear_ads (64). Any other Form of kl.setst with #immed7 = 64 is a wrong Form (Rule GR19.1).

kl.clearads is a usage instruction, admitted in every Valid State (Rule GR19.3). It leaves State unchanged, and StateExtension, except that it clears the flag of any material that Rule GR38 destroys, such as HasRndNum of the ECC Machines. It discards the implementation-defined state, in the ADS and in MachineUse and AuxInfo (MachineUse and AuxInfo Fields), including the progress of an interrupted long-running operation (Rule GR38).

Software uses kl.clearads to make the SCC smaller before exporting a locker for another target. A destination with a different KLE unit would drop the ADS anyway.

Destructive Configuration Instructions

kl.clear and kl.clearall (kl.clear and kl.clearall) are two of the destructive configuration instructions, the configuration instructions that discard the CC in a locker without reading it, other than kl.setste. kl.setste also discards the Content of its locker (Rule GR15), but it is not one of them: it leaves klnamedlocker unchanged (Rule GR21), and it is not exempt from the KLE locker-Off exception. The other destructive configuration instructions are:

a provisioning- or import-opening kl.mgmt (defined in the next section, kl.mgmt), which zeroizes the locker before configuring it;
kl.clone and kl.rename (defined later in kl.clone, kl.rename, and kl.swap), which replace the CC of their destination locker with that of the source; and
kl.swap (same section), a special case that overwrites both its lockers, each with the CC of the other, so nothing is lost.

A destructive configuration instruction destroys the CC it replaces right after the locker-state-independent checks of Rule GR12, the check of the MDH operand of kl.mgmt included, whatever the outcome, unless it names KLNL while klnamedlocker = 32, when it finds no locker and performs no operation (Rule GR13.2), or it is a kl.clone, kl.rename or kl.swap whose source and destination are the same locker, which performs no operation (kl.clone, kl.rename, and kl.swap).

Item 6 of Rule GR12 gives the accesses exempt from the KLE locker-Off exception; the source access of kl.clone and kl.rename and either access of a kl.swap on two lockers are not.

KLF capacity that kl.mgmt or kl.clone allocates to a locker reads as zero, to the locker’s Machine and to every architectural access, until written. An implementation that supports Level C (Table 4) must also zeroize at once the Content and any ADS of every locker whose CC is discarded by kl.clear, kl.clearall or as the previous CC of the destination of kl.rename or kl.clone, or that transitions to an Error State (Rule GR15), and the KLIOBUF bytes that a write of kliobuflen or a kl.clearall makes inaccessible (kliobuflen); any other implementation need only release them.

kl.mgmt

Synopsis

Open or complete a management operation on a locker.

Mnemonics

kl.mgmt uses the encoding of only Forms A, C and D of kl.setst, but is a distinct instruction.

kl.mgmt Kd, #immed7 with no auxiliary input.
Reserved.
kl.mgmt Kd, #immed7, Vs with auxiliary input in a vector register.
kl.mgmt Kd, #immed7, Xs with auxiliary input in two or four GPRs (RV64/RV32).

Encoding

kl.mgmt is an R-type instruction with the encoding of kl.setst (kl.setst and kl.setstq), G = 0b11 and #immed7[6:3] = 0b0111, that is, #immed7 in 56–63.

Description

For this instruction, Rules GR2, GR3, GR4, GR5, GR6 and GR21 apply.

kl.mgmt brackets the body of a locker management operation (Provisioning, Import, and Export): it opens a provisioning, an export or an import on locker Kd, and completes it. A kl.mgmt that opens, resp. completes, a management operation is an opening, resp. completing, kl.mgmt, named after its operation: a provisioning-opening kl.mgmt, an export-completing kl.mgmt, and so on.

A provisioning- or import-opening kl.mgmt is allowed in every State (Table 13). It is a destructive configuration instruction, which erases the memory of the locker before using it: this prevents any previous content from leaking into a nested management operation.

Like kl.setst, kl.mgmt changes the locker’s State, but with different semantics. The State reached depends on both the locker’s previous State and #immed7. Besides the command in #immed7, a kl.mgmt that needs it receives an MDH: when opening a provisioning or an import, it selects the variant of the operation and may become the locker’s MDH; when completing an import or an export, it restores the State recorded in ml, the copy of the MDH that the caller saved (Management States and Formats).

Table 17 gives the values of #immed7; every other value is reserved (Rule GR1).

The Forms supply the MDH as follows:

Form A carries no auxiliary operand, and supplies an all-zero MDH (Rule GR3).
Form C carries it in the lowest 128 bits of Vs (Rules GR5, GR12 apply).
Form D carries it as a 128-bit operand in two or four GPRs starting at Xs (Rule GR2).

Locker Management Operations gives the precise semantics of each operation.

kl.getmd, kl.getmdl, and kl.getmdv

Synopsis

Export the MDH of a locker.

Mnemonics

kl.getmdl Xd, Ks
kl.getmd Xd, Ks
kl.getmdv Vd, Ks

Encoding

kl.getmd* are R-type instructions that share the opcode and funct3 of kl.exec, with funct2 = 0b11.

r names KLNL as Rule GR4 specifies.

With bit v (bit 29) = 0, bit h (bit 28) selects kl.getmdl (h = 0) or kl.getmd (h = 1), and the result goes to GPRs: one GPR on RV64 and a pair on RV32 for kl.getmdl, a pair on RV64 and a quartet on RV32 for kl.getmd (Rule GR2). With v = 1, the instruction is kl.getmdv, which writes the entire MDH to the lowest 128 bits of a vector register; h must then be 0. v = h = 1 encodes kl.getnl (CSR Getters and Setters: kl.get*, kl.set*, and kl.set*i).

Description

These instructions copy the MDH of locker Ks, which is all-zero for an Unconfigured locker:

kl.getmdl copies bits [63:0] to GPR Xd on RV64, and to the pair X[d+1] @ X[d] on RV32.
kl.getmd copies bits [127:0]: on RV64, bits [63:0] to Xd and bits [127:64] to X[d+1]; on RV32, to the quartet X[d+3] @ X[d+2] @ X[d+1] @ X[d].
kl.getmdv copies bits [127:0] to vector register Vd, on RV32 as on RV64. Bits [VL × SEW − 1 : 128] are written with zeros, and the tail follows the tail-agnostic policy (RVV/KLV).

They do not check MDH validity (Validity of Metadata). Ks may be KLNL (Rule GR4).

kl.getst and kl.getstx

The pseudo-instructions kl.getst Xd, Ks kl.getstx Xd, Ks return the State, resp. StateExtension, field of the MDH of the source locker, for instance to determine whether it is in an Error State (State and StateExtension Fields). They read the MDH with kl.getmdl and extract the field by shifting and masking. Ks may be KLNL; the expansion then uses kl.getmdl with r = 1. With Xd = X0 the instruction writes nothing (Rule GR3).

On RV64, kl.getst expands to

kl.getmdl Xd, Ks
srli Xd, Xd, 18
andi Xd, Xd, 0x3F

and kl.getstx by the same code, with the constants in Steps 2 and 3 changed to 24 and 0x0F, respectively.

On RV32 the code is the same, but Xd must be even (Rule GR2) and X[d+1] is also overwritten with MDH bits [63:32].

CSR Getters and Setters: kl.get, kl.set, and kl.set*i

Like vsetvl and related instructions of the vector extension, these instructions set and get certain CSR values without a CSR access, which is slow in many implementations.

Synopsis

Get, resp. set, the value of klnamedlocker, kliobuflen, kliobuftop, and klstart.

Mnemonics

kl.getnl/getbl/getbt/getks Xd
kl.setnl/setbl/setbt/setks Xs1
kl.setnli/setbli/setbti/setksi #uimm7

Encodings

The encodings are variants of those of kl.getmd* (kl.getmd, kl.getmdl, and kl.getmdv) and kl.setst (kl.setst and kl.setstq):

kl.getnl Xd, kl.getbl Xd, kl.getbt Xd, kl.getks Xd: these instructions use the kl.getmd* encoding with v = h = 1, r = 0 and rs1 = 1, 2, 3, and 4, respectively; rd holds Xd.
kl.setnl Xs1, kl.setbl Xs1, kl.setbt Xs1, kl.setks Xs1: the kl.setst encoding with G = 0b10, r = 0, F = 0b00, #immed7 = 0, and rd = 1, 2, 3, and 4, respectively; rs1 holds Xs1.
kl.setnli #uimm7, kl.setbli #uimm7, kl.setbti #uimm7, kl.setksi #uimm7: the kl.setst encoding with G = 0b10, r = 0, F = 0b01, rs1 = 0, and rd = 1, 2, 3, and 4, respectively; #immed7 holds #uimm7.

Every other encoding with v = h = 1 in the kl.getmd* encoding, or with G = 0b10 in the kl.setst encoding, is reserved.

Description

kl.getnl, kl.getbl, kl.getbt, and kl.getks write klnamedlocker, kliobuflen, kliobuftop, and klstart, respectively, zero-extended, to Xd.

kl.setnl, kl.setbl, kl.setbt, and kl.setks write X[rs1] to klnamedlocker, kliobuflen, kliobuftop, and klstart, respectively, with the effect of a CSR write.

kl.setnli, kl.setbli, kl.setbti, and kl.setksi write zero-extended #uimm7 to klnamedlocker, kliobuflen, kliobuftop, and klstart, respectively, with the effect of a CSR write.

kl.getnl, kl.setnl, kl.setnli, kl.getks, kl.setks and kl.setksi are part of Zkl common; the ones on kliobuflen and kliobuftop are part of Zklio and reserved (Rule GR1) without it. They are not gated as accesses to the CSRs: the privilege of the CSR is not checked, and software should use them to read or write klnamedlocker, kliobuflen, kliobuftop and klstart. They behave as reads and writes of the CSRs: the CSRs are WARL: a written value above the maximum of the CSR is replaced by that maximum (a reserved value leaves klnamedlocker unchanged), and mklmaxiobuflen ≥ kliobuflen ≥ kliobuftop is enforced (mklmaxiobuflen, kliobuflen, kliobuftop).

They are configuration instructions, not usage instructions: Usage Control does not gate them.

kl.rstrl, kl.rstrh, and kl.rstrv

Synopsis: Restrict the policies encoded in a CC in a locker.
Mnemonics: kl.rstrl  Kd, Xs1
kl.rstrh  Kd, Xs1
kl.rstrv  Kd, Vs1
Encoding: kl.rstr* are R-type instructions that share the opcode and funct3 of kl.exec, with funct2 (the two msbs of funct7) = 0b01.

r names KLNL as Rule GR4 specifies.

With bit v (bit 29) = 0, bit h (bit 28) selects kl.rstrl (h = 0) or kl.rstrh (h = 1), and the input comes from a GPR (a GPR pair on RV32). With v = 1, the instruction is kl.rstrv, h must be 0, and the input comes from the lowest 128 bits of a vector register; v = h = 1 is reserved.

Description

These instructions narrow the policies of the CC in locker Kd, whose MDH is md, as their operand requests: Xs1, or Vs1 for kl.rstrv, formatted as an MDH.

Operand

kl.rstrl takes bits [63:0] of the operand, and may change MachinePolicy;
kl.rstrh takes bits [127:64], supplied in Xs1[63:0], and may change Locality, UsagePolicy and ExpirationDate;
kl.rstrv takes both halves, and applies both sets of rules.

The request rq is the 128-bit MDH image that these halves form; the fields of a half that the instruction does not take are not requested and stay unchanged. In a half that the instruction takes, a non-zero field other than these four transitions the locker to Invalid.

Per-field behavior

Each field of rq narrows the matching field of md (Narrowing of Metadata), except as stated below for Locality. A set MachinePolicy or UsagePolicy bit, or an ExpirationDate later than a non-zero md.ExpirationDate, changes nothing and is not an error. A non-zero Locality subfield of rq that differs from that of md and is not a permitted replacement below transitions the locker to Privilege Violation.

MachinePolicy: no disabled function can be re-enabled, and a request that disables the operation associated with the current State takes effect as Rule GR20 states. A Machine with fields that exist only for some values of MachinePolicy, such as the ECC Machines (Elliptic Curve Cryptography), states what a narrowing does to them.
Locality: each subfield (Table 9), bits [1:0], [3:2], [5:4], 6, 7 and 8, is treated independently. A subfield of rq that is zero or equal to that of md changes nothing, and a zero subfield of md takes the value of rq. A non-zero HW Binding subfield may be replaced only by a stricter entry of its chain: SiPScrt by ChipFamScrt or ChipScrt, ChipFamScrt by ChipScrt, OEMScrt by ProdScrt or DevScrt, and ProdScrt by DevScrt. Any other change, including a weakening or a change of a non-zero Boot Session or SW Filter subfield, transitions the locker to Privilege Violation instead of overriding the field. A later export binds its SCC to the new Locality.

Validity of the result

Validity (Validity of Metadata) is evaluated first, on the changed fields only. A request that would produce an unsupported or invalid value, such as a reserved Locality subfield or a non-zero ExpirationDate without Zklexpire, transitions the locker to Invalid, even if it also asks for a change that gives Privilege Violation, such as a Locality that names an unconfigured entry without a configured substitute. Only a request with valid values can give Privilege Violation. A request that transitions the locker to an Error State changes no other field of md beyond those of Rule GR15.

States

The kl.rstr instructions are not usage instructions (Rule GR17). They act only in a Valid State: on an Unconfigured or Error-State locker they perform no operation (Rule GR13.2), and in a Configuration State Rule GR13.3 applies.

A kl.rstr narrows only the CC in Kd. Copies of the same secret made earlier, such as clones made or SCCs exported before the narrowing, keep their wider policies (The Cryptographic Locker File and Authentication Information).

These instructions let privileged code give different processes customized copies of a CC, bound to per-process Localities or limited to a subset of its functions, such as separate encryption-only and decryption-only copies, which some modes do not keep apart (Accepted Risks). This may avoid repeated expensive round-trips to trusted environments.

kl.clone, kl.rename, and kl.swap

Synopsis

Copy, move or exchange the CCs of lockers.

Mnemonics

kl.{clone, rename, swap} Kd, Ks

Either Kd or Ks, not both, may be KLNL (Rule GR4).

Encoding

These are R-type instructions that share the opcode and funct3 of kl.exec, with funct2 = 0b10.

Field T (bits [28:27]) selects the instruction:

00 encodes kl.clone.
01 encodes kl.rename.
10 encodes kl.swap.
11 encodes kl.derive (kl.derive).

Description

kl.clone

Clones source locker Ks into destination locker Kd, either of which, not both, may be KLNL (Rule GR4):

If source and destination are the same locker, the instruction performs no operation and sets no *llockerstatus or KLS field to Dirty (mllockerstatus, sllockerstatus, and vsllockerstatus for Dirtiness Tracking), even if the locker is Unconfigured, Off, or in a Configuration State; in the last case, Rule GR13.3 does not apply.
If they are different lockers and neither of them is KLNL while klnamedlocker = 32, the instruction first clears the destination, as kl.clear would, even if it then raises an exception (Destructive Configuration Instructions); if klnamedlocker named the destination, it becomes 32. Every *llockerstatus field in effect for the destination and every KLS field in effect are set to Dirty, whatever the outcome. The source then decides the result:
- An Unconfigured source leaves the destination Unconfigured.
- A source in a Configuration State raises a KLE privilege-violation exception (Rule GR13.3).
- A source in an Error State is cloned as its MDH alone (Rule GR15).
- Any other source is copied verbatim, with its internal data, MDH and internal state, unless the available KLF capacity cannot hold the clone, in which case the instruction raises a KLE out-of-memory exception. As the one exception, if the source has an interrupted long-running operation, the copy restarts it (Rule GR38): its progress is zeroed and the values drawn or computed for the operation are discarded, as at an import that completes without Content2. Like the source, the copy stays usable whatever the current Locality Secrets. kl.clone is not a usage instruction, so no UsagePolicy restricts it (Rule GR17).

kl.rename

If Ks and Kd name the same locker, through KLNL too, no operation is performed, even if the locker is Off, and no *llockerstatus or KLS field is set to Dirty. Otherwise the CC of Ks, Configuration State included, becomes the CC of Kd, the previous CC of Kd is discarded, as kl.clear would, Ks becomes Unconfigured, and the *llockerstatus fields in effect for both lockers and the KLS fields in effect are set to Dirty. With an Unconfigured source, kl.rename acts as kl.clear Kd, except that it always sets these fields to Dirty. If klnamedlocker = s, it becomes d; otherwise, if it is d, it becomes 32.

kl.swap

If Ks and Kd name the same locker, through KLNL too, no operation is performed, even if the locker is Off, and no *llockerstatus or KLS field is set to Dirty. Otherwise the CCs of Ks and Kd are exchanged, and if klnamedlocker ∈ {s,d}, it takes the other index. The *llockerstatus fields in effect for both lockers and the KLS fields in effect are set to Dirty.

With klnamedlocker = 32, a kl.clone, kl.rename or kl.swap with a KLNL operand finds no locker and performs no operation, its other locker untouched (Rule GR13.2).

Neither kl.rename nor kl.swap raises a KLE out-of-memory exception or edits the content of any MDH: they move or exchange entire lockers. When Ks and Kd name the same locker, kl.clone, kl.rename and kl.swap still make the checks of Rule GR12, except that of a locker whose *llockerstatus field is Off. mllockerstatus, sllockerstatus, and vsllockerstatus for Dirtiness Tracking and Emulation of Unsupported Machines give the behavior under lazy loading and emulation, when the source or destination locker is Off in some *llockerstatus.

kl.derive

Synopsis

Transfer data from one locker into another without exposing it to software.

Mnemonic

kl.derive Kd, Ks1, Xs2

Either Kd or Ks1, not both, may be KLNL (Rule GR4).

Encoding

kl.derive is an R-type instruction.

The auxiliary input is always a GPR: kl.derive has no form without one, and no vector form.

Description

A kl.derive transfers data from a source endpoint to a destination endpoint; the architecture decides which pairs of endpoints are admitted.

Definition: Source endpoint.: A source endpoint is what a Machine lists as a source for a State in Derivation Endpoints of the Machines: an exportable field, whose availability may depend on StateExtension or on an MDH field that the Machine names, such as OutputType of ECC (MachineUse bits used by the Elliptic Curve Machines); otherwise the kl.exec output, the data that a Form C kl.exec permitted in that State would emit. A field configured by a SKID is never exportable (Rule GR55.1).
Definition: Destination endpoint.: A destination endpoint is what a Machine lists as a destination for a State in Derivation Endpoints of the Machines: an importable field that an admitted pair names; or the kl.exec input, the data that a Form B kl.exec of that State would absorb. It fixes the minimum, upper limit and granularity of the transfer. A key field is a destination only in Ready or in a State that the Machine names for loading it, such as Set_Key of HMAC (HMAC), and never when KeyType is 1 (Rule GR55.1).
Definition: Admitted pairs.: An admitted pair consists of a source and a destination endpoint; the MDH of each locker, not an operand of kl.derive, determines its endpoint. Rules GR31.1 and GR31.2 admit two families of pairs, Rule GR31.3 narrows them for a sealed source, and these Rules state for each whether the transfer is restricted or unrestricted (Table 15). Any other pair is not admitted (Rule GR31). An admitted pair fixes the semantics of the transfer and its updates to the two States and to klstart (Rules GR28–GR31.3); kl.derive changes no other state of the hart (Table 13).

Let length be the value provided by the auxiliary GPR, and eff_length the number of bytes transferred (Rule GR28): min(length, dest_length) for a destination field of dest_length bytes, and length otherwise. kl.derive moves eff_length bytes from an endpoint of the source locker to an endpoint of the destination locker without exposing them to software: the output of one Machine becomes an input of another, possibly into a key field or a kl.exec input, as the admitted pairs allow. Xs2 = X0 gives length = 0, and Rule GR29 gives the outcome when length is zero or short.

A transfer is unrestricted only where software could also obtain the moved data by issuing kl.exec instructions, as for the kl.exec outputs of Rule GR31.2 and a shared secret that its Machine allows to export through kl.exec; otherwise it is restricted, as for any other shared secret (Rule GR31.1) and for a sealed source (Rule GR31.3).

Source and destination must be different lockers, else an illegal-instruction exception is raised. Both lockers are checked before any state change or transfer: first under Rule GR27, then under Rules GR29 and GR30.

KLE Memory Instructions

The checks of the KLE memory instructions and their behavior in the memory model are defined in Memory Instructions and Memory Model.

kl.load and kl.input

Mnemonics: kl.load %offset(Xs), Xl
kl.input %offset(Xs), Xl
kl.input is an alias for kl.load, for source code in which klnamedlocker is known to be 32.
Encoding

kl.load/kl.input is an I-type instruction. %offset is immed12, sign-extended to XLEN bits.

Description

The locker is not an operand: with klnamedlocker < 32, kl.load copies data into the locker that klnamedlocker names; with klnamedlocker = 32, into the KLIOBUF.

For klnamedlocker < 32: kl.load imports the Content of a PI or an SCC into the locker, but not its MDH, which kl.mgmt carries. A non-zero Xl raises an illegal-instruction exception; otherwise, kl.load makes the checks of kl.mvin (Rule GR24).

For each j in [klstart, image_end-1], kl.load loads the byte at memory address (Xs + %offset + j) mod 2^XLEN into byte j of the serialized image S of the locker’s Content, in 16-byte blocks from a 16-byte aligned address (Rule GR12). klstart tracks the prefix-complete number of bytes loaded; if klstart ≥ image_end, nothing is transferred.

With a system-specific format, kl.load transfers the data that follows the MDH unchanged, as the serialized image S (Rules for the Import of a System-Specific Format).
For klnamedlocker = 32: With Xl = 0, kl.load and kl.store designate no locker and fall through (Rule GR12, item 5). With Xl ≠ 0, as kl.input and kl.output, they require Zklio and a configured KLIOBUF (Third Group of Illegal-Instruction Exception Grounds) and transfer the bytes of the KLIOBUF transfer window.
Definition: KLIOBUF transfer window.: Let n = min(Xl, kliobuftop). The KLIOBUF transfer window of kl.input and kl.output consists of the offsets j with klstart ≤ j < n. For each j in the window, kl.input copies the byte at address (Xs + %offset + j) mod 2^XLEN to KLIOBUF byte j, and kl.output copies KLIOBUF byte j to that address. No other byte is accessed, in memory or in the KLIOBUF; in particular, bytes from kliobuftop on are never transferred, whatever Xl. If klstart ≥ n, the window is empty: the checks of Rule GR11 are still made, then nothing is transferred and klstart is set to 0.

kl.store and kl.output

Mnemonics

kl.store %offset(Xs), Xl
kl.output %offset(Xs), Xl
kl.output is an alias for kl.store, for source code in which klnamedlocker is known to be 32.

Encoding

kl.store/kl.output is an S-type instruction. %offset is immed[11:5] @ immed[4:0], sign-extended to XLEN bits.

Description

The locker is not an operand: with klnamedlocker < 32, kl.store copies data out of the locker that klnamedlocker names; with klnamedlocker = 32, out of the KLIOBUF.

For klnamedlocker < 32: kl.store exports the serialized image S of the locker to memory, but not its MDH, which kl.getmd* extracts. A non-zero Xl raises an illegal-instruction exception; otherwise, kl.store makes the checks of kl.mvout (Rule GR24).

For each j in [klstart, image_size-1], kl.store stores byte j of S at memory address (Xs + %offset + j) mod 2^XLEN, in 16-byte blocks to a 16-byte aligned address (Rule GR12); the bytes from image_end on are stored as zero. klstart tracks the prefix-complete number of bytes stored; if klstart ≥ image_size, nothing is transferred. Software does not use kl.store on an Error-State locker (Export and Import of a Locker in an Error State).
For klnamedlocker = 32: kl.output is described with kl.input (kl.load and kl.input): it copies the bytes of the KLIOBUF transfer window from the KLIOBUF to memory.

Rules

This section collects the Rules that govern the behavior of the KLE ISA. Many of them deal only with classes of States, namely Unconfigured, Valid, Error, Configuration, Complete and Inert, and of instructions, namely Usage, Memory and Configuration; Configuration instructions are further inspection, destructive, transfer and narrowing ones. Other Rules are instruction-specific. A Rule GRn.m belongs to the group that Rule GRn opens, and details its principle.

Table 11 names the properties that the Rules establish together. It is informative: the Rules govern.

Table 11. Invariants that the Rules establish (informative)
	Invariant	Rules
I1	Secrets flow downhill (P1, P16): a secret leaves a locker only inside an SCC, as a `kl.exec` output that its Machine defines, or by a `kl.derive` into a locker whose policies are at least as strict.	GR8–GR9, GR27–GR31.3, GR46–GR51, GR54–GR55.3
I2	Exceptions are precise: an exception has no effect beyond those that Rule GR16 lists.	GR16, GR28, GR32, GR45
I3	Errors live in the locker: an instruction that enters an Error State retires, keeps the committed prefix, zeroes the unwritten output and clears the Content.	GR14, GR15
I4	Inert lockers are no-ops: an instruction on an inert locker falls through, except in the cases that Rule GR13.2 lists.	GR14, GR13.2
I5	Progress is prefix-complete (P3): an interrupted instruction commits a prefix of its transfer, which `klstart` records, and resumes from it.	GR7, GR18, GR32–GR34
I6	Management is always available (P6, P13): every State admits the instructions that inspect, clear or reconfigure a locker, and every Valid, Error or Configuration State admits an export.	GR13.1, GR13.3
I7	Asynchrony is invisible to program order: a handler observes a KLE instruction as completed or precisely halted.	GR34, GR35, GR39–GR42

Content Confidentiality

GR8

No extraction (P1, P16). Once the provisioning, or the base import of a system-specific format (Rules for the Import of a System-Specific Format), that binds a key to its Metadata completes, no instruction returns in clear the value of the key, or of any other secret field of the Content, except as an output defined by the Machine for kl.exec (Rule GR31.2); the clear blocks of an SCC hold no secret field (Rule GR9).

GR9

Clear blocks: An SCC carries the first SCC_ClearLen1 128-bit blocks of Content1, and the first SCC_ClearLen2 blocks of Content2, in clear: they are authenticated with their segment, as associated data, but not encrypted (Generation of an SCC from a Fully Configured Locker).

SCC_ClearLen1 is the number of whole blocks that the public fields of the Machine fill, which its Serialized Content places first, together with any padding that it places after them; it is 0 for a Machine that designates no public field. Which fields are public depends only on the Machine, MachineExtension and KeyType of the MDH, and their number of blocks also on the MachinePolicy, which determines the fields present (Length of External Formats and KLF Capacity Usage of a Locker). A public field holds, in every State and at every point of an operation, only a value that the cryptographic role of the field makes public, such as a public key, a ciphertext or a signature, or zero; it never holds a key, a SKID, a value derived from a secret field other than such a public value, or an intermediate value of an operation (Rule GR37) other than a part of its public result, and it is never a kl.derive destination.
SCC_ClearLen2 is implementation-defined and documented, at most AuxDataLen − 2, and depends only on IMPQUAL and on the fields of the MDH other than ADSDropped; the clear blocks of Content2 hold only values computable from the public fields and from constants of the Machine.
No value of a clear block is used before its segment is authenticated (Decryption and Authentication of a Complete SCC into a Locker); a failed authentication zeroes or drops the whole segment, its clear blocks included.

Zklio

With Zklio, the KLIOBUF can replace the vector operands of kl.exec, so that code runs on cores without vector registers; kl.setst and kl.mgmt use Form D instead of Form C.

GR10

With Zklio, every Form of kl.exec that reads inputs from or writes outputs to vector registers, the native Form in its Machine and State, admits a substitution: a Form D kl.exec, using the KLIOBUF in their place, however the Machine describes the use of the native Form. Rules GR10.1 and GR10.2 state its operands and its failures.

GR10.1	Operands. Where a Form A or B `kl.exec` expects a vector input, its substitution takes the input from [`klstart`, `kliobuftop`-1] instead of a vector register, and where a Form A or C `kl.exec` expects a vector output, its substitution writes it to [`klstart`, `kliobuftop`-1] (Rule MR9), a Form A substitution writing each block’s output over its input.
GR10.2	Failures. For a substitution of `kl.exec` (Rule GR10) that is not a wrong Form (Rule GR19.1), a non-zero `kliobuflen` with a `kliobuftop` invalid for the Machine transitions the locker to Error State Invalid, whether the KLIOBUF is used as input or only as output (Rule GR18).

GR11

These instructions access the KLIOBUF and require it to be configured, with a non-zero kliobuflen, even for an empty transfer window:

a kl.load or kl.store issued with klnamedlocker = 32 and Xl ≠ 0 (kl.input, kl.output), which names no locker and never falls through;
the KLIOBUF variants of kl.mvin and kl.mvout; and
a substitution that is not a wrong Form (Rule GR19.1).

Without Zklio, the KLIOBUF is never configured. An unconfigured KLIOBUF is a ground of the Third Group of Illegal-Instruction Exception Grounds for kl.input and kl.output, and of the Fourth Group of Illegal-Instruction Exception Grounds for the others.

Checks and Outcomes

GR12

The locker-state-independent checks come first, in this order; the first that fails decides the outcome:

the First Group of Illegal-Instruction Exception Grounds: illegal-instruction exception, or virtual-instruction exception where the group states it;
a pending fatal condition: KLE fatal-error exception;
the Second Group of Illegal-Instruction Exception Grounds: illegal-instruction exception;
no active CSK: KLE missing-CSK exception (Architectural Requirements on the Context Sealing Key);
the klnamedlocker check: KLNL, kl.mvin, kl.mvout, and kl.load and kl.store other than kl.input and kl.output, designate the locker that klnamedlocker names (Rule GR4); if it is 32, they designate none, item 6 is skipped, and the instruction falls through after item 8 (Rule GR13.2);
an access to a locker whose *llockerstatus field in effect is Off, except as KLE locker-Off in Exceptions states: KLE locker-Off exception;
the Third Group of Illegal-Instruction Exception Grounds: illegal-instruction exception;
for a kl.load or kl.store that designates a locker: the address breakpoint of the first component access, then a load, resp. store, address-misaligned exception if the effective address is not 16-byte aligned (Rule GR41).

GR13

Admission by State class. After the locker-state-independent checks (Rule GR12) come the locker-state-dependent checks, which include the Fourth Group of Illegal-Instruction Exception Grounds: the class of the locker’s State decides which instructions are admitted and what the others do, as Rules GR13.1–GR13.5 state. An admitted instruction then has an outcome of Rule GR14.

GR13.1	Every State. The instructions that Table 13 marks as admitted in every State are admitted whatever the State of the locker, and no Machine may restrict them; on an inert locker they act as Rule GR13.2 states.
GR13.2	Inert locker. An instruction on an inert locker falls through (Rule GR14), with the results of Table 14, except: a destructive configuration instruction or a `kl.setste` on an Unconfigured or Error-State locker acts as on any locker: the first raises an exception only after its destructive step (Rule GR16), the second none (Rule GR26); on a `KLNL` that names no locker, both fall through; a `kl.clone`, `kl.rename` or `kl.swap` acts as kl.clone, kl.rename, and kl.swap states whichever of its lockers is inert, and falls through if either is a `KLNL` that names no locker; a `kl.derive` falls through only if either operand is a `KLNL` that names no locker, if its source is inert, or if its source is in a Valid State and its destination is inert; otherwise it is checked as Rule GR27 states.
GR13.3	Configuration State. Besides the instructions of Rule GR13.1, a Configuration State admits an export-opening `kl.mgmt`, which opens a nested export, and the management transfers and completing `kl.mgmt` of the operation under way (Rule GR24, Locker Management Operations). Any other instruction traps and leaves the State unchanged: illegal-instruction exception: a management transfer of the other direction, or a completing `kl.mgmt` with an inconsistent `ml`.State; KLE privilege-violation exception: a usage instruction, a `kl.clone` from the locker into another one, or a `kl.rstr*` on it.
GR13.4	Valid State, configuration instruction. No management operation is under way in a Valid State, so a management transfer or a completing `kl.mgmt` raises an illegal-instruction exception (Rule GR24). Every other configuration instruction is admitted, a `kl.rstr*` with the effect of Rule GR20.
GR13.5	Valid State, usage instruction. The instruction checks these conditions in order; the first that applies decides the outcome: a substitution (Rule GR10) with an unconfigured KLIOBUF: illegal-instruction exception (Rule GR11); a UsagePolicy that forbids the instruction: KLE privilege-violation exception (Rule GR17); a non-zero ExpirationDate (ExpirationDate Field): an unreadable secure clock raises a KLE clock-unavailable exception, leaving the State unchanged, and a passed date transitions the locker that carries it to Error State Expired; an instruction that the Machine, the State or MachinePolicy does not admit, a wrong Form included: no operation, no exception, Error State Invalid (Rule GR19, MR1); otherwise, a `kl.exec` makes the checks of Rule GR18, then those of its Machine (Rules MR6, MR10), and a `kl.derive` those of Rules GR29 and GR30, the source before the destination (Rule GR27), before performing the operation; any other instruction performs its operation.

GR14

The checks lead to one of the outcomes of Table 12. An instruction that falls through performs no operation and raises no exception, makes no check beyond those of Rule GR12, and reads no operand other than its locker designators and those that these checks inspect: it accesses no memory, and needs neither a configured KLIOBUF nor Zklio.

Table 12. Outcomes of the checks
Outcome	Locker and other KLE state	Output window¹	`klstart`²
Operation	As the instruction states	Written	0
Exception	Unchanged, except as Rule GR16 states	Unchanged	Unchanged, except as Rule GR16 states
Fall through	Unchanged, except `klnamedlocker` as Rule GR21 states	Zeros	0
Error State	The Error State, the Content cleared (Rule GR15)	Zeros	0
Empty window (Rule GR18, item 1)	Unchanged	Unchanged	0
¹ The part of the output window that the instruction has not written; only `kl.exec` and `kl.mvout` have one. For `kl.exec`: elements [`vstart`, `vl`-1] of `Vd`, or bytes [`klstart`, `kliobuftop`-1] of the KLIOBUF, which a Form D `kl.exec` that falls through, or that item 4 of Rule GR13.5 transitions to Invalid, takes as its window whatever its native Form, with no length or granularity check. For `kl.mvout`: its destination GPRs; elements [`vstart`, `vl`-1] of its vector destination, the tail following the tail-agnostic policy; or bytes [0, `kliobuftop`-1] of the KLIOBUF. Elements below `vstart` are unchanged, and an unconfigured KLIOBUF is not accessed. ² For an instruction that honors `klstart` (klstart), except `kl.mvin` and `kl.mvout`, which keep it; a precise halt sets it as Rule GR33 states. `kl.clearall`, and a `kl.mgmt` that passes items 1–6 of Rule GR12, also write 0 to it; any other instruction leaves it unchanged.

GR15

An instruction that transitions a locker to an Error State retires: the prefix that it has committed stays committed, and the unwritten part of its output window, if it has one, is zeroed (Table 12). The locker clears its Content beyond the MDH and releases the internal resources that held it, any ADS included; AuxDataLen and ADSDropped are set to 0, a Version of 3 to 0 (Rules for the Import of a System-Specific Format), and a KeyType of 2 to 0. Every implementation-defined field or subfield (MachineUse and AuxInfo Fields) is set to 0.

GR16

A KLE fatal-error exception resets the KLE state (KLE fatal-error in Exception causes in decreasing priority order). Any other exception leaves the KLE state unchanged, except for these changes, made even when the instruction then raises an exception:

the destructive step (Destructive Configuration Instructions) of a provisioning- or import-opening kl.mgmt, which zeroizes the locker and sets klnamedlocker (Rule GR21), and of a kl.clone, which clears its destination as kl.clear would, with the same effect on klnamedlocker (kl.clone, kl.rename, and kl.swap) and on the *llockerstatus and KLS fields it sets to Dirty;
the zeroization of SIV, IMPQUAL and SIV2 by an import-opening kl.mgmt (Provisioning- and Import-Opening kl.mgmt);
the clearing of klstart by any kl.mgmt that passes items 1–6 of the locker-state-independent checks (Locker Management Operations); and
the completed prefix, and the klstart that records it, that a memory instruction commits when one of its component accesses raises a memory exception (Rules GR41 and GR34).

For a resumed instruction, “unchanged” refers to the state when it is issued again, not at the halt; the prefix committed by earlier attempts is part of that state and is not undone.

Rules Governing Valid States

GR17

Table 13 states, for every instruction, whether it is a usage instruction, and so subject to the UsagePolicy (UsagePolicy Field), which state it may modify, and whether it is admitted whatever the State of the locker it accesses. An instruction that the UsagePolicy forbids raises a KLE privilege-violation exception, at the point of the check order stated by Rule GR13.5.

Table 13. State modification and usage control, per instruction
Instructions	May modify KLE state	May modify other state	Usage instruction	Admitted in every State	Notes
`kl.size`, `kl.avail`	No	Yes	No	Yes
`kl.exec`	Yes	Yes	Yes	No
`kl.mvin`, `kl.mvout`	Yes	Yes	No^*	No	The direction determines which state changes. Both advance `klstart` by the bytes transferred.
`kl.setst`	Yes	Yes, vector forms reset `vstart` on retirement	Yes, see note	No	Not a usage instruction with the immediates `kl_state_inert` (`kl.clear`) and `kl_cfg_clearall` (`kl.clearall`).
`kl.setste`	Yes	No	No	Yes
`kl.clear`	Yes	Yes, vector Forms reset `vstart` on retirement	No	Yes	Encoding of `kl.setst`; see its row.
`kl.clearall`	Yes	No	No	Yes	Encoding of `kl.setst`; see its row.
`kl.clearads`	Yes	No	Yes	No	Encoding of `kl.setst`; see its row.
`kl.mgmt`	Yes	Yes (see note)	No	Provisioning and import opening	Vector forms reset `vstart` on retirement. A provisioning- or import-opening `kl.mgmt` is admitted in every State, an export-opening one in every Valid, Error or Configuration State; no Machine may restrict an export-opening one either.
`kl.getmd`, `kl.getmdl`, `kl.getmdv`, `kl.getst`, `kl.getstx`	No	Yes	No	Yes
`kl.getnl`, `kl.getbl`, `kl.getbt`, `kl.getks`	No	Yes	No	N/A	Read the CSR they name.
`kl.setnl`, `kl.setnli`, `kl.setbl`, `kl.setbli`, `kl.setbt`, `kl.setbti`, `kl.setks`, `kl.setksi`	Yes	No	No	N/A	Write only the CSR they name, with the effect of a CSR write.
`kl.rstrl`, `kl.rstrh`, `kl.rstrv`	Yes	Yes (see note)	No	No	`kl.rstrv` resets `vstart` on retirement.
`kl.clone`	Yes	No	No	Yes, see note	Except from a source in a Configuration State (Rule GR13.3).
`kl.rename`, `kl.swap`	Yes	No	No	Yes
`kl.derive`	Yes	No	Yes	No	The UsagePolicy fields of the source and destination lockers are evaluated separately for the source and the destination (Rule GR27).
`kl.load`	Yes	No	No^*	No	Updates `klstart` and locker.
`kl.store`	Yes	Yes	No^*	No	Modifies `klstart` and memory, but no locker.
`kl.input`	Yes	No	No	N/A	Modifies the KLIOBUF and `klstart`, but no locker.
`kl.output`	Yes	Yes	No	N/A	Modifies `klstart` and memory, but no locker.
^* Usable only in the States admitted by Rule GR24; on an Unconfigured or Error-State locker they perform no operation (Rule GR13.2). "Admitted in every State": Rule GR13.1 applies; no Machine may restrict the instruction. N/A: the instruction accesses no locker.

GR18

A Form A–C kl.exec, or a Form D kl.exec that substitutes for one (Zklio), checks its transfer window after the conditions of Rule GR13.5, in this order:

A klstart ≥ the length, which includes a length of 0, makes the window empty: the instruction writes 0 to klstart and does not reach the Machine, which keeps its State.
Otherwise, a length invalid for the Machine transitions the locker to Error State Invalid.
Any other klstart that is not an interruption point (Rule GR33.2) transitions the locker to Error State Invalid.

GR19

Admission by the Machine. In a Valid State, the Machine decides which usage instructions and Forms it admits, and what each does; an instruction that it does not admit performs no operation and transitions the locker to Error State Invalid (Rule GR13.5, item 4). Rules GR19.1–GR19.5, Rule GR38 and Rule MR1 constrain that choice.

GR19.1	Wrong Form. A wrong Form of a usage instruction is a Form that is none of: a native Form of the instruction expected in the locker’s State (for `kl.setst`, as determined by its immediate); a Form that kl.setst and kl.setstq admits in place of a native Form of `kl.setst`; with `Zklio`, the substitution of that native Form (Rule GR10).
GR19.2	Not admitted by default. Unless the Machine allows it and defines what it does, a Valid State does not admit: a `kl.exec` in Ready; a `kl.setst` naming the current State, except in Ready (Rule GR19.3) and in a State that loads a field, where it restarts the load (Rule MR14).
GR19.3	Always admitted. A `kl.setst` naming Ready and `kl.clearads` (kl.clearads) are admitted in every Valid State, whatever the MachinePolicy of the locker, subject to items 1–3 of Rule GR13.5; a wrong Form of either is not admitted (Rule GR19.1). In States Success and Failure, they are the only usage instructions admitted. Unless the Machine defines another Form for it, a `kl.setst` naming Ready is of Form A.
GR19.4	Immediates of `kl.setst`. A `kl.setst` whose `#immed7` neither the architecture nor the Machine admits in the current State transitions a locker in a Valid State to Error State Invalid.
GR19.5	Success and Failure. No State admits a `kl.setst` that names Success or Failure (`#immed7` 54 or 55). Only a Machine may enter these States, as the outcome of an operation that it performs, such as a verification within a `kl.setst` that names another State (Rule MR18).

GR20

A kl.rstrl or kl.rstrv (kl.rstrl, kl.rstrh, and kl.rstrv) that narrows MachinePolicy to a value that the Machine forbids transitions the locker to Error State Invalid. Any other narrowing changes no State; from the next instruction on, Rule MR1 checks each kl.exec, kl.derive and usage kl.setst against the narrowed MachinePolicy, at issue and on entering a State.

Rules Governing the Named Locker

GR21

Besides writes by software, through the CSR or kl.setnl and kl.setnli (CSR Getters and Setters: kl.get*, kl.set*, and kl.set*i), only these instructions affect klnamedlocker:

a kl.mgmt that names a locker and raises no exception sets it to the number of that locker, opening, completing or falling through on an inert locker (an Unconfigured or Error-State one) alike; a kl.mgmt that reaches the destructive step of a provisioning or import opening does the same, even if it then raises an exception (Rule GR16); a kl.mgmt that raises an exception otherwise leaves it unchanged; a kl.mgmt issued with KLNL while klnamedlocker is 32 falls through and leaves it 32 (Rule GR13.2);
a destructive configuration instruction except kl.mgmt and kl.swap that clears or overwrites the named locker as its destination, whether it names it by number or as KLNL and whatever its State, sets klnamedlocker to 32, even if it then raises an exception, as a reconfiguration of that locker would, and kl.clearall sets it to 32;
a kl.rename or kl.swap that moves the CC of the named locker sets it to the receiving locker’s number (kl.clone, kl.rename, and kl.swap).

Rules Governing the State and StateExtension Fields and their Transitions

State encodes up to 55 Valid States: Ready, Success, Failure and up to 52 States defined by the Machine.

Figure 1 (State and StateExtension Fields) shows the default state transitions that apply to all Machines.

The following rules apply to all Machines:

GR22

When the CC is in Ready, Success, Failure or an Error State, the State field of the MDH holds that State, and StateExtension too for an Error State, so that they identify it without inspecting other fields or the Content.

GR23

A transition allowed by a Machine is triggered by an explicit kl.setst or under conditions stated by the Machine’s specification. The State reached need not be the one that a kl.setst names: besides Error State transitions, an operation may determine the next State, as a verification determines Success or Failure. Transitions to and between Configuration States use kl.mgmt, kl.rename or kl.swap.

Rules Governing Configuration States

GR24

The management transfers into the locker, kl.load and kl.mvin, are admitted in States kl_cfg_provisioning, kl_cfg_importing and kl_cfg_ppi_importing; those out of it, kl.store and kl.mvout, in States kl_cfg_exporting and kl_cfg_ppi_exporting. They require a klstart that is a multiple of 16 and, for a KLIOBUF variant of kl.mvin or kl.mvout, a configured KLIOBUF; otherwise they raise an illegal-instruction exception (Fourth Group of Illegal-Instruction Exception Grounds). The images that these instructions transfer are described in Management of Cryptographic Contexts.

GR25

The completing kl.mgmt (Locker Management Operations), issued with the saved ml as an argument, leaves the locker:

after a provisioning, or after the base import of a system-specific format, whose ml.State is 0 (Rule GR51), in State Ready, with MachineUse zero, and StateExtension zero except for the flags that the system-specific import sets;
after any other import, or after an export, in the State supplied in ml, which is a Configuration State after a nested operation: for an import, the State that the locker had when it was exported, restored with the StateExtension the locker had then, carried in the SCC; for an export, the State that the locker had when the export was opened; or
in an Error State, or in Failure, if a check made at completion fails: Authentication Failed for the SIV check, and otherwise the outcome that the failing check prescribes.

Rules Governing Inert Lockers

Recall from Definition: Inert Locker. that an inert locker is an Unconfigured locker, a locker in an Error State, or KLNL while klnamedlocker = 32. Rule GR13.2 states what instructions do on an inert locker, and Table 14 the results of those that fall through.

Table 14. Results of instructions on an inert locker
Instruction	Error State	Unconfigured locker	`KLNL` & `klnamedlocker` = 32
kl.size Form A	Writes 16 to `Xd`.	Writes 0 to `Xd`.
kl.avail Form A	Writes to `Xd` 1 if the MDH fields that identify the Machine name an implemented combination, and 0 otherwise.	Writes 0 to `Xd`.
kl.getmd* and kl.getst	Writes the MDH, resp. its State or StateExtension field.	Writes zeros to the destination.
kl.clear †	Clears the locker; the `llockerstatus` and `KLS` fields in effect become Dirty*.	Writes nothing to the locker; every `llockerstatus` field in effect becomes Dirty* if any of them was Off, and every `KLS` field in effect if one was Off or `klnamedlocker` changes.	Writes nothing.
† `kl.clear` updates `klnamedlocker` as Rule GR21 states.

GR26

A kl.setste (kl.setste), a configuration instruction, transitions a locker in any State, Unconfigured included, to the Error State that it names after the locker-state-independent checks of Rule GR12, raising no exception even where reaching that State implicitly would raise one. A locker in an Error State is exported without kl.mgmt as its 16-byte MDH alone, all fields included (kl.avail and kl.size), and a single kl.mgmt re-imports the image (Export and Import of a Locker in an Error State).

Rules GR12 and GR13.2 close a check-then-use race: between a State/StateExtension check and the next instruction, a handler may clear a locker being provisioned or imported, which sets klnamedlocker to 32 and forces a restart (Management of Cryptographic Contexts), or set an Error State. The instructions that follow then perform no operation, a KLNL opening with klnamedlocker = 32 included, instead of acting on the KLIOBUF or trapping, and do not change State or StateExtension. Only the check after the last instruction is required; earlier checks only react sooner.

Derivation Rules

The Rules of this section apply to kl.derive.

GR27

Each condition of Rule GR13.5, starting with the State class (Rule GR13), is checked first on the source of a kl.derive and then on its destination, before the next condition. A condition that applies to both lockers takes effect on both; one that applies to the source only leaves the destination unchanged.

GR28

Transfer size and progress: A destination field of dest_length bytes receives eff_length = min(length, dest_length) bytes and is zero-filled beyond them; any other destination receives eff_length = length bytes. Each endpoint advances as the kl.exec instructions producing or consuming the bytes would, except a field source, which is read from its first byte: byte i of the transfer is byte i of the field, and zero in the unused part of a final partial output unit. A field is the source of one kl.derive at most: with the first committed unit, its locker leaves the State in which the field is a source, as its Machine states, so that a later kl.derive fails Rule GR29 item 2.

Every check that can raise an exception precedes the first unit. If a field fails a check when its transfer completes (Rule MR3), its locker takes the outcome that its Machine specifies, or else Invalid, and the instruction retires; the source keeps the effects of the units already transferred.

GR29

After the checks of Rule GR13.5, the following checks are made in order; a failed check transitions the locker named to Error State Invalid (Rule GR15), and nothing more is transferred:

klstart must be 0; otherwise the destination transitions.
The source must be a source endpoint; otherwise the source transitions.
The destination must be a destination endpoint; otherwise the destination transitions.
The pair must be admitted; otherwise both transition.
The effective length (Rule GR28) must meet the length constraints of the destination, a final partial input unit included, and the eff_length bytes must fit its remaining capacity; otherwise the destination transitions.
A destination that receives a whole value has the following length conditions; otherwise the destination transitions:
- A destination key field of dest_length bytes is loaded in full: it requires length ≥ dest_length and a source field, or remaining kl.exec output, of at least dest_length bytes, unless its Machine admits a shorter key under conditions that it states, as HMAC does; a key field that receives a shared secret (Rule GR31.1) is never zero-padded by it, except a key field whose Machine states its own padding, as the K0 of HMAC does (cite:[nist-fips-198-1] §4, Step 3); any other such field receives the first dest_length bytes of a secret of at least dest_length bytes. The eff_length bytes it receives (Rule GR28) replace whatever a kl.exec loaded into it and complete its loading; a key written in State Ready is followed by the initialization that the Machine performs in that State.
- A message input receiving a shared secret (Rule GR31.1) requires a length equal to the length of the secret.
The source must be able to supply the eff_length bytes, a final partial output unit included (Rule GR28), and eff_length must be at least 16 for a sealed source (Rule GR31.3); otherwise the source transitions.

Apart from their failure outcomes, these checks change nothing; the checks on the transferred values are made per unit (Rule GR28).

GR30

Before a nonempty restricted transfer that Rule GR29 admits begins, the destination transitions to Error State Privilege Violation, and nothing is transferred, if its SCProtection is lower than that of the source, or if the narrowing of its MDH by that of the source (Narrowing of Metadata) fails. Otherwise the narrowed policies govern the transfer, but are written only with its first committed unit (Rule GR28).

GR31

Admitted pairs. A kl.derive makes either a restricted transfer, which narrows the destination by the source (Rule GR30), or an unrestricted transfer, which applies no policy narrowing. Rules GR31.1–GR31.3 state the admitted pairs, which Table 15 summarizes; no other pair is admitted. They make a transfer unrestricted only where kl.exec instructions could already reveal the moved data to software.

GR31.1	Shared secret. A shared secret of a key-agreement or key-encapsulation Machine moves into a key field of a symmetric Machine that Derivation Endpoints of the Machines lists as a destination for it, or into the `kl.exec` input of a hash function, MAC or XOF that Derivation Endpoints of the Machines lists for it. If its Machine explicitly allows it to export through `kl.exec`, it moves as an unrestricted transfer of its field. Otherwise, as the ML-KEM `sharedkey`, it moves only as a restricted transfer and only to these destinations: no other message input receives it, not even one that a Machine defines. A shared secret of a sealed variant is moreover a sealed source (Rule GR31.3).
GR31.2	`kl.exec` output. The `kl.exec` output of a Machine that Derivation Endpoints of the Machines lists as a source can be moved, as an unrestricted transfer, into a key field of a symmetric Machine that Derivation Endpoints of the Machines lists as a destination. The output of a sealed locker is instead a sealed source (Rule GR31.3). No other `kl.exec` output is a source.
GR31.3	Sealed source. A sealed source is the shared secret of the sealed variant of an Elliptic Curve or ML-KEM Machine (Elliptic Curve Cryptography, ML-KEM), or the output in Hash_Output of a sealed locker: a hash function, MAC or XOF locker whose message input or key a sealed source has entered, and which therefore emits no output through `kl.exec` and verifies no tag (Hash and MAC Functions, and XOFs, HMAC). A transfer from a sealed source is a restricted transfer (Rule GR30) of at least 16 bytes (Rule GR29 item 7). Its admitted pairs are those that Rule GR31.1 admits for a shared secret, resp. Rule GR31.2 for the output of a locker that is not sealed, except those whose destination is the key of keystream generation, OFB or CMAC, or `K1 ‖ K2` of nonce masking (Derivation Endpoints of the Machines). A message input or an HMAC `K0` that receives it makes its locker sealed, so that every source that holds sealed material is itself sealed.

Table 15. Admitted pairs of `kl.derive`, summarizing Rules GR31.1–GR31.3 (informative)
Source	Transfer	Destinations, as Derivation Endpoints of the Machines lists them
A shared secret that its Machine allows to export through `kl.exec`	Unrestricted	A key field of a symmetric Machine, or the `kl.exec` input of a hash function, MAC or XOF
Any other shared secret, such as the ML-KEM `sharedkey`	Restricted
The `kl.exec` output of a source Machine	Unrestricted	A key field of a symmetric Machine
A sealed source: the shared secret of a sealed variant, or the Hash_Output of a sealed locker	Restricted, of at least 16 bytes	Those of the same source unsealed, except the key of keystream generation, OFB or CMAC, and `K1 ‖ K2` of nonce masking

Interruptibility and Resumability of KLE Instructions

GR32

The architecturally resumable instructions are:

kl.exec, which halts only at an interruption point of its Machine and State (Rule GR33.2);
the vector kl.mvin and kl.mvout, which transfer several 128-bit blocks and halt only at a block boundary; and
kl.load, kl.store, kl.input and kl.output, which commit their 16-byte blocks of S (kl.load, kl.store) or their bytes (kl.input, kl.output) as a prefix in offset order (Rule GR33.1), whatever the order of their component accesses (Rule GR41).

Every other KLE instruction is uninterruptible: it completes, raises an exception with only the effects of Rule GR16, or has no architecturally visible effect, except that a long-running operation (Long-Running Operation) halts as Rule GR36 states; an implementation achieves this with option 1, 2 or 5 of Rule GR34, option 1 subject to Rule GR35. A kl.derive is never long-running and requires klstart = 0 (Rule GR29).

GR33

Precise halt. On a precise halt of a resumable instruction (Rule GR32), the completed prefix is committed at both endpoints of the transfer, klstart records its byte count or, for kl.mvin and kl.mvout, the image offset that kl.mvin and kl.mvout specifies, and the instruction does not retire, xepc holding its address. The failing and subsequent units have no effect, except as Rule GR33.1 permits for a memory instruction. A synchronous exception raised by a component access halts the instruction precisely, with klstart at the last prefix-complete point, among those that the instruction permits, before the faulting byte (RVV 1.0 §3.7). Rules GR33.1–GR33.3 define the points at which it may halt and the state that it leaves.

GR33.1	Prefix-complete point. On a precise halt, `klstart` records a prefix-complete point of the transfer, that is, an offset below which every component access has been performed. For `kl.load` and `kl.store`, the prefix-complete points are the multiples of 16. A component access at or beyond it may already have had an architecturally visible effect; re-executing the instruction from that point produces the correct final state. The recorded point never moves back over a prefix committed in this or an earlier attempt.
GR33.2	Interruption point. An interruption point of a KLE instruction in a State of a Machine is a `klstart` value at which the instruction may halt precisely: a multiple of the Machine’s granularity within the transfer window, unless the Machine, or a macro such as `PROCESS_VLI` (Macro: Processing Variable Length Inputs into a Fixed Length Output), defines another set. For a `kl.exec` with a vector operand it is also a multiple of `SEW`/8; if no non-zero point of the set is, the only interruption point is 0.
GR33.3	Halted state. The state that a halted instruction leaves is described entirely by: the locker, `klstart`, `vstart` and the committed output prefix (Rule GR33); the identity of the halted instruction, held in the hart state that software saves and restores, not in the KLE (Rule GR37); for a Long-Running Operation, the progress field P (Rule GR37) and the ADS; and under option 5 of Rule GR34, the restart count.

GR34

When a handler accesses an input, output or locker of a preempted instruction, or other KLE state the instruction may affect, the implementation chooses one of:

Background completion: the hart waits for the instruction to complete; this option does not apply to the memory instructions kl.load, kl.store, kl.input and kl.output. A KLE fatal error detected before the instruction completes makes every conflicting access (Rule GR35) wait for the KLE unit reset, and the outputs of the instruction are then zero.
Atomic completion before the interrupt is taken.
Precise halt and resumption at the prefix-complete point that klstart records (Rule GR33.1); as for vstart in RVV 1.0, forward progress must eventually be guaranteed for the granule that klstart reports.
Timeout, then precise halt and resumption: option 3, after a system-imposed timeout.
Precise halt and restart at the klstart and vstart with which the instruction was issued, discarding the partial work of the attempt, at most R consecutive times for the same locker and instruction, against livelock:
- R is a choice of the implementation, documented for each instruction that uses this option.
- The KLE unit keeps the restart count with the halted state of the locker (Rule GR33.3) and with the ADS. The completion of the instruction, or a State transition, resets it; the completion of a kl.mgmt does not, and an export and an import that retain the ADS keep it.
- A kl.input or kl.output names no locker and does not use this option.
- Past the bound, the instruction is not restarted: a memory instruction continues under option 3, as it does once a component access of any attempt has had a visible effect; any other instruction, uninterruptible ones (Rule GR32) and a long-running kl.setst included, completes before any interrupt is taken, or halts under option 3 or 4 if it supports one.
- An internal computation of a Long-Running Operation restarts under its own rules within the same bound, keeping the committed prefix of the enclosing instruction.

kl.exec and the vector kl.mvin and kl.mvout use option 3 or 4 (Rule GR33); a long-running operation (Long-Running Operation) may also use option 5 (Rule GR36).

GR35

Under every option of Rule GR34, before the issuing hart performs a conflicting access, the in-flight operation must have completed, or have halted precisely with klstart set as Rule GR33.1 requires. A conflicting access is:

an ordinary load or store overlapping the memory region of the in-flight KLE operation;
an access to a locker that the operation uses, including the issue of another KLE instruction involving it;
a read or write of klstart, vstart, klnamedlocker, kliobuflen or kliobuftop, including by the getter and setter instructions (CSR Getters and Setters: kl.get*, kl.set*, and kl.set*i);
a write to a privileged CSR that governs the operation: the mklcsk group (mklcsk CSR Group), mklmaxiobuflen (mklmaxiobuflen), a Locality CSR (Locality Secret CSR Groups), a *llockerstatus CSR (mllockerstatus, sllockerstatus, and vsllockerstatus for Dirtiness Tracking), a *stateen0 CSR, or a write to mstatus, sstatus or vsstatus that changes KLS;
the issue of a KLE instruction that reads or writes the authentication registers SIV, IMPQUAL and SIV2, such as an export- or import-opening kl.mgmt, while the operation reads or writes them;
a read or write of a GPR, a vector register or a KLIOBUF byte that the operation writes, including the issue of a kl.output, of kl.mvin KLIOBUF, or of any other instruction that reads or writes the KLIOBUF; or
a write to a vector register or to the KLIOBUF that the operation reads, including the issue of a kl.input targeting it.

Scalar operands in GPRs, vl and vtype are captured at issue, so accessing them is not a conflicting access. When it is issued, a KLE instruction sets to Dirty the *llockerstatus and KLS fields that it affects.

Together, Rules GR34 and GR35 make asynchronous execution by the KLE unit invisible to same-hart program order, as Memory Instructions and Memory Model requires. Beyond them, the architecture specifies only the allowed interruption points of its instructions and Machines; an implementation may also preempt a Long-Running Operation at points that it defines itself, as the next section states.

Implementation-Defined Interruption of Long-Running Operations

Definition: Long-running operation.: A kl.exec or kl.setst that accesses only its lockers and the values of the operands captured at issue may be long-running, such as a scalar multiplication, a key generation or a signature; so may a component operation of one, a computation on state already in its lockers between the reading of its inputs and the writing of its outputs, such as completing the load of a field.

GR36	On preemption, a long-running operation behaves as an option of Rule GR34 that the interrupt or exception allows; the implementation supports at least one of options 3, 4 and 5. Whether a long-running `kl.setst` is resumable under option 3 or 4 is implementation-defined; one that is resumable makes its State transition only at completion, and until then its State admits only that `kl.setst`, a `kl.setst` naming Ready (Rule GR19.3), `kl.clearads` and configuration instructions.
GR37	A long-running operation that halts at implementation-defined points obeys the following: Progress. It records its progress in a progress field P of the MDH, which is MachineUse or a subfield of it, in an implementation-defined format. P is non-zero and monotonically increasing from the first precise halt of the operation until its completion, and zero otherwise. Interruption points. Only the timing of the halt determines the interruption point. The set of the interruption points, and the progress recorded at each, never depend on key material, a secret field, plaintext or ciphertext, or the value of any ephemeral random value drawn for the operation, except that, where the Machine’s standard allows the execution time to reveal the number of iterations of a loop, such as a rejection loop (ML-DSA), they may depend on that number. Intermediate state. It keeps its intermediate results in the ADS and updates architected Content only at completion. Besides the changes that the semantics of the instruction make at its issue and retirement, it changes only P and AuxDataLen in the MDH, and AuxDataLen depends only on the State and on the halt point. Inputs. It takes no input after it starts: its inputs are those of the definition, captured when the instruction that starts it is issued, and it keeps copies of them in the ADS, so a resumed instruction does not re-read the operands. The resuming instruction, a `kl.exec` or a `kl.setst`, must be the halted one with the same operand registers, immediate and, for a vector operand, `vtype` and `vl`, and, for a KLIOBUF operand, `kliobuftop`; otherwise the locker transitions to Error State Invalid. A re-issue with an empty window (item 1 of Rule GR18) is not a resumption and leaves the operation halted. Material. The random and intermediate values that the operation keeps in a state field or in the ADS are its material, meaningful only while P is non-zero. A Machine may nevertheless write such a random value, an ephemeral random value, and its flag to architected Content before completion, such as ECC’s `RndNum` and `HasRndNum` (Elliptic Curve Cryptography) or ML-DSA’s `rnd` (ML-DSA); a restart discards it (Rule GR38).
GR38	A State in which a `kl.exec` may be interrupted under Rule GR36 admits only that instruction and Form, the `kl.setst` instructions that its Machine allows in the State, `kl.clearads` (Rule GR19.3) and configuration instructions. If the progress field P of its operation (Rule GR37) is non-zero, the instruction resumes the operation, or restarts it within the bound of option 5 of Rule GR34. An interrupt, and an export or an import that retains the ADS, leave P, the material and the ADS unchanged. These events zero P, and all but the last destroy the material, every intermediate value computed or randomly drawn for the operation: a restart, after which the restarted operation generates the material anew; while P is non-zero, `kl.clearads` and every transition of the locker’s State, a same-State `kl.setst` included; the moves of a management operation into and out of a Configuration State are not such transitions (Rule MR17); an import, or an export completion that restores a Valid State, that does not retain the ADS, such as on an `IMPQUAL` mismatch, a failed `SIV2` check or ADSDropped = 1 (Decryption and Authentication of a Complete SCC into a Locker): it restarts the operation and discards the ADS; a `kl.clone`, which restarts the operation in the copy (kl.clone, kl.rename, and kl.swap), the source keeping its P and material; the completion of the operation, after which the algorithm of the Machine determines whether the material is kept.

Memory Instructions and Memory Model

The KLE memory instructions are kl.load, kl.store, kl.input and kl.output; they are RISC-V memory instructions. kl.mvin and kl.mvout access no memory and are not memory instructions.

GR39	A KLE memory instruction may be decomposed into component accesses of any granularity, none of them required to be atomic, performed in any order that the semantics of the instruction and the memory model allow; among the component accesses of one instruction, ordering follows RVWMO, even with `Ztso`.
GR40	KLE memory instructions appear to execute in program order on the local hart. Their component accesses are ordinary loads (`kl.load`, `kl.input`) or stores (`kl.store`, `kl.output`) of the issuing hart: between instructions they follow RVWMO, and with `Ztso` RVTSO; `FENCE` and the `.aq`/`.rl` annotations order them as they order ordinary loads and stores, and `FENCE.I` and `SFENCE.VMA` affect them as they affect ordinary loads and stores; other harts observe them as ordinary memory operations under RVWMO, or under RVTSO with `Ztso`, with no order among those of one instruction guaranteed before it completes.
GR41	After the checks of Rules GR12 and GR13, each component access of a KLE memory instruction checks, in offset order, the address breakpoint, then the page, guest-page and access faults, as per the Privileged Specification. The address breakpoint of the first component access of a `kl.load` or `kl.store` that designates a locker is instead checked at item 8 of Rule GR12, before the address-misaligned exception, and only if the transfer window is not empty and the locker is not inert; the alignment is checked even for an empty window. That access is at the effective address plus `klstart`, with a size of 16 bytes, and both exceptions write that address to `xtval`; a `klstart` that is not a multiple of 16 is left to Rule GR24. Only the checks are in offset order: the accesses themselves are performed in any order that Rule GR39 allows. A KLE memory instruction completes, and may retire or take a trap with `xepc` past it, only after every component access has passed address translation and permission checks and has been performed. Otherwise a component access raises the corresponding precise exception for that execution attempt, and the instruction halts as Rules GR34 and GR33 state.
GR42	For the syntactic dependencies of RVWMO, each locker, as one unit, and each byte of the KLIOBUF is a register, and a KLE memory instruction has these registers: Source registers: `Xs` and `Xl`, the CSRs `klstart`, `kliobuflen`, `kliobuftop` and `klnamedlocker`, for `kl.load` the locker that it writes, and the data source registers below. `Xs`, `Xl`, `klstart`, `kliobuflen`, `kliobuftop` and `klnamedlocker`, and for `kl.load` and `kl.store` the locker that `klnamedlocker` names, are address source registers. Data source registers: for `kl.store`, the locker it reads; for `kl.output`, the KLIOBUF bytes it reads; none for `kl.load` and `kl.input`. Destination registers: `klstart`, an accumulating CSR, tracked as one unit; for `kl.load`, the locker it writes; for `kl.input`, the KLIOBUF bytes it writes. The instruction carries a dependency from each source register to `klstart`. Every other KLE instruction carries a dependency from each register, locker and KLIOBUF byte that it reads to each that it writes, so that a dependency passes from a `kl.load` or `kl.input` through lockers and the KLIOBUF to a later `kl.store` or `kl.output`.
GR43	KLE memory instructions support only idempotent memory: a component access whose effective memory attributes (the PMAs, as modified by the page-based memory type where `Svpbmt` is implemented) are non-idempotent or have side effects is not made, and raises a load, resp. store, access-fault exception (cf. Rule GR41), with `xtval` holding the offending address. Re-execution raises the same exception at the same offending byte, unless that byte no longer has such attributes.
GR44	No component operation of a KLE memory instruction draws random bits (Rule MR19) or reads the clock (ExpirationDate Field).

Randomness

GR45

RBG/DRBG failures. If the entropy source has failed permanently (for Zkr, the DEAD state), an operation that needs random bits is not performed and its locker transitions to Invalid; for kl.clone and kl.derive, that locker is the destination. If the bits are only temporarily unavailable, as after a health-test failure from which the source can recover, the instruction waits and, past a documented, implementation-defined bound, raises a KLE RBG-unavailable exception (Rule GR16); while the instruction has written nothing beyond the prefix that klstart records, an interrupt ends the wait and the instruction is re-executed after it (Rule GR32); otherwise an interrupt ends the wait early only where Rules GR34 and GR36 allow it. An instruction draws all the random bits that it needs before it writes any of its output beyond the prefix that klstart records, to Vd or the KLIOBUF, so that a KLE RBG-unavailable exception leaves its output unchanged and an in-place kl.exec can be re-executed on its intact input; after a permanent failure the locker is Invalid (Rule GR15).

Rules for the Import of a System-Specific Format

GR46

System-specific formats are optional and only imported: a PI, or a PCCC of base type pi, with Version = 3 is invalid Metadata (Validity of Metadata). Such an import replaces a provisioning and is never a snapshot of a running Machine: the format supplies every field that the Machine needs and cannot set itself. Version = 3 appears only during such an import, base or nested, and in the PCCC of a nested export taken during it. An implementation may support several such formats and distinguishes them in an implementation-defined way.

A system-specific format is imported, not provisioned, because it may authenticate its data: SCC import code already handles an Authentication Failed error, whereas provisioning code does not, since completing a provisioning authenticates nothing. Import is also conceptually right: like SCCs, such formats come from sources external to the caller. As after a provisioning of a KLE format, however, a successful import of a system-specific format ends in Ready with no ADS, and the MDH fields that describe a started Machine are zero (Rule GR47).

GR47	The base import of a system-specific format opens with a KLE-format MDH: Version: 3. AuxDataLen: the length, in 128-bit blocks, of the data after the MDH, zero-padded to a whole number of blocks. Software records it before the import, and `kl.size` and `kl.load` read it (kl.avail and kl.size, serialized image). The format carries no ADS. Machine, MachinePolicy and MachineExtension: the Machine that the import configures, which the format determines, by naming it or by its own definition; no `kl.mgmt` rewrites them. The opening `kl.mgmt` checks them as for any import, and allocates the capacity of Rule GR53. Before converting the data, the import-completing `kl.mgmt` checks that the Machine and MachineExtension of the MDH equal those that the format determines, and that the MachinePolicy of the MDH enables only operations that the format allows; if not, the locker transitions to Error State Invalid. SCProtection, UsagePolicy, Locality and ExpirationDate: the policies, applied as in any import. The format may supply values for UsagePolicy, Locality and ExpirationDate, which narrow those of the MDH, and a minimum SCProtection, which the MDH must meet (Rule GR51). AuxInfo: as in a PI of the Machine; the import uses this value unless the format supplies one. State, StateExtension, KeyType, ADSDropped and MachineUse: zero.
GR48	A system-specific format may carry policies beyond those of the declared MDH; the implementation converts them, in an implementation-defined way, into KLE policies at least as strong, which apply in addition to those of the MDH, never in their place, and a policy that cannot be so converted is a failed translation (Rule GR51). The format defines whether and how its data is protected: this specification requires neither encryption nor authentication. The format and the implementer of its import either prevent the import from producing an inconsistent state or reject the data that would produce one (Rule GR49).
GR49	A system-specific format and its import circumvent no requirement of this specification or of the referenced standard of the Machine; the architect of the format and the implementer of its import ensure this. The base import leaves a locker whose MDH and Content the following sequence could also have produced: a provisioning of the same Machine; the usage instructions that load each field that the converted Content configures and the PI does not carry, or that set it by an operation (Rule MR16), then a `kl.setst` naming Ready; and the narrowing of step 3 of Rule GR51. No initialization operation of the format leaves a field with a value that the operations of the Machine could not produce, and no conversion bypasses a check or a derivation of the Machine (Rule MR4).
GR50	Until the import completes, the locker holds the loaded data as received: authentication, decryption, conversion and policy translation occur only in the completing `kl.mgmt`. A nested export taken during the import (Management States and Formats) is a PCCC that carries only what software supplied: the MDH, which keeps Version 3 and AuxDataLen, then the loaded data, at ContentOffset 0; its nested import opens with that MDH and restores the locker.
GR51	The `kl.mgmt` that completes a system-specific import receives an `ml` whose State is 0 and proceeds in four steps; a step that leaves the locker in an Error State ends the import. Unwrap and convert. It authenticates and/or decrypts the data, if the format is authenticated and/or encrypted; a failed authentication gives Error State Authentication Failed, and so does any other failed check that the format defines, when the format authenticates its data. It then makes the check of Rule GR47, converts the data to the internal representation that KLE expects, translates the policies of the format, and takes AuxInfo from the format where it supplies a value. Any other failure in this step invalidates the locker. Check. The converted Content undergoes every check that the Machine makes on a provisioning or an import of the same fields, with the same outcomes (Rule MR3); each field that it configures is then in the same status, its flag included, as after a complete load of that field by `kl.exec` (Rule MR14). Narrow. It narrows the declared MDH by the translated policies (Narrowing of Metadata); a failed narrowing, or a format that requires a higher side-channel protection level than the declared SCProtection, gives Error State Privilege Violation. *Enter Ready.* It sets Version and AuxDataLen to 0 and zeroes the implementation-defined subfields of AuxInfo (MachineUse and AuxInfo Fields). Unless a Machine check left the locker in Failure, it then enters Ready, performing the operations of entering it (Rule MR17) or, at this completion only, the initialization operations of the format instead. The other provisioning actions of the Machine, such as setting a default or clearing a field or its flag, apply only to the fields that the converted Content does not configure, and to their flags; none clears a flag set in step 2.

A CC imported from a system-specific format can be bound by its Locality to the implementations meant to use it. Code examples (Appendix: Writing Software for KLE) include no such import.

Error Handling Architecture

An error condition has one of three outcomes: it raises an exception; it is recorded in the locker as an Error State, which travels with the CC and stays readable until the locker is reconfigured; or, on an inert locker, it lets instructions have only the outcome described in Table 14, i.e., most fall through and raise no exception. This section describes when exceptions are raised and when Error States are set.

Exceptions

The grounds of each KLE exception follow, in the descending priority order of Exception causes in decreasing priority order, except the memory exceptions, listed last.

First Group of Illegal-Instruction Exception Grounds

These grounds depend only on the presence of a KLE unit and of its features, and on the current privilege mode; they raise an illegal-instruction exception, except as items 2 and 3 state:

An access denied by KLS = Off or by a *stateen0 gate;
an hstateen0 denial while V=1, or a guest access for which CSRs prescribes one, raises a virtual-instruction exception instead.
An access to a KLE CSR unavailable in the current mode (Table 10, CSRs); in VS-mode or VU-mode, where the Privileged Specification prescribes it, a virtual-instruction exception instead.

KLE fatal-error

The main fatal condition is an integrity failure of a hart’s KLF (The Cryptographic Locker File and Authentication Information); implementations may define others. Detection and the resulting KLE unit reset (KLE Unit Reset and M-mode-only Harts) may be synchronous or asynchronous; the KLE unit records the condition, and the first KLE instruction or KLE CSR access issued, or in flight, after detection performs no further operation and raises the exception (in the order of Rule GR12), with xepc holding its address; a prefix that an in-flight instruction has already committed stays (Rule GR33). The reset takes effect as early as the detection, and no later than when that instruction or access is issued. If it takes effect earlier, the KLE unit retains only the internal state needed to raise this exception, none for any other exception, and clears that state when it raises it. Meanwhile no instruction accesses the KLF.

Second Group of Illegal-Instruction Exception Grounds

These grounds depend only on the instruction encoding, the GPR numbers, the vector configuration and kliobuftop; they raise an illegal-instruction exception:

A reserved encoding, including KLNL where Rule GR4 does not admit it, or a vector operand while vtype.vill is set (RVV/KLV).
A reserved value of r or R, or a non-zero locker register field that they replace (Rule GR4), or, in a kl.derive with R = 00, equal locker indices (kl.derive).
A GPR pair or quartet not meeting Rule GR2.
A vector operand that Rules GR5 and GR6, kl.exec or kl.mvin and kl.mvout exclude, other than the MDH operand of kl.mgmt, or a KLIOBUF variant of kl.mvin or kl.mvout with kliobuftop not a multiple of 16 (kl.mvin and kl.mvout).
An encoding of an unimplemented extension.

KLE missing-CSK

No CSK is active (mklcsk CSR Group); raised by every KLE instruction and KLE CSR access, except as Architectural Requirements on the Context Sealing Key states.

KLE locker-Off

An access to a locker marked Off, except the destination access of a destructive configuration instruction other than kl.swap, and any access of a kl.clone, kl.rename or kl.swap whose source and destination are the same locker (Destructive Configuration Instructions, kl.clone, kl.rename, and kl.swap, mllockerstatus, sllockerstatus, and vsllockerstatus for Dirtiness Tracking); kl.load, kl.mvin and kl.setste are not exempt.

Third Group of Illegal-Instruction Exception Grounds

These grounds do not depend on the State of a locker (Rule GR12, item 7):

An MDH operand of kl.mgmt in Vs shorter than 128 bits, whatever the operation (Rules GR5, GR12, kl.mgmt).
A Form A–C kl.exec with klstart ≠ vstart × SEW / 8 (Rule GR7).
A non-zero Xl where KLE Memory Instructions forbids it.
A kl.load or kl.store issued with klnamedlocker = 32 and Xl ≠ 0 (kl.input, kl.output) without Zklio, or with an unconfigured KLIOBUF (Rule GR11).
A kl.derive whose KLNL operand names its other locker (kl.derive).
A kl.avail or kl.size of Form B or C while mstatus.kleemulation is 1, that reaches the lookup of item 5 of kl.size with an MDH whose combination of Machine fields the KLE unit does not natively implement (KLE Emulation Control in mstatus).

Fourth Group of Illegal-Instruction Exception Grounds

These grounds depend on the State of the locker (Rule GR13), and none applies to an inert locker:

A transfer that the locker’s State does not admit, or a misaligned klstart (Rules GR13.4, GR24).
A kl.mgmt out of sequence (Locker Management Operations).
An instruction of Rule GR11 other than kl.input and kl.output, with an unconfigured KLIOBUF.

KLE unsupported-Metadata

Unsupported Metadata at a provisioning- or import-opening kl.mgmt, which leaves the locker Unconfigured (Provisioning- and Import-Opening kl.mgmt); only an M-mode handler can resolve it, by emulating the Machine (Emulation of Unsupported Machines). Accessing or using a locker in State kl_stateext_unsupported raises no such exception.

KLE privilege-violation

A usage instruction that the UsagePolicy denies (Rule GR17), or any use, clone or restriction of a locker in a Configuration State (Rule GR13.3).

KLE clock-unavailable

The secure clock cannot be read to check a non-zero ExpirationDate (ExpirationDate Field).

KLE out-of-memory

Insufficient KLF capacity for provisioning, import, or cloning (Locker Management Operations, kl.clone, kl.rename, and kl.swap).

KLE RBG-unavailable

Random bits that an operation needs remain unavailable past the bound of Rule GR45.

Memory exceptions

The load/store address breakpoint, address-misaligned, and page, guest-page and access-fault exceptions of a KLE memory instruction (GR41, Memory Instructions and Memory Model).

Error States

These conditions set an Error State without an exception; the list is informative, and the cited Rules govern:

Invalid:
- invalid Metadata or SKID (Validity of Metadata, System Keys);
- an instruction that the Machine, its State or MachinePolicy does not admit (Rule GR19, MR1), or a kl.derive that fails a check of Rule GR29;
- a transfer window of a length that the Machine does not admit, or a klstart inside it that is not an interruption point (Rule GR18);
- a permanent RBG failure (Rule GR45);
- a configuration error of the Machine (Rule MR2);
- a field that fails its check when a kl.derive transfer completes, unless its Machine specifies another outcome (Rule GR28);
- a provisioning completion with a non-zero AuxDataLen or ADSDropped (Locker Management Operations);
- a system-specific import whose MDH does not match its format, or whose format check fails when the format does not authenticate its data, or whose conversion or policy translation fails (Rules GR47 and GR51).
Expired: an ExpirationDate that has passed (ExpirationDate Field).
Privilege Violation: a failed narrowing (Narrowing of Metadata, kl.rstrl, kl.rstrh, and kl.rstrv, Rule GR30), a SKID resolution below the minimum SCProtection that the SKS associates with the SKID (Rule GR55.2), a restricted kl.derive into a destination of lower SCProtection (Rule GR30), or a system-specific import whose format requires a higher side-channel protection level than the declared SCProtection (Rule GR51).
Authentication Failed: a failed SCC authentication, at the completion of an import (Decryption and Authentication of a Complete SCC into a Locker) or of an export (Export-Completing kl.mgmt), so software checks the State after both; and a failed check that a system-specific format defines, when the format authenticates its data (Rule GR51).
Any Error State: the one that a kl.setste names (Rule GR26).

Two outcomes are not Error States: a Machine enters Failure on a data error (Rule MR2) or on a failed verification of an AEAD tag or a signature, which is a result, not an error; and an ADS that fails its check at import is dropped, the SCC accepted (Decryption and Authentication of a Complete SCC into a Locker).

Correspondence of Exceptions to Error States

Table 16 gives, for each KLE exception, the outcome that a handler that neither resolves nor forwards it produces under Rule SR10; the exception itself sets no Error State.

Table 16. Error State that a handler that neither resolves nor forwards an exception sets
Exception	Error State
KLE fatal-error	None: the condition is not recoverable.
KLE missing-CSK	None.
KLE locker-Off	None.
KLE unsupported-Metadata	Unsupported
KLE privilege-violation	Privilege Violation; a locker in a Configuration State keeps its State.
KLE clock-unavailable	Expired
KLE out-of-memory	Out of Memory
KLE RBG-unavailable	Invalid
Any other exception that an opening `kl.mgmt` raises after zeroizing its locker	Invalid

For kl.clone and kl.derive, which name two lockers, that State is set on the locker on which the exception is raised: for kl.clone, the destination of a KLE out-of-memory exception; for kl.derive, the endpoint where the failing check is detected, the source being checked first (Rule GR27).

Management of Cryptographic Contexts

Following the RISC-V philosophy, KLE splits locker management into sequences of simple instructions, not single instructions that drive large state machines or microcode. As a consequence:

the state machines that manage keys and algorithms, which CISC key-protection solutions hide (cite:[IBM-z-arch] “Protection of Cryptographic Keys” or cite:[intel-keylocker]), are exposed to software: the hardware is simpler, though it enforces rules against misuse, and the software more complex;
interrupts and exceptions can separate the instructions of a management sequence, so context switching, process and virtual machine migration, hibernation, and interoperability between KLE implementations need explicit support; and
so does dynamic locker management, lazy context loading included, where other architectures cache repeated key uses implicitly.

Throughout, KLE preserves the integrity of the MDH and the confidentiality and integrity of the Content of a CC, and binary compatibility holds across implementations that support the same sub-extensions.

Appendix: Writing Software for KLE provides guidelines for system software.

Management States and Formats

A management operation is open from its opening kl.mgmt until its completing kl.mgmt, or until a destructive configuration instruction (Destructive Configuration Instructions) or a transition to an Error State discards the locker’s CC, which ends every open operation on it; kl.rename and kl.swap carry an open operation with the CC they move. While it is open, the locker is in a Configuration State. kl.mgmt opens or completes an operation according to its #immed7:

Table 17. Values (decimal) of #immed7 for provisioning, importing, and exporting
Value	Mnemonic	Description
56	`kl_cfg_provisioning`	Prepare a locker for provisioning.
57	`kl_cfg_exporting`	Prepare a locker for export.
58	`kl_cfg_importing`	Prepare a locker for import.
63	`kl_cfg_management_end`	Complete the current management operation.

Management operations use various formats to move a CC. The first two are the Provisioning Input (PI) and the Sealed Cryptographic Context (SCC):

Definition: Provisioning Input (PI).

The MDH, with State and StateExtension zero, followed by the clear Content. A PI is not a locker, so it is never Unconfigured.

Definition: Sealed Cryptographic Context (SCC).

Up to five sections, in this order, section 5 consisting of Content1 followed by Content2:

Table 18. Plaintext of the Sealed Cryptographic Context (SCC) Format, all Sections in Order
Section	Section Name	Size	Description
1	`MDH`	128 bits	See Metadata.
2	`SIV`	128 bits	Authentication tag for `MDH`, the Locality Secrets its Locality names, and `Content1` (Generation of an SCC from a Fully Configured Locker).
3	`IMPQUAL`	128 bits, if present	Identifies the implementation of the KLE unit. Non-authoritative, and ignored when ADSDropped = 1.
4	`SIV2`	128 bits, if present	Authentication tag for `IMPQUAL`, `SIV` and `Content2`. Non-authoritative, and not verified when ADSDropped = 1.
5.a	`Content1`	A multiple of 128 bits. See Length of External Formats and KLF Capacity Usage of a Locker.	Keys and other Machine-specific information that the Machine needs to function correctly. Its first `SCC_ClearLen1` blocks are in clear (Rule GR9); the rest is encrypted in memory, and inside the KLE unit while the SCC is imported or exported.
5.b	`Content2`	A multiple of 128 bits.	ADS: data that the Machine does not need to function correctly. Its first `SCC_ClearLen2` blocks are in clear (Rule GR9); the rest is encrypted in memory, and inside the KLE unit while the SCC is imported or exported.

The clear blocks let software read public values, such as a public key, from an SCC in memory; they are authenticated only when the SCC is imported, so software does not rely on a value read from them as authentic (Rule SR19).

Sections 3, 4 and 5.b form the implementation-specific ADS, of size AuxDataLen (AuxDataLen and ADSDropped Fields). KLE generates an image with ADSDropped = 1 only as an SCC-shaped PCCC, when a nested export preserves an interrupted import after Content2 was dropped; since ADSDropped is unauthenticated, import also accepts this layout in an SCC modified to set the bit.

Definition: Base (Management) Operation.

A base management operation is a provisioning from a PI, in State kl_cfg_provisioning; an import of an SCC or of a system-specific format (Rules for the Import of a System-Specific Format), in kl_cfg_importing; or an export of a locker in a Valid State, in kl_cfg_exporting. A provisioning or an import is base when ml.State is not a Configuration State, whatever the State of the locker it opens on; an export is base when it is opened on a locker in a Valid State.

Definition: Nested Management Operation and Base Type.

An exception may interrupt an open operation. A handler then saves the locker by a nested export, an export opened on a locker in a Configuration State, and restores it by a nested import of the resulting image, opened whatever the State of the locker; the image is the Partially Configured Cryptographic Context (PCCC) defined below. Nested operations may themselves be interrupted and nested. States kl_cfg_ppi_exporting and kl_cfg_ppi_importing result only from nested operations, and are not #immed7 values. Each Configuration State (Table 8) encodes the base type of its operation, which fixes the format and length of the locker’s image at every nesting depth (kl.avail and kl.size):

pi, for a provisioning: kl_cfg_provisioning, and kl_cfg_ppi_exporting and kl_cfg_ppi_importing (“ppi” means “partial provisioning input”) for nested operations;
scc otherwise: kl_cfg_exporting and kl_cfg_importing, for base and nested operations alike.

Definition: Partially Configured Cryptographic Context (PCCC).

The third format is the image that an export produces on a locker already in a Configuration State: an MDH holding a Configuration State, in the format of its base type, without further encryption or authentication:

base type pi: a PI-shaped image, the MDH followed by the clear Content that software supplied in the PI; software clears such a locker before giving control to another software context, of the same or a lower privilege, which could otherwise export it (Rule SR1);
base type scc: an SCC-shaped image, in the format of an SCC: the MDH followed by SIV and, when present, IMPQUAL and SIV2, as ContentOffset prescribes (serialized image), and by the Content already in the locker, in the form of an SCC, its clear blocks in clear and the rest as ciphertext; with Version = 3, the MDH followed only by the Content as software supplied it (Rules for the Import of a System-Specific Format).

The fourth format is used for CCs in an Error State.

Definition: Error-State image.: The exported image of an Error-State locker is the MDH alone: its export reads the MDH from the locker and writes it to memory; its import is a single kl.mgmt (Export and Import of a Locker in an Error State).

Software saves the locker’s MDH as ml before opening an export, and an import takes ml from the image. The completing kl.mgmt restores State from ml, so each nesting level keeps its own State; completing a base operation leaves the locker in a Valid or Error State, and completing a nested operation restores the Configuration State that ml carries (Rule GR25).

Encryption during management

While an SCC is imported, or a locker exported as one, the locker holds its Content encrypted, except for its clear blocks (Rule GR9): the base export-opening kl.mgmt encrypts it and generates SIV and, if AuxDataLen ≥ 2, IMPQUAL and SIV2; the base import- or export-completing kl.mgmt decrypts and authenticates it once the whole image is in place, or restores it from an internal copy (Export-Completing kl.mgmt); with ADSDropped = 1, no Content2 is loaded or authenticated.

Definition: Serialized image.

content_size is the length in bytes of the serialized Content of the locker, as a PI or an SCC according to the base type of its image (Length of External Formats and KLF Capacity Usage of a Locker), as given by the locker’s MDH. In a PI, an SCC or a PCCC, the Content starts at a ContentOffset that depends on that MDH:

0 if MDH.Version is 3 (Rules for the Import of a System-Specific Format), content_size and max_admissible then both being 16 × AuxDataLen;
otherwise, 16 if AuxDataLen = 0, and 48 if AuxDataLen ≥ 2, if MDH.State is a Valid State, kl_cfg_importing or kl_cfg_exporting;
0 if MDH.State is 0 (the MDH of a PI), kl_cfg_provisioning, kl_cfg_ppi_importing or kl_cfg_ppi_exporting.

The serialized image S of the locker is Content, SIV ‖ Content, or SIV ‖ IMPQUAL ‖ SIV2 ‖ Content for ContentOffset = 0, 16 or 48, respectively; while the locker is under management, the authentication registers (The Cryptographic Locker File and Authentication Information) hold its leading fields. Its size is image_size = ContentOffset + content_size, the value that kl.size reports minus 16.

max_admissible is the length in bytes of the longest Content of the locker’s base type that the implementation can hold for the Machine: pi_content_size for base type pi, and content1_size plus the largest supported content2_size for base type scc (kl.avail and kl.size); with ADSDropped = 1, content2_size counts as zero. Bytes of Content beyond max_admissible belong to a discarded ADS (Decryption and Authentication of a Complete SCC into a Locker), and are not transferred. The transferred part of S ends at image_end = ContentOffset + min(content_size, max_admissible). Accesses to S are 16-byte granular: the management transfer instructions (Rule GR4) transfer whole 16-byte blocks, and all their offsets and lengths, klstart, content_size, max_admissible, image_size and image_end, are multiples of 16.

Length of External Formats and KLF Capacity Usage of a Locker

GR52

The length of an external image depends only on fields in bits [63:0] of its MDH, as follows, where the bullets are considered in order:

an Error State image, State 0 with a StateExtension of 1–5, or 6 with Zklexpire, whatever its other fields hold: the length is 16 bytes (see Definition: Error State.);
any other image with Version = 3: the length is 16 + 16 × AuxDataLen bytes (Rule GR47);
a PI: the length depends on Machine, MachinePolicy, MachineExtension and KeyType;
an SCC: the length depends on Machine, MachinePolicy, MachineExtension, KeyType, StateExtension, AuxDataLen and ADSDropped;
a PCCC: as the format of its base type (Management States and Formats).

GR53

The KLF capacity used by a locker is fixed when the opening kl.mgmt or the kl.clone that configures it allocates it, and depends only on the Machine, MachinePolicy, MachineExtension, SCProtection and KeyType of the MDH it installs and, during a system-specific import, on AuxDataLen. It covers every field that its Machine may use in every State it can reach and the largest ADS that the implementation keeps for the Machine. It also covers, during a system-specific import, the 16 × AuxDataLen bytes that the locker holds as received (Rule GR50), even if they exceed what the Machine normally occupies; upon base import completion the implementation may release any excess capacity beyond what the converted CC occupies. A later change of State or MachinePolicy does not change it; it is released only as stated above at a base import completion, when the locker enters an Error State (Rule GR15), or when it is destructively configured; with KeyType = 2 it is that of KeyType = 0.

Single-Share Key Export Rule for Masked Implementations

GR54

Single-share export: A multi-share implementation of a Machine provisions, imports and exports all its keys and secrets as reconstructed values. Such an implementation may copy System Key material from the SKS into the locker and expand it into shares, but exports the key only as its SKID (Rule GR55.1); no ADS, alone or combined with any other data that KLE exports, including other SCCs of the same CC, may allow or facilitate recovering a key value configured by a SKID.

Reconstructing or re-randomizing a key is usually an inexpensive operation, for instance when a block cipher in counter mode generates the masks; an implementation with a slower share generator may keep shares or masks in the ADS.

System Keys

GR55

System Keys. A System Key is identified by a 64-bit SKID, from which a system-specific SKS retrieves the key: the images of the locker carry the SKID in place of the key (Rule GR55.1), and the SKS resolves the SKID and binds policies to it (Rules GR55.2 and GR55.3).

GR55.1	SKID field. In a PI, an SCC or a PCCC, the key fields of a System Key together hold its SKID, 64 bits, instead of the key values; for a Machine with several keys, the SKS retrieves all of them from that single SKID. A field configured by a SKID is never exportable, and a key field of a locker whose KeyType is 1 is never importable, by `kl.derive`; no instruction outputs the key value of such a field, which a PI, an SCC or a PCCC replaces by the SKID. A key value that a Machine holds in another field, such as its `state` or `block`, only between two steps of one instruction is in no Serialized Content, so it needs no such replacement. For `SHA3-224_HMAC` to `SHA3-512_HMAC`, `KMAC128`, `KMAC256`, `KMACXOF128` and `KMACXOF256`, whose `state` is an invertible function of the key and of values that the SCC carries, the Serialized Content holds `state xor state_mask` (Rule GR55.2) in every State but Ready (KMAC128, KMAC256, KMACXOF128, and KMACXOF256, HMAC).
GR55.2	SKID resolution. The SKS resolves a SKID that is allowed for the Machine and MachinePolicy, whatever the current privilege mode, into a key value that depends on the SKID alone and, for a Machine that Rule GR55.1 names, a 1600-bit state mask `state_mask` that depends on the SKID and the Machine alone; it resolves a SKID carried in an SCC only after the SCC is authenticated. No instruction outputs `state_mask`; its bits are pseudorandom, and independent of every value that a Machine computes from a key of any SKID. The KLE unit keeps `state_mask` with the resolved key, so an export does not consult the SKS. A SKID that the SKS does not resolve transitions the locker to Error State Invalid (Validity of Metadata); the policies that the SKS associates with a resolved key (Rule GR55.3) narrow the MDH of the locker (Narrowing of Metadata), and a failed narrowing transitions the locker to Error State Privilege Violation. The SKS may also associate a minimum SCProtection with a SKID; a resolution whose MDH has an SCProtection lower than that minimum transitions the locker to Error State Privilege Violation.
GR55.3	SKID policies. The SKS associates a Locality (Locality Field) with every SKID, and may associate further policies, such as a UsagePolicy, with some SKIDs only. A policy that it does not associate leaves the corresponding field unchanged when the MDH is narrowed (Narrowing of Metadata).

The state mask of Rule GR55.2 hides the capacity part of state, of c bits (Parameters of the SHA-3 family); its rate part is known once a CC in Hash_Output is exported, since that rate holds output. Whoever holds the CSK can compare masked states, and so learns which CCs of one SKID and Machine absorbed equal block-aligned prefixes. By importing a masked state XORed with a chosen value, that party also obtains E(w) = P(w xor state_mask) xor state_mask, a single-key Even–Mansour cipher over KECCAK-p[1600, 24] whose unknown key is the capacity part of the mask. A generic attack then needs D × T ≈ 2^c for D queries and time T (Dunkelman, Keller and Shamir, EUROCRYPT 2012), so at least 2^c/2 operations: the generic security of the sponge itself, 128 bits for KMAC128. The SKS may derive state_mask from a secret of its own with a KDF of SP 800-108r1, under a label that no key derivation uses. A derivation by KMAC or cSHAKE from the key is unsafe: the KMAC Machine does not check cshake_block (KMAC128, KMAC256, KMACXOF128, and KMACXOF256), so anyone allowed to use the SKID with KMAC computes cSHAKE over key_block with any function name and customization string.

Locker Management Operations

This section defines the operations that kl.mgmt performs for the #immed7 values of Table 17.

Two steps are common to every operation below and are not repeated in their descriptions; after the checks of Rule GR12, a kl.mgmt with KLNL and klnamedlocker = 32 performs only these two (Rule GR13.2):

It updates klnamedlocker as Rule GR21 states.
It clears klstart as Rule GR14 states, so a kl.mgmt rejected by items 1–6 of Rule GR12 does not destroy the progress of the ongoing operation. Software restores klstart to resume interrupted management operations.

The next six subsections describe the semantics of kl.mgmt:

Provisioning- and Import-Opening kl.mgmt

Software first obtains the MDH, ml, and supplies it with a Form C or D kl.mgmt. For an import, software first saves ml in its local state and supplies it to the import-completing kl.mgmt, to restore the State the locker had when it was exported (Rule GR25).

The kl.mgmt instruction:

zeroizes the target locker, as a destructive configuration instruction; bytes of the Content of the serialized image S not yet written since this opening read as zero through every architectural access (kl.store, kl.mvout, verbatim export); its authentication fields read the current values of the authentication registers (The Cryptographic Locker File and Authentication Information), which an import opening zeroizes;

if #immed7 = kl_cfg_importing and ml is in an Error State (State 0, StateExtension 1–6), instead takes the short import path of Export and Import of a Locker in an Error State: it configures the locker immediately in that Error State, or in Invalid if the MDH is invalid, skips the steps below, and opens no management operation;
for an import, zeroizes the authentication registers SIV, IMPQUAL and SIV2 (The Cryptographic Locker File and Authentication Information);
copies ml into M, zeroing MachineUse and the implementation-defined subfields of AuxInfo (MachineUse and AuxInfo Fields) for a provisioning; the checks below are made on M, the locker’s MDH staying zero;
for a provisioning:
1. requires ml.State to be 0, else the Metadata is invalid; the locker’s State stays Unconfigured during the checks below, until successful configuration;
2. requires M.AuxDataLen and M.ADSDropped to be 0: if either is non-zero, the locker transitions to Error State Invalid and the instruction terminates;
transitions the locker to Error State Invalid if M is invalid Metadata (Validity of Metadata), an Unconfigured ml being invalid for an import unless ml.Version is 3, and skips the steps below;
raises a KLE unsupported-Metadata exception if M is unsupported Metadata (Validity of Metadata);
attempts to allocate the KLF capacity that the fields Machine, MachinePolicy, MachineExtension, SCProtection and KeyType of M require (Length of External Formats and KLF Capacity Usage of a Locker) and, if M.Version is 3, the capacity for 16 × M.AuxDataLen bytes of data (Rule GR50), and raises a KLE out-of-memory exception if it cannot;
for a provisioning, installs M as the locker’s MDH, with State kl_cfg_provisioning;
for an import:
1. installs M as the locker’s MDH, with ADSDropped = 1 if M.Version is not 3, M.AuxDataLen ≥ 2, and either M.ADSDropped = 1 or M.AuxDataLen exceeds the maximum of the implementation for the Machine, and with ADSDropped = 0 otherwise (Step 4 of Decryption and Authentication of a Complete SCC into a Locker);
2. sets the locker’s State to kl_cfg_importing if ml.State is a Valid State, kl_cfg_importing or kl_cfg_exporting, or ml.Version is 3;
3. sets it to kl_cfg_ppi_importing if the base type of ml.State is pi (Management States and Formats).

Whenever a check above fails, raising a KLE exception or transitioning the locker to Error State Invalid, every MDH field other than State and StateExtension remains zero and no KLF capacity is allocated; after a KLE out-of-memory exception, the locker remains Unconfigured until a handler sets Error State Out of Memory (SR10). This does not apply to configuring a locker directly into an Error State from ml, which installs the MDH as Export and Import of a Locker in an Error State states.

Clearing the locker right after the locker-state-independent checks of Rule GR12, before any check of the opening itself, guarantees that any later failure has the same effect: the old content is destroyed and klnamedlocker names the locker (Rules GR21 and GR16). The capacity check then counts the locker’s own allocation as free.

Export-Opening kl.mgmt

Software first saves a copy, ml, of the locker’s MDH, to restore the State when completing the export. kl.mgmt can be of Form A, C or D, and ignores its auxiliary input. Depending on ml.State:

Unconfigured: no operation and no exception. No management operation is opened, the authentication registers are unchanged, and only the common steps above take effect (Rule GR13.2).
An Error State: the locker is unchanged, and no management operation is opened (Rule GR26); Export and Import of a Locker in an Error State details this short export path.
A Valid State: if the Locality of the MDH names an unconfigured entry without a configured substitute (Locality Field), no operation and no exception: no management operation is opened, the State and the authentication registers are unchanged, and only the common steps above take effect. Otherwise the instruction prepares the locker to produce an SCC, encrypting its contents and computing the authentication tag(s) as Generation of an SCC from a Fully Configured Locker specifies, and sets its State to kl_cfg_exporting. The opening kl.mgmt changes no MDH field other than State: an implementation that creates or changes an ADS, or uses MachineUse, always keeps AuxDataLen and MachineUse current, so that the MDH software reads before opening the export is the one the export authenticates.
A Configuration State (the export of a partially configured locker, or a nested export):
1. no encryption or authentication occurs: the locker’s contents are exported verbatim, in their order in the PI (for a partially provisioned locker) or in the SCC (for a partially imported locker, or a locker whose own export was interrupted);
2. the locker’s State is set to kl_cfg_ppi_exporting or kl_cfg_exporting, according to its base type (Management States and Formats).

Common Properties of Completing kl.mgmt

Two special cases:

kl_cfg_management_end issued on a locker in a Valid State raises an illegal-instruction exception: no management operation is open on it.
kl_cfg_management_end issued on an Unconfigured or Error-State locker performs no operation, raises no exception and ignores ml; only the common steps above take effect (Rule GR13.2).

These two special cases aside, a kl.mgmt issued to complete a management operation first reads the target locker’s MDH, and completes a provisioning if its State is kl_cfg_provisioning, an import if it is kl_cfg_importing or kl_cfg_ppi_importing, and an export if it is kl_cfg_exporting or kl_cfg_ppi_exporting.

When completing an import or an export, it consumes only the State field of the auxiliary operand ml, which restores the locker’s State to the value that ml records; no other MDH field is written from ml. The locker keeps the StateExtension that it holds during the operation: for an export, the one that it had when the export was opened; for an import, the one carried in the image (Decryption and Authentication of a Complete SCC into a Locker). The completion restores StateExtension @ State without reading ml.StateExtension. An Error State never reaches a completion: its image is the MDH alone, imported by the short import path, and an export opened on an Error-State locker opens no operation (Export and Import of a Locker in an Error State).

On completing an SCC import or a locker export, authentication is checked only if setting locker.MDH.State to ml.State restores a Valid State; the probability of accepting an incorrect State is negligible. A nested completion checks only the base type, without authentication. If a completion that restores a Valid State finds that the Locality of the MDH names an unconfigured entry with no configured substitute (Locality Field), the locker transitions to Error State Invalid without decryption or authentication.

The kl.mgmt completing an import or an export admits these values of ml.State (Management States and Formats); any other, 61–63 included, raises an illegal-instruction exception:

a locker whose MDH has Version = 3: kl_cfg_importing or kl_cfg_exporting, and, for a locker in kl_cfg_importing, also State 0, which completes the system-specific import (Rule GR51);
otherwise, a locker of base type scc (kl_cfg_importing or kl_cfg_exporting): a Valid State (1–55), kl_cfg_importing or kl_cfg_exporting;
a locker of base type pi (kl_cfg_ppi_importing or kl_cfg_ppi_exporting): kl_cfg_provisioning, kl_cfg_ppi_importing or kl_cfg_ppi_exporting, never a Valid State, so the clear Content of a partially provisioned locker becomes usable only by completing its provisioning.

Provisioning-Completing kl.mgmt

No MDH saved at provisioning start is needed: kl.mgmt can be of Form A, C or D, and ignores its auxiliary input. It transfers no data to or from memory, vector registers, the KLIOBUF or another locker, so the random generation of keys for KeyType = 2 never waits for, or delays, a data transfer (Rule MR19).

Completing a provisioning requires AuxDataLen = 0 and ADSDropped = 0; if locker.MDH.State is kl_cfg_provisioning and either field is non-zero, the locker transitions to Error State Invalid, and the instruction terminates.

The operation makes the provisioned locker available to software by:

for KeyType = 2, generating the key and setting KeyType to 0 (KeyType Field, Rule GR45), and for KeyType = 1, applying the SKID resolution of System Keys;
converting the locker’s content into the internal format of the KLE unit;
performing any check required by the Machine on the fields of the PI (Rule MR3); a failed check transitions the locker as Rule MR2 classifies it, to Error State Invalid for a configuration error or to Failure for a data error, in place of the step below; and
setting State to Ready, with the operations of entering it (Rule MR17), and StateExtension, MachineUse and the implementation-defined subfields of AuxInfo to 0.

If a process is preempted during provisioning, kl.store or kl.mvout exports only the original PI information, unencrypted. Within a provisioning, only its completing kl.mgmt may generate secret random material needed to configure the locker, retrieve key material from the SKS, or derive, expand or re-share that material, so that no such material is exposed in an unencrypted export of a partially provisioned locker.

Import-Completing kl.mgmt

Software uses Form C or D of kl.mgmt to supply the value ml saved when the import started. The image authenticated as AD[0] is the MDH held in the target locker, i.e., the one carried in the SCC and loaded when the import started, with its State restored from ml and ADSDropped cleared only in the copy used for authentication (Decryption and Authentication of a Complete SCC into a Locker).

If locker.MDH.Version is 3 and ml.State is 0, the instruction completes the system-specific import as Rules for the Import of a System-Specific Format states.
If ml.State is a Valid State (the import of the export of a fully configured locker):
1. locker.MDH.State is set to ml.State.
2. The KLE unit decrypts and authenticates the locker’s content.
3. If authentication fails, the target locker transitions to Error State Authentication Failed, without an exception. Otherwise, the ADS is processed, or dropped, as Decryption and Authentication of a Complete SCC into a Locker states; then, if KeyType = 1, the SKID is resolved, and the narrowing of System Keys is applied.
4. The KLE unit converts the locker’s content into its internal format.
5. The KLE unit performs the checks that the Machine attaches to the fields that the import restores (Rule MR3); a failed check transitions the locker as when completing a provisioning (Rule MR2). This makes the locker available to software.
Otherwise (the import of the export of a partially configured locker, or of a nested export), locker.MDH.State is set to ml.State.

Export-Completing kl.mgmt

Software uses Form C or D of kl.mgmt to supply the MDH value ml saved when the export began. Then:

The State of the locker is set to ml.State.
If ml.State is a Valid State, the instruction restores the locker to the clear format it had when the export began, and makes it accessible to software:
1. it decrypts and authenticates the contents as when completing an import, with the MDH held in the locker as AD[0], and ADSDropped cleared in the copy that first-segment authentication consumes;
2. if the SIV check fails, the locker transitions to Error State Authentication Failed, and the instruction terminates without an exception; otherwise it performs Steps 14–15 of Decryption and Authentication of a Complete SCC into a Locker, and then the steps that follow authentication in the import-completing kl.mgmt (Locker Management Operations): SKID resolution and narrowing for KeyType = 1, conversion into the internal format, and the checks of Rule MR3, with the same outcomes.
If ml.State is not a Valid State, the locker’s contents are not changed further.

Instead of decrypting and authenticating the locker’s contents in Step 2.a, an implementation may restore the clear contents from an internal copy, made when the export was opened, if the outcome is identical; the specification defines no mechanism for this, and Step 2.b then follows as after a successful SIV check. The copy is valid only if, since the export was opened:

no instruction has written the locker’s MDH or contents, moved its CC, or opened or completed a management operation on it other than this export, so that a nested export or import, a destructive configuration instruction, kl.setste, kl.rename or kl.swap on the locker invalidates the copy;
SIV and, if the image carries them, IMPQUAL and SIV2 still hold the values that the opening generated; and
the CSK and the LST_eff entry of every Locality that the MDH names (Locality Field), which the decryption and authentication use, are unchanged.

With a valid copy, Step 2.b still performs SKID resolution and narrowing for KeyType = 1 against the current SKS state, so a revoked SKID or a changed SKS policy has the same outcome as on the full path.

Without a valid copy, the instruction decrypts and authenticates as Step 2.a states. With one, it uses the copy only if ml.State equals the State that the locker had when the export was opened; otherwise it transitions the locker to Error State Authentication Failed, as the failing SIV check would.

SCC Export and Import Algorithms

Section The SCC Authenticated Encryption Scheme defines the authenticated encryption scheme, and Generation of an SCC from a Fully Configured Locker and Decryption and Authentication of a Complete SCC into a Locker the SCC export and import algorithms.

The SCC Authenticated Encryption Scheme

SCC export and import use a variant of AES-GCM-SIV cite:[DBLP-journals-iacr-GueronLL17,RFC8452] that differs from the standard as follows: the POLYVAL input does not contain the lengths of the associated data and plaintext, since they are already implied by the MDH; the nonce is omitted, which amounts to the all-zero nonce of RFC 8452; a domain separation bit, sep, distinguishes the two segments of the content sealed in an SCC: the architected content (sep = 0) and the optional implementation-specific content (sep = 1); sep replaces bit 126 of the tag input and of every counter block; and for sep = 0, bit 47 of MDH (the first block of the associated data), i.e., the unauthenticated ADSDropped bit of the MDH (AuxDataLen and ADSDropped Fields), is cleared before POLYVAL is evaluated. The clear blocks of a segment (Rule GR9) are appended to its associated data, and only the remaining blocks are encrypted.

The Key Derivation (RFC 8452 Key Derivation) and POLYVAL (POLYVAL Hashing Function) functions are defined first, then SCC generation from a locker (Generation of an SCC from a Fully Configured Locker) and SCC import into a locker (Decryption and Authentication of a Complete SCC into a Locker).

In the pseudocode, AESE256(K, B) denotes the AES-256 encryption of the 128-bit block B under the 256-bit key K (FIPS 197 cite:[nist-fips-197]).

RFC 8452 Key Derivation

function SCC_KeyDeriv(key : bits(256))
    → struct{enc_key : bits(256), auth_key : bits(128)} =
{
  local A : array [0..5] of bits(128);
  local i : int;

  foreach(i from 0 to 5) do:
    A[i] ← AESE256(key, bin(i,128));

  return struct { enc_key  = A[5][63:0] @ A[4][63:0] @ A[3][63:0] @ A[2][63:0],
                  auth_key = A[1][63:0] @ A[0][63:0] }
}

POLYVAL Hashing Function

function POLYVAL(auth_key : bits(128), blocks[] : array of bits(128), n : int)
    → bits(128) =
{
  local tmp : bits(128) ← zeros(128);
  local i : int;

  foreach(i from 0 to n-1) do:
    tmp ← tmp xor blocks[i];
    tmp ← Montmul(tmp, auth_key);

  return tmp;
}

POLYVAL uses Montgomery multiplication, Montmul(a, b), in the field F = GF(2)[x] modulo x¹²⁸ + x¹²⁷ + x¹²⁶ + x¹²¹ + 1. A 128-bit value V represents the element whose coefficient of x^k is V[k]; byte order and bit order both run forward, as in cite:[RFC8452] §3, under which x⁰ is the byte string 0x01 followed by fifteen zero bytes, i.e., the value 1. Then:

Montmul(a, b) = a · b · x^-128 in the field F.

The SCC encryption and decryption functions, AES-GCM-SIV Encryption for SCC Generation and AES-GCM-SIV Decryption for SCC Import, use this notation:

AD[] denotes the Associated Data as an array of len_AD 128-bit blocks, that is AD[0] ‖ AD[1] ‖ … ‖ AD[len_AD-1], in that order;
P[], resp. C[], denotes a Plaintext, resp. a Ciphertext, as arrays of len_PC 128-bit blocks, that is P[0] ‖ P[1] ‖ … ‖ P[len_PC-1], resp. C[0] ‖ C[1] ‖ … ‖ C[len_PC-1], in that order;
K is a 256-bit Key; and
SIV is a 128-bit SIV/tag.

AES-GCM-SIV Encryption for SCC Generation

function SCC_Encrypt(AD[] : array of bits(128), sep: bits(1),
    P[] : array of bits(128), K : bits(256), len_AD : int, len_PC : int)
  → {SIV : bits(128), C[] : array of bits(128)} =
{
  local AD_auth : array [0..len_AD-1] of bits(128) ← AD[];
  local keys : struct{enc_key : bits(256), auth_key : bits(128)};
  local i : int;

  keys ← SCC_KeyDeriv(K);
  if (sep = 0) then:
    AD_auth[0][47] ← 0;
  SIV ← POLYVAL(keys.auth_key, AD_auth[] ‖ P[], len_AD + len_PC);
  SIV ← AESE256(keys.enc_key, zeros(1) @ sep @ SIV[125:0]);

  foreach(i from 0 to len_PC - 1) do:
    C[i] ← P[i] xor AESE256(keys.enc_key,
             ones(1) @ sep @ SIV[125:32]
               @ bin((int(SIV[31:0]) + i) mod 2**32, 32));

  return ( SIV, C[] );
}

len_PC never exceeds max_admissible / 16 (serialized image), and len_AD never exceeds 7 plus the number of clear blocks of the segment.

AES-GCM-SIV Decryption for SCC Import

function SCC_Decrypt(AD[] : array of bits(128), sep: bits(1),
    SIV : bits(128), C[] : array of bits(128), K : bits(256),
    len_AD : int, len_PC : int)
  → {correct : bool, P[] : array of bits(128)} =
{
  local AD_auth : array [0..len_AD-1] of bits(128) ← AD[];
  local keys : struct{enc_key : bits(256), auth_key : bits(128)};
  local s, tmp : bits(128);
  local i : int;

  keys ← SCC_KeyDeriv(K);
  if (sep = 0) then:
    AD_auth[0][47] ← 0;

  foreach(i from 0 to len_PC - 1) do:
    P[i] ← C[i] xor AESE256(keys.enc_key,
             ones(1) @ sep @ SIV[125:32]
               @ bin((int(SIV[31:0]) + i) mod 2**32, 32));

  s ← POLYVAL(keys.auth_key, AD_auth[] ‖ P[], len_AD + len_PC);
  tmp ← AESE256(keys.enc_key, zeros(1) @ sep @ s[125:0]);

  if (tmp ≠ SIV) then:
    foreach(i from 0 to len_PC - 1) do:
      P[i] ← zeros(128);
    return ( false, P[] );

  return ( true, P[] );
}

The comparison tmp ≠ SIV is performed in constant time. SCC_KeyDeriv, SCC_Encrypt and SCC_Decrypt have the protection of the SCProtection level of the locker that is exported or imported (The Cryptographic Locker File and Authentication Information); at every level, they take a time independent of the CSK, the derived keys, the Locality Secrets and the plaintext. It is strongly recommended that their memory accesses also be independent of these values.

Generation of an SCC from a Fully Configured Locker

A locker K(i) in a Valid State is fully provisioned, and opening it for export creates the serialized and authenticated SCC, encrypted except for its clear blocks (Rule GR9), by the steps below.

The Locality substitution rules of Locality Field apply: LST_eff[j] is the value of LST entry j after substitution, and replaces LST[j] in the export and import algorithms. An unconfigured entry (Locality Field) with no configured substitute makes the Metadata invalid at provisioning or import, and makes the export-opening kl.mgmt of a locker in a Valid State perform no operation (Rule SR12). Entry 9 of LST is hkllocality, and entry 10 is skllocality.

After kl.clearads, a fully configured locker has AuxDataLen = 0 and ADSDropped = 0 (kl.clearads); KLE sets ADSDropped = 1 only in an SCC-shaped PCCC, to preserve an interrupted import after Content2 was dropped (Management States and Formats).

Exporting a Fully Configured Locker K(i)

Step 1: Read the MDH with kl.getmd; if it is in an Error State, use the method of Export and Import of a Locker in an Error State instead.
Step 2: Store the MDH at offset 0 of the SCC buffer, in the byte order of Endianness.
The export-opening kl.mgmt Kd/KLNL, #kl_cfg_exporting performs Steps 3 and 4:
1. Process the architected content:
  1. saved_MDH ← K(i).MDH, len_AD ← 1
  2. K(i).MDH.State ← kl_cfg_exporting
  3. AD[0] ← saved_MDH (no need to mask ADSDropped: it is zero in a fully configured locker).
  4. foreach(j from 0 to 10) do:
    
    If saved_MDH.Locality names Locality #j (Table 9), then
    
    AD[len_AD] ← LST_eff[j], len_AD ← len_AD + 1
  5. n1 ← SCC_ClearLen1 for saved_MDH (Rule GR9); foreach(j from 0 to n1 − 1) do:
    
    AD[len_AD] ← K(i).Content1_PT[j], len_AD ← len_AD + 1
  6. len_PC ← the number of 128-bit blocks of Content1, minus n1.
  7. SIV, Content1_CT[] ←
    SCC_Encrypt(AD, 0,
    K(i).Content1_PT[n1..n1+len_PC-1], CSK, len_AD, len_PC)
2. If AuxDataLen ≥ 2, process the implementation-specific content:
  1. len_AD2 ← 2,
    AD2[0] ← IMPQUAL ← the IMPQUAL of the implementation (AuxDataLen and ADSDropped Fields), formed from the values of mklvendorid, mklarchid and mklimpid out of KLE unit reset, AD2[1] ← SIV.
  2. n2 ← SCC_ClearLen2 for saved_MDH and IMPQUAL (Rule GR9); foreach(j from 0 to n2 − 1) do:
    
    AD2[len_AD2] ← K(i).Content2_PT[j], len_AD2 ← len_AD2 + 1
  3. len_PC2 ← AuxDataLen − 2 − n2, the number of 128-bit blocks of Content2 that are encrypted.
  4. SIV2, Content2_CT[] ←
    SCC_Encrypt(AD2, 1, K(i).Content2_PT[n2..n2+len_PC2-1], CSK, len_AD2, len_PC2)
A loop of kl.store or kl.mvout instructions saves the serialized image S (serialized image) at offset 16 of the SCC buffer:
1. If AuxDataLen = 0, S = SIV ‖ Content1_CL ‖ Content1_CT, where Content1_CL is Content1_PT[0..n1-1].
2. Otherwise, S = SIV ‖ IMPQUAL ‖ SIV2 ‖ Content1_CL ‖ Content1_CT ‖ Content2_CL ‖ Content2_CT, where Content2_CL is Content2_PT[0..n2-1], and any of the four parts may be empty.
3. Store S to memory.
The completing kl.mgmt restores the locker as Export-Completing kl.mgmt specifies.

An export completed prematurely fails authentication at import (Decryption and Authentication of a Complete SCC into a Locker) with overwhelming probability, and an import completed prematurely fails it at once; an operation left incomplete keeps the locker in a Configuration State, in which most instructions fail.

Decryption and Authentication of a Complete SCC into a Locker

The following algorithm imports the SCC of a fully configured locker. For an SCC whose MDH is in an Error State, use the method of Export and Import of a Locker in an Error State.

Importing a Fully Configured Locker K(i)

Step 1: Read M, the MDH of the SCC, from memory, in the byte order of Endianness.
The import-opening kl.mgmt Kd/KLNL, #kl_cfg_importing, Vs/Xs, with M in Vs or Xs, performs the following Steps:
1. Clear and deallocate K(i), and zeroize SIV, IMPQUAL and SIV2.
2. Make the opening checks of Provisioning- and Import-Opening kl.mgmt on M, stopping with their outcome if one fails.
3. K(i).MDH ← M, with K(i).MDH.ADSDropped ← 1 if M.Version is not 3, M.AuxDataLen ≥ 2, and either M.ADSDropped = 1 or M.AuxDataLen exceeds the implementation’s maximum for the Machine, and ← 0 otherwise.
4. Determine the SCC layout from K(i).MDH.
5. Set the appropriate Configuration State according to Provisioning- and Import-Opening kl.mgmt.
A loop around kl.load/kl.mvin instructions performs the following step:
1. Load the rest of the SCC from its offset 16, to the length that the working MDH gives: with ADSDropped = 1, SIV, IMPQUAL, SIV2 and Content1, but no Content2.
The completing kl.mgmt decrypts and authenticates the SCC and makes it available to software:
1. saved_MDH ← the MDH image held in K(i), that is M with the working ADSDropped and its State field restored from the auxiliary operand of the completing kl.mgmt.
2. AD[0] ← saved_MDH, len_AD ← 1. SCC_Decrypt clears ADSDropped in its local copy of AD[0] before authenticating it; the MDH held in K(i) is unchanged by that computation.
3. foreach (j from 0 to 10) do:
  1. If saved_MDH.Locality names Locality #j (Table 9), then:
    
    AD[len_AD] ← LST_eff[j], len_AD ← len_AD + 1
4. n1 ← SCC_ClearLen1 for saved_MDH (Rule GR9);
5. foreach (j from 0 to n1 − 1) do:
  1. AD[len_AD] ← K(i).Content1[j], len_AD ← len_AD + 1; then len_PC ← the number of 128-bit blocks of Content1, minus n1.
6. correct, K(i).Content1[n1..n1+len_PC-1] ←
  SCC_Decrypt(AD, 0, SIV,
  K(i).Content1[n1..n1+len_PC-1], CSK, len_AD, len_PC).
7. If correct ≠ true, the SCC is rejected: K(i) transitions to Error State kl_stateext_mgmt_auth (Authentication Failed, Rule GR15), and the remaining steps are skipped.
8. If K(i).MDH.AuxDataLen ≥ 2 and K(i).MDH.ADSDropped = 0, process the implementation-specific content:
  1. len_AD2 ← 2, AD2[0] ← K(i).IMPQUAL, AD2[1] ← SIV.
  2. If K(i).IMPQUAL = the IMPQUAL of the implementation (AuxDataLen and ADSDropped Fields), formed from the values of mklvendorid, mklarchid and mklimpid out of KLE unit reset, then:
    
    n2 ← SCC_ClearLen2 for saved_MDH and K(i).IMPQUAL (Rule GR9);
    
    foreach (j from 0 to n2 − 1) do:
    
    AD2[len_AD2] ← K(i).Content2[j], len_AD2 ← len_AD2 + 1.
    
    len_PC2 ← K(i).MDH.AuxDataLen − 2 − n2, the number of encrypted 128-bit blocks of Content2.
    
    correct, K(i).Content2[n2..n2+len_PC2-1] ←
    SCC_Decrypt(AD2, 1, SIV2,
    K(i).Content2[n2..n2+len_PC2-1], CSK, len_AD2, len_PC2).
  3. else:
    
    correct ← false.
  4. If correct ≠ true, then:
    
    drop Content2 and set K(i).MDH.ADSDropped to 1.
9. If K(i).MDH.AuxDataLen = 0 or K(i).MDH.ADSDropped = 1:
  1. Zero the implementation-defined subfields of the MDH (MachineUse and AuxInfo Fields);
  2. ADSDropped ← 0; and
  3. AuxDataLen ← 0 (it may be set to at least 2 again if the implementation generates a replacement ADS right away).

Design Rationale for the Sealing Construction

This section is informative.

Omitting the nonce shrinks the payload and lets the derived keys be cached; the nonce-misuse resistance of AES-GCM-SIV keeps the construction secure for up to O(2⁶⁴) blocks observed by an adversary. On cloud servers, each virtual machine and supervisor domain should have its own CSK; M-mode firmware moves a CC between them by importing its SCC under the source CSK and exporting it under the target CSK.

The SIV, the GCM-SIV tag, is the encryption of the POLYVAL hash (POLYVAL Hashing Function) of the MDH with ADSDropped cleared, the Locality Secrets and the Content. Including the Locality Secrets in the SIV, instead of deriving keys from them, binds the SCC to the Localities for one Montmul per block, far less than most KDFs, and keeps the keys cacheable, since a change of the set derives no new keys. Distinct sets give the same SIV with probability at most max(len_AD + len_PC) × 2^-126, the maximum taken over the two sets. Taking SIV as AD2[1] makes SIV2 and the second keystream depend on the first payload, so an ADS cannot be grafted onto another SCC. As in AES-GCM-SIV, bit 127 separates tag inputs from keystream inputs; bit 126 separates the keystreams of the two segments, at the cost of one bit of security.

The clear blocks (Rule GR9) are associated data, but the POLYVAL input is the same as if they were encrypted; the authenticated MDH and IMPQUAL fix their number, so the lengths stay implied and the bound above holds. Leaving public fields unencrypted saves one AES-256 evaluation per clear block at export and at import, and lets software read them from the SCC. They are restricted to values that their role makes public because an export is not gated by UsagePolicy (UsagePolicy Field), and because a clear block is readable on any device and after the CC expires; which fields are clear depends on no value that a kl.rstrl or a transition changes, so a field that held a secret never becomes clear.

Export and Import of a Locker in an Error State

A locker in an Error State is only an MDH (Rule GR15) and uses no KLF capacity. Its import checks the MDH as any supplied MDH (Validity of Metadata). There is no Content to encrypt, and KLE does not authenticate the MDH: any software in the current environment can produce any Error State by issuing kl.setste, so authentication would prove nothing. Neither direction produces an SCC or a PCCC, opens a management operation, uses SIV, SIV2 or IMPQUAL, or takes part in resumption.

Exporting such a locker needs no kl.mgmt: kl.getst (kl.getst and kl.getstx) finds an Error State, and kl.getmd or kl.getmdv (kl.getmd, kl.getmdl, and kl.getmdv) reads the MDH, which software stores; kl.size reports 16. A kl.mgmt with #immed7 = kl_cfg_exporting on such a locker is permitted but useless: it leaves the locker unchanged and opens no management operation, and only its common steps take effect, klnamedlocker naming the locker and klstart becoming 0 (Locker Management Operations).

Importing the image takes one uninterruptible kl.mgmt with #immed7 = kl_cfg_importing and the 16-byte MDH as the auxiliary operand, carried whole by Form C or D. It zeroizes the locker that it names; if the MDH is invalid Metadata (Validity of Metadata), it transitions the locker to Error State Invalid, as any import does; otherwise the MDH is installed as is, with only AuxDataLen and ADSDropped set to 0 (Rule GR15), and nothing else is transferred. A kl.mgmt with #immed7 = kl_cfg_management_end is not needed after it, and performs no operation (Rule GR13.2).

Architectural Requirements on the Context Sealing Key

The KLE unit operates only with an active Context Sealing Key (CSK): with a hardwired CSK it is available from reset, otherwise once the CSK is established. Without an active CSK, every KLE instruction and KLE CSR access raises a KLE missing-CSK exception, except writes to the mklcsk group and accesses to the Locality Secret CSR groups (Locality Secret CSR Groups), which are configured independently of the CSK.

Each hart holds a CSK, established in exactly one of four ways:

M-mode programs it through the mklcsk CSR group (mklcsk CSR Group); M-mode can then read it in clear, and no software can read it in any other way.
A secure hardware block exclusive to M-mode, such as Caliptra cite:[caliptra], or a port to one, configures it through a dedicated interface based on public-key encryption, at the request of M-mode only, by a handle or a wrapped key; addressing and key transport are platform-specific and outside the scope of this specification.
It is hardwired at manufacturing time and cannot be reconfigured or revoked.
A secure RBG (Prerequisites) generates it at boot. All harts of a subsystem of an SoC that the platform defines and documents hold the same such CSK, so that processes can migrate among them, and cannot exchange SCCs with other subsystems; the CSK survives the reset or fatal condition of a single hart and is regenerated only at the power-on reset of the subsystem, so the SCCs sealed under it cannot be imported after a power loss.

The third and fourth ways mainly suit specialized embedded deployments. Harts among which processes or CCs migrate must hold the same CSK: under the first and second ways, M-mode establishes it on each. A hart reset or a KLE fatal condition (Error Handling Architecture) resets the hart’s KLE state (KLE Unit Reset and M-mode-only Harts) and, under the first and second ways only, its CSK, which must then be established again.

When the CSK is shared across devices, CCs meant to be device-bound need to name ChipScrt or DevScrt in their Locality.

Persistence of a configurable CSK is implementation-specific. Transferring a CSK to another endpoint, such as the M-mode firmware of another device, a local TPM (for instance across suspension or host hibernation), or a cloud-based HSM, requires an authenticated public-key wrapping mechanism, which this specification does not define.

KLE Unprivileged State out of Reset

This section and KLE Privileged State out of Reset are authoritative for the KLE state out of reset:

all lockers are in State Unconfigured, with zeroized contents;
with Zklio, kliobuflen = 0 (the KLIOBUF is unconfigured), kliobuftop = 0, and the KLIOBUF is zeroized;
klstart = 0;
klnamedlocker = 32; and
the three authentication registers of The Cryptographic Locker File and Authentication Information are zero.

KLE Unit Reset and M-mode-only Harts

A KLE unit reset of a hart resets that hart’s KLE architectural state (KLE Unprivileged State out of Reset, KLE Privileged State out of Reset) and no other hart’s, and leaves shared Locality Secrets unchanged. A hart reset causes one, and so does a fatal condition (Error Handling Architecture), with the differences of KLE Privileged State out of Reset. It also unconfigures a CSK established under the first or second way (Architectural Requirements on the Context Sealing Key); it neither clears nor regenerates a hardwired or boot-generated CSK.

A non-retentive hart suspend is not a hart reset. Whether it retains the KLE state of the hart (lockers, KLIOBUF, CSRs and authentication registers) is implementation-defined, and retention is strongly recommended; an implementation documents whether and how it retains that state, and software that cannot rely on retention exports its lockers before the suspend (Software Guidelines).

On an M-mode-only hart, every software-programmable Locality Secret whose CSR group is not implemented is unconfigured (Locality Field), and KLS is treated as Initial where the KLE Privileged Architecture is not implemented; Privileged Architecture states which of its CSRs may exist on such a hart.