Enforce an encryption policy on macOS computers to protect data on the hard drive and escrowing recovery keys stored in Workspace ONE UEM so the keys can be recovered at later time.
With FileVault2, Workspace ONE UEM builds on native capabilities to encrypt the drive and provides functionality within the Workspace ONE Intelligent Hubto force the user to complete the encryption process.
Once the decision is made to encrypt your managed devices, you have options that allow you to choose the best recovery model for your deployment. These include recovery keys for Personal use, Institutional use, or a combination of both.
Institutional and Personal recovery is useful if the user will benefit from viewing and keeping a Personal Recovery Key, but the company will need a quick way to decrypt the device using a Institutional Recovery Key when necessary.
Once FileVault is enabled on the device, the Personal Recovery Key will be reported to the server.
Institutional recovery is beneficial because the network administrator can decrypt any device using a single Institutional Recovery Key, saving time by not needing to enter a unique Personal Recovery Key for each computer.
Generally, Institutional recovery is reserved for Corporate Owned, Line-of-Business devices where the user does not have the ability to decrypt the device if they forget the login password.
Once FileVault is enabled on the device, the Institutional Recovery Key will be reported to the server.
An Institutional recovery key is a pre-made recovery key that can be installed on a system prior to the encryption process. Institutional recovery keys are not automatically generated and must be manually created before they can be used.
This section explains how to create an Institutional Recovery Key for macOS High Sierra (10.13) and above. However, the steps to create an Institutional Recovery Key for macOS Sierra (10.12) and below can be found at https://support.apple.com/en-us/HT202385.
To distribute the corporate recovery key through Workspace ONE UEM, first create the FileVault Corporate Recovery Key and then upload it to the configuration profile on the UEM console by following the steps:
Create FileVault Keychain.
Copy FileVaultMaster Keychain to Documents.
Unlock FileVaultMaster Keychain.
Add FileVaultMaster Keychain to Keychain Access Utility.
Validate FileVaultMaster Keychain Unlock.
Delete and Confirm Private Key Deletion.
Export FileVault Recovery Key Certificate.
Some of the additional steps to perform after exporting FileVaultMaster Recovery Key certificate are to:
Re-Lock the FileVaultMaster Keychain.
Delete keychain from keychain access – To remove references to the FileVaultMaster keychain in Keychain Access.
Store the keychain and password – Store both the keychain (containing the certificate and private key) and the Keychain Password in multiple, secure locations. Without both you will be unable to decrypt any FileVault 2 drives encrypted with this Institutional Recovery Key.
Create FileVault Keychain
On a macOS computer (10.13+), select the Launchpad icon and then select Others > Terminal.
In the Terminal window, type the following command to create a FileVaultMaster keychain. Follow the prompts to apply password to the created keychain.
sudo security create-filevaultmaster-keychain /Library/Keychains/FileVaultMaster.keychain.
Once the command is complete, launch the Finder.
Press Shift+command+G and enter /Library/keychains as the folder name.
Select Go to access the folder and to fetch the created keychain.
Ensure you make copies and securely store both the keychain file and the password used to create the keychain. This keychain contains the certificate and private key to decrypt any FileVault 2 encrypted devices.
Copy FileVaultMaster Keychain to Documents
Before you start using the created FileVaultMaster keychain, make a copy of it and save in a secure location. Because, you need the modified keychain to encrypt a device and unmodified keychain to recover encryptrd devices.
In Terminal, type the following to copy the keychain file. When prompted, enter your admin account password to elevate your rights.
cp /Library/Keychains/FileVaultMaster.keychain ~/Documents/FileVaultMaster.keychain
sudo cp /Library/Keychains/FileVaultMaster.keychain /Library/Keychains/FileVaultMaster2.keychain
Unlock FileVaultMaster Keychain
You can unlock the FileVaultMaster keychain using command followed by providing password.
Unlock the FileVaultMaster keychain by entering the following command and enter the password you used when the keychain was created.
security unlock-keychain /Library/Keychains/FileVaultMaster.keychain
If you get an unexpected result during this step, the unlock idle time might have elapsed. You need to re-issue the unlock command in the Terminal window.
Add FileVaultMaster Keychain to Keychain Access Utility
Add the FileVaultMaster keychain to the Access Utility using the keychain access application.
Before you add the FileVaultMaster keychain to the Keychain Access Utility, open the Keychain Access application through Terminal window using the following command.
open /Applications/Utilities/Keychain\ Access.app/
If you unlocked the keychain correctly, the keychain should show the unlocked icon in Keychain Access Utility. If it does not, you need to re-issue the unlock and re-add the keychain.
Validate FileVaultMaster Keychain Unlock
Validate the FileVaultMaster keychain to ensure it is unlocked.
After adding the FileVaultMaster keychain file, validate if it is unlocked by performing the following steps.
Ensure that the FileVaultMaster keychain shows unlocked icon.
Ensure that you can view the private key and certificate in the keychain.
Delete and Confirm Private Key Deletion
Once the validation of FileVaultMaster keychain file is complete, ensure you delete the FileVaultMaster Password Key (private key).
Navigate to FileVault Master Password Key > Delete "FileVault Master Password Key" and select Delete to confirm deletion of the private key.
Enter your administrative User Name and Password.
Select Modify Keychain.
By the end of this step, you have a FileVaultMaster.keychain file which does not contain the private key. This Keychain can be placed in \Library\Keychains in order to manually enable FileVault2 encryption with an Corporate Recovery Key.
Export FileVault Recovery Key Certificate
The configuration profile which configures the Institutional recovery key on the Workspace ONE UEM console requires only the certificate and not the keychain file.
Select the FileVault Recovery Key certificate in the FileVaultMaster keychain.
Select Export FileVault Recovery Key (....)...
Provide the certificate name as FileVaultMaster (in keeping the name consistent with the keychain file that it was created from).
Choose the location to save the certificate where you can access the key from your browser. (In this example, ~/Documents/).
By the end of this step, you now have a certificate file which DOES NOT contain the private key.
Enabling Personal as the recovery type will allow the user of the device to use a recovery key to decrypt their device. Additionally, that key can be reported to the UEM console to allow administrators to use the key to decrypt the device if necessary.
Use Personal keys rather than Enterprise keys because Workspace ONE UEM can audit access to these keys, since they are escrowed in the UEM console. Also, Personal keys are beneficial because they are unique to each device. This means that the compromise of one key on one device does not compromise the security of other devices.
Once this profile is deployed to the device, the user will see a prompt from the Workspace ONE Intelligent Hub taking them through the process of encrypting the disk. If configured, users may also be shown the recovery key to give them the option of saving it for later use. After a reboot, the device will begin the encryption process in the background and the user can continue their daily tasks normally without fear of interruption.
Enable Personal Recovery Encryption for a macOS Device
Personal recovery encryption is useful if the user wants the benefit of viewing and keeping a Personal Recovery Key from decrypt.
Configure a new Disk Encryption profile.
Choose Personal as the recovery type and configure the recovery key settings as needed.
Once FileVault is enabled on the device, the Personal Recovery Key will be reported to a Workspace ONE UEM server or another designated server.
View Escrowed Personal Recovery Key on the UEM Console
The personal recovery key is generated when FileVault 2 encryption is enabled and remains valid until the personal recovery key is changed or the disk is decrypted using that key.
To view an escrowed recovery key, perform the following within the Device Details page on the UEM console.
Select the Security tab.
Select View Recovery Key.
Note the Personal Recovery Key that is escrowed.
If required, note the Previous Recovery Key. The Previous Recovery Key field is loaded with the old key only if the Personal Recovery Key had been rotated at least once.
Close when finished viewing the key.
If an encrypted macOS volume is decrypted and then re-encrypted, then the previous personal recovery key would become invalid and a new one is created as part of the re-encryption process.
View Escrowed Personal Recovery Key on the SSP
The personal recovery key can also be viewed on the Self Service Portal, where the FileVault Personal Recovery Key (PRK) is automatically rotated 15 minutes after being accessed by the device user.
To view an escrowed recovery key on the SSP portal, perform the following steps:
Recover an Encrypted Disk Using a Personal Recovery Key
If you forget your personal password for FileVault, you can use a Recovery Key to regain access.
Start into recovery-mode (CMD+R at start), a different partition or connect the disk to another macOS.
Access the terminal and run the following command. The command fetches a list of the Logical CoreStorage Volumes.
diskutil cs list.
Find the Logical Volume (last on the list) and copy the UUID – it is in the format of XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX. Logical Volume is used to specify which volume must be unlocked and decrypted.
Ensure that you have the Personal Recovery Key available and run the command below. Replace "UUID" with the UUID retrieved in step 3. You are prompted to enter the Passphrase and the Personal Recovery Key.
diskutil cs unlockVolume UUID
You can now see a response showing that the volume is unlocked and mounted. Now, you can recover any necessary files.
Now that the volume is unlocked, you can begin the decryption process by using the following command and replacing "UUID" with the UUID retrieved in step 3. You are prompted to enter the Passphrase and the Personal Recovery Key.
diskutil cs revert UUID
To monitor the decryption status, use the following command. The status is located in the Logical Volume Family information.
diskutil cs list
Personal Recovery Key Rotation
To maintain the security of the FileVault Personal Recovery Key (PRK), Workspace ONE UEM supports a native MDM mechanism to automatically rotate the key after they have been accessed by a user in Self-Service Portal or by an administrator in the UEM Console in Device Details. This enforces a security practice that the PRK should only be viewed when needed to unlock a disk, and it needs to be re-secured in a timely manner
To use the automatic recovery key rotation feature, you must have:
Automatic Recovery Key Rotation When Viewed
When the Personal Recovery Key (PRK) is accessed through the Device Details page or the Self Service Portal, 15 minutes later, the native MDM command to rotate the PRK is queued for the device to process the command on the next check-in. Additionally, an event log is captured with the details, such as when the key was last viewed and by what user. The event logs also report the status of the PRK rotation command lifecycle.
Recovery key rotation can be performed by both the admins (through the UEM console) and the users (through the SSP). Step 1 details the procedure for admins and step 2 details the procedure for users.
Device must be encrypted with a Personal Recovery Key escrowed to the UEM console.
Select the View Recovery Key under the Security section of the Summary tab. The View Recovery Key page appears displaying the Current Personal Recovery Key with the timestamp it was rotated and additionally the previous recovery key for backup
If the recovery key was never rotated, the Previous Personal Recovery Key field remains empty
Approximately 15 minutes after completing step a, the MDM command to rotate the recovery key is queued for the device. For more information on auditing the key access and rotation lifecycle, see the View Rotated Recovery Key Event Logs section.
View Recovery Key Event Logs
When the command to rotate the recovery key is initiated, or when the recovery key sample is received, or any event related to the PRK occurs, it can be viewed on the UEM console. The events are tracked as Event Logs in the Troubleshooting tab on the Device Details page.
Retrieve the Recovery Key from API
The automatic recovery key rotation feature is available only for macOS devices. This feature was introduced to maintain the security of the FileVault Personal Recovery Key (PRK). Due to server performance reasons, the automatic rotation from APIs which returns the recovery key is removed. The automatic rotation functionality is available when the PRK is viewed in Device Details or SSP.
Note: It is recommended to follow up with a second API call to rotate the key as the automatic rotation will not occur.
Following GET APIs are used in retrieving the recovery key:
/devices/security - Retrieves the security information of the device identified by device ID
/devices/<id>/security - Retrieves the security information of the device identified by device ID
/devices/<uuid>/security/recovery-key - Retrieves the recovery key by the device UUID
Rotate Key Via API
To rotate the recovery key, use the following API:
Note: Use this API after calling one of the above GET calls.
macOS 10.15 Catalina introduces the Bootstrap Token feature to help with granting a SecureToken to mobile account users and the optional administrator account created during device enrollment through Apple Business Manager. This feature does not affect how local accounts are granted SecureTokens.
The introduction of Apple File System (APFS) in macOS 10.13 changed how FileVault encryption keys are generated and stored. These keys are generated either during the initial local user account creation or during the first login by a user. The SecureToken, which contains the generated keys, is a wrapped Key Encryption Key (KEK) protected by the user’s password. Any macOS account that must use FileVault authentication is required to have a SecureToken enabled. Directory (network) users are not eligible for SecureToken enablement.
Before macOS Catalina, enabling a mobile account user for SecureToken required specific workflows, some of which required entering existing SecureToken enabled administrator credentials to enable the new user account for SecureToken. Bootstrap Token eliminates this process for MDM enrolled devices.
For User Approved MDM (UAMDM) enrolled devices on macOS 10.15.4 or later, a Bootstrap Token is automatically generated and escrowed to Workspace ONE UEM on the first login by any user who is SecureToken enabled. If needed, a Bootstrap Token can also still be generated and escrowed manually using the
/usr/bin/profiles command-line tool.
A Bootstrap Token cannot be generated and escrowed automatically if a local user account creation is skipped during Setup Assistant.
After the Bootstrap Token is escrowed in Workspace ONE UEM, future user accounts can use it during login to be automatically enabled with a SecureToken. When a mobile account or device enrollment created administrator logs in, macOS automatically requests the Bootstrap Token from the UEM server and uses it with the user credentials to enable a unique SecureToken for that user on that volume.
The Bootstrap Token is a unique key used for only this purpose by MDM and cannot be used instead of a Personal Recovery Key (PRK).
For existing deployed systems, administrators can use the
/usr/bin/profiles command-line tool with user credentials for an existing SecureToken enabled administrator account to manually generate a Bootstrap Token for future logins by mobile accounts.
Using console API's, administrators can now check for
BootstrapTokenEscrowStatus for macOS devices. For macOS Big Sur devices, additional details about Bootstrap Token will also be returned.
The following device security info API responses are updated to contain bootstrap token information:
Action - GET
Version - 1
Manually Create a Bootstrap Token
After a macOS 10.15 device is enrolled, an MDM setting will be automatically sent to the device to make Bootstrap Token available for escrow in UEM.
To verify the availability and to generate a Bootstrap Token, perform the following steps:
On the Mac, navigate to Applications > Utilities > Terminal.
To know if Bootstrap Token is supported, run the following command:
sudo profiles status -type bootstraptoken
This command will return output similar to the following:
Bootstrap Token supported on server:YES Bootstrap Token escrowed to server:YES(Or NO)
The first line indicates that UEM supports Bootstrap Token and the second line indicates if it has already been escrowed or not. If the Bootstrap Token has not yet been escrowed, proceed to Step 3.
Note: The automatic escrow of Bootstrap Token only happens on macOS 10.15.4 or later. For versions between 10.15.0 and 10.15.3, it must be manually done.
To generate and escrow a Bootstrap Token, run the following command:
sudo profiles install -type bootstraptoken
This command is interactive and requires the admin username and password to be entered.
Enter the admin username:adminuser Enter the password for user 'adminuser': profiles: Create Bootstrap Token created profiles: Bootstrap Token created profiles: Bootstrap Token escrowing to server... profiles: Bootstrap Token escrowed
After the Bootstrap Token is escrowed, you can run the command from Step 2 again to verify:
sudo profiles status –type bootstraptoken Bootstrap Token supported on server: YES Bootstrap Token escrowed to server: YES
For further verification, run the following command to list which accounts can unlock the FileVault encrypted disk:
diskutil apfs listcryptousers /
This command must return the UUID of the newly enabled mobile account and the Bootstrap Token External Key.
You can compare this list with
sudo fdesetup list to verify the UUIDs of SecureToken enabled accounts:
Cryptographic users for disk1s5 (3 found) | +-- 16C00654-9A3E-4129-BF21-A66261BBA58C | Type: Local Open Directory User | +-- 2457711A-523C-4604-B75A-F48A571D5036 | Type: MDM Bootstrap Token External Key | +-- C3701A60-377E-4A55-94B8-3147975C357A Type: Local Open Directory User
sudo fdesetup list adminuser,16C00654-9A3E-4129-BF21-A66261BBA58C mobileuser,C3701A60-377E-4A55-94B8-3147975C357A
Manually Delete a Bootstrap Token
If you want to remove the Bootstrap Token for a device, run the following command:
sudo profiles remove -type bootstraptoken Enter the admin username:adminuser Enter the password for user 'adminuser': profiles: Bootstrap Token deleted profiles: Bootstrap Token clearing on server... profiles: Bootstrap Token cleared
Bootstrap Token is deleted from the device and the UEM server.
View the Event Logs
To view the event logs in Workspace ONE UEM console, navigate to Devices> Details View > Troubleshooting.
Filter by Module = Devices to see Event Logs related to Bootstrap Token: