encodekey128

Encode 128-bit Key

ENCODEKEY128 r32, r32

Wraps a 128-bit AES key into a handle.

Details

Wraps a 128-bit AES key into an encoded Key Locker handle, where the second r32 operand contains the key and the first r32 receives status/handle information. The ZF flag is set to indicate success (ZF=0) or failure (ZF=1). This instruction requires KEYLOCKER support and uses the internal wrapping key loaded by LOADIWKEY.

Pseudocode Operation

IF CPUID.KEYLOCKER = 0 THEN #UD FI;
key_material ← src[31:0];
handle_out ← AES_WRAP_128(key_material, INTERNAL_WRAPPING_KEY);
dest[31:0] ← handle_out;
ZF ← 0;

Example

ENCODEKEY128 eax, eax

Encoding

Binary Layout

Format Legacy

Opcode F3 0F 38 FA

Extension KEYLOCKER

Operands

dest
32-bit general-purpose register (e.g. EAX)
src
32-bit general-purpose register (e.g. EAX)

Reference (Intel® SDM)

Instruction Forms

Opcode	Instruction	Op/En	64/32-bit Mode	CPUID	Description
F3 0F 38 FA 11:rrr:bbb	ENCODEKEY128 r32, r32, <XMM0-2>, <XMM4-6>	A	V/V	AESKLE	Wrap a 128-bit AES key from XMM0 into a key handle and output handle in XMM0—2.

Instruction Operand Encoding

Op/En	Operand 1	Operand 2	Operand 3	Operand 4	Operand 5	Operand 6
A	N/A	ModRM:reg (w)	ModRM:r/m (r)	Implicit XMM0 (r, w)	Implicit XMM1—2 (w)	Implicit XMM4—6 (w)

Description

The ENCODEKEY1281 instruction wraps a 128-bit AES key from the implicit operand XMM0 into a key handle that is then stored in the implicit destination operands XMM0-2. The explicit source operand specifies handle restrictions, if any. The explicit destination operand is populated with information on the source of the key and its attributes. XMM4 through XMM6 are reserved for future usages and software should not rely upon them being zeroed.

Operation

ENCODEKEY128
#GP (0) if a reserved bit2 in SRC[31:0] is set
InputKey[127:0] := XMM0;
KeyMetadata[2:0] = SRC[2:0];
KeyMetadata[23:3] = 0;          // Reserved for future usage
KeyMetadata[27:24] = 0;        // KeyType is AES-128 (value of 0)
KeyMetadata[127:28] = 0;       // Reserved for future usage

// KeyMetadata is the AAD input and InputKey is the Plaintext input for WrapKey128
Handle[383:0] := WrapKey128(InputKey[127:0], KeyMetadata[127:0], IWKey.Integrity Key[127:0], IWKey.Encryption Key[255:0]);

DEST[0] := IWKey.NoBackup;
DEST[4:1] := IWKey.KeySource[3:0];
DEST[31:5] = 0;
XMM0 := Handle[127:0];    // AAD
XMM1 := Handle[255:128]; // Integrity Tag
XMM2 := Handle[383:256]; // CipherText
XMM4 := 0;  // Reserved for future usage
XMM5 := 0;  // Reserved for future usage
XMM6 := 0;  // Reserved for future usage
RFLAGS.OF, SF, ZF, AF, PF, CF := 0;

Intel C/C++ Compiler Intrinsic Equivalent

ENCODEKEY128  unsigned int _mm_encodekey128_u32(unsigned int htype, __m128i key, void* h);
Exceptions (All Operating Modes)
#GP                     If reserved bit is set in source register value.
#UD                     If the LOCK prefix is used.
If CPUID.07H.00H:ECX.KEY_LOCKER[23] = 0.
If CR4.KL = 0.
If CPUID.19H:EBX.AESKLE[0] = 0.
If CR0.EM = 1.
If CR4.OSFXSR = 0.
#NM                    If CR0.TS = 1.
ENCODEKEY128—Encode 128-Bit Key With Key Locker                                                                                         Vol. 2A 3-284

Flags Affected

All arithmetic flags (OF, SF, ZF, AF, PF, CF) are cleared to 0. Although they are cleared for the currently defined operations, future extensions may report information in the flags. 1. Further details on Key Locker and usage of this instruction can be found here: https://software.intel.com/content/www/us/en/develop/download/intel-key-locker-specification.html. 2. SRC[31:3] are currently reserved for future usages. SRC[2], which indicates a no-decrypt restriction, is reserved if CPUID.19H:EAX[2] is 0. SRC[1], which indicates a no-encrypt restriction, is reserved if CPUID.19H:EAX[1] is 0. SRC[0], which indicates a CPL0-only restriction, is reserved if CPUID.19H:EAX[0] is 0. ENCODEKEY128—Encode 128-Bit Key With Key Locker Vol. 2A 3-283