Apple Home Key is an NFC protocol used by select HomeKit-certified locks to authenticate a user using a virtual key provisioned into their Apple device.

There are three main components to the standard:

• Network:
  • HAP: Used to provision reader private keys, issuer keys, configure public keys of the devices that are given access to a particular Apple Home instance;
• NFC:
  • Authentication: runs on the SE and is based on the Car Key protocol, with minor changes, such as lack of direct pairing (which is done via HAP instead), changes to the KDF influenced by multi-reader environment and other;
  • Attestation exchange: implemented via HCE and uses ISO18013 engagement and NFC data transfer.

Just like the parent protocol, Home Key has the following advantages:

• This protocol provides reader authentication, data encryption, forward secrecy;
• It has potential for key sharing*, although this functionality is not implemented;
• In theory, future locks could implement UWB-based access as it's supported by specification.

• Endpoint - end device;
• Reader - a lock or any other device that performs authentication;
• Issuer - a party that's generating keys;
• Nonce - Single-use number;
• EC - Elliptic Curve;
• If a key is mentioned without algorithm info, assume its secp256r1;
• ISO18013 - ISO specification for mobile identity documents;
• Copernicus - codename of the Home Key applet implementation;
• UnifiedAccess - type codename of Copernicus-based wallet passes.
• ECP - Apple Enhanced Contactless Polling

For HAP/HomeKit part of the Home Key, refer to comprehensive overview done by @kupa22.

_{Previously this section contained examples of some requests with possible meanings for each of their parts. With new knowledge, previous assumptions have been deemed to be misleading, and thus have been removed.}

HardwareFinish of the first lock added to your home installation influences the color of the lock art for the whole home.

Following finish variations were found in IOS system files:

Color	Art	Value	Notes
Black		00 00 00
Gold		AA D6 EC
Silver		E3 E3 E3
Tan		CE D5 DA	The default color. If an unexisting color combo is chosen, this color will be selected as a fallback

_{00 also has to be appended to color value
Credit to @kupa22 for finding rest of the key colors}

ECP allows Home Keys to work via express mode and is required to be implemented by certified locks.

The full Home Key ECP frame looks like this

   6a 02 cb 02 06 021100 deadbeefdeadbeef

The following characteristics can be noted:

• It belongs to the Access(02) reader group with a dedicated subtype HomeKey(06);
• It contains a single 3-byte TCI with a value of 02 11 00, no other variations have been met. IOS file system contains multiple copies of a Home Key pass JSON with this TCI;
• The final 8 bytes of an ECP Home Key frame contain a reader group identifier, which allows IOS to differentiate between keys for different Home installations.

(NOTE) The actual reader identifier is 16 bytes long, first 8 bytes are the same for all locks in a single home, while the latter 8 are unique to each one. Only the first 8 are used for ECP.
(BUG) If more than one Home Key is added to a device, ECP stops working correctly, as a device responds to any reader emitting Home Key ECP frame even if the reader identifier is not known to it.
(BUG) If you disable express mode for a single key while having multiple with enabled express mode, it won't appear on a screen when brought near to a reader. Disabling express mode for all home keys fixes this issue.

Home Key uses two application identifiers:

1. Home Key Primary:
   A0000008580101. Used for authentication. Implemented on the SE;
2. Home Key Configuration:
   A0000008580102. Used for attestation exchange. Implemented via HCE. Can only be selected after a successful STANDARD authentication with a following EXCHANGE and CONTROL FLOW commands.

In most situations, a reader will only use the Primary applet.
Configuration applet will be selected only if a new device has been invited and key data hasn't been provisioned into a lock prior to that; Invitation is attested by the HAP pairing key of the person to whom the device belongs to.

Commands are executed in the following sequence:

1. SELECT USER APPLET:
   Reader transmits Home Key AID; Device responds with a version list TLV; Reader has to verify that there is a protocol version match between a list provided by a device and itself;
2. FAST (AUTH0):
   Reader transmits required protocol version, transaction nonce, ephemeral public secp256r1 key, and its identifier;
   Device responds with an authentication cryptogram and its own ephemeral public secp256r1 key;
   Reader tries to verify that cryptogram was generated by a known device with the aforementioned encryption key;
   A) If cryptograms match and there is no data to synchronize, authentication is confirmed and the session is completed;
   B) If there's a cryptogram mismatch or there is data to synchronize, we continue the command flow;
