Contents of a LocalPolicy file for a Mac with Apple silicon

Ownership handoff between operating systems

Access to the Owner Identity Key (OIK) is referred to as “Ownership.” Ownership is required to allow users to resign the LocalPolicy after making policy or software changes. The OIK is protected with the same key hierarchy as described in Sealed Key Protection (SKP), with the OIK being protected by the same Key encryption key (KEK) as the Volume encryption key (VEK). This means it’s normally protected by both user passwords and measurements of the operating system and policy. There’s only a single OIK for all operating systems on the Mac. Therefore, when installing a second operating system, explicit consent is required from the users on the first operating system to hand off Ownership to the users on the second operating system. However, users don’t yet exist for the second operating system, when the installer is running from the first operating system. Users in operating systems aren’t normally generated until the operating system is booted and the Setup Assistant is running. Thus two new actions are required when installing a second operating system on a Mac with Apple silicon:

• Creating a LocalPolicy for the second operating system

• Preparing an “Install User” for handing off Ownership

When running an Install Assistant and targeting installation for a secondary blank volume, a prompt asks the user if they’d like to copy a user from the current volume to be the first user of the second volume. If the user says yes, the “Install User” which is created is, in reality, a KEK which is derived from the selected user’s password and hardware keys, which is then used to encrypt the OIK as it’s being handed to the second operating system. Then from within the second operating system Install Assistant, it prompts for that user’s password, to allow it to access the OIK in the Secure Enclave for the new operating system. If users opt not to copy a user, the Install User is still created the same way, but an empty password is used instead of a user’s password. This second flow exists for certain system administration scenarios. However, users who want to have multivolume installs and want to perform Ownership handoff in the most secure fashion should always opt to copy a user from the first operating system to the second operating system.

LocalPolicy on a Mac with Apple silicon

For a Mac with Apple silicon, local security policy control has been delegated to an application running in the Secure Enclave. This software can utilize the user’s credentials and the boot mode of the primary CPU to determine who can change the security policy and from what boot environment. This helps prevent malicious software from using the security policy controls against the user by downgrading them to gain more privileges.

LocalPolicy manifest properties

The LocalPolicy file contains some architectural 4CCs that are found in most all Image4 files—such as a board or model ID (BORD), indicating a particular Apple chip (CHIP), or Exclusive Chip Identification (ECID). But the 4CCs below focus only on the security policies that users can configure.

LocalPolicy Nonce Hash (lpnh)

• Type: OctetString (48)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The lpnh is used for anti-replay of the LocalPolicy. This is an SHA384 hash of the LocalPolicy Nonce (LPN), which is stored in the Secure Storage Component and accessible using the Secure Enclave Boot ROM or Secure Enclave. The raw anti-replay value is never visible to the Application Processor, only to the sepOS. An attacker wanting to convince LLB that a previous LocalPolicy they had captured was valid would need to place a value into the Secure Storage Component, which hashes to the same lpnh value found in the LocalPolicy they want to replay. Normally there is a single LPN valid on the system—except during software updates, when two are simultaneously valid—to allow for the possibility of falling back to booting the old software in the event of an update error. When any LocalPolicy for any operating system is changed, all policies are re-signed with the new lpnh value corresponding to the new LPN found in the Secure Storage Component. This change happens when the user changes security settings or creates new operating systems with a new LocalPolicy for each.

Remote Policy Nonce Hash (rpnh)

• Type: OctetString (48)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The rpnh behaves the same way as the lpnh but is updated only when the remote policy is updated, such as when changing the state of Find My enrollment. This change happens when the user changes the state of Find My on their Mac.

recoveryOS Nonce Hash (ronh)

• Type: OctetString (48)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The ronh behaves the same way as the lpnh, but is found exclusively in the LocalPolicy for system recoveryOS. It’s updated when the system recoveryOS is updated, such as on software updates. A separate anti-replay value from the lpnh and rpnh is used so that when a device is put into a disabled state by Find My, existing operating systems can be disabled (by removing their LPN and RPN from the Secure Storage Component), while still leaving the system recoveryOS bootable. In this way, the operating systems can be reenabled when the system owner proves their control over the system by putting in their iCloud password used for the Find My account. This change happens when a user updates the system recoveryOS or creates new operating systems.

Next Stage Image4 Manifest Hash (nsih)

• Type: OctetString (48)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The nsih field represents an SHA384 hash of the Image4 manifest data structure that describes the booted macOS. The macOS Image4 manifest contains measurements for all the boot objects—such as iBoot, the static trust cache, device tree, Boot Kernel Collection, and signed system volume (SSV) volume root hash. When LLB is directed to boot a given macOS, it’s designed to ensure that the hash of the macOS Image4 manifest attached to iBoot matches what’s captured in the nsih field of the LocalPolicy. In this way, the nsih captures the user intention of what operating system the user has created a LocalPolicy for. Users change the nsih value implicitly when they perform a software update.

