Difference between revisions of "SPL services"

From Nintendo Switch Brew
Jump to navigation Jump to search
(consistency)
(47 intermediate revisions by 8 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.
 +
 
= csrng =
 
= csrng =
 +
This is "nn::spl::detail::IRandomInterface".
 +
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
 
! 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 a type-6 buffer and fills it with random data from [[SMC#GetRandomBytes|GetRandomBytes SMC]]. Same command for "spl:" and "csrng" services.
  
−
= spl: =
+
= spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu =
−
[2.0.0+] Where previously only one AES engine was utilized, there is now support for 4 of them.
+
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+] When the session closes, all AES engines that were locked are automatically unlocked.
+
[2.0.0+] Where previously only one AES keyslot was used, there is now support for 4 of them.
 +
 
 +
[2.0.0+] When the session closes, all allocated AES keyslots are automatically freed.
  
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
−
! Cmd || Name || Notes
+
! Cmd || Name || Permissions
−
|-
 
−
| 0 || [[#GetConfig]] || Wrapper for [[SMC#GetConfig|GetConfig]].
 
−
|-
 
−
| 1 || [[#UserExpMod]] || User supplied modulus and exponent.
 
−
|-
 
−
| 2 || [[#GenerateAesKek]] || Wrapper for [[SMC#KeygenAndSealX|KeygenAndSealX]].
 
 
|-
 
|-
−
| 3 || [[#LoadAesKey]] || Wrapper for [[SMC#SetKeyslotFromXY|SetKeyslotFromXY]].
+
| 0 || [[#GetConfig]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 4 || [[#GenerateAesKey]] || Decrypts 0x10 bytes using AES ECB and uses [[SMC#SetKeyslotFromXY|SetKeyslotFromXY]] with a fixed Y.
+
| 1 || [[#ExpMod]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 5 || [[#SetConfig]] || Wrapper for [[SMC#SetConfig|SetConfig]].
+
| 2 || [[#GenerateAesKek]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 7 || [[#GetRandomBytes]] || Uses [[SMC#PrngX931|PrngX931]].
+
| 3 || [[#LoadAesKey]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 9 || [[#DecryptImportPrivkForExpMod0]] || Wrapper for [[SMC#ImportParamsForFWithXY|ImportParamsForFWithXY]].
+
| 4 || [[#GenerateAesKey]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 10 || [[#ExpMod0]] || Wrapper for [[SMC#ExpMod|ExpMod]].
+
| 5 || [[#SetConfig]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 11 || [[#IsDevelopment]] ||
+
| 7 || [[#GenerateRandomBytes]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 12 || [[#GenerateSpecificAesKey]] || Wrapper for [[SMC#KeygenA|KeygenA]].
+
| 9 || [[#ImportLotusKey]] || spl:fs
 
|-
 
|-
−
| 13 || [[#DecryptPrivk]] || Wrapper for [[SMC#DecryptExpModParamsWithXY|DecryptExpModParamsWithXY]].
+
| 10 || [[#DecryptLotusMessage]] || spl:fs
 
|-
 
|-
−
| 14 || [[#DecryptAesKey]] || Decrypts 0x10 bytes using AES ECB and uses [[SMC#SetKeyslotFromXY|SetKeyslotFromXY]] with fixed X and Y.
+
| 11 || [[#IsDevelopment]] || spl:, spl:mig, spl:fs, spl:ssl spl:es, spl:manu
 
|-
 
|-
−
| 15 || [[#DecryptAesCtr]] || Wrapper for [[SMC#SymmetricCrypto|SymmetricCrypto]].
+
| 12 || [[#GenerateSpecificAesKey]] || spl:fs
 
|-
 
|-
−
| 16 || [[#ComputeCmac]] || Wrapper for [[SMC#CMAC|CMAC]].
+
| 13 || [[#DecryptRsaPrivateKey]] || spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 17 || [[#DecryptImportPrivkForExpMod1]] || Wrapper for [[SMC#ImportParamsFor10WithXY|ImportParamsFor10WithXY]].
+
| 14 || [[#DecryptAesKey]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 18 || [[#ExpMod1]] || Wrapper for [[SMC#ExpModAndKeygenAndSealZ|ExpModAndKeygenAndSealZ]].
+
| 15 || [[#CryptAesCtr]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 19 || [[#LoadRsaKey]] || Wrapper for [[SMC#SetKeyslotFromZ|SetKeyslotFromZ]].
+
| 16 || [[#ComputeCmac]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 20 || [2.0.0+] [[#GenerateRsaKek]] || Wrapper for [[SMC#KeygenAndSealZ|KeygenAndSealZ]].
+
| 17 || [[#ImportEsKey]] || spl:es
 
|-
 
|-
−
| 21 || [2.0.0+] [[#LockAesEngine]] ||
+
| 18 || [[#UnwrapTitleKey]] || spl:es
 
|-
 
|-
−
| 22 || [2.0.0+] [[#UnlockAesEngine]] ||
+
| 19 || [[#LoadTitleKey]] || spl:fs
 
|-
 
|-
−
| 23 || [2.0.0+] [[#GetSplWaitEvent]] ||
+
| 20 || [2.0.0+] [[#UnwrapCommonTitleKey]] || spl:es
−
|}
 
−
 
 
−
== GetConfig ==
 
−
Takes a u32 ('''ConfigItem'''), and returns a u64 ('''ConfigVal''').
 
−
 
 
−
{| class="wikitable" border="1"
 
 
|-
 
|-
−
! ConfigItem || Name
+
| 21 || [2.0.0+] [[#AllocateAesKeyslot]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 1 || DisableProgramVerification
+
| 22 || [2.0.0+] [[#FreeAesKeyslot]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 2 || MemoryConfiguration
+
| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 3 || Returns 0x2C?
+
| 24 || [3.0.0+] [[#SetBootReason]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 4 || Returns 0x02?
+
| 25 || [3.0.0+] [[#GetBootReason]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
 
|-
 
|-
−
| 5 || HardwareType (0=Icosa, 1=Copper)
+
| 26 || [5.0.0+] ImportSslKey || spl:ssl
 
|-
 
|-
−
| 6 || IsRetail
+
| 27 || [5.0.0+] SslExpMod || spl:ssl
 
|-
 
|-
−
| 7 || IsRecoveryBoot
+
| 28 || [5.0.0+] ImportDrmKey || spl:es
 
|-
 
|-
−
| 8 || DeviceId (byte7 clear)
+
| 29 || [5.0.0+] DrmExpMod || spl:es
 
|-
 
|-
−
| 9 || BootReason
+
| 30 || [5.0.0+] ReEncryptRsaPrivateKey || spl:manu
 
|-
 
|-
−
| 10 || MemoryArrange
+
| 31 || [5.0.0+] GetPackage2Hash || spl:fs
 
|-
 
|-
−
| 11 || IsDebugMode
+
| 31 || [6.0.0+] UnwrapElicenseKey || spl:es
 
|-
 
|-
−
| 12 || KernelMemoryConfiguration
+
| 32 || [6.0.0+] [[#LoadElicenseKey]] || spl:es
−
|-
 
−
| 13 || BatteryProfile
 
 
|}
 
|}
  
 +
== GetConfig ==
 +
Wrapper for [[SMC#GetConfig|GetConfig SMC]].
  
−
[[PCV_services|PCV]] configures memory profiles based on id2.
+
Takes a u32 ('''ConfigItem'''), and returns one or more u64s ('''ConfigVal''').
−
{| class="wikitable" border="1"
 
−
|-
 
−
!  Platform
 
−
!  Version
 
−
!  Revision
 
−
!  id2
 
−
|-
 
−
|  "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
 
−
|-
 
−
|}
 
  
 +
== ExpMod ==
 +
Wrapper for [[SMC#ExpMod|ExpMod SMC]].
  
−
[[Process Manager services|PM]] checks id1 and if non-zero, calls fsp-pr SetEnabledProgramVerification(false).
 
−
 
−
[[NIM_services|NIM]] checks that id8 output must match the [[Settings_services|set:cal]] DeviceId with byte7 cleared, otherwise panic.
 
−
 
−
[3.0.0+] [[Loader services|RO]] checks id11, if set then skipping NRR rsa signatures is allowed.
 
−
 
−
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.
 
−
 
−
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.
 
−
 
−
== 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''').
 
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''').
  
Line 156: Line 105:
  
 
== GenerateAesKek ==
 
== GenerateAesKek ==
 +
Wrapper for [[SMC#GenerateAesKek|GenerateAesKek SMC]].
 +
 
Takes a 16-byte EKS ('''Encryption Key Source''') and two words ('''KeyGeneration''' and '''option''') as input.
 
Takes a 16-byte EKS ('''Encryption Key Source''') and two words ('''KeyGeneration''' and '''option''') as input.
−
'''KeyGeneration''' ranges from 0 to 2.
 
  
−
Returns an hardware scrambled sealed KEK ('''Key Encryption Key''' used as '''key_x''').
+
Returns a scrambled sealed KEK ('''Key Encryption Key''' used as '''key_x''').
  
 
== LoadAesKey ==
 
== LoadAesKey ==
 +
Wrapper for [[SMC#LoadAesKey|LoadAesKey SMC]].
 +
 
Takes a u32 ('''keyslot''') and two 16-byte keys ('''key_x''' and '''key_y''').
 
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'''.
 
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.
+
[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 ==
 
== GenerateAesKey ==
 
Takes a 16-byte KEK ('''key_x''') and a 16-byte encrypted key ('''enc_key''').
 
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'''.
+
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 [[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+] 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 ==
 
== SetConfig ==
 +
Wrapper for [[SMC#SetConfig|SetConfig SMC]].
 +
 
Takes a u32 ('''ConfigItem''') and a u64 ('''ConfigVal''').
 
Takes a u32 ('''ConfigItem''') and a u64 ('''ConfigVal''').
  
Line 182: Line 136:
 
! ConfigItem || Name
 
! ConfigItem || Name
 
|-
 
|-
−
| 13 || BatteryProfile
+
| 13 || IsChargerHiZModeEnabled
 
|}
 
|}
  
 
Any other '''ConfigItem''', besides 13, can't be set.
 
Any other '''ConfigItem''', besides 13, can't be set.
  
−
== DecryptImportPrivkForExpMod0 ==
+
== ImportLotusKey ==
 +
Wrapper for [[SMC#ImportLotusKey|ImportLotusKey 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''').
 
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 or 1.
+
'''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.
 
Decrypts '''enc_privk_in_buf''' with a key generated from '''key_x''' and '''key_y''' and imports it for later usage.
  
−
== ExpMod0 ==
+
[5.0.0+] The '''version''' param was removed, and this now calls [[SMC#ReEncryptRsaPrivateKey|ReEncryptRsaPrivateKey SMC]] instead.
−
Takes one type-10 (C descriptor) buffer ('''data_out_buf''') and 3 type-9 (X descriptor) buffers ('''data_in_buf''', '''param0_in_buf''' and '''param1_in_buf''').
 
  
−
Decrypts '''data_in_buf''' into '''data_out_buf''' using the private key imported with [[#DecryptImportPrivkForExpMod0]] and the supplied buffers '''param0_in_buf''' and '''param1_in_buf'''.
+
== DecryptLotusMessage ==
 +
Takes 3 type-9 (X descriptor) buffers ('''data_in_buf''', '''mod_in_buf''' and '''label_hash_in_buf''').
  
−
Returns and unknown u32.
+
Uses [[SMC#SecureExpMod|SecureExpMod SMC]] to decrypt '''data_in_buf''' using the private key imported with [[#ImportLotusKey]] and the supplied '''mod_in_buf''' and '''label_hash_in_buf'''.
  
 
== IsDevelopment ==
 
== IsDevelopment ==
Line 208: Line 164:
  
 
== GenerateSpecificAesKey ==
 
== GenerateSpecificAesKey ==
 +
Wrapper for [[SMC#GenerateSpecificAesKey|GenerateSpecificAesKey SMC]].
 +
 
Takes a 16-byte seed ('''key_seed''') and two words ('''KeyGeneration''' and '''option''') as input.
 
Takes a 16-byte seed ('''key_seed''') and two words ('''KeyGeneration''' and '''option''') as input.
−
'''KeyGeneration''' ranges from 0 to 2.
 
  
−
Returns an hardware scrambled (unsealed?) key ('''key_a''').
+
Returns a scrambled key ('''key_a''').
 +
 
 +
== DecryptRsaPrivateKey ==
 +
Wrapper for [[SMC#DecryptRsaPrivateKey|DecryptRsaPrivateKey SMC]].
  
−
== 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''').
 
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 or 1.
+
'''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'''.
 
Decrypts '''enc_privk_in_buf''' into '''dec_privk_out_buf''' with a key generated from '''key_x''' and '''key_y'''.
  
 
Used by [[SSL_services|SSL]]-sysmodule for TLS client-privk.
 
Used by [[SSL_services|SSL]]-sysmodule for TLS client-privk.
 +
 +
[5.0.0+] The '''version''' param was removed, and this now calls [[SMC#DecryptOrImportRsaPrivateKey|DecryptOrImportRsaPrivateKey SMC]] instead.
  
 
== DecryptAesKey ==
 
== DecryptAesKey ==
 
Takes a 16-byte encrypted key ('''enc_key''') and two words ('''KeyGeneration''' and '''option''') as input.
 
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''').
+
Decrypts (AES-ECB) '''enc_key''' with a key generated from fixed '''key_x''' and '''key_y''' set with [[SMC#LoadAesKey|LoadAesKey SMC]] and returns a 16-byte decrypted key ('''dec_key''').
  
−
[2.0.0+] Introduced same engine allocation code as for [[#GenerateAesKey]].
+
[2.0.0+] Introduced same keyslot allocation code as for [[#GenerateAesKey]].
  
−
== DecryptAesCtr ==
+
== CryptAesCtr ==
 
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''').
 
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'''.
+
Uses [[SMC#ComputeAes|ComputeAes 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.
+
[2.0.0+] Verifies the keyslot was allocated in the current session.
  
 
== ComputeCmac ==
 
== ComputeCmac ==
 +
Wrapper for [[SMC#ComputeCmac|ComputeCmac SMC]].
 +
 
Takes one type-9 (X descriptor) buffer ('''data_in_buf''') and a u32 ('''type?''').
 
Takes one type-9 (X descriptor) buffer ('''data_in_buf''') and a u32 ('''type?''').
  
 
Returns a 16-byte CMAC calculated over '''data_in_buf'''.
 
Returns a 16-byte CMAC calculated over '''data_in_buf'''.
  
−
[2.0.0+] Verifies the engine is locked by current session.
+
[2.0.0+] Verifies the keyslot was allocated in the current session.
 +
 
 +
== ImportEsKey ==
 +
Wrapper for [[SMC#ImportEsKey|ImportEsKey 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+] The '''version''' param was removed, and this now calls [[SMC#ReEncryptRsaPrivateKey|ReEncryptRsaPrivateKey SMC]] instead.
 +
 
 +
== UnwrapTitleKey ==
 +
Wrapper for [[SMC#UnwrapTitleKey|UnwrapTitleKey SMC]].
  
−
== DecryptImportPrivkForExpMod1 ==
+
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''').
−
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 or 1.
+
[3.0.0+] Now takes an additional 4-bytes of input.
  
−
Decrypts '''enc_privk_in_buf''' with a key generated from '''key_x''' and '''key_y''' and imports it for later usage.
+
Decrypts '''data_in_buf''' into '''data_out_buf''' using the private key imported with [[#ImportEsKey]] and the supplied '''mod_in_buf'''. Afterwards, verifies RSA-OAEP encoding using '''label_hash_in_buf'''.
  
−
== ExpMod1 ==
+
Returns an u32 ('''dec_data_size''').
−
Takes 3 type-9 (X descriptor) buffers ('''data_in_buf''', '''param0_in_buf''' and '''param1_in_buf''').
 
  
−
Decrypts '''data_in_buf''' using the private key imported with [[#DecryptImportPrivkForExpMod1]] and the supplied buffers '''param0_in_buf''' and '''param1_in_buf'''.
+
== LoadTitleKey ==
 +
Wrapper for [[SMC#LoadTitleKey|LoadTitleKey SMC]].
  
−
Generates and returns a 16-byte key ('''key_z''').
+
Takes a u32 ('''keyslot''') and a 16-byte sealed titlekey.
  
−
== LoadRsaKey ==
+
Sets the specified '''keyslot''' with the titlekey.
−
Takes a u32 ('''keyslot''') and a 16-byte key ('''key_z''').
 
  
−
Sets the specified '''keyslot''' with a key generated from '''key_z'''.
+
[2.0.0+] Verifies the keyslot was allocated in the current session.
  
−
[2.0.0+] Verifies the engine is locked by current session.
+
== UnwrapCommonTitleKey ==
 +
Wrapper for [[SMC#UnwrapCommonTitleKey|UnwrapCommonTitleKey SMC]].
  
−
== GenerateRsaKek ==
 
 
Takes a 16-byte EKS ('''Encryption Key Source''').
 
Takes a 16-byte EKS ('''Encryption Key Source''').
  
−
Returns an hardware scrambled sealed KEK ('''Key Encryption Key''' used as '''key_z''').
+
[3.0.0+] Now takes an additional 4-bytes of input.
 +
 
 +
Returns a sealed titlekey.
 +
 
 +
== AllocateAesKeyslot ==
 +
Returns an allocated keyslot, or 0xD01A if all keyslots are taken. You need to allocate a keyslot before using AES functions.
 +
 
 +
== FreeAesKeyslot ==
 +
Takes a single u32 and frees the keyslot. The keyslot must have been allocated by current session otherwise 0xD21A will be returned.
 +
 
 +
== GetAesKeyslotAvailableEvent ==
 +
Returns an event handle for synchronizing with the AES keyslots.
 +
 
 +
== SetBootReason ==
 +
Sets a static dword in spl .bss to the input u32 '''BootReason'''.
 +
 
 +
[4.0.0+] returns 0xD41A if a value has been previously set without being [[#GetBootReason|gotten]].
 +
 
 +
== GetBootReason ==
 +
Returns the static dword '''BootReason''' in spl .bss that can be set via [[#SetBootReason]].
  
−
== LockAesEngine ==
+
[4.0.0+] returns 0xD61A if a value has not previously been set, and unsets the value after getting it.
−
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 ==
+
== LoadElicenseKey ==
−
Takes a single u32 and unlocks the engine with that id. It must be owned by current session otherwise 0xD21A will be returned.
+
Same as [[#LoadTitleKey|LoadTitleKey]].
  
−
== GetSplWaitEvent ==
+
[[Category:Services]]
−
Returns an event handle for synchronizing with the locked AES engine.
 

Revision as of 22:43, 15 May 2019

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.

csrng

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

Cmd Name
0 #GenerateRandomBytes

GenerateRandomBytes

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 keyslot was used, there is now support for 4 of them.

[2.0.0+] When the session closes, all allocated AES keyslots are automatically freed.

Cmd Name Permissions
0 #GetConfig spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
1 #ExpMod 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 #GenerateRandomBytes spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
9 #ImportLotusKey spl:fs
10 #DecryptLotusMessage 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 #CryptAesCtr spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
16 #ComputeCmac spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
17 #ImportEsKey spl:es
18 #UnwrapTitleKey spl:es
19 #LoadTitleKey spl:fs
20 [2.0.0+] #UnwrapCommonTitleKey spl:es
21 [2.0.0+] #AllocateAesKeyslot spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
22 [2.0.0+] #FreeAesKeyslot spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
23 [2.0.0+] #GetAesKeyslotAvailableEvent spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
24 [3.0.0+] #SetBootReason spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
25 [3.0.0+] #GetBootReason spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
26 [5.0.0+] ImportSslKey spl:ssl
27 [5.0.0+] SslExpMod spl:ssl
28 [5.0.0+] ImportDrmKey spl:es
29 [5.0.0+] DrmExpMod spl:es
30 [5.0.0+] ReEncryptRsaPrivateKey spl:manu
31 [5.0.0+] GetPackage2Hash spl:fs
31 [6.0.0+] UnwrapElicenseKey spl:es
32 [6.0.0+] #LoadElicenseKey spl:es

GetConfig

Wrapper for GetConfig SMC.

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

ExpMod

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 keyslot in use (0..3) is allocated by the current spl session, otherwise errors with 0xD21A. Previously, keyslot 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 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 a u32 (ConfigItem) and a u64 (ConfigVal).

ConfigItem Name
13 IsChargerHiZModeEnabled

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

ImportLotusKey

Wrapper for ImportLotusKey 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+] The version param was removed, and this now calls ReEncryptRsaPrivateKey SMC instead.

DecryptLotusMessage

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

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

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+] The version param was removed, and this now calls DecryptOrImportRsaPrivateKey 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 keyslot allocation code as for #GenerateAesKey.

CryptAesCtr

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 ComputeAes SMC to decrypt data_in_buf into data_out_buf, using the key set in the specified keyslot.

[2.0.0+] Verifies the keyslot was allocated in the 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 keyslot was allocated in the current session.

ImportEsKey

Wrapper for ImportEsKey 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+] The version param was removed, and this now calls ReEncryptRsaPrivateKey SMC instead.

UnwrapTitleKey

Wrapper for UnwrapTitleKey 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).

[3.0.0+] Now takes an additional 4-bytes of input.

Decrypts data_in_buf into data_out_buf using the private key imported with #ImportEsKey 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 keyslot was allocated in the current session.

UnwrapCommonTitleKey

Wrapper for UnwrapCommonTitleKey SMC.

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

[3.0.0+] Now takes an additional 4-bytes of input.

Returns a sealed titlekey.

AllocateAesKeyslot

Returns an allocated keyslot, or 0xD01A if all keyslots are taken. You need to allocate a keyslot before using AES functions.

FreeAesKeyslot

Takes a single u32 and frees the keyslot. The keyslot must have been allocated by current session otherwise 0xD21A will be returned.

GetAesKeyslotAvailableEvent

Returns an event handle for synchronizing with the AES keyslots.

SetBootReason

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

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

GetBootReason

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

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

LoadElicenseKey

Same as LoadTitleKey.

Retrieved from "https://switchbrew.org/w/index.php?title=SPL_services&oldid=6901"