SPL services

SPL is responsible for handling all cryptographic operations within the system and relaying them to the Secure Monitor when necessary.

During [1.0.0-3.0.2], the only existing services were "csrng" and "spl:". However, in [4.0.0+] the "spl:" service was refactored and split into new services with different permission levels. Each service exposes the IPC command list differently in order to prevent cryptographic operations to take place in the wrong context.

csrng

This is "nn::spl::detail::IRandomInterface".

Cmd	Name
0	#GetRandomBytes

GetRandomBytes

Takes a type-6 buffer and fills it with random data from GetRandomBytes SMC. Same command for "spl:" and "csrng" services.

spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu

These are "nn::spl::detail::IGeneralInterface", "nn::spl::detail::ICryptoInterface", "nn::spl::detail::IFsInterface", "nn::spl::detail::ISslInterface", "nn::spl::detail::IEsInterface" and "nn::spl::detail::IManuInterface"(?).

[2.0.0+] Where previously only one AES engine was utilized, there is now support for 4 of them.

[2.0.0+] When the session closes, all AES engines that were locked are automatically unlocked.

Cmd	Name	Permissions
0	#GetConfig	spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
1	#UserExpMod	spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
2	#GenerateAesKek	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
3	#LoadAesKey	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
4	#GenerateAesKey	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
5	#SetConfig	spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
7	#GetRandomBytes	spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
9	#LoadSecureExpModKey	spl:fs
10	#SecureExpMod	spl:fs
11	#IsDevelopment	spl:, spl:mig, spl:fs, spl:ssl spl:es, spl:manu
12	#GenerateSpecificAesKey	spl:fs
13	#DecryptRsaPrivateKey	spl:ssl, spl:es, spl:manu
14	#DecryptAesKey	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
15	#DecryptAesCtr	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
16	#ComputeCmac	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
17	#LoadRsaOaepKey	spl:es
18	#UnwrapRsaOaepWrappedTitleKey	spl:es
19	#LoadTitleKey	spl:fs
20	[2.0.0+] #UnwrapAesWrappedTitleKey	spl:es
21	[2.0.0+] #LockAesEngine	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
22	[2.0.0+] #UnlockAesEngine	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
23	[2.0.0+] #GetSplWaitEvent	spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
24	[3.0.0+] #SetSharedData	spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
25	[3.0.0+] #GetSharedData	spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
26	[5.0.0+] ImportSslRsaKey	spl:ssl
27	[5.0.0+] SecureExpModWithSslKey	spl:ssl
28	[5.0.0+] ImportEsRsaKey	spl:es
29	[5.0.0+] SecureExpModWithEsKey	spl:es
30	[5.0.0+] EncryptManuRsaKeyForImport	spl:manu
31	[5.0.0+] GetPackage2Hash	spl:fs

GetConfig

Wrapper for GetConfig SMC.

Takes a u32 (ConfigItem), and returns one or more u64s (ConfigVal).

ConfigItem	Name
1	#DisableProgramVerification
2	#DramId
3	#SecurityEngineIrqNumber
4	#Version
5	#HardwareType
6	#IsRetail
7	#IsRecoveryBoot
8	#DeviceId
9	[1.0.0-4.0.0] #BootReason
10	#MemoryArrange
11	#IsDebugMode
12	#KernelMemoryConfiguration
13	#IsChargerHiZModeEnabled
14	[4.0.0+] #IsKiosk
15	[5.0.0+] #NewHardwareType
16	[5.0.0+] #NewKeyGeneration
17	[5.0.0+] #Package2Hash

DisableProgramVerification

PM checks this item and if non-zero, calls fsp-pr SetEnabledProgramVerification(false).

DramId

This is extracted directly from FUSE_RESERVED_ODM4.