Cryptex1 Image4 Manifest Hash (spih)

• Type: OctetString (48)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The spih field represents an SHA384 hash of the Cryptex1 Image4 manifest data structure. The Cryptex1 Image4 manifest contains measurements of its cryptexes, their file system seals, and their associated trust cache. When macOS is starting up, the XNU kernel and Page Protection Layer ensure that the hash of the Cryptex1 Image4 manifest matches what iBoot published from the spih field of the LocalPolicy. Users change the spih value implicitly when they install a Rapid Security Response or perform a software update. The Cryptex1 Image4 Manifest Hash can be updated independently of the Next Stage Image4 Manifest Hash.

Cryptex1 Generation (stng)

• Type: 64 bit unsigned integer

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The stng field is a counter value representing when the Cryptex1 Image4 Manifest Hash was last updated in a LocalPolicy. It provides an anti-replay value in place of lpnh during the Page Protection Layer’s evaluation of the local policy for applying the Incoming Cryptex. Users increase the stng value implicitly when they install a Rapid Security Response or a software update.

Auxiliary Kernel Collection (AuxKC) Policy Hash (auxp)

• Type: OctetString (48)

• Mutable environments: macOS

• Description: The auxp is an SHA384 hash of the user-authorized kext list (UAKL) policy. This is used at AuxKC generation time to help ensure that only user-authorized kexts are included in the AuxKC. smb2 is a prerequisite for setting this field. Users change the auxp value implicitly when they change the UAKL by approving a kext from Privacy & Security in System Settings (macOS 13 or later) or the Security & Privacy pane in System Preferences (macOS 12 or earlier).

Auxiliary Kernel Collection (AuxKC) Image4 Manifest Hash (auxi)

• Type: OctetString (48)

• Mutable environments: macOS

• Description: After the system verifies that the UAKL hash matches what’s found in the auxp field of the LocalPolicy, it requests that the AuxKC be signed by the Secure Enclave processor application that’s responsible for LocalPolicy signing. Next, an SHA384 hash of the AuxKC Image4 manifest signature is placed into the LocalPolicy to avoid the potential for mixing and matching previously signed AuxKCs to an operating system at boot time. If iBoot finds the auxi field in the LocalPolicy, it attempts to load the AuxKC from storage and validate its signature. It also verifies that the hash of the Image4 manifest attached to the AuxKC matches the value found in the auxi field. If the AuxKC fails to load for any reason, the system continues to boot without this boot object and (so) without any third-party kexts loaded. The auxp field is a prerequisite for setting the auxi field in the LocalPolicy. Users change the auxi value implicitly when they change the UAKL by approving a kext from Privacy & Security in System Settings (macOS 13 or later) or the Security & Privacy pane in System Preferences (macOS 12 or earlier).

Auxiliary Kernel Collection (AuxKC) Receipt Hash (auxr)

• Type: OctetString (48)

• Mutable environments: macOS

• Description: The auxr is an SHA384 hash of the AuxKC receipt, which indicates the exact set of kexts that were included into the AuxKC. The AuxKC receipt can be a subset of the UAKL, because kexts can be excluded from the AuxKC even if they’re user authorized if they’re known to be used for attacks. In addition, some kexts that can be used to break the user-kernel boundary may lead to decreased functionality, such as an inability to use Apple Pay or play 4K and HDR content. Users who want these capabilities opt in to a more restrictive AuxKC inclusion. The auxp field is a prerequisite for setting the auxr field in the LocalPolicy. Users change the auxr value implicitly when they build a new AuxKC from Privacy & Security in System Settings (macOS 13 or later) or the Security & Privacy pane in System Preferences (macOS 12 or earlier).

CustomOS Image4 Manifest Hash (coih)

• Type: OctetString (48)

• Mutable environments: 1TR

• Description: The coih is an SHA384 hash of CustomOS Image4 manifest. The payload for that manifest is used by iBoot (instead of the XNU kernel) to transfer control. Users change the coih value implicitly when they use the kmutil configure-boot command-line tool in 1TR.

APFS volume group UUID (vuid)

• Type: OctetString (16)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The vuid indicates the volume group the kernel should use as root. This field is primarily informational and isn’t used for security constraints. This vuid is set by the user implicitly when creating a new operating system install.

Key encryption key (KEK) Group UUID (kuid)

• Type: OctetString (16)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The kuid indicates the volume that was booted. The key encryption key has typically been used for Data Protection. For each LocalPolicy, it’s used to protect the LocalPolicy signing key. The kuid is set by the user implicitly when creating a new operating system install.

