Difference between revisions of "SPL services"

From Nintendo Switch Brew
Jump to navigation Jump to search
Line 73: Line 73:
  
 
== GetConfig ==
 
== GetConfig ==
Takes a u32 ('''ConfigItem'''), and returns a u64 ('''ConfigVal''').
+
Takes a u32 ('''ConfigItem'''), and returns one or more u64s ('''ConfigVal''').
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
Line 79: Line 79:
 
! ConfigItem || Name
 
! ConfigItem || Name
 
|-
 
|-
| 1 || DisableProgramVerification
+
| 1 || [[#DisableProgramVerification]]
 
|-
 
|-
| 2 || MemoryConfiguration
+
| 2 || [[#DRAMId]]
 
|-
 
|-
| 3 || SecurityEngineIRQNumber
+
| 3 || [[#SecurityEngineIRQNumber]]
 
|-
 
|-
| 4 || Version (returns the current [[Package2#Versions|Package1 Maxver Constant]] - 1).
+
| 4 || [[#Version]]
 
|-
 
|-
| 5 || HardwareType (0=Icosa (nx-abca2), 1=Copper (nx-abcb))
+
| 5 || [[#HardwareType]]
 
|-
 
|-
| 6 || IsRetail
+
| 6 || [[#IsRetail]]
 
|-
 
|-
| 7 || IsRecoveryBoot
+
| 7 || [[#IsRecoveryBoot]]
 
|-
 
|-
| 8 || DeviceId (byte7 clear)
+
| 8 || [[#DeviceId]]
 
|-
 
|-
| 9 || BootReason
+
| 9 || [1.0.0-4.0.0] BootReason
 
|-
 
|-
 
| 10 || MemoryArrange
 
| 10 || MemoryArrange
 
|-
 
|-
| 11 || IsDebugMode
+
| 11 || [[#IsDebugMode]]
 
|-
 
|-
| 12 || KernelMemoryConfiguration
+
| 12 || [[#KernelMemoryConfiguration]]
 
|-
 
|-
| 13 || BatteryProfile
+
| 13 || [[#BatteryProfile]]
 
|-
 
|-
| 14 || [4.0.0+] FUSE_RESERVED_ODM4 bit 10
+
| 14 || [4.0.0+] [[#Unknown0]]
 
|-
 
|-
| 15 || [5.0.0+] Always 0
+
| 15 || [5.0.0+] Unknown1
 
|-
 
|-
| 16 || [5.0.0+] IsNewSoc?
+
| 16 || [5.0.0+] [[#IsT214]]
 
|-
 
|-
| 17 || [5.0.0+] Package2Meta
+
| 17 || [5.0.0+] [[#Package2Hash]]
 
|}
 
|}
  
[[Process Manager services|PM]] checks id1 and if non-zero, calls fsp-pr SetEnabledProgramVerification(false).
+
=== DisableProgramVerification ===
 +
[[Process Manager services|PM]] checks this item and if non-zero, calls fsp-pr SetEnabledProgramVerification(false).
  
[[PCV_services|PCV]] configures memory profiles based on id2.
+
=== DRAMId ===
 +
This is extracted directly from [[Fuse_registers#FUSE_RESERVED_ODM4|FUSE_RESERVED_ODM4]].
 +
 
 +
[[PCV_services|PCV]] configures memory profiles based on DRAMId.
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
Line 122: Line 126:
 
!  Version @ 40800
 
!  Version @ 40800
 
!  Revision
 
!  Revision
id2
+
DRAMId
 
|-
 
|-
 
|  jetson-tx1
 
|  jetson-tx1
Line 156: Line 160:
 
|}
 
|}
  
=== Hardware Types ===
+
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 [[Package2#Versions|Package1 Maxver Constant]] - 1.
 +
 
 +
=== HardwareType ===
 +
[1.0.0+] This item is obtained by checking bits 8 and 2 from [[Fuse_registers#FUSE_RESERVED_ODM4|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_registers#FUSE_RESERVED_ODM4|FUSE_RESERVED_ODM4]]. It can be 0 (Icosa), 1 (Copper), 3 (Unknown) 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_registers#FUSE_RESERVED_ODM4|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_services|NIM]] checks if this item matches the [[Settings_services|set:cal]] DeviceId with byte7 cleared. If they don't match, a panic is thrown.
 +
 
 +
=== 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.
  
nx-abcb is the SDEV unit. Among other differences, this has extra hardware to support HDMI output.
+
[2.0.0+] This is also used with certain debug [[SVC|SVCs]].
  
nx-abca2 hardware types are variations of the retail form factor.
+
[3.0.0+] [[Loader services|RO]] checks this and if set then skipping NRR rsa signatures is allowed.
  
=== Notes ===
+
=== 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.
  
SPL uses id3 for setting up the security engine IRQ.
+
=== BatteryProfile ===
 +
This tells if the TI Charger (bq24192) is active.
  
[[NIM_services|NIM]] checks that id8 output must match the [[Settings_services|set:cal]] DeviceId with byte7 cleared, otherwise panic.
+
=== IsT214 ===
 +
This item is obtained from [[Fuse_registers#FUSE_RESERVED_ODM2|FUSE_RESERVED_ODM2]] if bit 11 from [[Fuse_registers#FUSE_RESERVED_ODM4|FUSE_RESERVED_ODM4]] is set, [[Fuse_registers#FUSE_RESERVED_ODM0|FUSE_RESERVED_ODM0]] matches 0x8E61ECAE and [[Fuse_registers#FUSE_RESERVED_ODM1|FUSE_RESERVED_ODM1]] matches 0xF2BA3BB2.
  
[3.0.0+] [[Loader services|RO]] checks id11, if set then skipping NRR rsa signatures is allowed.
+
This is speculated to be related to the new SoC T214.
  
Kernel uses id11 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 [[SVC|SVCs]].
+
=== Unknown0 ===
 +
This item is bit 10 from [[Fuse_registers#FUSE_RESERVED_ODM4|FUSE_RESERVED_ODM4]].
  
Kernel reads id12 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.
+
=== Package2Hash ===
 +
This is a SHA-256 hash calculated over the [[Package2|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 ==
 
== UserExpMod ==

Revision as of 20:23, 14 March 2018

csrng

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

Cmd Name
0 #GetRandomBytes

GetRandomBytes

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

spl:

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

[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 Notes
0 #GetConfig Wrapper for GetConfig SMC.
1 #UserExpMod Speculative name. Wrapper for ExpMod SMC.
2 #GenerateAesKek Wrapper for GenerateAesKek SMC.
3 #LoadAesKey Wrapper for LoadAesKey SMC.
4 #GenerateAesKey Decrypts 0x10 bytes using AES ECB and uses LoadAesKey SMC with a fixed Y.
5 #SetConfig Wrapper for SetConfig SMC.
7 #GetRandomBytes Uses GetRandomBytes SMC.
9 #LoadSecureExpModKey Speculative name. Wrapper for LoadSecureExpModKey SMC.
10 #SecureExpMod Speculative name. Uses SecureExpModSMC.
11 #IsDevelopment
12 #GenerateSpecificAesKey Wrapper for GenerateSpecificAesKey SMC.
13 #DecryptPrivk Speculative name. Wrapper for PrivateRsa SMC.
14 #DecryptAesKey Decrypts 0x10 bytes using AES ECB and uses LoadAesKey SMC with fixed X and Y.
15 #DecryptAesCtr Wrapper for CryptAes SMC.
16 #ComputeCmac Wrapper for ComputeCmac SMC.
17 #LoadRsaOaepKey Speculative name. Wrapper for LoadRsaOaepKey SMC.
18 #UnwrapRsaOaepWrappedTitleKey Speculative name. Wrapper for UnwrapRsaOaepWrappedTitleKey SMC.
19 #LoadTitleKey Wrapper for LoadTitleKey SMC.
20 [2.0.0+] #UnwrapAesWrappedTitleKey Wrapper for UnwrapAesWrappedTitleKey SMC.
21 [2.0.0+] #LockAesEngine
22 [2.0.0+] #UnlockAesEngine
23 [2.0.0+] #GetSplWaitEvent
24 [3.0.0+] #SetSharedData
25 [3.0.0+] #GetSharedData

GetConfig

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 #BatteryProfile
14 [4.0.0+] #Unknown0
15 [5.0.0+] Unknown1
16 [5.0.0+] #IsT214
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.

PCV configures memory profiles based on DRAMId.

Platform Version @ 40800 Revision DRAMId
jetson-tx1 11_40800_01_V9.8.3_V1.6 N/A N/A
nx-abcb 10_40800_NoCfgVersion_V9.8.4_V1.6 0 0
nx-abca2 10_40800_NoCfgVersion_V9.8.7_V1.6 0 0 or 3
nx-abca2 10_40800_NoCfgVersion_V9.8.7_V1.6 1 4
nx-abca2 10_40800_NoCfgVersion_V9.8.7_V1.6 2 1
nx-abca2 10_40800_NoCfgVersion_V9.8.7_V1.6 3 2

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 (Unknown) 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.

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.

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.

BatteryProfile

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

IsT214

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.

This is speculated to be related to the new SoC T214.

Unknown0

This item is bit 10 from FUSE_RESERVED_ODM4.

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

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

Takes a 16-byte EKS (Encryption Key Source) and two words (KeyGeneration and option) as input. KeyGeneration ranges from 0 to 2.

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

LoadAesKey

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 enc_key with a key generated from the supplied key_x and a fixed key_y.

[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

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

ConfigItem Name
13 BatteryProfile

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

LoadRsaOaepKey

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

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 #UnwrapRsaOaepWrappedTitleKey and the supplied mod_in_buf. Afterwards, verifies RSA-OAEP encoding using label_hash_in_buf.

Returns an u32 (dec_data_size).

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

Takes a 16-byte seed (key_seed) and two words (KeyGeneration and option) as input. KeyGeneration ranges from 0 to 2.

Returns a scrambled key (key_a).

DecryptPrivk

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.

DecryptAesKey

Takes a 16-byte encrypted key (enc_key) and two words (KeyGeneration and option) as input. KeyGeneration ranges from 0 to 2.

Decrypts enc_key with a key generated from fixed key_x and key_y 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).

Decrypts 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

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.

LoadSecureExpModKey

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.

SecureExpMod

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

Decrypts 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.

LoadTitleKey

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

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.