3. STANDARD (AUTH1):
   Reader combines keys, nonces, other data exchanged during the transaction and signs it using its own private key; A device verifies that a signature is valid, and returns an encrypted payload containing signature of the transaction data using the device key; Common keys are established during this step to be used in FAST command in next communications.
4. EXCHANGE:
   Using the established encrypted channel, reader can request a switch to a configuration applet, by providing a shared secret to be used during that operation.
   In cases when a reader does not recognize the device, the communication continues further with configuration.

• CONTROL FLOW: Used in between other commands to communicate transaction state to the device. This command is responsible for UX, such as:
  • Success checkmark;
  • Failure exclamation mark;
  • Error messages;
  • Notify about a switch to configuration applet;

5. SELECT CONFIGURATION APPLET:
   Reader transmits Home Key Configuration AID. Device responds positively without any data; Re-selection is done because the device has to switch routing from the SE to HCE for attestation transfer.
6. ENVELOPE:
   Reader transmits BER-TLV-encoded data with nested CBOR or NDEF messages.
   First ENVELOPE command and response pair mimics ISO18013 NFC handover with NDEF.
   Following command-response pairs mimic CBOR data transfer with nested encrypted data. The data format is the same as in ISO18013.
   Useful payload part contains device's secp256r1 public key used by Home Key, attested by the public ed25519 HAP key of device owner.

• GET RESPONSE: If a response to ENVELOPE or GET RESPONSE had an sw 6100, reader uses this command to request additional response parts.

An alternative overview of the NFC transaction flow can be seen here.

Any response rather than 9500 means that applet is not available

Currently only versions 0100 and 0200 aka 1.0 and 2.0 are known

5c[04]: 
  02000100   # Supports version 2.0, and version 1.0

FLAG and TYPE parameters seem to correlate with overall transaction length;

Flag:

• 00 if intending to use STANDARD command (no cryptogram will be generated in response);
• 01 if trying to use FAST command only (still can continue with STANDARD if fail).

Status other than 9500 cannot be encountered

86[41]: 
  046e197441b017a6452dfe33a3645860c09a7fb34f3e84c9d6a834c737fe4e4185b37cccc2004b9cb08f837b0920d42c59ab1ce403a95cefdfe221120175f82218
9d[10]:
  7656a6256aee6f9bdc55ed45d96026a3

In order to guarantee privacy due to the lack of reader authentication in FAST command, the endpoint does not return identifiable data as-is. To find out if there's a cryptogram match, a reader has to iterate over all possible enrolled device combinations;

For a check to be successful, the following data about the endpoint should be already present:

• Persistent key, generated during last successful STANDARD session with this reader identifier and endpoint combination;
• Endpoint public key;

Cryptogram is calculated using the HKDF SHA256 with 64-byte length, null salt, and custom shared info. Persistent key is used to derive the final result:

Shared info is built using the following data, in the same order as presented:

Following python code provides an example of cryptogram generation:

key_size = 16
hkdf = HKDF(
    algorithm=hashes.SHA256(),
    length=key_size * 4,
    salt=None,
    info=info,
).derive(k_persistent)
kcmac = hkdf[: key_size * 1]
kenc = hkdf[key_size * 1 : key_size * 2]
kmac = hkdf[key_size * 2 : key_size * 3]
krmac = hkdf[key_size * 3 :]
calculated_cryptogram = kcmac

9e[40]:
  57a071cfeeff242878c68ef02fc430fe59cbf56741a1cadfcb0b23f962723d7321b67ab65015d50688edd17e7e658f4f6547b79bcbf9024a3bf701c216256050

During the STANDARD command, the reader generates a signature over commonly known data in order to prove to the endpoint that it's safe to talk to, thus protecting against malicious readers. The device, in turn, generates its own signature, in order to prove itself to the reader.

Authentication hash uses the following components for input material, in the same order as presented:

This data is then signed using the ECDSA, and the resulting signature in point form is then used.
Following python code provides an example of signature generation:

signature = reader_private_key.sign(
  authentication_hash_input, ec.ECDSA(hashes.SHA256())
)
x, y = decode_dss_signature(signature)
signature_point_form = bytes([*x.to_bytes(32, "big"), *y.to_bytes(32, "big")])