Value	Description
0	DramId_EristaIcosaSamsung4gb
1	DramId_EristaIcosaHynix4gb
2	DramId_EristaIcosaMicron4gb
3	Reserved
4	DramId_EristaIcosaSamsung6gb
5	[5.0.0+] Reserved
6	[5.0.0+] Reserved
7	[5.0.0+] DramId_MarikoIowax1x2Samsung4gb
8	[5.0.0+] DramId_MarikoIowaSamsung4gb
9	[5.0.0+] DramId_MarikoIowaSamsung8gb
10	[5.0.0+] Reserved
11	[5.0.0+] Reserved
12	[5.0.0+] DramId_MarikoHoagSamsung4gb
13	[5.0.0+] DramId_MarikoHoagSamsung8gb

PCV configures memory profiles based on DramId.

Platform	DramId	Version
jetson-tx1	N/A	11_40800_01_V9.8.3_V1.6
nx-abcb	EristaIcosaSamsung4gb	10_40800_NoCfgVersion_V9.8.7_V1.6
nx-abcb	EristaIcosaMicron4gb	10_40800_NoCfgVersion_V9.8.4_V1.6
nx-abcb	EristaIcosaHynix4gb	10_40800_NoCfgVersion_V9.8.4_V1.6
nx-abca2	EristaIcosaSamsung4gb or EristaIcosaMicron4gb	10_40800_NoCfgVersion_V9.8.7_V1.6
nx-abca2	EristaIcosaHynix4gb	10_40800_NoCfgVersion_V9.8.7_V1.6
nx-abca2	EristaIcosaSamsung6gb	10_40800_NoCfgVersion_V9.8.7_V1.6
nx-abca2	MarikoIowax1x2Samsung4gb	01_204000_NoCfgVersion_V0.3.1_V2.0
nx-abca2	MarikoIowaSamsung4gb or MarikoHoagSamsung4gb	01_204000_NoCfgVersion_V0.3.1_V2.0
nx-abca2	MarikoIowaSamsung8gb or MarikoHoagSamsung8gb	01_204000_NoCfgVersion_V0.4.2_V2.0

nx-abcb (Copper) is the SDEV unit. Among other differences, this has extra hardware to support HDMI output.

nx-abca2 (Icosa) hardware types are variations of the retail form factor.

SecurityEngineIrqNumber

SPL uses this for setting up the security engine IRQ.

Version

The current Package1 Maxver Constant - 1.

HardwareType

[1.0.0+] This item is obtained by checking bits 8 and 2 from FUSE_RESERVED_ODM4. It can be 0 (Icosa), 1 (Copper) or 3 (Invalid).

[4.0.0+] This item is obtained by checking bits 8, 2 and 16-19 from FUSE_RESERVED_ODM4. It can be 0 (Icosa), 1 (Copper), 3 (Mariko) or 4 (Invalid).

A value of 2 (Hoag?) is always mapped to 4 (Invalid).

IsRetail

This item is obtained by checking bits 9 and 0-1 from FUSE_RESERVED_ODM4. It can be 0 (Debug), 1 (Retail) or 2 (Invalid).

IsRecoveryBoot

Used to determine if the system is booting from SafeMode firmware.

DeviceId

NIM checks if this item matches the set:cal DeviceId with byte7 cleared. If they don't match, a panic is thrown.

BootReason

Used to determine how the system booted.

MemoryArrange

PM uses this item for selecting the appropriate size for each LimitableResource_Memory.

IsDebugMode

Kernel uses this to determine behavior of svcBreak positive arguments. It will break instead of just force-exiting the process which is what happens on retail.

[2.0.0+] This is also used with certain debug SVCs.

[3.0.0+] RO checks this and if set then skipping NRR rsa signatures is allowed.

The value of this field is loaded from BootConfig unsigned-config+0x10 u8 bit1.

KernelMemoryConfiguration

Kernel reads this when setting up memory-related code. If bit0 is set, it will memset various allocated memory-regions with 0x58, 0x59, 0x5A ('X', 'Y', 'Z') instead of zero. This allows Nintendo devs to find uninitialized memory bugs. If bit17-16 is 0b01, the kernel assumes 6GB of DRAM instead of 4GB.

