OSX/libsecurity_translocate/lib/SecTranslocate.h

   1 /*
   2  * Copyright (c) 2016 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef H_LIBSECURITY_TRANSLOCATE
  25 #define H_LIBSECURITY_TRANSLOCATE
  26
  27 #include <CoreFoundation/CoreFoundation.h>
  28
  29 CF_ASSUME_NONNULL_BEGIN
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /*!
  36     @function SecTranslocateStartListening
  37
  38     @abstract Initialize the SecTranslocate Library as the XPC Server, Disk Arbitration Listener, and Launch Services Notification listener
  39
  40     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
  41
  42     @result True on success False on failure
  43  */
  44 Boolean SecTranslocateStartListening(CFErrorRef* __nullable error)
  45 __OSX_AVAILABLE(10.12);
  46
  47 /*!
  48  @function SecTranslocateStartListeningWithOptions
  49
  50  @abstract Initialize the SecTranslocate Library as the XPC Server, Disk Arbitration Listener, and Launch Services Notification listener
  51
  52  @param options (currently unused) A dictionary of options that could impact server startup
  53  @param outError On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
  54
  55  @result True on success False on failure
  56  */
  57 Boolean SecTranslocateStartListeningWithOptions(CFDictionaryRef options, CFErrorRef * __nullable outError)
  58 __OSX_AVAILABLE(10.12);
  59
  60 /*!
  61     @function SecTranslocateCreateSecureDirectoryForURL
  62
  63     @abstract Create a CFURL pointing to a translocated location from which to access the directory specified by pathToTranslocate.
  64
  65     @param pathToTranslocate URL of the directory to be accessed from a translocated location.
  66     @param destinationPath URL where the directory of interest should be translocated, or NULL for a random UUID location
  67     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
  68
  69     @result A CFURL pointing to the translocated location of the directory.
  70
  71     @discussion
  72         Calls to this function and SecTranslocateDeleteSecureDirectory are serialized to ensure only one call to either
  73         is operating at a time.
  74         Translocations will be created in the calling users's DARWIN_USER_TEMPDIR/AppTranslocation/<UUID>
  75
  76         pathToTranslocated is expected to be of the form /some/dir/myApp.app
  77         destinationPath is expected to be of the form /<DARWIN_USER_TEMPDIR>/AppTranslocation/<DIR>/d/myApp.app
  78
  79         Resulting translocations are of the form /<DARWIN_USER_TEMPDIR>/AppTranslocation/<DIR>/d/myApp.app
  80             <DIR> will be a UUID if destinationPath isn't specified.
  81
  82         If pathToTranslocate is in a quarantined mountpoint, the quarantine attributes will be propagated to the
  83             translocated location.
  84
  85         pathToTranslocate will cause a failure if it doesn't resolve to a path that exists, or it exceeds MAXPATHLEN
  86
  87         destinationPath will cause a failure if
  88             1. it doesn't match the app (last directory) specified by path to translocate
  89             2. it differs from an already existing mount location for pathToTranslocate
  90             3. It isn't in the user's current temp dir
  91             4. someone created a file with the same name as the provided path
  92             5. It doesn't match the form /<DARWIN_USER_TEMPDIR>/AppTranslocation/<DIR>/d/myApp.app
  93
  94         pathToTranslocate is returned if it should not be translocated based on policy. It is retained if so it can be treated as a copy.
  95
  96         This function can be run from any process. If the process is not the xpc server, then an xpc call is made.
  97  */
  98 CFURLRef __nullable SecTranslocateCreateSecureDirectoryForURL (CFURLRef pathToTranslocate, CFURLRef __nullable destinationPath, CFErrorRef* __nullable error)
  99 __OSX_AVAILABLE(10.12);
 100
 101 /*!
 102     @function SecTranslocateCreateGeneric
 103
 104     @abstract Create a CFURL pointing to a translocated location from which to access the directory specified by pathToTranslocate.
 105
 106     @param pathToTranslocate URL of the directory to be accessed from a translocated location.
 107     @param destinationPath URL where the directory of interest should be translocated
 108     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 109
 110     @result A CFURL pointing to the translocated location of the directory.
 111
 112     @discussion
 113         Calls to this function, and the others dealng with creation / deletion of mounts are serialized to ensure only one call to either
 114         is operating at a time.
 115         Translocations will be created in specified destinationPath
 116
 117         pathToTranslocated is expected to be a folder
 118
 119         If pathToTranslocate is in a quarantined mountpoint, the quarantine attributes will be propagated to the
 120             translocated location.
 121
 122         pathToTranslocate will cause a failure if it doesn't resolve to a path that exists, or it exceeds MAXPATHLEN
 123         This function can be run from any process. If the process is not the xpc server, then an xpc call is made.
 124  */
 125 CFURLRef __nullable SecTranslocateCreateGeneric (CFURLRef pathToTranslocate, CFURLRef destinationPath, CFErrorRef* __nullable error)
 126 __OSX_AVAILABLE(10.16);
 127
 128 /*!
 129     @function SecTranslocateAppLaunchCheckin
 130
 131     @abstract Register that a translocated pid is running
 132
 133     @param pid the pid to register
 134
 135     @discussion this function will log if there is a problem. The actual work is either sent to the server via xpc, or dispatched async.
 136
 137         This function can be run from any process. If the process is not the xpc server, then an xpc call is made.
 138  */
 139 void SecTranslocateAppLaunchCheckin(pid_t pid)
 140 __OSX_AVAILABLE(10.12);
 141
 142 /*!
 143     @function SecTranslocateURLShouldRunTranslocated
 144
 145     @abstract Implements policy to decide whether the entity defined by path should be run translocated
 146
 147     @param path URL to the entity in question
 148
 149     @param shouldTranslocate true if the path should be translocated, false otherwise
 150
 151     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 152
 153     @result true on success, false on failure (on failure error is set if provided). shouldTranslocate gives the answer
 154
 155     @discussion The policy is as follows:
 156         1. If path is already on a nullfs mountpoint - no translocation
 157         2. No quarantine attributes - no translocation
 158         3. If QTN_FLAG_DO_NOT_TRANSLOCATE is set or QTN_FLAG_TRANSLOCATE is not set - no translocations
 159         4. Otherwise, if QTN_FLAG_TRANSLOCATE is set - translocation
 160
 161         This function can be called from any process or thread.
 162  */
 163 Boolean SecTranslocateURLShouldRunTranslocated(CFURLRef path, bool* shouldTranslocate, CFErrorRef* __nullable error)
 164 __OSX_AVAILABLE(10.12);
 165
 166 /*!
 167     @function SecTranslocateIsTranslocatedURL
 168
 169     @abstract indicates whether the provided path is an original path or a translocated path
 170
 171     @param path path to check
 172
 173     @param isTranslocated true if the path is translocated, false otherwise
 174
 175     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 176
 177     @result true on success, false on failure (on failure error is set if provided). isTranslocated gives the answer
 178
 179     @discussion will return
 180         1. false and EPERM if the caller doesn't have read access to the path
 181         2. false and ENOENT if the path doesn't exist
 182         3. false and ENINVAL if the parameters are broken
 183         4. true and isTranslocated = true if the path is on a nullfs mount
 184         5. true and isTranslocated = false if the path is not on a nullfs mount
 185
 186         If path is a symlink, the results will reflect whatever the symlink actually points to.
 187
 188         This function can be called from any process or thread.
 189 */
 190 Boolean SecTranslocateIsTranslocatedURL(CFURLRef path, bool* isTranslocated, CFErrorRef* __nullable error)
 191 __OSX_AVAILABLE(10.12);
 192
 193 /*!
 194     @function SecTranslocateCreateOriginalPathForURL
 195
 196     @abstract finds the original path to a file given a translocated path
 197
 198     @param translocatedPath the path to look up
 199
 200     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 201
 202     @result A valid, existant path, or NULL on error
 203
 204     @discussion will return
 205         1. NULL and EPERM if the caller doesn't have read access to the path
 206         2. NULL and ENOENT if the path doesn't exist
 207         3. NULL and ENINVAL if the parameters are broken
 208         4. A retained copy of translocatedPath if it isn't translocated
 209         5. The real path to original untranslocated file/directory.
 210
 211         If translocatedPath is a symlink, the results will reflect whatever the symlink actually points to.
 212
 213         This function can be called from any process or thread.
 214 */
 215 CFURLRef __nullable SecTranslocateCreateOriginalPathForURL(CFURLRef translocatedPath, CFErrorRef* __nullable error)
 216 __OSX_AVAILABLE(10.12);
 217
 218 /*!
 219  @function SecTranslocateDeleteSecureDirectory
 220
 221  @abstract Unmount the translocated directory structure and delete the mount point directory.
 222
 223  @param translocatedPath a CFURL pointing to a translocated location.
 224
 225  @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL).
 226
 227  @result true on success, false on error.
 228
 229  @discussion This function will make sure that the translocatedPath belongs to the calling user before unmounting.
 230     After an unmount, this function will iterate through all the directories in the user's AppTranslocation directory
 231     and delete any that aren't currently mounted on.
 232     This function can only be called from the XPC Server. An error will be returned if this is called from any other process.
 233
 234  */
 235 Boolean SecTranslocateDeleteSecureDirectory(CFURLRef translocatedPath, CFErrorRef* __nullable error)
 236 __OSX_AVAILABLE(10.12);
 237
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243 CF_ASSUME_NONNULL_END
 244
 245 #endif /* H_LIBSECURITY_TRANSLOCATE */