Changes

Jump to navigation Jump to search
9,187 bytes added ,  18:44, 12 May 2020
no edit summary
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 =
This is "nn::spl::detail::IRandomInterface".
 
{| class="wikitable" border="1"
|-
! Cmd || Name
|-
| 0 || [[#GenerateRandomBytes]]
|}
 
== GenerateRandomBytes ==
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: =
This is "nn::spl::detail::IGeneralInterface".
 
{| class="wikitable" border="1"
|-
! Cmd || Name || Notes
|-
| 0 || [[#GetConfig]] || wrapper for [[SMC#GetConfig|GetConfig]]
|-
| 1 || ExpMod || user supplied modulus and exponent[[#ModularExponentiate]]
|-
| 2 5 || [[#KeygenAndSealX]] || wrapper for [[SMC#KeygenAndSealX|KeygenAndSealXSetConfig]]
|-
| 3 7 || SetKeyslotFromXY || wrapper for [[SMC#SetKeyslotFromXY|SetKeyslotFromXYGenerateRandomBytes]]
|-
| 4 11 || [[#IsDevelopment]]|-| 24 || [3.0.0+] [[#SetBootReason]]|-| 25 || [3.0.0+] [[#GetBootReason]]|} == GetConfig ==Wrapper for [[SMC#GetConfig|GetConfig SMC]]. Takes an input u32 '''ConfigItem'''. Returns one or more output u64s '''ConfigValue'''. == ModularExponentiate ==Wrapper for [[SMC#ModularExponentiate|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 [[SMC#GenerateAesKek|GenerateAesKek SMC]]. Takes an input 16-byte '''KeySource''' and two input u32s '''Generation''' and '''Option'''. Returns an output 16-byte '''AccessKey'''. == LoadAesKey ==Wrapper for [[SMC#LoadAesKey|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 [[SMC#LoadAesKey|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 [[SMC#SetConfig|SetConfig SMC]]. Takes an input u32 '''ConfigItem''' and an input u64 '''ConfigValue'''. Only '''ConfigItem''' 13 (IsChargerHiZModeEnabled) can be set. == ImportLotusKey ==Wrapper for [[SMC#DecryptAndImportLotusKey| DecryptAESECBWithX 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 [[SMC#ReencryptDeviceUniqueData|ReencryptDeviceUniqueData SMC]] instead. == DecryptLotusMessage ==Takes 3 input type-0x9 buffers '''DataIn''', '''ModIn''' and '''LabelHashIn'''. Uses the [[SMC#ModularExponentiateByStorageKey| decrypts 0x10 bytes 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 [[SMC#GenerateSpecificAesKey|GenerateSpecificAesKey SMC]]. Takes an input 16-byte '''KeySource''' and two input u32s '''Generation''' and '''Option'''. Returns an output 16-byte '''AesKey'''. == DecryptDeviceUniqueData ==Wrapper for [[SMC#DecryptDeviceUniqueData|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_services|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 [[SMC#LoadAesKey|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''', uses an input type-0x45 buffer '''DataIn''' and an input 16-byte '''IvCtr'''. Uses [[SMC#SetKeyslotFromXYComputeAes|SetKeyslotFromXYComputeAes 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 [[SMC#ComputeCmac|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 [[SMC#DecryptAndImportEsDeviceKey|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 fixed Ykey generated from '''AccessKey''' and '''KeySource''' and imports it for later usage. [5.0.0+] The '''Version''' argument was removed and this now calls the [[SMC#ReencryptDeviceUniqueData|ReencryptDeviceUniqueData SMC]] instead. == UnwrapTitleKey ==Wrapper for [[SMC#PrepareEsDeviceUniqueKey|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 [[SMC#LoadPreparedAesKey|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 [[SMC#PrepareEsCommonKey|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 [[#GetBootReason|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|LoadTitleKey]]. = spl:mig =This is "nn::spl::detail::ICryptoInterface". {| class="wikitable" border="1"
|-
! Cmd | 5 || [[#SetConfig]] || wrapper for [[SMC#SetConfig|SetConfig]]Name
|-
| 7 0 || Prng || uses [[SMC#PrngX931|PrngX931GetConfig]]
|-
| 9 1 || ImportExpModParams || wrapper for [[SMC#ImportParamsForFWithXY|ImportParamsForFWithXYModularExponentiate]]
|-
| 10 5 || ExpMod || wrapper for [[SMC#ExpMod|ExpModSetConfig]]
|-
| 11 7 || [[#IsDevUnit]] || uses [[SMC#GetConfig|GetConfigGenerateRandomBytes]]
|-
| 12 11 || KeygenA || wrapper for [[SMC#KeygenA|KeygenAIsDevelopment]]
|-
| 13 24 || [[#DecryptExpModParamsWithXY]3.0.0+] || wrapper for [[SMC#DecryptExpModParamsWithXY|DecryptExpModParamsWithXYSetBootReason]]
|-
| 14 25 || DecryptAESECB || decrypts 0x10 bytes using AES ECB, uses [3.0.0+] [[SMC#SetKeyslotFromXY|SetKeyslotFromXYGetBootReason]] with fixed X and Y
|-
| 15 2 || SymmetricCrypto || wrapper for [[SMC#SymmetricCrypto|SymmetricCryptoGenerateAesKek]]
|-
| 16 3 || CMAC || wrapper for [[SMC#CMAC|CMACLoadAesKey]]
|-
| 17 4 || ImportExpModParams || wrapper for [[SMC#ImportParamsFor10WithXY|ImportParamsFor10WithXYGenerateAesKey]]
|-
| 18 14 || ExpModAndKeygenAndSealZ || wrapper for [[SMC#ExpModAndKeygenAndSealZ|ExpModAndKeygenAndSealZDecryptAesKey]]
|-
| 19 15 || SetKeyslotFromZ || wrapper for [[SMC#SetKeyslotFromZ|SetKeyslotFromZCryptAesCtr]]
|-
| 20 16 || KeygenAndSealZ || wrapper for [[SMC#KeygenAndSealZ|KeygenAndSealZComputeCmac]]
|-
| 21 || || [2.0.0+] [[#AllocateAesKeyslot]]
|-
| 22 || || [2.0.0+] [[#DeallocateAesKeySlot]]
|-
| 23 || GetSplWaitEvent || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]
|}
== GetConfig =spl:fs =Takes an input word (ConfigItem), and returns a u64 with the config paramsThis is "nn::spl::detail::IFsInterface".
{| class="wikitable" border="1"
|-
! ConfigItem Cmd || Name|-| 0 || [[#GetConfig]]|-| 1 || [[#ModularExponentiate]]
|-
| 1 5 || DisableProgramVerification[[#SetConfig]]
|-
| 2 7 || MemoryConfiguration[[#GenerateRandomBytes]]
|-
| 5 11 || HardwareType (0=Icosa, 1=Copper)[[#IsDevelopment]]
|-
| 7 24 || IsRecoveryBoot[3.0.0+] [[#SetBootReason]]
|-
| 8 25 || DeviceId (byte7 clear)[3.0.0+] [[#GetBootReason]]
|-
| 9 2 || BootReason[[#GenerateAesKek]]
|-
| 10 3 || MemoryArrange[[#LoadAesKey]]
|-
| 11 4 || AllowSkippingNrrSignatures[[#GenerateAesKey]]
|-
| 13 14 || BatteryProfile?[[#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
|}
Output from this when used by [[NIM_services|NIM]] must match the [[Settings_services|set= spl:cal]] DeviceId with byte7 cleared, otherwise NIM will panicssl =This is "nn::spl::detail::ISslInterface".
{| class="wikitable" border="1"|-! Cmd || Name|-| 0 || [[#GetConfig]]|-| 1 || [[Loader services#ModularExponentiate]]|-| 5 || [[#SetConfig]]|-| 7 || [[#GenerateRandomBytes]]|-| 11 || [[#IsDevelopment]]|-| 24 |RO| [3.0.0+][[#SetBootReason] checks id11, if set then skipping NRR rsa signatures is allowed]|-| 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|}
== KeygenAndSealX =spl:es =Takes 16-bytes as input and two u32s. Outputs random-looking 16-bytesThis is "nn::spl::detail::IEsInterface".
Same input gives same output{| class="wikitable" border="1"|-! Cmd || Name|-| 0 || [[#GetConfig]]|-| 1 || [[#ModularExponentiate]]|-| 5 || [[#SetConfig]]|-| 7 || [[#GenerateRandomBytes]]|-| 11 || [[#IsDevelopment]]|-| 24 || [3. Output changes when system is rebooted0.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]]|}
== SetConfig =spl:manu =Takes two input words, a ConfigItem and the value to setThis is "nn::spl::detail::IManuInterface".
{| class="wikitable" border="1"
|-
! ConfigItem 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 || Battery profile?[[#DecryptDeviceUniqueData]]|-| 30 || [5.0.0+] ReencryptDeviceUniqueData
|}
== IsDevUnit ==No input params. Returns an u8 flag for whether the system is devunit. Output flag is 0 on retail. == DecryptExpModParamsWithXY ==Last SPL cmd used by [[SSL_services|SSLCategory:Services]]-sysmodule for TLS client-privk.

Navigation menu