X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/ce3c8656732c924baf7e88df75eab50891bdc471..fa7225c82381bac4432a6edf16f53b5370238d85:/OSX/libsecurity_translocate/lib/SecTranslocate.h diff --git a/OSX/libsecurity_translocate/lib/SecTranslocate.h b/OSX/libsecurity_translocate/lib/SecTranslocate.h new file mode 100644 index 00000000..ba5a8136 --- /dev/null +++ b/OSX/libsecurity_translocate/lib/SecTranslocate.h @@ -0,0 +1,218 @@ +/* + * Copyright (c) 2016 Apple Inc. All Rights Reserved. + * + * @APPLE_LICENSE_HEADER_START@ + * + * This file contains Original Code and/or Modifications of Original Code + * as defined in and that are subject to the Apple Public Source License + * Version 2.0 (the 'License'). You may not use this file except in + * compliance with the License. Please obtain a copy of the License at + * http://www.opensource.apple.com/apsl/ and read it before using this + * file. + * + * The Original Code and all software distributed under the License are + * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, + * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. + * Please see the License for the specific language governing rights and + * limitations under the License. + * + * @APPLE_LICENSE_HEADER_END@ + */ + +#ifndef H_LIBSECURITY_TRANSLOCATE +#define H_LIBSECURITY_TRANSLOCATE + +#include + +CF_ASSUME_NONNULL_BEGIN + +#ifdef __cplusplus +extern "C" { +#endif + +/*! + @function SecTranslocateStartListening + + @abstract Initialize the SecTranslocate Library as the XPC Server, Disk Arbitration Listener, and Launch Services Notification listener + + @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL) + + @result True on success False on failure + */ +Boolean SecTranslocateStartListening(CFErrorRef* __nullable error) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateStartListeningWithOptions + + @abstract Initialize the SecTranslocate Library as the XPC Server, Disk Arbitration Listener, and Launch Services Notification listener + + @param option (currently unused) A dictionary of options that could impact server startup + @param outError On error will be populated with an error object describing the failure (a posix domain error such as EINVAL) + + @result True on success False on failure + */ +Boolean SecTranslocateStartListeningWithOptions(CFDictionaryRef options, CFErrorRef * __nullable outError) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateCreateSecureDirectoryForURL + + @abstract Create a CFURL pointing to a translocated location from which to access the directory specified by pathToTranslocate. + + @param pathToTranslocate URL of the directory to be accessed from a translocated location. + @param destinationPath URL where the directory of interest should be translocated, or NULL for a random UUID location + @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL) + + @result A CFURL pointing to the translocated location of the directory. + + @discussion + Calls to this function and SecTranslocateDeleteSecureDirectory are serialized to ensure only one call to either + is operating at a time. + Translocations will be created in the calling users's DARWIN_USER_TEMPDIR/AppTranslocation/ + + pathToTranslocated is expected to be of the form /some/dir/myApp.app + destinationPath is expected to be of the form //AppTranslocation//d/myApp.app + + Resulting translocations are of the form //AppTranslocation//d/myApp.app + will be a UUID if destinationPath isn't specified. + + If pathToTranslocate is in a quarantined mountpoint, the quarantine attributes will be propagated to the + translocated location. + + pathToTranslocate will cause a failure if it doesn't resolve to a path that exists, or it exceeds MAXPATHLEN + + destinationPath will cause a failure if + 1. it doesn't match the app (last directory) specified by path to translocate + 2. it differs from an already existing mount location for pathToTranslocate + 3. It isn't in the user's current temp dir + 4. someone created a file with the same name as the provided path + 5. It doesn't match the form //AppTranslocation//d/myApp.app + + pathToTranslocate is returned if it should not be translocated based on policy. It is retained if so it can be treated as a copy. + + This function can be run from any process. If the process is not the xpc server, then an xpc call is made. + */ +CFURLRef __nullable SecTranslocateCreateSecureDirectoryForURL (CFURLRef pathToTranslocate, CFURLRef __nullable destinationPath, CFErrorRef* __nullable error) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateAppLaunchCheckin + + @abstract Register that a translocated pid is running + + @param pid the pid to register + + @discussion this function will log if there is a problem. The actual work is either sent to the server via xpc, or dispatched async. + + This function can be run from any process. If the process is not the xpc server, then an xpc call is made. + */ +void SecTranslocateAppLaunchCheckin(pid_t pid) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateURLShouldRunTranslocated + + @abstract Implements policy to decide whether the entity defined by path should be run translocated + + @param path URL to the entity in question + + @param shouldTranslocate true if the path should be translocated, false otherwise + + @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL) + + @result true on success, false on failure (on failure error is set if provided). shouldTranslocate gives the answer + + @discussion The policy is as follows: + 1. If path is already on a nullfs mountpoint - no translocation + 2. No quarantine attributes - no translocation + 3. If QTN_FLAG_DO_NOT_TRANSLOCATE is set or QTN_FLAG_TRANSLOCATE is not set - no translocations + 4. Otherwise, if QTN_FLAG_TRANSLOCATE is set - translocation + + This function can be called from any process or thread. + */ +Boolean SecTranslocateURLShouldRunTranslocated(CFURLRef path, bool* shouldTranslocate, CFErrorRef* __nullable error) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateIsTranslocatedURL + + @abstract indicates whether the provided path is an original path or a translocated path + + @param path path to check + + @param isTranslocated true if the path is translocated, false otherwise + + @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL) + + @result true on success, false on failure (on failure error is set if provided). isTranslocated gives the answer + + @discussion will return + 1. false and EPERM if the caller doesn't have read access to the path + 2. false and ENOENT if the path doesn't exist + 3. false and ENINVAL if the parameters are broken + 4. true and isTranslocated = true if the path is on a nullfs mount + 5. true and isTranslocated = false if the path is not on a nullfs mount + + If path is a symlink, the results will reflect whatever the symlink actually points to. + + This function can be called from any process or thread. +*/ +Boolean SecTranslocateIsTranslocatedURL(CFURLRef path, bool* isTranslocated, CFErrorRef* __nullable error) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateCreateOriginalPathForURL + + @abstract finds the original path to a file given a translocated path + + @param translocatedPath the path to look up + + @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL) + + @result A valid, existant path, or NULL on error + + @discussion will return + 1. NULL and EPERM if the caller doesn't have read access to the path + 2. NULL and ENOENT if the path doesn't exist + 3. NULL and ENINVAL if the parameters are broken + 4. A retained copy of translocatedPath if it isn't translocated + 5. The real path to original untranslocated file/directory. + + If translocatedPath is a symlink, the results will reflect whatever the symlink actually points to. + + This function can be called from any process or thread. +*/ +CFURLRef __nullable SecTranslocateCreateOriginalPathForURL(CFURLRef translocatedPath, CFErrorRef* __nullable error) +__OSX_AVAILABLE(10.12); + +/*! + @function SecTranslocateDeleteSecureDirectory + + @abstract Unmount the translocated directory structure and delete the mount point directory. + + @param translocatedPath a CFURL pointing to a translocated location. + + @param error On error will be populated with an error object describing the failure (a posix domain error such as EINVAL). + + @result true on success, false on error. + + @discussion This function will make sure that the translocatedPath belongs to the calling user before unmounting. + After an unmount, this function will iterate through all the directories in the user's AppTranslocation directory + and delete any that aren't currently mounted on. + This function can only be called from the XPC Server. An error will be returned if this is called from any other process. + + */ +Boolean SecTranslocateDeleteSecureDirectory(CFURLRef translocatedPath, CFErrorRef* __nullable error) +__OSX_AVAILABLE(10.12); + + +#ifdef __cplusplus +} +#endif + +CF_ASSUME_NONNULL_END + +#endif /* H_LIBSECURITY_TRANSLOCATE */