manpagez: man pages & more
man fdesetup(8)
Home | html | info | man
fdesetup(8)               BSD System Manager's Manual              fdesetup(8)


NAME

     fdesetup -- FileVault enabling tool


SYNOPSIS

     fdesetup verb [options]


DESCRIPTION

     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 recov-
     ery key.  Some status related commands can be run from a non-root ses-
     sion.

     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 a
     personal recovery key using the -norecoverykey option, though this is not
     recommended unless you are also installing an institutional recovery key.
     Either type of keys can be added or changed at a later time.

     Data passed in via stdin should be a property list using the example for-
     mat described later. When enabling FileVault, the top level Username and
     Password key values must be for an existing MacOS X user. For other com-
     mands that require authentication, the top level Username key is ignored,
     and the Password key value should either be an existing FileVault user
     password or the personal recovery key (in the example form "AU2A-PHMK-
     WBGX-PWKX-M3X3-VAPY"). If a password is not in the property list,
     fdesetup will prompt the user for it.  Added Username parameters should
     be short names of existing users.  Some commands allow you to authenti-
     cate and unlock by providing the -key option followed by the path to a
     keychain file containing the private key of the institutional recovery
     key.  Do not include the certificate in this keychain.

     With the -keychain option, an institutional recovery key can be set up by
     placing an X.509 asymmetric public certificate in the /Library/Key-
     chains/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 FileVaultMas-
     ter.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 status command will indicate if FileVault is On or Off.  If a File-
     Vault 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.  Use the hasinstitutionalrecoverykey command to see if the institu-
     tional recovery key is active.

     The list command will display the short names and UUIDs of any enabled
     FileVault users. The remove command will remove a user from FileVault.

     The syncusers command synchronizes Open Directory attributes (e.g. user
     pictures) with FileVault users, and removes FileVault users that were
     removed from Open Directory.   In most cases these changes will already
     be updated in FileVault.  syncusers 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, these commands will return
     "true", otherwise they will return "false".  Note that "false" may also
     be returned if any error occurs, or if FileVault is not yet fully
     enabled.

     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 insti-
     tutional recovery key.  You can only have one recovery key of each type,
     so any associated existing key will be removed.  The removerecovery com-
     mand 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 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 reboot(8) and, upon suc-
     cessful 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
     this option.


VERBS

     Each command verb is listed with its description and individual argu-
     ments.

     help
                Shows abbreviated help

     list       [-verbose]
                List enabled users.

     enable     [[[-user username ...] [-usertoadd added_username ...]] |
                [-inputplist]] [-outputplist] [-prompt] [-forcerestart]
                [-authrestart] [-keychain | [-certificate path_to_cer_file]]
                [-defer file_path] [-norecoverykey] [-verbose]
                Enables FileVault.

     disable    [-verbose]
                Disables FileVault.

     status     [-verbose]
                Returns current status about FileVault.

     sync
                Synchronizes information from Open Directory to FileVault.

     add        -usertoadd added_username ... | -inputplist [-verbose]
                Adds additional FileVault users.   A FileVault user password
                or recovery key must be used to authenticate.

     remove     -uuid user_uuid | -user username [-verbose]
                Removes enabled user from FileVault.

     changerecovery -personal | -institutional [[-keychain] | [-certificate
                path_to_cer_file]] [-key path_to_keychain_file] [-inputplist]
                [-verbose]
                Updates the current recovery key.   Either personal and/or
                institutional options must be specified.  When changing the
                personal recovery key, the updated personal recovery key will
                be automatically generated.   When changing either key, the
                old value will be removed and replaced.  changerecovery can
                also be used to add either type of recovery user if it was not
                already set up.

     removerecovery -personal | -institutional [[-key path_to_keychain_file] |
                [-inputplist]] [-verbose]
                Removes the current recovery key.   Either personal and/or
                institutional options must be specified.   If the recovery key
                had been sent to a corporate server, this removal does not
                notify the server that it was removed from this computer.

     authrestart [[-key path_to_keychain_file] | [-inputplist]] [-verbose]
                Immediately restarts the system, bypassing the initial unlock.
                The command may not work on all systems.

     isactive   [-verbose]
                Returns status 0 if FileVault is enabled along with the string
                "true".  Will return status 1 if FileVault is Off, along with
                "false".

     haspersonalrecoverykey [-verbose]
                Returns the string "true" if FileVault contains a personal
                recovery key.

     hasinstitutionalrecoverykey [-verbose]
                Returns the string "true" if FileVault contains an institu-
                tional recovery key.

     usingrecoverykey [-verbose]
                Returns the string "true" if FileVault is currently unlocked
                using the personal recovery key.

     supportsauthrestart
                Returns the string "true" if the system supports the authenti-
                cated restart option.

     validaterecovery [-inputplist] [-verbose]
                Returns the string "true" if the personal recovery key is val-
                idated.  The validated recovery key must be in the form xxxx-
                xxxx-xxxx-xxxx-xxxx-xxxx.

     showdeferralinfo
                If the defer mode is set, this will show the current settings.

     version
                Displays current tool version.


OPTIONS

     -defer file_path
             Defer enabling FileVault until the user password is obtained, and
             recovery key and system information will be written to the file
             path.

     -user user_shortname
             Short user name.

     -uuid user_uuid
             User UUID in canonical form:
             11111111-2222-3333-4444-555555555555.

     -usertoadd added_user
             Additional user(s) to be added to FileVault.

     -inputplist
             Acquire configuration information from stdin when enabling or
             adding users to FileVault.

     -prompt
             Always prompt for information.

     -forcerestart
             Force a normal restart after FileVault has been successfully con-
             figured.

     -authrestart
             Do an authenticated restart after a successful enable occurs.

     -outputplist
             Outputs the recovery key and additional system information to
             stdout in a plist dictionary.  If the recovery key changes, a
             Change key will be set and the EnableDate will contain the date
             of the change.   This should not be used when using the deferred
             mode.

     -keychain
             Use the institutional recovery key stored in /Library/Key-
             chains/FileVaultMaster.keychain.

     -certificate path_to_cer_file
             Use the certificate data located at the path. Any existing
             /Library/Keychains/FileVaultMaster.keychain file will be moved
             away with the location logged in the system log.  Do not set this
             option if your certificate data is located in the input plist
             information.

     -key path_to_keychain_file
             Use the keychain file located at the path containing the private
             key for the currently installed institiutional recovery key to
             unlock and authenticate FileVault.

     -norecoverykey
             Do not return a personal recovery key.


DEFERRED ENABLEMENT

     The -defer option can be used with the enable command option to delay
     enabling FileVault until after the current (or next) user logs out, thus
     avoiding the need to enter a password when the tool is run. The user will
     be prompted at logout time for the password, at which point an attempt
     will be made to enable FileVault. If the volume is not already a
     CoreStorage volume, the system may need to be restarted to start the
     encryption process. Logout dialogs are automatically dismissed and can-
     celed after 60 seconds if no interaction occurs and the user will be
     prompted again at the next logout time.

     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 be used as 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, -user, and -norecoverykey.

     Note that if the designated user doesn't complete the setup at logout,
     FileVault will not be enabled, and the configuration will remain and be
     used again for the designated user's next logout, thereby 'nagging' the
     user to enable FileVault. To remove an active deferred enablement config-
     uration, you can use the disable command, even if FileVault is not cur-
     rently enabled.


INPUT PROPERTY LIST

               <plist>
                   <dict>
                       <key>Username</key>
                       <string>sally</string>
                       <key>Password</key>
                       <string>secret</string>
                       <key>AdditionalUsers</key>
                       <array>
                           <dict>
                               <key>Username</key>
                               <string>johnny</string>
                               <key>Password</key>
                               <string>topsecret</string>
                           </dict>
                           <dict>
                               <key>Username</key>
                               <string>henry</string>
                               <key>Password</key>
                               <string>classified</string>
                           </dict>
                           (etc)
                       </array>
                       <key>Certificate</key>
                       <data>2v6tJdfabvtofALrDtXAu1w5cUOMCumz
                             ...
                       </data>
                       <key>KeychainPath</key>
                       <string>/privatekey.keychain</string>
                       <key>KeychainPassword</key>
                       <string>topsecret</string>
                   </dict>
               </plist>

     Username
             Short name of OD user used in enabling FileVault.

     Password
             Used for 1) Password of OD user used in enabling FileVault, 2)
             Password to authenticate to FileVault after enablement, 3) Per-
             sonal recovery key used to authenticate to FileVault after
             enablement

     AdditionalUsers
             An array of dictionaries for each OD user that will be added dur-
             ing enablment.

     AdditionalUsers/Username
             The OD short user name for a user to be added to the FileVault
             user list.

     AdditionalUsers/Password
             The OD user password for a user to be added to the FileVault user
             list.

     Certificate
             The institutional recovery key asymmetric certficate data.

     KeychainPath
             The path to the private key keychain file if you are authenticat-
             ing to certain comamnds.

     KeychainPassword
             The password to the private key keychain.


