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 SecTranslocateAppLaunchCheckin
 103
 104     @abstract Register that a translocated pid is running
 105
 106     @param pid the pid to register
 107
 108     @discussion this function will log if there is a problem. The actual work is either sent to the server via xpc, or dispatched async.
 109
 110         This function can be run from any process. If the process is not the xpc server, then an xpc call is made.
 111  */
 112 void SecTranslocateAppLaunchCheckin(pid_t pid)
 113 __OSX_AVAILABLE(10.12);
 114
 115 /*!
 116     @function SecTranslocateURLShouldRunTranslocated
 117
 118     @abstract Implements policy to decide whether the entity defined by path should be run translocated
 119
 120     @param path URL to the entity in question
 121
 122     @param shouldTranslocate true if the path should be translocated, false otherwise
 123
 124     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 125
 126     @result true on success, false on failure (on failure error is set if provided). shouldTranslocate gives the answer
 127
 128     @discussion The policy is as follows:
 129         1. If path is already on a nullfs mountpoint - no translocation
 130         2. No quarantine attributes - no translocation
 131         3. If QTN_FLAG_DO_NOT_TRANSLOCATE is set or QTN_FLAG_TRANSLOCATE is not set - no translocations
 132         4. Otherwise, if QTN_FLAG_TRANSLOCATE is set - translocation
 133
 134         This function can be called from any process or thread.
 135  */
 136 Boolean SecTranslocateURLShouldRunTranslocated(CFURLRef path, bool* shouldTranslocate, CFErrorRef* __nullable error)
 137 __OSX_AVAILABLE(10.12);
 138
 139 /*!
 140     @function SecTranslocateIsTranslocatedURL
 141
 142     @abstract indicates whether the provided path is an original path or a translocated path
 143
 144     @param path path to check
 145
 146     @param isTranslocated true if the path is translocated, false otherwise
 147
 148     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 149
 150     @result true on success, false on failure (on failure error is set if provided). isTranslocated gives the answer
 151
 152     @discussion will return
 153         1. false and EPERM if the caller doesn't have read access to the path
 154         2. false and ENOENT if the path doesn't exist
 155         3. false and ENINVAL if the parameters are broken
 156         4. true and isTranslocated = true if the path is on a nullfs mount
 157         5. true and isTranslocated = false if the path is not on a nullfs mount
 158
 159         If path is a symlink, the results will reflect whatever the symlink actually points to.
 160
 161         This function can be called from any process or thread.
 162 */
 163 Boolean SecTranslocateIsTranslocatedURL(CFURLRef path, bool* isTranslocated, CFErrorRef* __nullable error)
 164 __OSX_AVAILABLE(10.12);
 165
 166 /*!
 167     @function SecTranslocateCreateOriginalPathForURL
 168
 169     @abstract finds the original path to a file given a translocated path
 170
 171     @param translocatedPath the path to look up
 172
 173     @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL)
 174
 175     @result A valid, existant path, or NULL on error
 176
 177     @discussion will return
 178         1. NULL and EPERM if the caller doesn't have read access to the path
 179         2. NULL and ENOENT if the path doesn't exist
 180         3. NULL and ENINVAL if the parameters are broken
 181         4. A retained copy of translocatedPath if it isn't translocated
 182         5. The real path to original untranslocated file/directory.
 183
 184         If translocatedPath is a symlink, the results will reflect whatever the symlink actually points to.
 185
 186         This function can be called from any process or thread.
 187 */
 188 CFURLRef __nullable SecTranslocateCreateOriginalPathForURL(CFURLRef translocatedPath, CFErrorRef* __nullable error)
 189 __OSX_AVAILABLE(10.12);
 190
 191 /*!
 192  @function SecTranslocateDeleteSecureDirectory
 193
 194  @abstract Unmount the translocated directory structure and delete the mount point directory.
 195
 196  @param translocatedPath a CFURL pointing to a translocated location.
 197
 198  @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL).
 199
 200  @result true on success, false on error.
 201
 202  @discussion This function will make sure that the translocatedPath belongs to the calling user before unmounting.
 203     After an unmount, this function will iterate through all the directories in the user's AppTranslocation directory
 204     and delete any that aren't currently mounted on.
 205     This function can only be called from the XPC Server. An error will be returned if this is called from any other process.
 206
 207  */
 208 Boolean SecTranslocateDeleteSecureDirectory(CFURLRef translocatedPath, CFErrorRef* __nullable error)
 209 __OSX_AVAILABLE(10.12);
 210
 211
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 CF_ASSUME_NONNULL_END
 217
 218 #endif /* H_LIBSECURITY_TRANSLOCATE */