[apple/security.git] / OSX / libsecurity_translocate / lib / SecTranslocate.h

/*
 * 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 <CoreFoundation/CoreFoundation.h>

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 options (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/<UUID>
 
        pathToTranslocated is expected to be of the form /some/dir/myApp.app
        destinationPath is expected to be of the form /<DARWIN_USER_TEMPDIR>/AppTranslocation/<DIR>/d/myApp.app
        
        Resulting translocations are of the form /<DARWIN_USER_TEMPDIR>/AppTranslocation/<DIR>/d/myApp.app
            <DIR> 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 /<DARWIN_USER_TEMPDIR>/AppTranslocation/<DIR>/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 SecTranslocateCreateGeneric
 
    @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
    @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 the others dealng with creation / deletion of mounts are serialized to ensure only one call to either
        is operating at a time.
        Translocations will be created in specified destinationPath
 
        pathToTranslocated is expected to be a folder
        
        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
        This function can be run from any process. If the process is not the xpc server, then an xpc call is made.
 */
CFURLRef __nullable SecTranslocateCreateGeneric (CFURLRef pathToTranslocate, CFURLRef destinationPath, CFErrorRef* __nullable error)
__OSX_AVAILABLE(10.16);

/*!
    @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 */
Commit	Line	Data
fa7225c8 A	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
6b200bc3	52	@param options (currently unused) A dictionary of options that could impact server startup
fa7225c8 A	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
d64be36e A	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
fa7225c8 A	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 */