| fdesetup(8) | System Manager's Manual | fdesetup(8) |
fdesetup —
FileVault configuration tool
fdesetup |
verb [options] |
fdesetup is used to enable or disable
FileVault, to list, add, or remove enabled FileVault users, and to obtain
status about the current state of FileVault. Most commands require root
access and need to be authenticated with either a FileVault password, a
personal recovery key (if enabled), and in some cases the private key from
the installed institutional recovery key. Some status related commands can
be run from a non-root session.
Certain commands on CoreStorage volumes allow you to authenticate and unlock by providing the -key option followed by the path to a keychain file containing the private key of the installed institutional recovery key. Do not include the certificate in this keychain.
By default, when enabling FileVault
fdesetup will only return a personal recovery key.
Given the proper certificate information, fdesetup
can install an institutional recovery key. You can also set it up without
creating a personal recovery key using the -norecoverykey
option, though this is not recommended unless you are also installing an
institutional recovery key. On APFS volumes, if you already have a personal
recovery key created from a previous enablement, it will not remove or
create a new personal recovery key, allowing you to reuse the existing key.
Either type of keys can be added or changed at a later time.
With the -keychain option, an institutional recovery key can be set up by placing an X.509 asymmetric public certificate in the /Library/Keychains/FileVaultMaster.keychain file. security create-filevaultmaster-keychain can be used to create the keychain. Alternatively a certificate can be passed in by using the -certificate option and entering the path to the DER encoded certificate file. In this case the FileVaultMaster.keychain file will be created using the certificate. With your .cer file, the optional certificate data can be obtained using the base64 tool. For example: 'base64 /path/to/mycert.cer > /mynewdata.txt', at which point you would copy the data string contained in the text file and place it into the Certificate <data></data> value area of the property list. The certificate should be self signed, and the common name must be "FileVault Recovery Key"
Because the user password may not be immediately available, read the DEFERRED ENABLEMENT section below for information on how to delay enabling FileVault until the user logs in or out.
The status command will indicate if FileVault is On or Off. If a FileVault master keychain is installed into the /Library/Keychains folder it will also report this back. Note that this, by itself, does not indicate whether or not FileVault has been set up with an institutional recovery key. The -extended option will display extended status information, including the time remaining for encrypting or decrypting. The calculation of this remaining time may take a few minutes and is only an approximate value.
The list command will display the short names and UUIDs of enabled FileVault users. You can use the -extended option to display a full list of existing user types along with some additional information. This information will include if the recovery key was escrowed, though note that it will show "Yes" even if the information has not yet been successfully sent to the server. You can also use the -offline option to get a list of currently locked and offline CoreStorage FileVault volumes. You can use this information as part of the haspersonalrecoverykey or hasinstitutionalrecoverykey commands.
The remove command will remove a user from FileVault given either the user name or the FileVault UUID.
The sync command synchronizes Open Directory attributes (e.g. user pictures) with appropriate FileVault users, and removes FileVault users that were removed from Open Directory. In most cases these changes will already be updated in FileVault. sync does not add users to FileVault.
Use the haspersonalrecoverykey or hasinstitutionalrecoverykey commands to see if FileVault has a personal or institutional recovery key set up. If FileVault is active and the key is set, by default these commands will return "true" or "false". Note that "false" may also be returned if any error occurs, or if FileVault is not yet fully enabled. You can use the device option to specify either a mount path (e.g. /Volumes/myvolume), a bsd name identifier (e.g. disk0), or Logical Volume or Logical Volume Family UUID (obtained using either the list command, or using diskutil(8)). If you specify a device parameter and it finds the institutional recovery key, a hex representation of the public key hash will be returned in lieu of "true".
If a user currently has the system unlocked using the recovery key, the usingrecoverykey command will return "true".
The changerecovery command changes or adds either the personal or institutional recovery key. You can only have one recovery key of each type, so any associated existing key will be removed. The removerecovery command will remove any existing recovery key of the type specified. It is not recommended that you remove all recovery keys since, if you lose your FileVault password, you may not be able to access your information. On APFS volumes using 10.14 or later, the existing recovery key can be used as authentication to change or remove the personal recovery key.
On supported hardware, fdesetup
allows restart of a FileVault-enabled system without requiring unlock during
the subsequent boot using the authrestart command.
WARNING: FileVault protections are reduced during authenticated restarts. In
particular, fdesetup deliberately stores at least
one additional copy of a permanent FDE (full disk encryption) unlock key in
both system memory and (on supported systems) the System Management
Controller (SMC). fdesetup must be run as root and
itself prompts for a password to unlock the FileVault root volume. Use
pmset
destroyfvkeyonstandby to prevent saving the key across standby
modes. Once authrestart is authenticated, it launches
shutdown(8) and, upon successful
unlock, the unlock key will be removed. You can also use this as an option
to the enable command if the system supports this feature.
The supportsauthrestart command will check the system to
see if it supports the authrestart command option, however
you should note that even if this returns true, FileVault must still be
enabled for authrestart to work.
Each command verb is listed with its description and individual arguments.
-extended] [-offline]
[-verbose]
-user username ...]
[-usertoadd added_username
...]] | [-inputplist]]
[-outputplist] [-prompt]
[-forcerestart]
[-authrestart] [-keychain
| [-certificate
path_to_cer_file]] [[-defer
file_path] [-forceatlogin
max_cancel_attempts]
[-dontaskatlogout]]
[-norecoverykey]
[-verbose]
-verbose]
-extended] [-verbose]
-verbose]
-verbose]
-keychain] |
[-certificate
path_to_cer_file]] [-key
path_to_keychain_file]
[-inputplist] [-verbose]
-key
path_to_keychain_file] |
[-inputplist]] [-verbose]
-inputplist]
[-delayminutes
number_of_minutes_to_delay]
[-verbose]
-verbose]
-device] [-verbose]
-device] [-verbose]
-verbose]
-inputplist] [-verbose]
-defer
file_path-user
user_shortname-uuid
user_uuid-usertoadd
added_user-inputplist-prompt-forcerestart-authrestart-outputplist-keychain-certificate
path_to_cer_file-key
path_to_keychain_file-norecoverykey-forceatlogin
max_cancel_attempts-dontaskatlogout-extended-offline-device
bsd_name_or_mount_path_or_lvf_or_lv_UUID-delayminutes
number_of_minutes_to_delayThe -defer option can be used with the enable command option to delay enabling FileVault until after the current (or next) local user logs in or out, thus avoiding the need to enter a password when the tool is run. Depending on the options set, the user will either be prompted at logout time for the password, or the user will be prompted to enable FileVault when they log in. If the volume is not already a CoreStorage volume, the system may need to be restarted to start the encryption process. Dialogs are automatically dismissed and canceled after 60 seconds if no interaction occurs.
The -defer option sets up a single user to be added to FileVault. If there was no user specified (e.g. without the -user option), then the currently logged in user will be added to the configuration and becomes the designated user. If there is no user specified and no users are logged in at the time of configuration, then the next user that logs in will become the designated user.
As recovery key information is not generated until the user password is obtained, the -defer option requires a path where this information will be written to. The property list file will be created as a root-only readable file and should be placed in a secure location. You can use the showdeferralinfo command to view the current deferral configuration information.
Options that can be used in conjunction with the -defer option include: -keychain, -certificate, -forcerestart, -forceatlogin, -dontaskatlogout, -user, and -norecoverykey.
Note that if the designated user is being prompted at logout to enable FileVault, and doesn't complete the setup, FileVault will not be enabled, but the configuration will remain and be used again for the designated user's next logout (or login if the -forceatlogin option is enabled), thereby 'nagging' the user to enable FileVault. When using the -forceatlogin option, the user is given a certain number of attempts to enable FileVault, in which they can cancel the operation and continue to use their system without FileVault. When the number of cancel attempts is reached, the user will not be able to log into their account until FileVault is enabled. The current value of the user's remaining attempts can be viewed using the showdeferralinfo command. Special values for the -forceatlogin option include setting it to '0' to force the enablement immediately at next login, a '-1' disables the check entirely, and a special value of '9999' means that the user will never be required to enable FileVault, though it will continually prompt the user until FileVault is enabled. If a personal recovery key is used, the user should probably be warned ahead of time that, upon successful enablement, they will need to write down and keep in a safe place the FileVault recovery key shown on the screen.
The designated user must be a local user (or a mobile account user).
To remove an active deferred enablement configuration, you can use the disable command, even if FileVault is not currently enabled.
Starting with macOS 10.15, when using the -defer
option at logout time, fdesetup may not finish the
enablement until after the system returns to the login window. If you are
displaying the recovery key to the user, it will not appear until the enable
operation has completed.
<plist>
<dict>
<key>Username</key>
<string>sally</string>
<key>Password</key>
<string>mypassword</string>
<key>AdditionalUsers</key>
<array>
<dict>
<key>Username</key>
<string>johnny</string>
<key>Password</key>
<string>johnnypassword</string>
</dict>
<dict>
<key>Username</key>
<string>henry</string>
<key>Password</key>
<string>henrypassword</string>
</dict>
(etc)
</array>
<key>Certificate</key>
<data>2v6tJdfabvtofALrDtXAu1w5cUOMCumz
...
</data>
<key>KeychainPath</key>
<string>/privatekey.keychain</string>
</dict>
</plist>
Care should be taken with passwords that may be used within files. Precautions should be taken in your scripts to try to pass plist data directly from one tool to another to avoid writing this information to a persistent location.
Starting in macOS 10.15, you cannot use
fdesetup to enable FileVault encryption unless one
of the following occurs:
1) The responsible application is authorized for "Full Disk Access" in the System Settings Privacy pane.
2) System Integrity Protection (SIP) is disabled.
3) fdesetup was run due to a device
configuration profile installation that was either DEP enrolled or MDM user
approved.
4) The user has explicitly authorized the enablement of FileVault via a confirmation dialog.
The exit status of the tool is set to indicate whether any error was detected. The values returned are:
| July 2, 2019 | macOS |