Toggle menu
Toggle preferences menu
Toggle personal menu
Not logged in
Log in or create an account to edit The Apple Wiki.
OOjs UI icon key-progressive.svg

The Apple Wiki maintains a database of firmware keys, used for decrypting the AES-encrypted files found in Apple's firmware images. This database, which currently holds 46,995 entries, supports the security research efforts of many organizations, in addition to jailbreak and downgrading tools.

Encryption obscures the contents of the firmware, but it still needs to be decrypted to work correctly on the device. This decryption is done by using a processor-specific GID key. Access to the processor's AES engine is restricted such that regular software in the operating system can not access it. We understand the importance of having these keys, so we provide this free service to further the research efforts around Apple platforms.

You can help contribute firmware keys we are currently missing. See our lists of wanted and incomplete key pages.

Tools

Community tools have been developed that ease the use of The Apple Wiki's key page database.

  • CLI:
    • ipsw, which describes itself as an "iOS/macOS Research Swiss Army Knife", can automatically decrypt IMG4 images.
  • Libraries:

Guidelines

  • Use tools listed above, or one of the supported methods of accessing the database. Other methods may break without notice when we make internal changes. In particular, we advise against direct parsing of wikitext.
  • Do not make excessive requests. To ensure fair access for everyone, we reserve the right to block access to IP addresses, user agents, or other unique identifiers found to consume excessive server resources. If you need bulk access to data, please use Semantic MediaWiki or Special:Export. If these options are not viable for your use case, contact us and we can discuss a solution.
  • Set a uniquely-identifying user agent. If you are directly making requests to the wiki, to avoid being unintentionally blocked, set a custom value for the User-Agent header. Include your project name, and a website or email address we can use to contact you if there are any issues.
  • Test keys you submit to the wiki. If another editor finds that submitted keys are not valid, they may delete them to ensure the integrity of our database.

We make use of community spam blocklists, in addition to web application firewall (WAF) features from Cloudflare. It is possible for these to incorrectly block legitimate users. If you believe you have been wrongly blocked, contact us to appeal.

Retrieval

To retrieve data from key pages without a third-party library, use one of the following supported methods. Other methods are not supported, and may run into issues in future.

Raw JSON

The Apple Wiki is planning to switch the format used to input keys data from wikitext and the {{Keys}} template, to JSON objects. This has the benefit of providing the data in a machine-friendly format from the outset, so HTML and wikitext parsing is no longer necessary. The wiki is also able to perform checks on the schema of the JSON, to ensure the data is valid. Our custom KeyPages MediaWiki extension handles rendering the HTML view, including populating the Semantic MediaWiki data.

All current consumers of keys data via wikitext parsing will be broken with this change. We will be working with tools that currently use wikitext parsing, and will begin changing the data format once we are confident most (ideally, all) API clients are ready to handle the new format.

Semantic MediaWiki

Use the ask API. You can see properties you can query for at Special:Browse, and experiment with queries at Special:Ask. An example query might look like:

https://theapplewiki.com/wiki/Special:Ask
  /-5B-5B:Keys:-2B-5D-5D
  /-5B-5BHas firmware device::iPhone10,6-5D-5D
  /-5B-5BHas firmware version::12.4-5D-5D
  /-3FHas download URL=url
  /-3FHas firmware baseband=baseband
  /-3FHas firmware build=build
  /-3FHas firmware codename=codename
  /-3FHas firmware device=device
  /-3FHas firmware version=version
  /-3FHas operating system=os
  /mainlabel=name
  /limit=1
  /format=json
  /type=simple

Test this request using the Ask page.

This may be overwhelming at first due to the complex syntax of Semantic MediaWiki queries. Semantic MediaWiki has extensive documentation on its query system if you want to learn more, but you will likely only need to use the requests provided here.

Here is what each part of the above request means:

Part Meaning
[[:Keys:+]]
Filter to pages in the Keys namespace.
[[Has firmware device::iPhone10,6]]
[[Has firmware version::12.4]]
Filter to pages that match these properties.
?Has download URL=url
?Has firmware baseband=baseband
?Has firmware build=build
?Has firmware codename=codename
?Has firmware device=device
?Has firmware version=version
?Has operating system=os
Specify the fields to return, and the names the fields will have in the output.
mainlabel=name
Specify the name of the field that contains the page name.
limit=1
Return one search result.
format=json
Set the output format to JSON. Most output formats are HTML.
type=simple
Collapse fields that return a single value, rather than returning arrays of values.

Once you know the page name, you can retrieve the key subobjects of the page:

https://theapplewiki.com/wiki/Special:Ask
  /-5B-5B-2DHas subobject::Keys:PeaceG 16G77 (iPhone10,6)-5D-5D
  /-3FHas filename=filename
  /-3FHas firmware device=device
  /-3FHas key=key
  /-3FHas key IV=iv
  /-3FHas key KBAG=kbag
  /-3FHas key DevKBAG=devkbag
  /mainlabel=filename
  /format=json
  /type=simple

Test this request using the Ask page.

Be aware that some devices, such as the iPhone 6s, have multiple board configurations with their own unique GID keys. This means that, within a single IPSW file, there may be multiple copies of an IMG4, encrypted with each board configuration's GID key. When this is the case, the device field will be populated. If the board configuration you are interested in is known, you may consider adding [[Has firmware device::...]] to the subobject query to simplify the output.

HTML parsing

HTML parsing is the original format used for firmware key retrieval. It is discouraged, but still maintained as an option.

Use the MediaWiki search API. Make sure to narrow your search to the Keys namespace, which has the numeric identifier 2304. An example query might look like:

https://theapplewiki.com/api.php
  ?format=json
  &action=query
  &list=search
  &utf8=
  &srsearch=intitle:16G77+intitle:iPhone10,6
  &srnamespace=2304
  &srlimit=1

Test this request in the API sandbox.

Then, retrieve the standalone HTML output using a render request:

https://theapplewiki.com/index.php
  ?title=Keys:PeaceG_16G77_(iPhone10,6)
  &action=render

Using an HTML parsing library, retrieve values by their HTML id value. We do not recommend using regular expressions to parse the HTML, as subtle changes to our template or the MediaWiki parser itself may produce subtly different HTML output. Particularly, in future, MediaWiki will switch to its new Parsoid parser by default, which generates more verbose HTML.