Keychain/FileVaultSPI.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*!
  19         @header FileVaultSPI
  20         The functions provided in FileVaultSPI implement code for Loginwindow to use when mounting
  21     FileVault home directories. Functions are also provided to allow recovery of an image with
  22     a recovery key pair (Master "Password")
  23 */
  24
  25 #ifndef _SECURITY_FILEVAULTSPI_H_
  26 #define _SECURITY_FILEVAULTSPI_H_
  27
  28 #include <Security/SecBase.h>
  29 #include <Security/SecCertificate.h>
  30 #include <CoreFoundation/CoreFoundation.h>
  31
  32 #if defined(__cplusplus)
  33 extern "C" {
  34 #endif
  35
  36 #pragma mark -------------------- SecFileVault functions --------------------
  37
  38 /*!
  39         @function SecFileVaultCreate
  40     @abstract Creates a FileVault disk image. If you want to enable a recovery key and already have a certificate to use, you can call SecFileVaultCreateUsingCertificate.
  41     @param password The password for the image. This should be the same as the user's login password.
  42         @param enableMasterPassword If set, the first identity in the special keychain will be used as the master key for the disk image.
  43     @param dmgout The file name and path for the FileVault disk image.
  44     @param volumeName The volume name for the mounted FileVault disk image (e.g. MYVOL).
  45     @param sizeSpec The size of the resulting FileVault disk image. See man hdiutil (e.g. CFSTR("20g")).
  46     @result A result code.  See "Security Error Codes" (SecBase.h).
  47 */
  48
  49 OSStatus SecFileVaultCreate (CFStringRef password, bool enableMasterPassword, CFURLRef dmgout, CFStringRef volumeName,
  50     CFStringRef sizeSpec);
  51
  52 /*!
  53         @function SecFileVaultMount
  54     @abstract Used when logging in to mount a FileVault disk image.
  55     @param password The password for the image. This will be the same as the user's login password.
  56         @param enableMasterPassword If set, the first identity in the special keychain will be used as the master key for the disk image.
  57     @param dmgout The file name for the FileVault disk image. This will be the same as was specified with SecFileVaultCreate.
  58     @param mountpoint The mountpoint for the mounted FileVault disk image. This will be passed to "hdiutil mount" as the mountpoint parameter
  59     @param devicepath The devicepath for the mounted FileVault disk image. Caller is responsible for freeing this string
  60     @result A result code.  See "Security Error Codes" (SecBase.h).
  61 */
  62
  63 OSStatus SecFileVaultUserMount (CFStringRef password, CFURLRef dmgin, CFURLRef mountpoint,CFStringRef *devicepath);
  64
  65 /*!
  66         @function SecFileVaultMasterMount
  67     @abstract To change the password for a FileVault disk image, the image must be mounted. After calling this, you can call SecFileVaultUserChangePassword to change the user's password. This is the same as SecFileVaultMount, except that the master key identity will be used to unlock the image.
  68     @param dmgin The file name for the FileVault disk image.
  69     @param mountpoint The mountpoint for the mounted FileVault disk image. This will be passed to "hdiutil mount" as the mountpoint parameter
  70     @param devicepath The devicepath for the mounted FileVault disk image. Caller is responsible for freeing this string
  71     @result A result code.  See "Security Error Codes" (SecBase.h).
  72 */
  73 OSStatus SecFileVaultMasterMount(CFURLRef dmgin, CFURLRef mountpoint,CFStringRef *devicepath);
  74
  75 /*!
  76         @function SecFileVaultUnmount
  77     @abstract Unmount a FileVault disk image. This will be called on logout. This is the inverse operation to SecFileVaultMount or SecFileVaultMasterMount. Essentially "hdiutil unmount -force <mountpoint>", followed by "hdiutil detach <devicepath>".
  78     @param mountpoint The mountpoint for the mounted FileVault disk image.
  79     @param devicepath The devicepath for the mounted FileVault disk image.
  80     @result A result code.  See "Security Error Codes" (SecBase.h).
  81 */
  82 OSStatus SecFileVaultUnmount(CFURLRef mountpoint,CFStringRef devicepath);
  83
  84 /*!
  85         @function SecFileVaultUserChangePassword
  86     @abstract Change the user password for a FileVault disk image to that given as the parameter.  This should be called when changing the user's account password info, or when resetting a user's forgotten password with . The image must have already been mounted with either SecFileVaultMount or SecFileVaultMasterMount.
  87     @param mountpoint The mountpoint for the mounted FileVault disk image.
  88     @param devicepath The devicepath for the mounted FileVault disk image.
  89     @result A result code.  See "Security Error Codes" (SecBase.h).
  90 */
  91 OSStatus SecFileVaultUserChangePassword(CFStringRef password, CFStringRef devicepath);
  92
  93 /*!
  94         @function SecFileVaultMakeMasterPassword
  95     @abstract This will create a special keychain in a special location if necessary and will generate a self-signed public/private key pair.  This is what to call if the user pushes an "Enable Master Password" button (irrevocable).
  96     @param masterPasswordPassword The password to use for the special keychain that will contain the key pair.
  97     @result A result code.  See "Security Error Codes" (SecBase.h).
  98 */
  99 OSStatus SecFileVaultMakeMasterPassword(CFStringRef masterPasswordPassword);
 100
 101 /*!
 102         @function SecFileVaultMasterPasswordEnabled
 103     @abstract This will return "true" if FileVault Master recovery keychain exists, and false if not. Note that this a machine-wide setting.
 104     @param keychainRef Returns a reference to the keychain, which you must release. Pass in NULL if you do not need a reference to the keychain
 105     @result "true" or "false".
 106 */
 107 Boolean SecFileVaultMasterPasswordEnabled(SecKeychainRef *keychainRef);
 108
 109 /*!
 110         @function SecFileVaultChangeMasterPasswordPassword
 111     @abstract This will change the keychain password for the special Master Password keychain. This has the same effect as changing the password for this keychain with Keychain Access.
 112     @param oldPassword The current password for the special Master Password keychain containing the recovery key pair.
 113     @param newPassword The new password for the special Master Password keychain containing the recovery key pair.
 114     @result A result code.  See "Security Error Codes" (SecBase.h).
 115 */
 116 OSStatus SecFileVaultChangeMasterPasswordPassword(CFStringRef oldPassword,CFStringRef newPassword);
 117
 118 #pragma mark -------------------- SecFileVault extended functions --------------------
 119
 120 /*!
 121         @function SecFileVaultMount
 122     @abstract Used when logging in to mount a FileVault disk image.
 123     @param password The password for the image. This will be the same as the user's login password.
 124         @param certificate A certificate file in DER encoding (.cer extension).
 125     @param dmgout The file name for the FileVault disk image. This will be the same as was specified with SecFileVaultCreate.
 126     @param mountpoint The mountpoint for the mounted FileVault disk image. This will be passed to "hdiutil mount" as the mountpoint parameter
 127     @param devicepath The devicepath for the mounted FileVault disk image. Caller is responsible for freeing this string
 128     @result A result code.  See "Security Error Codes" (SecBase.h).
 129 */
 130
 131 OSStatus SecFileVaultMount (CFStringRef password, CFURLRef certificate, CFURLRef dmgin, CFURLRef mountpoint,
 132     CFStringRef *devicepath);
 133
 134 /*!
 135         @function SecFileVaultCreateUsingCertificate
 136     @abstract Creates a FileVault disk image.
 137     @param password The password for the image. This should be the same as the user's login password.
 138         @param certificate A certificate file in DER encoding (.cer extension).
 139     @param dmgout The file name and path for the FileVault disk image.
 140     @param volumeName The volume name for the mounted FileVault disk image (e.g. MYVOL).
 141     @param sizeSpec The size of the resulting FileVault disk image. See man hdiutil (e.g. CFSTR("20g")).
 142     @result A result code.  See "Security Error Codes" (SecBase.h).
 143 */
 144
 145 OSStatus SecFileVaultCreateUsingCertificate (CFStringRef password, CFURLRef certificate, CFURLRef dmgout,
 146     CFStringRef volumeName, CFStringRef sizeSpec);
 147
 148 #if defined(__cplusplus)
 149 }
 150 #endif
 151
 152 #endif /* !_SECURITY_FILEVAULTSPI_H_ */