apple_device-management/mdm/profiles/com.apple.security.FDERecoveryKeyEscrow.yaml

title: FDE Recovery Key Escrow
description: The payload that configures FileVault recovery key escrow.
payload:
  payloadtype: com.apple.security.FDERecoveryKeyEscrow
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '10.13'
      multiple: false
      devicechannel: true
      userchannel: false
      requiresdep: false
      userapprovedmdm: false
      allowmanualinstall: true
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  content: |-
    If FileVault is enabled after this payload is installed on the system, the FileVault PRK will be encrypted with the specified certificate, wrapped with a CMS envelope and stored at:
    /var/db/FileVaultPRK.dat
    The encrypted data will be made available to the MDM server as part of the SecurityInfo command. Alternatively, if a site uses their own administration software, they can extract the PRK from the above location at any time. As the PRK will be encrypted using the certificate provided in the profile, only the author of the profile can extract the data.
    Notes:
    * The payload must exist in a "system" scoped profile.
    * It will be an error to install more than one payload of this type per machine.
    * The old payload ("com.apple.security.FDERecoveryRedirect") will no longer be supported. It will still be allowed to be installed, but will be ignored. (This is so servers can send out the same profile to old and new clients).
    * If only an old-style redirection payload is installed at the time FileVault is turned on (via Security Pref pane), an error will be displayed and FileVault will not be allowed to be enabled.
    * No warning/error will be provided if FileVault is already enabled and an old-style payload is installed. In this case, it's assumed the recovery key has already been escrowed with the server.
payloadkeys:
- key: Location
  type: <string>
  presence: required
  content: The description of the location where the system escrows the recovery key.
    The system inserts this text into the message the user sees when it enables FileVault.
- key: EncryptCertPayloadUUID
  type: <string>
  presence: required
  content: The UUID of a payload within the same profile that contains the certificate
    that the system uses to encrypt the recovery key. The referenced payload must
    be of type `com.apple.security.pkcs1`.
- key: DeviceKey
  type: <string>
  presence: optional
  content: |-
    The string that's included in help text if the user appears to have forgotten the password. Site admins can use this key to look up the escrowed key for the particular computer.

    This key replaces the `RecordNumber` key used in the previous escrow mechanism. If the key is missing, the system uses the device serial number instead.
notes:
- title: ''
  content: |-
    FileVault Full Disk Encryption (FDE) recovery keys are, by default, sent to Apple if the user requests them. Only one payload of this type is allowed per system.

    If FileVault is enabled after the system installs this payload, the system encrypts the FileVault PRK with the specified certificate, wrapped with a CMS envelope and stored at `/var/db/FileVaultPRK.dat`. The `SecurityInfo` command makes this encrypted data available to the MDM server.

    Alternatively, if a site uses its own administration software, it can extract the PRK from the foregoing location at any time. Because the PRK is encrypted using the certificate provided in the profile, only the author of the profile can extract the data.

    Note these cautions:

    - The payload needs to exist in a system-scoped profile.
    - Installing more than one payload of this type per computer results in an error.
    - The previous payload (`com.apple.security.FDERecoveryRedirect`) is no longer supported. You can still install the previous payload but the system ignores it, so servers can send out the same profile to old and new clients.
    - If only an old-style redirection payload is installed at the time FileVault is turned on through the Security Preferences pane, the system displays an error and doesn't enable FileVault.
    - The system doesn't provide a warning or error if FileVault is already enabled and an old-style payload is installed. In this case, it's assumed that the recovery key has already been escrowed with the server.

    Although the system no longer supports the previous FDE Recovery payload in macOS 10.13 and later, it's still supported in macOS 10.9 through 10.12. Designate that payload by specifying `com.apple.security.FDERecoveryRedirect` as the payload type.
examples:
- title: Profile example
  files:
  - file: examples/mdm/profiles/com.apple.security.FDERecoveryKeyEscrow/example1.plist