diff --git a/.gitignore b/.gitignore index aecebd82..934b03dc 100644 --- a/.gitignore +++ b/.gitignore @@ -269,5 +269,4 @@ global.json # Files generated at build time ResultNameResolver.Generated.cs -DefaultKeySet.Generated.cs -ResultNameResolver.Generated.cs \ No newline at end of file +DefaultKeySet.Generated.cs \ No newline at end of file diff --git a/KEYS.md b/KEYS.md index bca7006f..4a298cb5 100644 --- a/KEYS.md +++ b/KEYS.md @@ -2,104 +2,136 @@ Keys are required for decrypting most of the file formats used by the Nintendo Switch. -Keysets are stored as text files, and are loaded from `$HOME/.switch`. These 3 filenames are automatically read: -`prod.keys` - Contains common keys usedy by all Switch devices. -`console.keys` - Contains console-unique keys. +Key sets are stored as text files, and are loaded from `$HOME/.switch`. On Windows this path is usually `C:\Users\\.switch`. + +These 4 filenames are automatically read: +`prod.keys` - Contains keys shared by all retail Switch devices. +`dev.keys` - Contains keys shared by all development Switch devices. Optional. +`console.keys` - Contains console-unique keys. Optional. `title.keys` - Contains game-specific keys. -#### XTS-AES keys note +## Obtaining keys -The Switch uses 128-bit XTS-AES for decrypting the built-in storage (BIS), NCA header and the SD card contents. -This encryption method uses 2 128-bit keys: a "data" or "cipher" key, and a "tweak" key. +Keys can be obtained from a Switch that can run homebrew. The easiest way is to use [Lockpick_RCM](https://github.com/shchmue/Lockpick_RCM). See an up-to-date Switch homebrew guide for details. -In the keyfile these are stored as one 256-bit key with the data key first, followed by the tweak key. +After running Lockpick_RCM `/switch/prod.keys` and `/switch/title.keys` should be on your SD card. Copy these two files to the `.switch` directory specified above. -## Keyfile format +# Key file details +Dumping keys from a Switch is all that is needed for LibHac. -`prod.keys` and `console.keys` should be in the following format with one key per line: +The following section contains some additional information on keys, documentation on the key file format and a list of supported keys. + +## Key file format + +`prod.keys`, `dev.keys` and `console.keys` should be in the following format with one key per line: `key_name = hexadecimal_key_value` +Each line must contain fewer than 1024 characters. + e.g. (Not actual keys) ``` -master_key_00 = 63C9FCB338CDE3D037D29BB66F897C6B -master_key_01 = 4636CB976DFE95095C1F55151A8326C6 -header_key_source = 343795270AAD5D19EBE2956C9BC71F4C41836B21DC6ACD7BACD4F6AF4816692C +master_key_00 = 496620796F752772652072656164696E +master_key_01 = 6720746869732C20796F752772652061 +header_key_source = 206E657264AD5D19EBE2956C9BC71F4C41836B21DC6ACD7BACD4F6AF4816692C ``` -#### Title Keys +### Title keys `title.keys` should be in the following format with one key per line: -`rights_id,hexadecimal_key_value`. +`rights_id = hexadecimal_key_value`. e.g. (Not actual keys) ``` -01000000000100000000000000000003,B4A1F5575D7D8A81624ED36D4E4BD8FD -01000000000108000000000000000003,C8AD76F8C78E241ADFEE6EB12E33F1BD -01000000000108000000000000000004,F9C8EAD30BB594434E4AF62C483CD796 +01000000000100000000000000000003 = 68747470733A2F2F7777772E796F7574 +01000000000108000000000000000003 = 7562652E636F6D2F77617463683F763D +01000000000108000000000000000004 = 64517734773957675863513F4C696248 ``` -## Keyfile templates +### Dev keys + +Keys from `dev.keys` will always be loaded as dev keys. +Dev keys may also be loaded from `prod.keys`, allowing both key sets to be in the same file. +Because both key sets use the same key sources, only a small number of root keys are needed to derive each set. + +Key names that have `_dev` after the main key name but before the key index will be loaded as dev keys. + +e.g. (Not actual keys) +``` +master_key_0a = B6B0F17AC61696120A15FFD41A529CBE +master_key_dev_0a = 154A07EAFC50C6328A66C4FD2CDB277A +xci_header_key_dev = 118BA87386A242FA9DCCB06853E7A9F6 +``` + +## Key system + +This is meant to be a basic overview of the concepts used by the Switch's content key system. + +### Key generations +In a nutshell, the Switch's OS contains key sources or seeds. +These seeds are useless on their own, but given a "master key" they can be used to generate the actual content keys. +This master key is the root from which all content keys are derived. +Retail and development Switches have different master keys. + +The Switch uses what are called "key generations" (As in the noun, not the verb). +Each generation has its own master key which results in a different set of content keys for each one. +Content files are encrypted with the keys from the most recent generation. +e.g. A game built for system version 6.2.0 will be encrypted with the keys for 6.2.0. Older system versions would be unable to decrypt the content. + +### Root keys +Root keys are the keys used to derive other keys. +Erista (original Switch hardware version) and Mariko (second hardware version) have different root keys. +Both these root keys are used to derive the same master key which will then derive other keys. + +The current root key for Erista is `tsec_root_key_02`, and the key for Mariko is `mariko_kek`. +The main purpose of these keys is to generate the master key, so they're not really necessary for decrypting content. + +These root keys, with proper security, are supposed to be hardware secrets, unable to be accessed by software. + +Package1 is the only content that is not encrypted with these root keys or their derivatives. +Each Erista package1 is encrypted with its own unique key, and every Mariko package1 is encrypted with `mariko_bek`. + +## Key file templates This template contains the keys needed to derive all the keys used by hactoolnet, although not all of them are needed for every task. +In fact, more than 99% of all content can be decrypted by providing only the most recent master key. -Fill out the template with the actual keys to get a working keyfile. +LibHac contains the key sources that keys are derived from. Only a small number of root keys need to be provided, although any keys will be loaded from the key file if present. + +Providing the following keys will enable decryption of all retail content. +Every one of these keys also has a dev version. Providing them will enable decryption of all dev content. ``` -master_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -master_key_00 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -master_key_01 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -master_key_02 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -master_key_03 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -master_key_04 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -master_key_05 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +# Only the latest master key is needed to decrypt the vast majority of Switch content. +master_key_0a = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_mac_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_key_source_00 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_key_source_01 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_key_source_02 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_key_source_03 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_key_source_04 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -keyblob_key_source_05 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +# Package1 keys are used to decrypt package1, the first part of the OS loaded during boot. +package1_key_00 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_01 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_02 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_03 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_04 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_05 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -package1_key_00 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -package1_key_01 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -package1_key_02 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -package1_key_03 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -package1_key_04 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +# The XCI header key will decrypt the gamecard info in an XCI. Not usually needed. +xci_header_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -package2_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +# Methods of obtaining the keys below are not publicly available as of Oct. 2020, +# but they're included anyway for completion's sake -aes_kek_generation_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -aes_key_generation_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -titlekek_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +# Keys for Erista package1 since firmware 6.2.0. +package1_key_06 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_07 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_08 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_09 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +package1_key_0a = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -key_area_key_application_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -key_area_key_ocean_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -key_area_key_system_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -sd_card_kek_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -sd_card_save_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -sd_card_nca_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -sd_card_custom_storage_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -header_kek_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -header_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -xci_header_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -retail_specific_aes_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -per_console_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -eticket_rsa_kek = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -bis_key_source_00 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -bis_key_source_01 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -bis_key_source_02 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -bis_kek_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -save_mac_kek_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -save_mac_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -save_mac_sd_card_kek_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -save_mac_sd_card_key_source = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +# The Mariko boot encryption key (BEK) is used to decrypt Mariko package1. +# The Mariko key encryption key (KEK) is used to derive master keys on Mariko Switches. +# All content keys are the same on both Switch versions except for package1 keys. +# Together the Mariko BEK and KEK are enough to derive all current content keys and all +# content keys in the forseeable future except for Erista package1. +mariko_bek = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +mariko_kek = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` ### Console-unique keys @@ -111,7 +143,7 @@ tsec_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX secure_boot_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX sd_seed = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -# The below keys can be derived from tsec_key and secure_boot_key +# These keys can be derived from tsec_key and secure_boot_key device_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX bis_key_00 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX bis_key_01 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX @@ -119,6 +151,13 @@ bis_key_02 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX bis_key_03 = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` +#### XTS-AES keys note + +The Switch uses 128-bit XTS-AES for decrypting the built-in storage (BIS), NCA header and the SD card contents. +This encryption method uses 2 128-bit keys: a "data" or "cipher" key, and a "tweak" key. + +In the key file these are stored as one 256-bit key with the data key first, followed by the tweak key. + ## Complete key list Below is a complete list of keys that are currently recognized. \## represents a hexadecimal number between 00 and 1F @@ -126,42 +165,69 @@ Below is a complete list of keys that are currently recognized. ### Common keys ``` -master_key_source +tsec_root_kek +package1_mac_kek +package1_kek +tsec_auth_signature_## +tsec_root_key_## + keyblob_mac_key_source +keyblob_key_source_## +keyblob_## + +mariko_bek +mariko_kek +mariko_aes_class_key_## +mariko_master_kek_source_## + +master_kek_source_## +master_kek_## +master_key_source +master_key_## + +package1_key_## +package1_mac_key_## package2_key_source -aes_kek_generation_source -aes_key_generation_source -key_area_key_application_source -key_area_key_ocean_source -key_area_key_system_source -titlekek_source -header_kek_source -header_key_source -sd_card_kek_source -sd_card_nca_key_source -sd_card_save_key_source -retail_specific_aes_key_source -per_console_key_source +package2_key_## + bis_kek_source bis_key_source_00 bis_key_source_01 bis_key_source_02 -save_mac_kek_source -save_mac_key_source +bis_key_source_03 -header_key -xci_header_key -eticket_rsa_kek - -master_key_## -package1_key_## -package2_key_## +per_console_key_source +retail_specific_aes_key_source +aes_kek_generation_source +aes_key_generation_source +titlekek_source titlekek_## + +header_kek_source +header_key_source +header_key + +key_area_key_application_source +key_area_key_ocean_source +key_area_key_system_source key_area_key_application_## key_area_key_ocean_## key_area_key_system_## -keyblob_key_source_## -keyblob_## + +save_mac_kek_source +save_mac_key_source_00 +save_mac_key_source_01 +save_mac_sd_card_kek_source +save_mac_sd_card_key_source + +sd_card_kek_source +sd_card_save_key_source +sd_card_nca_key_source +sd_card_custom_storage_key_source + +xci_header_key +eticket_rsa_kek +ssl_rsa_kek ``` ### Console-unique keys @@ -174,10 +240,13 @@ bis_key_00 bis_key_01 bis_key_02 bis_key_03 +save_mac_key_00 +save_mac_key_01 keyblob_key_## keyblob_mac_key_## encrypted_keyblob_## sd_seed +save_mac_sd_card_key ```