Paired recoveryOS Trusted Boot Policy Measurement (prot)

• Type: OctetString (48)

• Mutable environments: 1TR, recoveryOS, macOS

• Description: A paired recoveryOS Trusted Boot Policy Measurement (TBPM) is a special iterative SHA384 hash calculation over the Image4 manifest of a LocalPolicy, excluding anti-replay values, to give a consistent measurement over time (because anti-replay values like lpnh are frequently updated). The prot field, which is found only in each macOS LocalPolicy, provides a pairing to indicate the recoveryOS LocalPolicy that corresponds to the macOS LocalPolicy.

Has Secure Enclave Signed recoveryOS Local Policy (hrlp)

• Type: Boolean

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The hrlp indicates whether or not the prot value (above) is the measurement of a Secure Enclave–signed recoveryOS LocalPolicy. If not, then the recoveryOS LocalPolicy is signed by the Apple online signing server, which signs things such as macOS Image4 files.

Local Operating System Version (love)

• Type: Boolean

• Mutable environments: 1TR, recoveryOS, macOS

• Description: The love indicates the OS version that the LocalPolicy is created for. The version is obtained from the next state manifest during LocalPolicy creation and is used to enforce recoveryOS pairing restrictions.

Secure Multi-Boot (smb0)

• Type: Boolean

• Mutable environments: 1TR, recoveryOS

• Description: If smb0 is present and true, LLB allows the next stage Image4 manifest to be globally signed instead of requiring a personalized signature. Users can change this field with Startup Security Utility or bputil to downgrade to Reduced Security.

Secure Multi-Boot (smb1)

• Type: Boolean

• Mutable environments: 1TR

• Description: If smb1 is present and true, iBoot allows objects such as a custom kernel collection to be Secure Enclave signed with the same key as the LocalPolicy. Presence of smb0 is a prerequisite for presence of smb1. Users can change this field using command-line tools such as csrutil or bputil to downgrade to Permissive Security.

Secure Multi-Boot (smb2)

• Type: Boolean

• Mutable environments: 1TR

• Description: If smb2 is present and true, iBoot allows the Auxiliary Kernel Collection to be Secure Enclave signed with the same key as the LocalPolicy. The presence of smb0 is a prerequisite for the presence of smb2. Users can change this field using Startup Security Utility or bputil to downgrade to Reduced Security and enable third-party kexts.

Secure Multi-Boot (smb3)

• Type: Boolean

• Mutable environments: 1TR

• Description: If smb3 is present and true, a user at the device has opted in to mobile device management (MDM) control of their system. Presence of this field makes the LocalPolicy-controlling Secure Enclave processor application accept MDM authentication instead of requiring local user authentication. Users can change this field using Startup Security Utility or bputil to enable managed control over third-party kexts and software updates. (In macOS 11.2 or later, MDM can also initiate an update to the latest macOS version if the current security mode is Full Security.)

Secure Multi-Boot (smb4)

• Type: Boolean

• Mutable environments: macOS

• Description: If smb4 is present and true, the device has opted in to MDM control of the operating system using Apple School Manager, Apple Business Manager, or Apple Business Essentials. Presence of this field makes the LocalPolicy-controlling Secure Enclave application accept MDM authentication instead of requiring local user authentication. This field is changed by the MDM solution when it detects that a device’s serial number appears in any of those three services.

System Integrity Protection (sip0)

• Type: 64 bit unsigned integer

• Mutable environments: 1TR

• Description: The sip0 holds the existing System Integrity Protection (SIP) policy bits that previously were stored in NVRAM. New SIP policy bits are added here (instead of using LocalPolicy fields like the below) if they’re used only in macOS and not used by LLB. Users can change this field using csrutil from 1TR to disable SIP and downgrade to Permissive Security.

System Integrity Protection (sip1)

• Type: Boolean

• Mutable environments: 1TR

• Description: If sip1 is present and true, iBoot allows failures to verify the SSV volume root hash. Users can change this field using csrutil or bputil from 1TR.

System Integrity Protection (sip2)

• Type: Boolean

• Mutable environments: 1TR

• Description: If sip2 is present and true, iBoot won’t lock the Configurable Text Read-only Region (CTRR) hardware register that marks kernel memory as non-writable. Users can change this field using csrutil or bputil from 1TR.

System Integrity Protection (sip3)

• Type: Boolean

• Mutable environments: 1TR

• Description: If sip3 is present and true, iBoot won’t enforce its built-in allow list for the boot-args NVRAM variable, which would otherwise filter the options passed to the kernel. Users can change this field using csrutil or bputil from 1TR.

Certificates and RemotePolicy

As described in LocalPolicy signing-key creation and management, the LocalPolicy Image4 also contains the Owner Identity Certificate (OIC) and the embedded RemotePolicy.