FileVault Recovery-Key Escrow

Athena can hold the FileVault personal recovery key of each Mac you manage. From a Mac's FileVault tab you have the Mac generate a new personal recovery key, Athena stores it encrypted on your own server, and an authorised administrator can reveal it later with a reason. Every reveal is audited. This is the macOS counterpart of BitLocker recovery-key escrow. Keys never leave your network, so it works on an air-gapped network.

How it works#

macOS never hands out a Mac's existing personal recovery key. The only way to get a key into Athena is to have the Mac make a new one. So in Athena, escrowing a key and rotating it are the same action:

1. You click Escrow / rotate key on the Mac's FileVault tab.
2. The agent asks macOS for a new personal recovery key. From that moment the Mac's previous personal recovery key no longer works, including any copy a user wrote down.
3. The agent sends the new key to the server, which stores it encrypted and confirms. The tab updates by itself and shows "The new FileVault recovery key is escrowed."

macOS requires authentication for a rotation, even for an agent running as root. The first time, you supply it (see First escrow). After that, Athena authenticates every later rotation with the key it already holds, so nothing else is needed.

Athena keeps only the current key for each Mac. There is no key history, because a rotated-away key no longer unlocks anything.

The FileVault tab#

Open Agents, select a Mac, and choose the FileVault tab (right after BitLocker). The tab is headed Personal recovery key and shows one of these:

The Escrow / rotate key button appears only if you may manage keys (see Permissions). The tab updates by itself when the Mac reports a new key or a failed rotation. You don't need to reload the page.

The Boot & Security section of the agent's inventory also shows the Mac's FileVault state. With agent 1.2.123 or later it shows the state (On, Off, Encrypting, Decrypting or Enable pending, with a percentage while it is encrypting or decrypting), plus the rows FileVault Unlock Users, Personal Recovery Key, Institutional Recovery Key and Deferred Enablement. Those rows are inventory only. The FileVault tab is where escrow happens.

First escrow#

When Athena holds no key for the Mac yet, the Escrow / rotate recovery key dialog asks for one of these, because macOS will not rotate without it:

• The Mac's current personal recovery key. Enter it in Current recovery key or that user's password and leave Unlock user name (only with a password) empty.
• A FileVault unlock user's name and password. Enter the user name in Unlock user name (only with a password) and that user's password in the second field. The FileVault Unlock Users row in Boot & Security lists who can unlock the Mac.

Then click Rotate now (it stays disabled until the second field is filled in). What you type is sent to the Mac once for this rotation. It is never stored, never logged and never written to an audit entry, and it is cleared when the dialog closes.

Rotating a key#

Once a key is escrowed, the dialog says "Athena authenticates with the key it already holds; nothing else is needed." Click Rotate now. Rotate after you have revealed a key to someone, for example, so the key they saw stops working.

After you click Rotate now you see one of these messages:

A new key is never lost

The agent saves the new key on the Mac, readable by root only, before it sends it, and deletes that copy only after the server confirms it has stored the key. If the confirmation is lost (for example the network drops or the server restarts), the server asks for the key again the next time the agent connects, and the agent sends it. While a key is waiting for confirmation, the agent refuses a new rotation and re-sends the waiting key instead, so a second rotation can never replace a key the server does not have yet.

When a rotation fails

If macOS does not rotate the key, the Mac's previous key stays valid, you see "The Mac could not rotate its FileVault recovery key; the previous key is still valid.", and the tab shows Last rotation failed with one of these reasons:

A successful rotation clears the Last rotation failed line.

Revealing a key#

To read a Mac's escrowed key to a user, for example at the FileVault unlock screen, click Reveal on its FileVault tab. Revealing follows the same rules as a BitLocker recovery-password reveal:

• You need the Reveal BitLocker recovery keys permission (Admin by default).
• A reason is required, with at least 3 visible characters (up to 500), for example a help desk ticket number. Reveal key stays disabled until you enter one.
• The reveal is written to the audit log with your name and the reason before the key is shown. If the audit entry cannot be written, the key is withheld.
• The key is shown in the form XXXX-XXXX-XXXX-XXXX-XXXX-XXXX. Copy puts it on your clipboard. The key hides automatically after 30 seconds, and if you copied it, closing the dialog clears the clipboard.

Permissions#

FileVault has no permissions of its own. It uses the BitLocker permissions, so one role setup covers disk encryption on Windows and macOS. See BitLocker permissions and Roles & Permissions.

How keys are stored#

Escrowed FileVault keys are encrypted on your Athena server with the same protection as BitLocker recovery passwords, which depends on the server's certificate authority. A key is decrypted only for a reveal or to authenticate a rotation. Keys and credentials are never written to logs or audit entries. See Certificates & PKI and back up the CA together with the database.

Audit events#

FileVault actions appear in the audit log with these event types. No row ever contains a recovery key or a credential.

REST API#

Everything the tab does is also available over the REST API (see API Reference and API Tokens). Responses use Athena's usual envelope, with the result in data. {id} is the agent's id.

For example, to rotate a Mac's key using the key Athena already holds:

curl -k -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{}' \
  "https://<server>:8443/api/filevault/agents/<agent-id>/rotate"

A 200 means the request reached the Mac. Check GET …/escrow afterwards: a new escrowedAt means the key was escrowed, and a new lastError means the rotation failed. There is no PowerShell cmdlet for FileVault escrow in this release.

Troubleshooting#

Related#

• macOS Agent: installing and running the agent on a Mac.
• BitLocker Management: disk encryption and recovery-key escrow on Windows.
• Boot & Security: FileVault state and unlock users in the inventory.
• Audit Event Types Reference: all audit events.
• Air-Gapped Operation: running Athena with no outbound connectivity.