EXAMPLES

     fdesetup enable
              Enable FileVault after prompting for an OpenDirectory user name
              and password, and return the personal recovery key.

     fdesetup enable -user sally -usertoadd johnny -usertoadd henry
              -outputplist > /secureplace/mykeyinfo.plist
              Enables FileVault, adds users sally, johnny and henry to the EFI
              login, and outputs the recovery key and other information into
              the file.  Note that the user sally here does not have more
              privileges than the other added users.

     fdesetup enable -keychain -norecoverykey
              Enables FileVault using an institutional recovery key in the
              FileVaultMaster.keychain file. No personal recovery key will be
              created.

     fdesetup enable -defer /MykeyAndInfo.plist
              Enables FileVault when the current user logs out and success-
              fully enters their password and then writes the personal recov-
              ery key and other relevant information to the file.

     fdesetup enable -certificate /mycertfile.cer
              Enables FileVault with an institutional recovery key based off
              the certificate data in the DER encoded file. A FileVaultMas-
              ter.keychain file will be created automatically.

     fdesetup enable -inputplist < /someinfo.plist
              Enables FileVault using information from the property list read
              in from stdin.

     fdesetup enable -authrestart
              Enables FileVault and then does an immediate authenticated
              restart.

     fdesetup status
              Shows the current status of FileVault.

     fdesetup list
              Lists the current FileVault users.

     fdesetup remove -uuid A6C75639-1D98-4F19-ACD5-1892BAE27991
              Removes the user with the UUID from the FileVault users list.

     fdesetup isactive
              Returns with exit status zero and "true" if FileVault is enabled
              and active.

     fdesetup add -usertoadd betty
              Adds the user betty to the existing FileVault setup.

     fdesetup changerecovery -personal -inputplist < /authinfo.plist
              Changes the existing recovery key and generates a new recovery
              key.

     fdesetup validaterecovery -inputplist < /fvinput1-recoverykeyonly.plist
              Gets the existing personal recovery key in the "Password" key
              value of the plist and returns "true" if the recovery key
              appears to be valid.


EXIT STATUS

     The exit status of the tool is set to indicate whether any error was
     detected. The values returned are:

     0                  No error, or successful operation.

     1                  FileVault is Off.

     2                  FileVault appears to be On but Busy.

     11                 Authentication error.

     12                 Parameter error.

     13                 Unknown command error.

     14                 Bad command error.

     15                 Bad input error.

     16                 Legacy FileVault error.

     17                 Added users failed error.

     18                 Unexpected keychain found error.

     19                 Keychain error. This usually means the FileVaultMaster
                        keychain could not be moved or replaced.

     20                 Deferred configuration setup missing or error.

     21                 Enable failed (Keychain) error.

     22                 Enable failed (CoreStorage) error.

     23                 Enable failed (DiskManager) error.

     24                 Already enabled error.

     25                 Unable to remove user.

     26                 Unable to change recovery key.

     27                 Unable to remove recovery key.

     28                 FileVault is either off, busy, or the volume is
                        locked.

     99                 Internal error.


SEE ALSO

     security(1), diskutil(8), base64(1), pmset(1)

MacOSX                          August 21, 2013                         MacOSX

Mac OS X 10.9 - Generated Thu Oct 17 07:37:58 CDT 2013
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.