Following python code provides an example of signature verification:

try:
  endpoint_public_key.verify(
      signature, verification_hash_input, ec.ECDSA(hashes.SHA256())
  )
except InvalidSignature as e:
  pass

Starting from the response of STANDARD command and onward, excluding OP CONTROL FLOW, a secure channel is used for communication. This means that both commands and responses will be encrypted.

Explaining the implementation could require a fully separate document itself, so it's omitted.
Instead, you're invited to take a look at session key derivation code and at a digital key secure session implementation itself;

SUCCESS is a flag that indicates transaction status:

• 00 - Failure;
• 01 - Success (Checkmark will appear);
• 40 - Need to switch to HCE applet for attestation exchange.

STEP is a second flag:

• 00 - Failure or success in normal circumstances;
• a0 - Need to switch to HCE applet for attestation exchange.

Any response rather than 9500 means that applet is not available. This applet is only selectable after EXCHANGE CONTROL FLOW (need attestation) commands have been successfully used.
otherwise the device will present an error and stop NFC communication.

FRMT real meaning is unknown, but according to observations it means the following:

• 01 NDEF nfc handover message in command and response (first command-response pair only);
• 00 CBOR message in command in response (other command-response pairs).

Status words:

Starting from ENVELOPE 00, ISO18013 secure context is used during communication.
ISO18013 secure context does not encrypt the outer payload, but only the inner data inside of the TLV tag.

Describing the implementation in full is out of the scope of this document. Instead, you're invited to take a look at session key derivation code and at a ISO18013 secure session implementation itself;

LE should be equal to the value returned in the previous response to ENVELOPE or GET RESPONSE;

Status words:

After a full attestation package has been retrieved using ENVELOPE GET RESPONSE, it has to be verified.

The verification process mimics the ISO18013 claim verification process. The attestation package itself is signed by the issuer key known to a lock, issuer identifier is located in unprotected headers.

Following python code provides an example of attestation verification:

attestation_package_cbor = cbor2.loads(attestation_package)
issuer_signed_cbor = attestation_package_cbor["documents"][0]["issuerSigned"]["issuerAuth"]
protected_headers, unprotected_headers, data, signature = issuer_signed_cbor
issuer_id = unprotected_headers[4]
data_cbor = cbor2.loads(cbor2.loads(data).value)
device_key_info = data_cbor["deviceKeyInfo"]["deviceKey"]
device_public_key_x, device_public_key_y = (
    device_key_info[-2],
    device_key_info[-3],
)
device_public_key_bytes = (
    bytes.fromhex("04")   device_public_key_x   device_public_key_y
)

issuer = find_issuer_by_id(issuers, id=issuer_id)
if issuer is None:
    raise ProtocolError(f"Could not find issuer {issuer_id}")

public_key = ed25519.Ed25519PublicKey.from_public_bytes(issuer.public_key)

data_to_sign = cbor2.dumps([COSE_CONTEXT, protected_headers, COSE_AAD, data])

try:
    public_key.verify(signature, data_to_sign)
except InvalidSignature:
    pass

Unlike with Car Keys, where invited keys are attested by the key of a car owner, each Home Key is attested by the HAP (AKA issuer) keys of each particular person.
This has the following advantages:

• People may be removed from Apple Home at will, as it wouldn't break the attestation chain for everyone else (only the HAP-issuer key of the removed person will be removed);
• It allows for a lock to support more enrolled devices, as the lock really only needs to permanently store issuer keys, and a single one can attest multiple devices at a time (phone watch).
  However in reality the lock still stores some amount of credentials locally, as attestation exchange takes much longer than FAST auth (0.2sec vs 1sec);
• Enrolled users can provision all of their new/buddy devices automatically, as they are the ones to attest them using their issuer key.

But there are also disadvantages:

• Home Key protocol, unlike Car Key protocol, does not support "free-for-all" sharing natively, as it assumes that each key is bound to a particular HAP key, which automatically requires someone to be present in your Apple Home;
• Home Key protocol lacks a practical key revocation mechanism, as all credential identifiers are self-assigned and not provided by the installation, so the attestation package from the enrolled issuer can be replayed by a compromised (e.g. stolen) device. There's a blocklist for cases like Find My Lock, but most existing locks can store only up to 16 suspended identifiers.