IsChargerHiZModeEnabled

This tells if the TI Charger (bq24192) is active.

NewKeyGeneration

This item is obtained from FUSE_RESERVED_ODM2 if bit 11 from FUSE_RESERVED_ODM4 is set, FUSE_RESERVED_ODM0 matches 0x8E61ECAE and FUSE_RESERVED_ODM1 matches 0xF2BA3BB2.

[5.0.0+] FS can now use this value for the KeyGeneration parameter when calling GenerateAesKek during "GetBisEncryptionKey".

IsKiosk

This item is bit 10 from FUSE_RESERVED_ODM4.

[4.0.0+] Settings uses this value to overwrite the quest flag from GetQuestFlag. This is used to detect if a Switch is a kiosk unit for display at retail stores.

NewHardwareType

This item is currently hardcoded to 0.

[5.0.0+] PCV overrides the value from HardwareType and configures PMIC devices with this item.

Value	Devices
0	max77620_sd0, max77621_cpu and max77621_gpu
1	max77620_sd0, max77812_cpu and max77812_gpu
2	max77620_sd0, max77812_cpu and max77812_gpu

Package2Hash

This is a SHA-256 hash calculated over the package2 image. Since the hash calculation is an optional step in pkg2ldr, this item is only valid in recovery mode. Otherwise, an error is returned instead.

UserExpMod

Wrapper for ExpMod SMC.

Takes one type-10 (C descriptor) buffer (data_out_buf) and 3 type-9 (X descriptor) buffers (data_in_buf, exp_in_buf and mod_in_buf).

Performs asymmetric crypto with user supplied modulus and exponent.

GenerateAesKek

Wrapper for GenerateAesKek SMC.

Takes a 16-byte EKS (Encryption Key Source) and two words (KeyGeneration and option) as input.

Returns a scrambled sealed KEK (Key Encryption Key used as key_x).

LoadAesKey

Wrapper for LoadAesKey SMC.

Takes a u32 (keyslot) and two 16-byte keys (key_x and key_y).

Sets the specified keyslot with a key generated from key_x and key_y.

[2.0.0+] Now verifies that the engine in use (0..3) is locked/owned by the current spl session, otherwise errors with 0xD21A. Previously engine was hardcoded to 0.

GenerateAesKey

Takes a 16-byte KEK (key_x) and a 16-byte encrypted key (enc_key).

Generates a new key by decrypting (AES-ECB) enc_key with a key generated from the supplied key_x and a fixed key_y set with LoadAesKey SMC.

[2.0.0+] Previously, it always used engine 0. Now it tries to allocate an engine to be used and returns 0xD01A if they're all busy. When the command is done, the engine is released.

SetConfig

Wrapper for SetConfig SMC.

Takes a u32 (ConfigItem) and a u64 (ConfigVal).

ConfigItem	Name
13	BatteryProfile

Any other ConfigItem, besides 13, can't be set.

LoadSecureExpModKey

Wrapper for LoadSecureExpModKey SMC.

Takes one type-9 (X descriptor) buffer (enc_privk_in_buf), a 16-byte KEK (key_x), a 16-byte key (key_y) and a u32 (version). version is 0 for normal keys or 1 for extended keys.

Decrypts enc_privk_in_buf with a key generated from key_x and key_y and imports it for later usage.

[5.0.0+] This now calls EncryptRsaKeyForImport SMC instead.

SecureExpMod

Takes 3 type-9 (X descriptor) buffers (data_in_buf, mod_in_buf and param0_in_buf).

Uses SecureExpMod SMC to decrypt data_in_buf using the private key imported with #LoadSecureExpModKey and the supplied mod_in_buf and param0_in_buf.

Generates and returns a 16-byte sealed titlekey.

IsDevelopment

No input params.

Uses #GetConfig internally with id=6. Returns true if output from that is 0, or if the SMC returned error 2.

Returns an u8 flag for whether the system is devunit. Output flag is 0 on retail.

