Difference between revisions of "SPL services"

From Nintendo Switch Brew
Jump to navigation Jump to search
(Confirmed)
 
(24 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
SPL ("Secure Platform services") is responsible for handling all cryptographic operations within the system and relaying them to the [[SMC|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.
 +
 +
In [2.0.0+] where previously only one AES keyslot was used, there is now support for 4 of them and when the session closes, all allocated AES keyslots are automatically freed.
 +
 
= csrng =
 
= csrng =
 
This is "nn::spl::detail::IRandomInterface".
 
This is "nn::spl::detail::IRandomInterface".
Line 6: Line 12:
 
! Cmd || Name
 
! Cmd || Name
 
|-
 
|-
| 0 || [[#GetRandomBytes]]
+
| 0 || [[#GenerateRandomBytes]]
 
|}
 
|}
  
== GetRandomBytes ==
+
== GenerateRandomBytes ==
Takes a type-6 buffer and fills it with random data. Same command for "spl:" and "csrng" services.
+
Takes an output type-0xA buffer and fills it with random data from [[SMC#GenerateRandomBytes|GenerateRandomBytes SMC]]. Same command for "spl:" and "csrng" services, except for buffer-type.
  
 
= spl: =
 
= spl: =
 
This is "nn::spl::detail::IGeneralInterface".
 
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.
 
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
! Cmd || Name || Notes
+
! Cmd || Name
 
|-
 
|-
| 0 || [[#GetConfig]] || Wrapper for [[SMC#GetConfig|GetConfig SMC]].
+
| 0 || [[#GetConfig]]
 
|-
 
|-
| 1 || [[#UserExpMod]] || Speculative name. Wrapper for [[SMC#ExpMod|ExpMod SMC]].
+
| 1 || [[#ModularExponentiate]]
 
|-
 
|-
| 2 || [[#GenerateAesKek]] || Wrapper for [[SMC#GenerateAesKek|GenerateAesKek SMC]].
+
| 5 || [[#SetConfig]]
 
|-
 
|-
| 3 || [[#LoadAesKey]] || Wrapper for [[SMC#LoadAesKey|LoadAesKey SMC]].
+
| 7 || [[#GenerateRandomBytes]]
 
|-
 
|-
| 4 || [[#GenerateAesKey]] || Decrypts 0x10 bytes using AES ECB and uses [[SMC#LoadAesKey|LoadAesKey SMC]] with a fixed Y.
+
| 11 || [[#IsDevelopment]]
 
|-
 
|-
| 5 || [[#SetConfig]] || Wrapper for [[SMC#SetConfig|SetConfig SMC]].
+
| 24 || [3.0.0+] [[#SetBootReason]]
 
|-
 
|-
| 7 || [[#GetRandomBytes]] || Uses [[SMC#GetRandomBytes|GetRandomBytes SMC]].
+
| 25 || [3.0.0+] [[#GetBootReason]]
|-
 
| 9 || [[#LoadSecureExpModKey]] || Speculative name. Wrapper for [[SMC#LoadSecureExpModKey|LoadSecureExpModKey SMC]].
 
|-
 
| 10 || [[#SecureExpMod]] || Speculative name. Uses [[SMC#SecureExpMod|SecureExpModSMC]].
 
|-
 
| 11 || [[#IsDevelopment]] ||
 
|-
 
| 12 || [[#GenerateSpecificAesKey]] || Wrapper for [[SMC#GenerateSpecificAesKey|GenerateSpecificAesKey SMC]].
 
|-
 
| 13 || [[#DecryptPrivk]] || Speculative name. Wrapper for [[SMC#PrivateRsa|PrivateRsa SMC]].
 
|-
 
| 14 || [[#DecryptAesKey]] || Decrypts 0x10 bytes using AES ECB and uses [[SMC#LoadAesKey|LoadAesKey SMC]] with fixed X and Y.
 
|-
 
| 15 || [[#DecryptAesCtr]] || Wrapper for [[SMC#CryptAes|CryptAes SMC]].
 
|-
 
| 16 || [[#ComputeCmac]] || Wrapper for [[SMC#ComputeCmac|ComputeCmac SMC]].
 
|-
 
| 17 || [[#LoadRsaOaepKey]] || Speculative name. Wrapper for [[SMC#LoadRsaOaepKey|LoadRsaOaepKey SMC]].
 
|-
 
| 18 || [[#UnwrapRsaOaepWrappedTitleKey]] || Speculative name. Wrapper for [[SMC#UnwrapRsaOaepWrappedTitleKey|UnwrapRsaOaepWrappedTitleKey SMC]].
 
|-
 
| 19 || [[#LoadTitleKey]] || Wrapper for [[SMC#LoadTitleKey|LoadTitleKey SMC]].
 
|-
 
| 20 || [2.0.0+] [[#UnwrapAesWrappedTitleKey ]] || Wrapper for [[SMC#UnwrapAesWrappedTitleKey|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 ==
 
== GetConfig ==
Takes a u32 ('''ConfigItem'''), and returns one or more u64s ('''ConfigVal''').
+
Wrapper for [[SMC#GetConfig|GetConfig SMC]].
  
{| class="wikitable" border="1"
+
Takes an input u32 '''ConfigItem'''. Returns one or more output u64s '''ConfigValue'''.
|-
 
! 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+] [[#NewKeyGeneration]]
 
|-
 
| 17 || [5.0.0+] [[#Package2Hash]]
 
|}
 
  
=== DisableProgramVerification ===
+
== ModularExponentiate ==
[[Process Manager services|PM]] checks this item and if non-zero, calls fsp-pr SetEnabledProgramVerification(false).
+
Wrapper for [[SMC#ModularExponentiate|ModularExponentiate SMC]].
  
=== DRAMId ===
+
Takes an output type-0xA buffer '''DataOut''' and 3 input type-0x9 buffers '''DataIn''', '''ExpIn''' and '''ModIn'''.
This is extracted directly from [[Fuse_registers#FUSE_RESERVED_ODM4|FUSE_RESERVED_ODM4]].
 
  
[[PCV_services|PCV]] configures memory profiles based on DRAMId.
+
Performs asymmetric crypto with user supplied modulus and exponent.
{| class="wikitable" border="1"
 
|-
 
!  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.
+
== GenerateAesKek ==
 +
Wrapper for [[SMC#GenerateAesKek|GenerateAesKek SMC]].
  
nx-abca2 (Icosa) hardware types are variations of the retail form factor.
+
Takes an input 16-byte '''KeySource''' and two input u32s '''Generation''' and '''Option'''. Returns an output 16-byte '''AccessKey'''.
  
=== SecurityEngineIRQNumber ===
+
== LoadAesKey ==
SPL uses this for setting up the security engine IRQ.
+
Wrapper for [[SMC#LoadAesKey|LoadAesKey SMC]].
  
=== Version ===
+
Takes an input u32 '''Keyslot''' , an input 16-byte '''AccessKey''' and an input 16-byte '''KeySource'''.
The current [[Package2#Versions|Package1 Maxver Constant]] - 1.
 
  
=== HardwareType ===
+
Sets the specified '''Keyslot''' with a key generated from '''AccessKey''' and '''KeySource'''.
[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 (IcosaMariko) or 4 (Invalid).
+
[2.0.0+] Now verifies that the keyslot in use (0..3) is allocated by the current spl session, otherwise errors with 0xD21A. Previously, keyslot was hardcoded to 0.
  
A value of 2 (Hoag?) is always mapped to 4 (Invalid).
+
== GenerateAesKey ==
 +
Takes an input 16-byte '''AccessKey''' and an input 16-byte '''KeySource'''. Returns an output 16-byte '''AesKey'''.
  
=== IsRetail ===
+
Generates a new key by decrypting (AES-ECB) '''KeySource''' with a key generated from the supplied '''AccessKey''' and the key set with [[SMC#LoadAesKey|LoadAesKey SMC]].
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 ===
+
[2.0.0+] Previously, it always used keyslot 0. Now it tries to allocate a keyslot to be used and returns 0xD01A if they're all busy. When the command is done, the keyslot is released.
Used to determine if the system is booting from SafeMode firmware.
 
  
=== DeviceId ===
+
== SetConfig ==
[[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.
+
Wrapper for [[SMC#SetConfig|SetConfig SMC]].
  
=== MemoryArrange ===
+
Takes an input u32 '''ConfigItem''' and an input u64 '''ConfigValue'''.
[[Process Manager services|PM]] uses this item for selecting the appropriate size for each [[SVC#LimitableResource|LimitableResource_Memory]].
 
  
=== IsDebugMode ===
+
Only '''ConfigItem''' 13 (IsChargerHiZModeEnabled) can be set.
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 [[SVC|SVCs]].
+
== ImportLotusKey ==
 +
Wrapper for [[SMC#DecryptAndImportLotusKey|DecryptAndImportLotusKey SMC]].
  
[3.0.0+] [[Loader services|RO]] checks this and if set then skipping NRR rsa signatures is allowed.
+
Takes an input type-0x9 buffer '''DataIn''', an input 16-byte '''AccessKey''', an input 16-byte '''KeySource''' and an input u32 '''Version''' (0 for normal keys or 1 for extended keys).
  
=== KernelMemoryConfiguration ===
+
Decrypts '''DataIn''' with a key generated from '''AccessKey''' and '''KeySource''' and imports it for later usage.
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 ===
+
[5.0.0+] The '''Version''' argument was removed and this now calls the [[SMC#ReencryptDeviceUniqueData|ReencryptDeviceUniqueData SMC]] instead.
This tells if the TI Charger (bq24192) is active.
 
  
=== NewKeyGeneration ===
+
== DecryptLotusMessage ==
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.
+
Takes 3 input type-0x9 buffers '''DataIn''', '''ModIn''' and '''LabelHashIn'''.
  
[5.0.0+] [[Filesystem services|FS]] can now use this value for the '''KeyGeneration''' parameter when calling [[#GenerateAesKek|GenerateAesKek]] during "GetBisEncryptionKey".
+
Uses the [[SMC#ModularExponentiateByStorageKey|ModularExponentiateByStorageKey SMC]] to decrypt '''DataIn''' using the private key imported with [[#ImportLotusKey]] and the supplied '''ModIn''' and '''LabelHashIn'''.
  
=== Unknown0 ===
+
== IsDevelopment ==
This item is bit 10 from [[Fuse_registers#FUSE_RESERVED_ODM4|FUSE_RESERVED_ODM4]].
+
No input. Returns an output u8 bool.
  
=== Package2Hash ===
+
Uses [[#GetConfig]] internally.
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 ==
+
== GenerateSpecificAesKey ==
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''').
+
Wrapper for [[SMC#GenerateSpecificAesKey|GenerateSpecificAesKey SMC]].
  
Performs asymmetric crypto with user supplied modulus and exponent.
+
Takes an input 16-byte '''KeySource''' and two input u32s '''Generation''' and '''Option'''. Returns an output 16-byte '''AesKey'''.
  
== GenerateAesKek ==
+
== DecryptDeviceUniqueData ==
Takes a 16-byte EKS ('''Encryption Key Source''') and two words ('''KeyGeneration''' and '''option''') as input.
+
Wrapper for [[SMC#DecryptDeviceUniqueData|DecryptDeviceUniqueData SMC]].
'''KeyGeneration''' ranges from 0 to 2.
 
  
Returns a scrambled sealed KEK ('''Key Encryption Key''' used as '''key_x''').
+
Takes an output type-0xA buffer '''DataOut''', an input type-0x9 '''DataIn''', an input 16-byte '''AccessKey''', an input 16-byte '''KeySource''' and an input u32 '''Version''' (0 for normal keys or 1 for extended keys).
  
== LoadAesKey ==
+
Decrypts '''DataIn''' into '''DataOut''' with a key generated from '''AccessKey''' and '''KeySource'''.
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'''.
+
Used by [[SSL_services|SSL]] for TLS client-privk.
  
[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.
+
[5.0.0+] The '''Version''' argument was removed.
  
== GenerateAesKey ==
+
== DecryptAesKey ==
Takes a 16-byte KEK ('''key_x''') and a 16-byte encrypted key ('''enc_key''').
+
Takes an input 16-byte '''KeySource''' and two input u32s '''Generation''' and '''Option'''. Returns an output 16-byte '''AesKey'''.
  
Generates a new key by decrypting '''enc_key''' with a key generated from the supplied '''key_x''' and a fixed '''key_y'''.
+
Decrypts (AES-ECB) '''KeySource''' with a key set with [[SMC#LoadAesKey|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.
+
[2.0.0+] Introduced same keyslot allocation code as for [[#GenerateAesKey]].
  
== SetConfig ==
+
== CryptAesCtr ==
Takes a u32 ('''ConfigItem''') and a u64 ('''ConfigVal''').
+
Takes an output type-0x46 buffer '''DataOut''', an input u32 '''Keyslot''', an input type-0x45 buffer '''DataIn''' and an input 16-byte '''IvCtr'''.
  
{| class="wikitable" border="1"
+
Uses [[SMC#ComputeAes|ComputeAes SMC]] to decrypt '''DataIn''' into '''DataOut''' using the key set in the specified '''Keyslot'''.
|-
 
! ConfigItem || Name
 
|-
 
| 13 || BatteryProfile
 
|}
 
  
Any other '''ConfigItem''', besides 13, can't be set.
+
[2.0.0+] Verifies the keyslot was allocated by the current session.
  
== LoadRsaOaepKey ==
+
== ComputeCmac ==
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''').
+
Wrapper for [[SMC#ComputeCmac|ComputeCmac SMC]].
'''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.
+
Takes an input type-0x9 buffer '''DataIn''' and an input u32 '''Keyslot'''. Returns an output 16-byte '''Cmac'''.
  
== UnwrapRsaOaepWrappedTitleKey ==
+
[2.0.0+] Verifies the keyslot was allocated by the current session.
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'''.
+
== ImportEsKey ==
 +
Wrapper for [[SMC#DecryptAndImportEsDeviceKey|DecryptAndImportEsDeviceKey SMC]].
  
Returns an u32 ('''dec_data_size''').
+
Takes an input type-0x9 buffer '''DataIn''', an input 16-byte '''AccessKey''', an input 16-byte '''KeySource''' and an input u32 '''Version''' (0 for normal keys or 1 for extended keys).
  
== IsDevelopment ==
+
Decrypts '''DataIn''' with a key generated from '''AccessKey''' and '''KeySource''' and imports it for later usage.
No input params.
 
  
Uses [[#GetConfig]] internally with id=6. Returns true if output from that is 0, or if the SMC returned error 2.
+
[5.0.0+] The '''Version''' argument was removed and this now calls the [[SMC#ReencryptDeviceUniqueData|ReencryptDeviceUniqueData SMC]] instead.
  
Returns an u8 flag for whether the system is devunit. Output flag is 0 on retail.
+
== UnwrapTitleKey ==
 +
Wrapper for [[SMC#PrepareEsDeviceUniqueKey|PrepareEsDeviceUniqueKey SMC]].
  
== GenerateSpecificAesKey ==
+
Takes an output type-0xA buffer '''DataOut''' and 3 input type-0x9 buffers '''DataIn''', '''ModIn''' and '''LabelHashIn'''. Returns an output u32 '''DataOutSize'''.
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''').
+
[3.0.0+] Now takes an input u32 '''Generation'''.
  
== DecryptPrivk ==
+
Decrypts '''DataIn''' into '''DataOut''' using the private key imported with [[#ImportEsKey]] and the supplied '''ModIn'''. Afterwards, verifies RSA-OAEP encoding using '''LabelHashIn'''.
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'''.
+
== LoadTitleKey ==
 +
Wrapper for [[SMC#LoadPreparedAesKey|LoadPreparedAesKey SMC]].
  
Used by [[SSL_services|SSL]]-sysmodule for TLS client-privk.
+
Takes an input u32 '''Keyslot''' and an input 16-byte '''AccessKey'''.
  
== DecryptAesKey ==
+
[2.0.0+] Verifies the keyslot was allocated in the current session.
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''').
+
== UnwrapCommonTitleKey ==
 +
Wrapper for [[SMC#PrepareEsCommonKey|PrepareEsCommonKey SMC]].
  
[2.0.0+] Introduced same engine allocation code as for [[#GenerateAesKey]].
+
Takes an input 16-byte '''KeySource'''. Returns an output 16-byte '''AccessKey'''.
  
== DecryptAesCtr ==
+
[3.0.0+] Now takes an input u32 '''Generation'''.
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'''.
+
== AllocateAesKeyslot ==
 +
Returns an output u32 '''Keyslot'''.
  
[2.0.0+] Verifies the engine is locked by current session.
+
Returns error 0xD01A if all keyslots are taken.
  
== ComputeCmac ==
+
== DeallocateAesKeySlot ==
Takes one type-9 (X descriptor) buffer ('''data_in_buf''') and a u32 ('''type?''').
+
Takes an input u32 '''Keyslot'''.
  
Returns a 16-byte CMAC calculated over '''data_in_buf'''.
+
Returns error 0xD21A if the keyslot wasn't allocated by current session.
  
[2.0.0+] Verifies the engine is locked by current session.
+
== GetAesKeyslotAvailableEvent ==
 +
Returns an output event handle for synchronizing with the AES keyslots.
  
== LoadSecureExpModKey ==
+
== SetBootReason ==
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''').
+
Takes an input u32 '''BootReason'''.
'''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.
+
[4.0.0+] Returns 0xD41A if a value has been previously set without being [[#GetBootReason|gotten]].
  
== SecureExpMod ==
+
== GetBootReason ==
Takes 3 type-9 (X descriptor) buffers ('''data_in_buf''', '''mod_in_buf''' and '''param0_in_buf''').
+
Returns an output u32 '''BootReason'''.
  
Decrypts '''data_in_buf''' using the private key imported with [[#LoadSecureExpModKey]] and the supplied '''mod_in_buf''' and '''param0_in_buf'''.
+
[4.0.0+] Returns 0xD61A if a value has not previously been set and unsets the value after getting it.
  
Generates and returns a 16-byte sealed titlekey.
+
== LoadPreparedAesKey ==
 +
Same as [[#LoadTitleKey|LoadTitleKey]].
  
== LoadTitleKey ==
+
= spl:mig =
Takes a u32 ('''keyslot''') and a 16-byte sealed titlekey.
+
This is "nn::spl::detail::ICryptoInterface".
  
Sets the specified '''keyslot''' with the titlekey.
+
{| class="wikitable" border="1"
 +
|-
 +
! Cmd || Name
 +
|-
 +
| 0 || [[#GetConfig]]
 +
|-
 +
| 1 || [[#ModularExponentiate]]
 +
|-
 +
| 5 || [[#SetConfig]]
 +
|-
 +
| 7 || [[#GenerateRandomBytes]]
 +
|-
 +
| 11 || [[#IsDevelopment]]
 +
|-
 +
| 24 || [3.0.0+] [[#SetBootReason]]
 +
|-
 +
| 25 || [3.0.0+] [[#GetBootReason]]
 +
|-
 +
| 2 || [[#GenerateAesKek]]
 +
|-
 +
| 3 || [[#LoadAesKey]]
 +
|-
 +
| 4 || [[#GenerateAesKey]]
 +
|-
 +
| 14 || [[#DecryptAesKey]]
 +
|-
 +
| 15 || [[#CryptAesCtr]]
 +
|-
 +
| 16 || [[#ComputeCmac]]
 +
|-
 +
| 21 || [2.0.0+] [[#AllocateAesKeyslot]]
 +
|-
 +
| 22 || [2.0.0+] [[#DeallocateAesKeySlot]]
 +
|-
 +
| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]
 +
|}
  
[2.0.0+] Verifies the engine is locked by current session.
+
= spl:fs =
 +
This is "nn::spl::detail::IFsInterface".
  
== UnwrapAesWrappedTitleKey ==
+
{| class="wikitable" border="1"
Takes a 16-byte EKS ('''Encryption Key Source''').
+
|-
 +
! Cmd || Name
 +
|-
 +
| 0 || [[#GetConfig]]
 +
|-
 +
| 1 || [[#ModularExponentiate]]
 +
|-
 +
| 5 || [[#SetConfig]]
 +
|-
 +
| 7 || [[#GenerateRandomBytes]]
 +
|-
 +
| 11 || [[#IsDevelopment]]
 +
|-
 +
| 24 || [3.0.0+] [[#SetBootReason]]
 +
|-
 +
| 25 || [3.0.0+] [[#GetBootReason]]
 +
|-
 +
| 2 || [[#GenerateAesKek]]
 +
|-
 +
| 3 || [[#LoadAesKey]]
 +
|-
 +
| 4 || [[#GenerateAesKey]]
 +
|-
 +
| 14 || [[#DecryptAesKey]]
 +
|-
 +
| 15 || [[#CryptAesCtr]]
 +
|-
 +
| 16 || [[#ComputeCmac]]
 +
|-
 +
| 21 || [2.0.0+] [[#AllocateAesKeyslot]]
 +
|-
 +
| 22 || [2.0.0+] [[#DeallocateAesKeySlot]]
 +
|-
 +
| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]
 +
|-
 +
| 9 || [[#ImportLotusKey]]
 +
|-
 +
| 10 || [[#DecryptLotusMessage]]
 +
|-
 +
| 12 || [[#GenerateSpecificAesKey]]
 +
|-
 +
| 19 || [[#LoadTitleKey]]
 +
|-
 +
| 31 || [5.0.0+] GetPackage2Hash
 +
|}
  
Returns a sealed titlekey.
+
= spl:ssl =
 +
This is "nn::spl::detail::ISslInterface".
  
== LockAesEngine ==
+
{| class="wikitable" border="1"
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.
+
|-
 +
! Cmd || Name
 +
|-
 +
| 0 || [[#GetConfig]]
 +
|-
 +
| 1 || [[#ModularExponentiate]]
 +
|-
 +
| 5 || [[#SetConfig]]
 +
|-
 +
| 7 || [[#GenerateRandomBytes]]
 +
|-
 +
| 11 || [[#IsDevelopment]]
 +
|-
 +
| 24 || [3.0.0+] [[#SetBootReason]]
 +
|-
 +
| 25 || [3.0.0+] [[#GetBootReason]]
 +
|-
 +
| 2 || [[#GenerateAesKek]]
 +
|-
 +
| 3 || [[#LoadAesKey]]
 +
|-
 +
| 4 || [[#GenerateAesKey]]
 +
|-
 +
| 14 || [[#DecryptAesKey]]
 +
|-
 +
| 15 || [[#CryptAesCtr]]
 +
|-
 +
| 16 || [[#ComputeCmac]]
 +
|-
 +
| 21 || [2.0.0+] [[#AllocateAesKeyslot]]
 +
|-
 +
| 22 || [2.0.0+] [[#DeallocateAesKeySlot]]
 +
|-
 +
| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]
 +
|-
 +
| 13 || [[#DecryptDeviceUniqueData]]
 +
|-
 +
| 26 || [5.0.0+] DecryptAndStoreSslClientCertKey
 +
|-
 +
| 27 || [5.0.0+] ModularExponentiateWithSslClientCertKey
 +
|}
  
== UnlockAesEngine ==
+
= spl:es =
Takes a single u32 and unlocks the engine with that id. It must be owned by current session otherwise 0xD21A will be returned.
+
This is "nn::spl::detail::IEsInterface".
  
== GetSplWaitEvent ==
+
{| class="wikitable" border="1"
Returns an event handle for synchronizing with the locked AES engine.
+
|-
 +
! Cmd || Name
 +
|-
 +
| 0 || [[#GetConfig]]
 +
|-
 +
| 1 || [[#ModularExponentiate]]
 +
|-
 +
| 5 || [[#SetConfig]]
 +
|-
 +
| 7 || [[#GenerateRandomBytes]]
 +
|-
 +
| 11 || [[#IsDevelopment]]
 +
|-
 +
| 24 || [3.0.0+] [[#SetBootReason]]
 +
|-
 +
| 25 || [3.0.0+] [[#GetBootReason]]
 +
|-
 +
| 2 || [[#GenerateAesKek]]
 +
|-
 +
| 3 || [[#LoadAesKey]]
 +
|-
 +
| 4 || [[#GenerateAesKey]]
 +
|-
 +
| 14 || [[#DecryptAesKey]]
 +
|-
 +
| 15 || [[#CryptAesCtr]]
 +
|-
 +
| 16 || [[#ComputeCmac]]
 +
|-
 +
| 21 || [2.0.0+] [[#AllocateAesKeyslot]]
 +
|-
 +
| 22 || [2.0.0+] [[#DeallocateAesKeySlot]]
 +
|-
 +
| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]
 +
|-
 +
| 13 || [[#DecryptDeviceUniqueData]]
 +
|-
 +
| 17 || [[#ImportEsKey]]
 +
|-
 +
| 18 || [[#UnwrapTitleKey]]
 +
|-
 +
| 20 || [2.0.0+] [[#PrepareEsCommonKey]]
 +
|-
 +
| 28 || [5.0.0+] DecryptAndStoreDrmDeviceCertKey
 +
|-
 +
| 29 || [5.0.0+] ModularExponentiateWithDrmDeviceCertKey
 +
|-
 +
| 31 || [6.0.0+] PrepareEsArchiveKey
 +
|-
 +
| 32 || [6.0.0+] [[#LoadPreparedAesKey]]
 +
|}
  
== SetSharedData ==
+
= spl:manu =
Sets a static dword in spl .bss to the user input u32.
+
This is "nn::spl::detail::IManuInterface".
  
[4.0.0+] returns 0xD41A if a value has been previously set without being [[#GetSharedData|gotten]].
+
{| class="wikitable" border="1"
 
+
|-
== GetSharedData ==
+
! Cmd || Name
Returns the static dword in spl .bss that can be set via [[#SetSharedData]].
+
|-
 +
| 0 || [[#GetConfig]]
 +
|-
 +
| 1 || [[#ModularExponentiate]]
 +
|-
 +
| 5 || [[#SetConfig]]
 +
|-
 +
| 7 || [[#GenerateRandomBytes]]
 +
|-
 +
| 11 || [[#IsDevelopment]]
 +
|-
 +
| 24 || [3.0.0+] [[#SetBootReason]]
 +
|-
 +
| 25 || [3.0.0+] [[#GetBootReason]]
 +
|-
 +
| 2 || [[#GenerateAesKek]]
 +
|-
 +
| 3 || [[#LoadAesKey]]
 +
|-
 +
| 4 || [[#GenerateAesKey]]
 +
|-
 +
| 14 || [[#DecryptAesKey]]
 +
|-
 +
| 15 || [[#CryptAesCtr]]
 +
|-
 +
| 16 || [[#ComputeCmac]]
 +
|-
 +
| 21 || [2.0.0+] [[#AllocateAesKeyslot]]
 +
|-
 +
| 22 || [2.0.0+] [[#DeallocateAesKeySlot]]
 +
|-
 +
| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]
 +
|-
 +
| 13 || [[#DecryptDeviceUniqueData]]
 +
|-
 +
| 30 || [5.0.0+] ReencryptDeviceUniqueData
 +
|}
  
[4.0.0+] returns 0xD61A if a value has not previously been set, and unsets the value after getting it.
+
[[Category:Services]]

Latest revision as of 18:44, 12 May 2020

SPL ("Secure Platform services") 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.

In [2.0.0+] where previously only one AES keyslot was used, there is now support for 4 of them and when the session closes, all allocated AES keyslots are automatically freed.

csrng

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

Cmd Name
0 #GenerateRandomBytes

GenerateRandomBytes

Takes an output type-0xA buffer and fills it with random data from GenerateRandomBytes SMC. Same command for "spl:" and "csrng" services, except for buffer-type.

spl:

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

Cmd Name
0 #GetConfig
1 #ModularExponentiate
5 #SetConfig
7 #GenerateRandomBytes
11 #IsDevelopment
24 [3.0.0+] #SetBootReason
25 [3.0.0+] #GetBootReason

GetConfig

Wrapper for GetConfig SMC.

Takes an input u32 ConfigItem. Returns one or more output u64s ConfigValue.

ModularExponentiate

Wrapper for ModularExponentiate SMC.

Takes an output type-0xA buffer DataOut and 3 input type-0x9 buffers DataIn, ExpIn and ModIn.

Performs asymmetric crypto with user supplied modulus and exponent.

GenerateAesKek

Wrapper for GenerateAesKek SMC.

Takes an input 16-byte KeySource and two input u32s Generation and Option. Returns an output 16-byte AccessKey.

LoadAesKey

Wrapper for LoadAesKey SMC.

Takes an input u32 Keyslot , an input 16-byte AccessKey and an input 16-byte KeySource.

Sets the specified Keyslot with a key generated from AccessKey and KeySource.

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

GenerateAesKey

Takes an input 16-byte AccessKey and an input 16-byte KeySource. Returns an output 16-byte AesKey.

Generates a new key by decrypting (AES-ECB) KeySource with a key generated from the supplied AccessKey and the key set with LoadAesKey SMC.

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

SetConfig

Wrapper for SetConfig SMC.

Takes an input u32 ConfigItem and an input u64 ConfigValue.

Only ConfigItem 13 (IsChargerHiZModeEnabled) can be set.

ImportLotusKey

Wrapper for DecryptAndImportLotusKey SMC.

Takes an input type-0x9 buffer DataIn, an input 16-byte AccessKey, an input 16-byte KeySource and an input u32 Version (0 for normal keys or 1 for extended keys).

Decrypts DataIn with a key generated from AccessKey and KeySource and imports it for later usage.

[5.0.0+] The Version argument was removed and this now calls the ReencryptDeviceUniqueData SMC instead.

DecryptLotusMessage

Takes 3 input type-0x9 buffers DataIn, ModIn and LabelHashIn.

Uses the ModularExponentiateByStorageKey SMC to decrypt DataIn using the private key imported with #ImportLotusKey and the supplied ModIn and LabelHashIn.

IsDevelopment

No input. Returns an output u8 bool.

Uses #GetConfig internally.

GenerateSpecificAesKey

Wrapper for GenerateSpecificAesKey SMC.

Takes an input 16-byte KeySource and two input u32s Generation and Option. Returns an output 16-byte AesKey.

DecryptDeviceUniqueData

Wrapper for DecryptDeviceUniqueData SMC.

Takes an output type-0xA buffer DataOut, an input type-0x9 DataIn, an input 16-byte AccessKey, an input 16-byte KeySource and an input u32 Version (0 for normal keys or 1 for extended keys).

Decrypts DataIn into DataOut with a key generated from AccessKey and KeySource.

Used by SSL for TLS client-privk.

[5.0.0+] The Version argument was removed.

DecryptAesKey

Takes an input 16-byte KeySource and two input u32s Generation and Option. Returns an output 16-byte AesKey.

Decrypts (AES-ECB) KeySource with a key set with LoadAesKey SMC.

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

CryptAesCtr

Takes an output type-0x46 buffer DataOut, an input u32 Keyslot, an input type-0x45 buffer DataIn and an input 16-byte IvCtr.

Uses ComputeAes SMC to decrypt DataIn into DataOut using the key set in the specified Keyslot.

[2.0.0+] Verifies the keyslot was allocated by the current session.

ComputeCmac

Wrapper for ComputeCmac SMC.

Takes an input type-0x9 buffer DataIn and an input u32 Keyslot. Returns an output 16-byte Cmac.

[2.0.0+] Verifies the keyslot was allocated by the current session.

ImportEsKey

Wrapper for DecryptAndImportEsDeviceKey SMC.

Takes an input type-0x9 buffer DataIn, an input 16-byte AccessKey, an input 16-byte KeySource and an input u32 Version (0 for normal keys or 1 for extended keys).

Decrypts DataIn with a key generated from AccessKey and KeySource and imports it for later usage.

[5.0.0+] The Version argument was removed and this now calls the ReencryptDeviceUniqueData SMC instead.

UnwrapTitleKey

Wrapper for PrepareEsDeviceUniqueKey SMC.

Takes an output type-0xA buffer DataOut and 3 input type-0x9 buffers DataIn, ModIn and LabelHashIn. Returns an output u32 DataOutSize.

[3.0.0+] Now takes an input u32 Generation.

Decrypts DataIn into DataOut using the private key imported with #ImportEsKey and the supplied ModIn. Afterwards, verifies RSA-OAEP encoding using LabelHashIn.

LoadTitleKey

Wrapper for LoadPreparedAesKey SMC.

Takes an input u32 Keyslot and an input 16-byte AccessKey.

[2.0.0+] Verifies the keyslot was allocated in the current session.

UnwrapCommonTitleKey

Wrapper for PrepareEsCommonKey SMC.

Takes an input 16-byte KeySource. Returns an output 16-byte AccessKey.

[3.0.0+] Now takes an input u32 Generation.

AllocateAesKeyslot

Returns an output u32 Keyslot.

Returns error 0xD01A if all keyslots are taken.

DeallocateAesKeySlot

Takes an input u32 Keyslot.

Returns error 0xD21A if the keyslot wasn't allocated by current session.

GetAesKeyslotAvailableEvent

Returns an output event handle for synchronizing with the AES keyslots.

SetBootReason

Takes an input u32 BootReason.

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

GetBootReason

Returns an output u32 BootReason.

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

LoadPreparedAesKey

Same as LoadTitleKey.

spl:mig

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

Cmd Name
0 #GetConfig
1 #ModularExponentiate
5 #SetConfig
7 #GenerateRandomBytes
11 #IsDevelopment
24 [3.0.0+] #SetBootReason
25 [3.0.0+] #GetBootReason
2 #GenerateAesKek
3 #LoadAesKey
4 #GenerateAesKey
14 #DecryptAesKey
15 #CryptAesCtr
16 #ComputeCmac
21 [2.0.0+] #AllocateAesKeyslot
22 [2.0.0+] #DeallocateAesKeySlot
23 [2.0.0+] #GetAesKeyslotAvailableEvent

spl:fs

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

Cmd Name
0 #GetConfig
1 #ModularExponentiate
5 #SetConfig
7 #GenerateRandomBytes
11 #IsDevelopment
24 [3.0.0+] #SetBootReason
25 [3.0.0+] #GetBootReason
2 #GenerateAesKek
3 #LoadAesKey
4 #GenerateAesKey
14 #DecryptAesKey
15 #CryptAesCtr
16 #ComputeCmac
21 [2.0.0+] #AllocateAesKeyslot
22 [2.0.0+] #DeallocateAesKeySlot
23 [2.0.0+] #GetAesKeyslotAvailableEvent
9 #ImportLotusKey
10 #DecryptLotusMessage
12 #GenerateSpecificAesKey
19 #LoadTitleKey
31 [5.0.0+] GetPackage2Hash

spl:ssl

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

Cmd Name
0 #GetConfig
1 #ModularExponentiate
5 #SetConfig
7 #GenerateRandomBytes
11 #IsDevelopment
24 [3.0.0+] #SetBootReason
25 [3.0.0+] #GetBootReason
2 #GenerateAesKek
3 #LoadAesKey
4 #GenerateAesKey
14 #DecryptAesKey
15 #CryptAesCtr
16 #ComputeCmac
21 [2.0.0+] #AllocateAesKeyslot
22 [2.0.0+] #DeallocateAesKeySlot
23 [2.0.0+] #GetAesKeyslotAvailableEvent
13 #DecryptDeviceUniqueData
26 [5.0.0+] DecryptAndStoreSslClientCertKey
27 [5.0.0+] ModularExponentiateWithSslClientCertKey

spl:es

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

Cmd Name
0 #GetConfig
1 #ModularExponentiate
5 #SetConfig
7 #GenerateRandomBytes
11 #IsDevelopment
24 [3.0.0+] #SetBootReason
25 [3.0.0+] #GetBootReason
2 #GenerateAesKek
3 #LoadAesKey
4 #GenerateAesKey
14 #DecryptAesKey
15 #CryptAesCtr
16 #ComputeCmac
21 [2.0.0+] #AllocateAesKeyslot
22 [2.0.0+] #DeallocateAesKeySlot
23 [2.0.0+] #GetAesKeyslotAvailableEvent
13 #DecryptDeviceUniqueData
17 #ImportEsKey
18 #UnwrapTitleKey
20 [2.0.0+] #PrepareEsCommonKey
28 [5.0.0+] DecryptAndStoreDrmDeviceCertKey
29 [5.0.0+] ModularExponentiateWithDrmDeviceCertKey
31 [6.0.0+] PrepareEsArchiveKey
32 [6.0.0+] #LoadPreparedAesKey

spl:manu

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

Cmd Name
0 #GetConfig
1 #ModularExponentiate
5 #SetConfig
7 #GenerateRandomBytes
11 #IsDevelopment
24 [3.0.0+] #SetBootReason
25 [3.0.0+] #GetBootReason
2 #GenerateAesKek
3 #LoadAesKey
4 #GenerateAesKey
14 #DecryptAesKey
15 #CryptAesCtr
16 #ComputeCmac
21 [2.0.0+] #AllocateAesKeyslot
22 [2.0.0+] #DeallocateAesKeySlot
23 [2.0.0+] #GetAesKeyslotAvailableEvent
13 #DecryptDeviceUniqueData
30 [5.0.0+] ReencryptDeviceUniqueData