With the upcoming release of Aliro, which solves most of the apparent issues and prominently declares support for cross-platform and open sharing, chances of Home Keys getting "open" sharing support are next to one.

During the tests, it was found that a single device can store up to 16 persistent keys used for FAST authentication.
The keys are overwritten in a FIFO/Cyclic fashion, with the oldest unused one removed the first. Even with this limitation, the possible amount of locks in a single household is virtually unlimited, as your device will still fall back to a STANDARD authentication or even an attestation exchange if needed.

Home Key standard allows each lock to declare any number of supported issuer keys and suspended credentials. Most locks declare up to 16 of each to be supported.

Configuration applet, utilized for attestation package retrieval, is believed to be implemented via HCE. The reasons for that are the following:

1. It doesn't work in power reserve mode, with NFC communication hanging on reselection;
2. The same attestation package transferred during communication can be found in the .pkpass file of the key inside of the normal file system;

That would explain the need for additional applet reselection, as this is one of the ways of returning control to the OS in order to give it the ability to read the package file and send it via NFC.
Also, storing a static 0.6-1kb package inside of the highly limited (1mb?) SE memory would've been wasteful.

It raises the question if the so similar Digital Car Key dual-applet system works the same way.

Nicolaus Copernicus was a Renaissance polymath, active as a mathematician, astronomer, and Catholic canon. - Wikipedia.

Besides, Copernicus is the internal codename of the applet used by Apple Home Keys.

Apple OS internals contain not one, but three codenames that start with such a name:

• CopernicusCar;
• CopernicusHome;
• CopernicusAccess.

Taking a deeper look, we find out that all of those applets share:

• the same primary internal AID A000000704D011500000000002000000;
• and container AID A000000704D011500000000001000000.

Which means that they share the same implementation.

Moreover, passes of those types are recognized by PassKit as being of UnifiedAccess type, which is potentially the internal name of that protocol group.

This tells:

1. Why there is so much overlap between the Car Key protocol (as described in an overview video), and a Home Key protocol - because it's the same code base, just with some features/quirks for each subtype turned on and off for particular instances;
2. That there could potentially be a third, publicly unknown Access implementation.
   The one based not on Seos (offices) or Mifare (hotels, offices, theme parks), but on the UnifiedAccess standard. This "Access" applet could be the one used in solutions provided to Hotels and managed Properties, the ones that have built-in sharing functionality. The only real-life implementation of this protocol variation was presumably done by Salto, as they are the only ones who offer native in-wallet key sharing;
3. Why the attestation exchange part of the Home Key protocol seemed too complex for the task it was aiming to achieve, especially the storage of validity dates, floor and room access flags, etc. In the context of shared/managed properties all of that info could be used for "offline synchronization", as an endpoint would be able to prove access to a particular zone of the property without a need for a reader to ring up a backend and continuously synchronize a list of allowed users.

Both the Home and Access Keys have system references starting with purpleTrustAir prefix. Additionally, Car, Home, and Access applets have references to them that start or end with pta.

Moreover, there exists an entry called ptc, which is presumably an abbreviation of PurpleTrustClassic, which can be found throughout the system. Unlike the air references, ptc has multiple applet AIDs assigned to it:

• Primary: FFFFFFFFFF222420A307ECE, A000000704C0000000000001;
• Container A000000704C0000000000000.

This information leads us to multiple assumptions about what PurpleTrust does, or what it has to do with UnifiedAccess:

• It's an Applet that implements crypto functionality external to the main CPU SEP used for general purposes, similar to StrongBox Keymaster on Android:
  • It could be related to ISO18013, which uses SE only for keys which are used for signing;
• It's responsible for sharing functionality used by UnifiedAccess applets:
  • Could be used for the storage of attestation packages;
  • Could be used for the storage of the issuer's private key, which is then used to sign attestations for the invitees.
• Classic implementation is either an older version of the implementation or a more secure one (running on the SE vs TEE), while Air could be newer or simpler (SEP-backed);

Passkit framework defines the following ISO18013 credential storage partitions:

• Identity
• UnifiedAccess

It proves that the usage of ISO18013 by UnifiedAccess was not a "one-time quick hack" but more like "temporary solutions are permanent".

