Changes

Jump to navigation Jump to search
1,787 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 =
! Cmd || Name
|-
| 0 || [[#GetRandomBytesGenerateRandomBytes]]
|}
== GetRandomBytes GenerateRandomBytes ==Takes a an output type-6 0xA buffer and fills it with random data from [[SMC#GetRandomBytesGenerateRandomBytes|GetRandomBytes GenerateRandomBytes SMC]]. Same command for "spl:" and "csrng" services. = spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu =These are "nn::spl::detail::IGeneralInterface", "nn::spl::detail::ICryptoInterface", "nn::spl::detail::IFsInterface", "nn::spl::detail::ISslInterface", "nn::spl::detail::IEsInterface" and "nn::spl::detail::IManuInterface"(?). [2.0.0+] Where previously only one AES engine was utilized, there is now support except for 4 of thembuffer-type.
[2.0.0+] When the session closes, all AES engines that were locked are automatically unlocked= spl: =This is "nn::spl::detail::IGeneralInterface".
{| class="wikitable" border="1"
|-
! Cmd || Name || Permissions|-| 0 || [[#GetConfig]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu|-| 1 || [[#UserExpMod]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu |-| 2 || [[#GenerateAesKek]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu |-| 3 || [[#LoadAesKey]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu|-| 4 || [[#GenerateAesKey]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu |-| 5 || [[#SetConfig]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu |-| 7 || [[#GetRandomBytes]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu|-| 9 || [[#LoadSecureExpModKey]] || spl:fs|-| 10 || [[#SecureExpMod]] || spl:fs|-| 11 || [[#IsDevelopment]] || spl:, spl:mig, spl:fs, spl:ssl spl:es, spl:manu|-| 12 || [[#GenerateSpecificAesKey]] || spl:fs|-| 13 || [[#DecryptRsaPrivateKey]] || spl:ssl, spl:es, spl:manu|-| 14 || [[#DecryptAesKey]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu|-| 15 || [[#DecryptAesCtr]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu|-| 16 || [[#ComputeCmac]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu |-| 17 || [[#LoadRsaOaepKey]] || spl:es|-| 18 || [[#UnwrapRsaOaepWrappedTitleKey]] || spl:es|-| 19 || [[#LoadTitleKey]] || spl:fs|-| 20 || [2.0.0+] [[#UnwrapAesWrappedTitleKey ]] || spl:es|-| 21 || [2.0.0+] [[#LockAesEngine]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu|-| 22 || [2.0.0+] [[#UnlockAesEngine]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
|-
| 23 0 || [2.0.0+] [[#GetSplWaitEventGetConfig]] || spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
|-
| 24 1 || [3.0.0+] [[#SetSharedDataModularExponentiate]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
|-
| 25 5 || [3.0.0+] [[#GetSharedDataSetConfig]] || spl:, spl:mig, spl:fs, spl:ssl, spl:es, spl:manu
|-
| 26 7 || [5.0.0+[#GenerateRandomBytes]] ImportSslRsaKey || spl:ssl
|-
| 27 11 || [5.0.0+[#IsDevelopment]] SecureExpModWithSslKey || spl:ssl
|-
| 28 24 || [53.0.0+] ImportEsRsaKey || spl:es[[#SetBootReason]]
|-
| 29 25 || [53.0.0+] SecureExpModWithEsKey || spl:es|-| 30 || [5.0.0+[#GetBootReason] EncryptManuRsaKeyForImport || spl:manu|-| 31 || [5.0.0+] GetPackage2Hash || spl:fs
|}
Wrapper for [[SMC#GetConfig|GetConfig SMC]].
Takes a an input u32 ('''ConfigItem'''), and returns . Returns one or more output u64s ('''ConfigValConfigValue''').
== UserExpMod ModularExponentiate ==Wrapper for [[SMC#ExpModModularExponentiate|ExpMod ModularExponentiate SMC]].
Takes one an output type-10 (C descriptor) 0xA buffer ('''data_out_bufDataOut''') and 3 input type-9 (X descriptor) 0x9 buffers ('''data_in_bufDataIn''', '''exp_in_bufExpIn''' and '''mod_in_bufModIn''').
Performs asymmetric crypto with user supplied modulus and exponent.
Wrapper for [[SMC#GenerateAesKek|GenerateAesKek SMC]].
Takes a an input 16-byte EKS ('''Encryption Key SourceKeySource''') and two words (input u32s '''KeyGenerationGeneration''' and '''optionOption''') as input. Returns a scrambled sealed KEK ('''Key Encryption Key''' used as an output 16-byte '''key_xAccessKey''').
== LoadAesKey ==
Wrapper for [[SMC#LoadAesKey|LoadAesKey SMC]].
Takes a an input u32 ('''keyslotKeyslot''') and two , an input 16-byte keys ('''key_xAccessKey''' and an input 16-byte '''key_yKeySource''').
Sets the specified '''keyslotKeyslot''' with a key generated from '''key_xAccessKey''' and '''key_yKeySource'''.
[2.0.0+] Now verifies that the engine keyslot in use (0..3) is locked/owned allocated by the current spl session, otherwise errors with 0xD21A. Previously engine , keyslot was hardcoded to 0.
== GenerateAesKey ==
Takes a an input 16-byte KEK ('''key_xAccessKey''') and a an input 16-byte encrypted key ('''enc_keyKeySource'''. Returns an output 16-byte '''AesKey''').
Generates a new key by decrypting (AES-ECB) '''enc_keyKeySource''' with a key generated from the supplied '''key_xAccessKey''' and a fixed '''key_y''' the key set with [[SMC#LoadAesKey|LoadAesKey SMC]].
[2.0.0+] Previously, it always used engine keyslot 0. Now it tries to allocate an engine a keyslot to be used and returns 0xD01A if they're all busy. When the command is done, the engine keyslot is released.
== SetConfig ==
Wrapper for [[SMC#SetConfig|SetConfig SMC]].
Takes a an input u32 ('''ConfigItem''') and a an input u64 ('''ConfigValConfigValue''').
{| class="wikitable" border="1"|-! Only '''ConfigItem || Name|-| ''' 13 || BatteryProfile|}(IsChargerHiZModeEnabled) can be set.
Any other '''ConfigItem''', besides 13, can't be set== ImportLotusKey ==Wrapper for [[SMC#DecryptAndImportLotusKey|DecryptAndImportLotusKey SMC]].
== LoadSecureExpModKey ==Wrapper Takes an input type-0x9 buffer '''DataIn''', an input 16-byte '''AccessKey''', an input 16-byte '''KeySource''' and an input u32 '''Version''' (0 for [[SMC#LoadSecureExpModKey|LoadSecureExpModKey SMC]]normal keys or 1 for extended keys).
Takes one type-9 (X descriptor) buffer (Decrypts '''enc_privk_in_bufDataIn'''), with a 16-byte KEK ('''key_x'''), a 16-byte key (generated from '''key_yAccessKey''') and a u32 ('''versionKeySource''').'''version''' is 0 for normal keys or 1 and imports it for extended keyslater usage.
Decrypts [5.0.0+] The '''enc_privk_in_buf''' with a key generated from '''key_x''' and '''key_yVersion''' argument was removed and imports it for later usagethis now calls the [[SMC#ReencryptDeviceUniqueData|ReencryptDeviceUniqueData SMC]] instead.
[5.0.0+] This now calls [[SMC#EncryptRsaKeyForImport|EncryptRsaKeyForImport SMC]] instead== DecryptLotusMessage ==Takes 3 input type-0x9 buffers '''DataIn''', '''ModIn''' and '''LabelHashIn'''.
== SecureExpMod ==Takes 3 type-9 (X descriptor) buffers ('''data_in_buf''', '''mod_in_buf''' and '''param0_in_buf'''). Uses the [[SMC#SecureExpModModularExponentiateByStorageKey|SecureExpMod ModularExponentiateByStorageKey SMC]] to decrypt '''data_in_bufDataIn''' using the private key imported with [[#LoadSecureExpModKeyImportLotusKey]] and the supplied '''mod_in_bufModIn''' and '''param0_in_bufLabelHashIn'''. Generates and returns a 16-byte sealed titlekey.
== IsDevelopment ==
No input params. Returns an output u8 bool.
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 [[SMC#GenerateSpecificAesKey|GenerateSpecificAesKey SMC]].
Takes a an input 16-byte seed ('''key_seedKeySource''') and two words (input u32s '''KeyGenerationGeneration''' and '''optionOption'''. Returns an output 16-byte '''AesKey''') as input.
Returns a scrambled key ('''key_a''')== DecryptDeviceUniqueData ==Wrapper for [[SMC#DecryptDeviceUniqueData|DecryptDeviceUniqueData SMC]].
== DecryptRsaPrivateKey ==Wrapper 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 [[SMC#DecryptRsaPrivateKey|DecryptRsaPrivateKey SMC]]normal keys or 1 for extended keys).
Takes one type-10 (C descriptor) buffer (Decrypts '''dec_privk_out_bufDataIn'''), one type-9 (X descriptor) buffer (into '''enc_privk_in_bufDataOut'''), with a 16-byte KEK ('''key_x'''), a 16-byte key (generated from '''key_yAccessKey''') and a u32 ('''version''').'''versionKeySource''' 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_services|SSL]] for TLS client-privk.
Used by [[SSL_services|SSL]]-sysmodule for TLS client-privk. [5.0.0+] This now calls [[SMC#DecryptOrImportRsaKey|DecryptOrImportRsaKey SMC]] insteadThe '''Version''' argument was removed.
== DecryptAesKey ==
Takes a an input 16-byte encrypted key ('''enc_keyKeySource''') and two words (input u32s '''KeyGenerationGeneration''' and '''optionOption'''. Returns an output 16-byte '''AesKey''') as input.
Decrypts (AES-ECB) '''enc_keyKeySource''' 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 keyslot allocation code as for [[#GenerateAesKey]].
== DecryptAesCtr CryptAesCtr ==Takes a an output type-0x46 (B descriptor) buffer ('''data_out_bufDataOut'''), a an input u32 ('''keyslotKeyslot'''), a an input type-0x45 (A descriptor) buffer ('''data_in_bufDataIn''') and a an input 16-byte CTR ('''aes_ctrIvCtr''').
Uses [[SMC#CryptAesComputeAes|CryptAes ComputeAes SMC]] to decrypt '''data_in_bufDataIn''' into '''data_out_bufDataOut''', using the key set in the specified '''keyslotKeyslot'''.
[2.0.0+] Verifies the engine is locked keyslot was allocated by the current session.
== ComputeCmac ==
Wrapper for [[SMC#ComputeCmac|ComputeCmac SMC]].
Takes one an input type-9 (X descriptor) 0x9 buffer ('''data_in_bufDataIn''') and a an input u32 ('''type?Keyslot'''. Returns an output 16-byte '''Cmac''').
Returns a 16-byte CMAC calculated over '''data_in_buf'''[2.0.0+] Verifies the keyslot was allocated by the current session.
== ImportEsKey ==Wrapper for [2.0.0+[SMC#DecryptAndImportEsDeviceKey|DecryptAndImportEsDeviceKey SMC]] Verifies the engine is locked by current session.
== LoadRsaOaepKey ==Wrapper Takes an input type-0x9 buffer '''DataIn''', an input 16-byte '''AccessKey''', an input 16-byte '''KeySource''' and an input u32 '''Version''' (0 for [[SMC#LoadRsaOaepKey|LoadRsaOaepKey SMC]]normal keys or 1 for extended keys).
Takes one type-9 (X descriptor) buffer (enc_privk_in_buf), Decrypts '''DataIn''' with a 16-byte KEK (key_x), a 16-byte key (key_y) generated from '''AccessKey''' and '''KeySource''' and a u32 (version). version is 0 for normal keys or 1 imports it for extended keyslater usage.
Decrypts enc_privk_in_buf with a key generated from key_x [5.0.0+] The '''Version''' argument was removed and key_y and imports it for later usagethis now calls the [[SMC#ReencryptDeviceUniqueData|ReencryptDeviceUniqueData SMC]] instead.
== UnwrapRsaOaepWrappedTitleKey UnwrapTitleKey ==Wrapper for [[SMC#UnwrapRsaOaepWrappedTitleKeyPrepareEsDeviceUniqueKey|UnwrapRsaOaepWrappedTitleKey PrepareEsDeviceUniqueKey SMC]].
Takes one an output type-10 (C descriptor) 0xA buffer ('''data_out_bufDataOut''') and 3 input type-9 (X descriptor) 0x9 buffers ('''data_in_bufDataIn''', '''mod_in_bufModIn''' and '''label_hash_in_bufLabelHashIn'''. Returns an output u32 '''DataOutSize''').
Decrypts '''data_in_buf''' into '''data_out_buf''' using the private key imported with [[#LoadRsaOaepKey]3.0.0+] and the supplied '''mod_in_buf'''. Afterwards, verifies RSA-OAEP encoding using Now takes an input u32 '''label_hash_in_bufGeneration'''.
Returns an u32 (Decrypts '''dec_data_sizeDataIn''' into '''DataOut''' using the private key imported with [[#ImportEsKey]] and the supplied '''ModIn'''. Afterwards, verifies RSA-OAEP encoding using '''LabelHashIn''').
== LoadTitleKey ==
Wrapper for [[SMC#LoadTitleKeyLoadPreparedAesKey|LoadTitleKey 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.
Takes a u32 ('''keyslot''') and a 16-byte sealed titlekey== UnwrapCommonTitleKey ==Wrapper for [[SMC#PrepareEsCommonKey|PrepareEsCommonKey SMC]].
Sets the specified Takes an input 16-byte '''keyslotKeySource'''. Returns an output 16-byte '''AccessKey''' with the titlekey.
[23.0.0+] Verifies the engine is locked by current sessionNow takes an input u32 '''Generation'''.
== UnwrapAesWrappedTitleKey AllocateAesKeyslot ==Wrapper for [[SMC#UnwrapAesWrappedTitleKey|UnwrapAesWrappedTitleKey SMC]]Returns an output u32 '''Keyslot'''.
Takes a 16-byte EKS ('''Encryption Key Source''')Returns error 0xD01A if all keyslots are taken.
Returns a sealed titlekey== DeallocateAesKeySlot ==Takes an input u32 '''Keyslot'''.
Returns error 0xD21A if the keyslot wasn't allocated by current session. == LockAesEngine GetAesKeyslotAvailableEvent ==Returns an output event handle for synchronizing with the id of the engine that was locked, or 0xD01A AES keyslots. == SetBootReason ==Takes an input u32 '''BootReason'''. [4.0.0+] Returns 0xD41A if all engines are busya value has been previously set without being [[#GetBootReason|gotten]]. You need to lock  == GetBootReason ==Returns an engine before using AES functionsoutput 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 || 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". {| 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]]|-| 9 || [[#ImportLotusKey]]|-| 10 || [[#DecryptLotusMessage]]|-| 12 || [[#GenerateSpecificAesKey]]|-| 19 || [[#LoadTitleKey]]|-| 31 || [5.0.0+] GetPackage2Hash|}
== UnlockAesEngine =spl:ssl =Takes a single u32 and unlocks the engine with that id. It must be owned by current session otherwise 0xD21A will be returnedThis is "nn::spl::detail::ISslInterface".
{| class="wikitable" border= GetSplWaitEvent =="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]]|-| 13 || [[#DecryptDeviceUniqueData]]|-| 26 || [5.0.0+] DecryptAndStoreSslClientCertKey|-Returns an event handle for synchronizing with the locked AES engine| 27 || [5.0.0+] ModularExponentiateWithSslClientCertKey|}
== SetSharedData =spl:es =Sets a static dword in This is "nn::spl .bss to the user input u32::detail::IEsInterface".
{| 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+] returns 0xD41A if a value has been previously set without being [[#GetSharedDataAllocateAesKeyslot]]|-| 22 ||gotten[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]]|}
== GetSharedData =spl:manu =Returns the static dword in This is "nn::spl .bss that can be set via [[#SetSharedData]]::detail::IManuInterface".
{| 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+] returns 0xD61A if a value has not previously been set, and unsets the value after getting it[[#AllocateAesKeyslot]]|-| 22 || [2.0.0+] [[#DeallocateAesKeySlot]]|-| 23 || [2.0.0+] [[#GetAesKeyslotAvailableEvent]]|-| 13 || [[#DecryptDeviceUniqueData]]|-| 30 || [5.0.0+] ReencryptDeviceUniqueData|}
[[Category:Services]]

Navigation menu