GenerateSpecificAesKey

Wrapper for GenerateSpecificAesKey SMC.

Takes a 16-byte seed (key_seed) and two words (KeyGeneration and option) as input.

Returns a scrambled key (key_a).

DecryptRsaPrivateKey

Wrapper for DecryptRsaPrivateKey SMC.

Takes one type-10 (C descriptor) buffer (dec_privk_out_buf), one type-9 (X descriptor) buffer (enc_privk_in_buf), a 16-byte KEK (key_x), a 16-byte key (key_y) and a u32 (version). version is 0 for normal keys or 1 for extended keys.

Decrypts enc_privk_in_buf into dec_privk_out_buf with a key generated from key_x and key_y.

Used by SSL-sysmodule for TLS client-privk.

[5.0.0+] This now calls DecryptOrImportRsaKey SMC instead.

DecryptAesKey

Takes a 16-byte encrypted key (enc_key) and two words (KeyGeneration and option) as input.

Decrypts (AES-ECB) enc_key with a key generated from fixed key_x and key_y set with LoadAesKey SMC and returns a 16-byte decrypted key (dec_key).

[2.0.0+] Introduced same engine allocation code as for #GenerateAesKey.

DecryptAesCtr

Takes a type-0x46 (B descriptor) buffer (data_out_buf), a u32 (keyslot), a type-0x45 (A descriptor) buffer (data_in_buf) and a 16-byte CTR (aes_ctr).

Uses CryptAes SMC to decrypt data_in_buf into data_out_buf, using the key set in the specified keyslot.

[2.0.0+] Verifies the engine is locked by current session.

ComputeCmac

Wrapper for ComputeCmac SMC.

Takes one type-9 (X descriptor) buffer (data_in_buf) and a u32 (type?).

Returns a 16-byte CMAC calculated over data_in_buf.

[2.0.0+] Verifies the engine is locked by current session.

LoadRsaOaepKey

Wrapper for LoadRsaOaepKey SMC.

Takes one type-9 (X descriptor) buffer (enc_privk_in_buf), a 16-byte KEK (key_x), a 16-byte key (key_y) and a u32 (version). version is 0 for normal keys or 1 for extended keys.

Decrypts enc_privk_in_buf with a key generated from key_x and key_y and imports it for later usage.

UnwrapRsaOaepWrappedTitleKey

Wrapper for UnwrapRsaOaepWrappedTitleKey SMC.

Takes one type-10 (C descriptor) buffer (data_out_buf) and 3 type-9 (X descriptor) buffers (data_in_buf, mod_in_buf and label_hash_in_buf).

Decrypts data_in_buf into data_out_buf using the private key imported with #LoadRsaOaepKey and the supplied mod_in_buf. Afterwards, verifies RSA-OAEP encoding using label_hash_in_buf.

Returns an u32 (dec_data_size).

LoadTitleKey

Wrapper for LoadTitleKey SMC.

Takes a u32 (keyslot) and a 16-byte sealed titlekey.

Sets the specified keyslot with the titlekey.

[2.0.0+] Verifies the engine is locked by current session.

UnwrapAesWrappedTitleKey

Wrapper for UnwrapAesWrappedTitleKey SMC.

Takes a 16-byte EKS (Encryption Key Source).

Returns a sealed titlekey.

LockAesEngine

Returns the id of the engine that was locked, or 0xD01A if all engines are busy. You need to lock an engine before using AES functions.

UnlockAesEngine

Takes a single u32 and unlocks the engine with that id. It must be owned by current session otherwise 0xD21A will be returned.

GetSplWaitEvent

Returns an event handle for synchronizing with the locked AES engine.

SetSharedData

Sets a static dword in spl .bss to the user input u32.

[4.0.0+] returns 0xD41A if a value has been previously set without being gotten.

GetSharedData

Returns the static dword in spl .bss that can be set via #SetSharedData.

[4.0.0+] returns 0xD61A if a value has not previously been set, and unsets the value after getting it.