Considering that ISO18013 for a Home Key can be found on a file system, it raises a question if it's the same for Identity, or if the different Partition part actually means that Identity document is stored somewhere else?

Indeed, Apple doesn't claim that ISO18013 Identity runs on the secure element. Instead, they say:

The information reflected on the user’s ID in Apple Wallet is stored in an encrypted format protected by the Secure Enclave.

By storing the private key for ID authentication in the iPhone device’s Secure Element, the ID is bound to the same device that the state-issuing authority created the ID for"

It means that base ISO18013 identity data is not stored in the secure element, but is instead stored in the file system either in a SEP-key-backed encrypted form or a plain form, with SE only being used for crypto-proof generation.
So it seems like Apple's ISO18013 implementation runs via HCE, with SE serving only for key storage. Looks quite similar to how it works with newer StrongBox-equipped Android devices. Eh :))?.

Aliro is practically confirmed to be a derivative of UnifiedAccess, which Home Key was built upon.

It means that Aliro will be using most, if not all of the concepts introduced with UnifiedAccess.
In addition to existing features, Aliro will feature:

• Proper key sharing:
  • Automatic sharing with users enrolled to the same Matter installation.
  • Revocable sharing with external users;
• BLE UWB support;
• Credential use limitations:
  • Time of day.
  • Day of the week;
• Potentially improved security thanks to the use of verification key injected into all credentials.

All Copernicus-based Car/Home/Access applets share the same implementation with the same memory usage regardless of instance type.
According to the Passkit framework (thanks to the SE memory management screen), the usage is as follows (numbers in bytes):

Copernicus executable code (Package) takes 54356 bytes (54 KB), with each instance (Personalized) taking an additional 5900 bytes each.

Modern IOS devices have about 0.7MB of memory available for users, which means that a user will be able to add about (700000 - 54356) / 5900 = 109 keys until the memory runs out.
In reality, due to the nature of JCOP, GC, and other things (such as additional provisioning for Selectable and Container memory, which I'm not entirely sure about, tell me if you know), the real number could differ.
Also, considering that a real user will install other applets, this amount could drop significantly, but regardless of that, no normal person will ever reach the limit.

• If you find any mistakes/typos or have extra information to add, feel free to raise an issue or create a PR;
• Please be aware that the information presented here is based on personal findings, observations, and assumptions, so there's no guarantee that it's correct in its entirety;
• Communication examples can be viewed in resources directory.

• @kupa22 - for full HAP part analysis, NFC protocol research;
• @kormax - ECP, NFC protocol research;

Additional thanks to:

• @gm3197 - for finding clues about ISO18013 being used in the Home Key protocol;
• @KhaosT - for creating a demo that caused Home Key to appear in Wallet, which played a part in inspiring me/others to explore this technology;
• @rednblkx and @vincentpeyrouse for helping with finding more info about ptc, pta and PurpleTrust.

• Resources that helped with research:
  • Parallel Home Key protocol research project:
    • Apple HomeKey - @kupa22;
  • Original inspiration:
    • KhaosT - Home Key demo (Archive);
  • General:
    • TLV8 format;
    • List of digital keys in mobile wallets;
    • IPSW.me - used to get IOS IPSW to look for clues in a file system;
    • TLV Utilities;
    • ASN1 decoder;
    • NDEF parser;
    • CBOR playground.
  • Source code:
    • Google: Identity credential.
  • Apple resources:
    • Apple Developer Documentation;
    • WWDC Introducing "Home Keys" (I'm not kidding);
    • Unlock your door with a home key on iPhone.
  • Device brochures:
    • Aqara A100 Zigbee;
    • Aqara D100 Zigbee;
    • Aqara Smart Lock U100;
    • Schlage encode plus;
    • Level Lock ;
    • TUO Smart Lock.
  • Other:
    • CSA-IOT - Aliro;
    • Salto Homelok - Apple Wallet Keys;
    • Aliro - collection of information about Aliro;
    • Matter - contains Aliro references.
• Devices and software used for analysis:
  • HAP-NodeJS - used to create virtual lock instances in order to look at communication and data structures;
  • Proxmark3 Easy - used to sniff Home Key transactions. Proxmark3 RDV2/4 can also be used;
  • Proxmark3 Iceman Fork - firmware for Proxmark3.