[apple/security.git] / libsecurity_codesigning / lib / SecStaticCode.h

/*
 * Copyright (c) 2006 Apple Computer, 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@
 */

/*!
	@header SecStaticCode
	SecStaticCode represents the Code Signing identity of code in the file system.
	This includes applications, tools, frameworks, plugins,	scripts, and so on.
	Note that arbitrary files will be considered scripts of unknown provenance;
	and thus it is possible to handle most files as if they were code, though that is
	not necessarily a good idea.
	
	Normally, each SecCode has a specific SecStaticCode that holds its static signing
	data. Informally, that is the SecStaticCode the SecCode "was made from" (by its host).
	There is however no viable link in the other direction - given a SecStaticCode,
	it is not possible to find, enumerate, or control any SecCode that originated from it.
	There might not be any at a given point in time; or there might be many.
*/
#ifndef _H_SECSTATICCODE
#define _H_SECSTATICCODE

#include <Security/CSCommon.h>

#ifdef __cplusplus
extern "C" {
#endif


/*!
	@function SecStaticCodeGetTypeID
	Returns the type identifier of all SecStaticCode instances.
*/
CFTypeID SecStaticCodeGetTypeID(void);


/*!
	@function SecStaticCodeCreateWithPath
	Given a path to a file system object, create a SecStaticCode object representing
	the code at that location, if possible. Such a SecStaticCode is not inherently
	linked to running code in the system.
	
	It is possible to create a SecStaticCode object from an unsigned code object.
	Most uses of such an object will return the errSecCSUnsigned error. However,
	SecCodeCopyPath and SecCodeCopySigningInformation can be safely applied to such objects.

	@param path A path to a location in the file system. Only file:// URLs are
	currently supported. For bundles, pass a URL to the root directory of the
	bundle. For single files, pass a URL to the file. If you pass a URL to the
	main executable of a bundle, the bundle as a whole will be generally recognized.
	Caution: Paths containing embedded // or /../ within a bundle's directory
	may cause the bundle to be misconstrued. If you expect to submit such paths,
	first clean them with realpath(3) or equivalent.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param attributes A CFDictionary containing additional attributes of the code sought.
	@param staticCode On successful return, contains a reference to the StaticCode object
	representing the code at path. Unchanged on error.
	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
	
	@constant kSecCodeAttributeArchitecture Specifies the Mach-O architecture of code desired.
	This can be a CFString containing a canonical architecture name ("i386" etc.), or a CFNumber
	specifying an architecture numerically (see mach/machine.h). This key is ignored if the code
	is not in Mach-O binary form. If the code is Mach-O but not universal ("thin"), the architecture
	specified must agree with the actual file contents.
	@constant kSecCodeAttributeSubarchitecture If the architecture is specified numerically
	(using the kSecCodeAttributeArchitecture key), specifies any sub-architecture by number.
	This key is ignored if no main architecture is specified; if it is specified by name; or
	if the code is not in Mach-O form.
	@constant kSecCodeAttributeUniversalFileOffset The offset of a Mach-O specific slice of a universal Mach-O file.
*/
extern const CFStringRef kSecCodeAttributeArchitecture;
extern const CFStringRef kSecCodeAttributeSubarchitecture;
extern const CFStringRef kSecCodeAttributeUniversalFileOffset;
extern const CFStringRef kSecCodeAttributeBundleVersion;

OSStatus SecStaticCodeCreateWithPath(CFURLRef path, SecCSFlags flags, SecStaticCodeRef *staticCode);

OSStatus SecStaticCodeCreateWithPathAndAttributes(CFURLRef path, SecCSFlags flags, CFDictionaryRef attributes,
	SecStaticCodeRef *staticCode);


/*!
	@function SecStaticCodeCheckValidity
	Performs static validation on the given SecStaticCode object. The call obtains and
	verifies the signature on the code object. It checks the validity of all
	sealed components (including resources, if any). It validates the code against
	a SecRequirement if one is given. The call succeeds if all these conditions
	are satisfactory. It fails otherwise.
	
	This call is only secure if the code is not subject to concurrent modification,
	and the outcome is only valid as long as the code is unmodified thereafter.
	Consider this carefully if the underlying file system has dynamic characteristics,
	such as a network file system, union mount, FUSE, etc.

	@param staticCode The code object to be validated.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	
	@constant kSecCSCheckAllArchitectures
	For multi-architecture (universal) Mach-O programs, validate all architectures
	included. By default, only the native architecture is validated.
	@constant kSecCSNoDnotValidateExecutable
	Do not validate the contents of the main executable. This is normally done.
	@constant kSecCSNoNotValidateResources
	Do not validate the presence and contents of all bundle resources (if any).
	By default, a mismatch in any bundle resource causes validation to fail.
	@constant kSecCSCheckNestedCode
	For code in bundle form, locate and recursively check embedded code. Only code
	in standard locations is considered.
	
	@param requirement On optional code requirement specifying additional conditions
	the staticCode object must satisfy to be considered valid. If NULL, no additional
	requirements are imposed.
	@param errors An optional pointer to a CFErrorRef variable. If the call fails
	(something other than errSecSuccess is returned), and this argument is non-NULL,
	a CFErrorRef is stored there further describing the nature and circumstances
	of the failure. The caller must CFRelease() this error object when done with it.
	@result If validation succeeds, errSecSuccess. If validation fails, an OSStatus value
	documented in CSCommon.h or certain other Security framework headers.
*/
enum {
	kSecCSCheckAllArchitectures = 1 << 0,
	kSecCSDoNotValidateExecutable = 1 << 1,
	kSecCSDoNotValidateResources = 1 << 2,
	kSecCSBasicValidateOnly = kSecCSDoNotValidateExecutable | kSecCSDoNotValidateResources,
	kSecCSCheckNestedCode = 1 << 3,
};

OSStatus SecStaticCodeCheckValidity(SecStaticCodeRef staticCode, SecCSFlags flags,
	SecRequirementRef requirement);

OSStatus SecStaticCodeCheckValidityWithErrors(SecStaticCodeRef staticCode, SecCSFlags flags,
	SecRequirementRef requirement, CFErrorRef *errors);


#ifdef __cplusplus
}
#endif

#endif //_H_SECSTATICCODE
Commit	Line	Data
b1ab9ed8 A	1	/*
	2	* Copyright (c) 2006 Apple Computer, 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	/*!
	25	@header SecStaticCode
	26	SecStaticCode represents the Code Signing identity of code in the file system.
	27	This includes applications, tools, frameworks, plugins, scripts, and so on.
	28	Note that arbitrary files will be considered scripts of unknown provenance;
	29	and thus it is possible to handle most files as if they were code, though that is
	30	not necessarily a good idea.
	31
	32	Normally, each SecCode has a specific SecStaticCode that holds its static signing
	33	data. Informally, that is the SecStaticCode the SecCode "was made from" (by its host).
	34	There is however no viable link in the other direction - given a SecStaticCode,
	35	it is not possible to find, enumerate, or control any SecCode that originated from it.
	36	There might not be any at a given point in time; or there might be many.
	37	*/
	38	#ifndef _H_SECSTATICCODE
	39	#define _H_SECSTATICCODE
	40
	41	#include <Security/CSCommon.h>
	42
	43	#ifdef __cplusplus
	44	extern "C" {
	45	#endif
	46
	47
	48	/*!
	49	@function SecStaticCodeGetTypeID
	50	Returns the type identifier of all SecStaticCode instances.
	51	*/
	52	CFTypeID SecStaticCodeGetTypeID(void);
	53
	54
	55	/*!
	56	@function SecStaticCodeCreateWithPath
	57	Given a path to a file system object, create a SecStaticCode object representing
	58	the code at that location, if possible. Such a SecStaticCode is not inherently
	59	linked to running code in the system.
	60
	61	It is possible to create a SecStaticCode object from an unsigned code object.
	62	Most uses of such an object will return the errSecCSUnsigned error. However,
	63	SecCodeCopyPath and SecCodeCopySigningInformation can be safely applied to such objects.
	64
65	@param path A path to a location in the file system. Only file:// URLs are
66	currently supported. For bundles, pass a URL to the root directory of the
67	bundle. For single files, pass a URL to the file. If you pass a URL to the
68	main executable of a bundle, the bundle as a whole will be generally recognized.
69	Caution: Paths containing embedded // or /../ within a bundle's directory
70	may cause the bundle to be misconstrued. If you expect to submit such paths,
71	first clean them with realpath(3) or equivalent.
72	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
73	@param attributes A CFDictionary containing additional attributes of the code sought.
74	@param staticCode On successful return, contains a reference to the StaticCode object
75	representing the code at path. Unchanged on error.
427c49bc	76	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	77	CSCommon.h or certain other Security framework headers.
	78
	79	@constant kSecCodeAttributeArchitecture Specifies the Mach-O architecture of code desired.
	80	This can be a CFString containing a canonical architecture name ("i386" etc.), or a CFNumber
	81	specifying an architecture numerically (see mach/machine.h). This key is ignored if the code
	82	is not in Mach-O binary form. If the code is Mach-O but not universal ("thin"), the architecture
	83	specified must agree with the actual file contents.
	84	@constant kSecCodeAttributeSubarchitecture If the architecture is specified numerically
	85	(using the kSecCodeAttributeArchitecture key), specifies any sub-architecture by number.
	86	This key is ignored if no main architecture is specified; if it is specified by name; or
	87	if the code is not in Mach-O form.
427c49bc	88	@constant kSecCodeAttributeUniversalFileOffset The offset of a Mach-O specific slice of a universal Mach-O file.
b1ab9ed8 A	89	*/
	90	extern const CFStringRef kSecCodeAttributeArchitecture;
	91	extern const CFStringRef kSecCodeAttributeSubarchitecture;
427c49bc	92	extern const CFStringRef kSecCodeAttributeUniversalFileOffset;
b1ab9ed8 A	93	extern const CFStringRef kSecCodeAttributeBundleVersion;
	94
	95	OSStatus SecStaticCodeCreateWithPath(CFURLRef path, SecCSFlags flags, SecStaticCodeRef *staticCode);
	96
	97	OSStatus SecStaticCodeCreateWithPathAndAttributes(CFURLRef path, SecCSFlags flags, CFDictionaryRef attributes,
	98	SecStaticCodeRef *staticCode);
	99
	100
	101	/*!
	102	@function SecStaticCodeCheckValidity
	103	Performs static validation on the given SecStaticCode object. The call obtains and
	104	verifies the signature on the code object. It checks the validity of all
	105	sealed components (including resources, if any). It validates the code against
	106	a SecRequirement if one is given. The call succeeds if all these conditions
	107	are satisfactory. It fails otherwise.
	108
	109	This call is only secure if the code is not subject to concurrent modification,
	110	and the outcome is only valid as long as the code is unmodified thereafter.
	111	Consider this carefully if the underlying file system has dynamic characteristics,
	112	such as a network file system, union mount, FUSE, etc.
	113
	114	@param staticCode The code object to be validated.
	115	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	116
	117	@constant kSecCSCheckAllArchitectures
	118	For multi-architecture (universal) Mach-O programs, validate all architectures
	119	included. By default, only the native architecture is validated.
	120	@constant kSecCSNoDnotValidateExecutable
	121	Do not validate the contents of the main executable. This is normally done.
	122	@constant kSecCSNoNotValidateResources
	123	Do not validate the presence and contents of all bundle resources (if any).
	124	By default, a mismatch in any bundle resource causes validation to fail.
	125	@constant kSecCSCheckNestedCode
	126	For code in bundle form, locate and recursively check embedded code. Only code
	127	in standard locations is considered.
	128
	129	@param requirement On optional code requirement specifying additional conditions
	130	the staticCode object must satisfy to be considered valid. If NULL, no additional
	131	requirements are imposed.
	132	@param errors An optional pointer to a CFErrorRef variable. If the call fails
427c49bc	133	(something other than errSecSuccess is returned), and this argument is non-NULL,
b1ab9ed8 A	134	a CFErrorRef is stored there further describing the nature and circumstances
b1ab9ed8 A	135	of the failure. The caller must CFRelease() this error object when done with it.
427c49bc	136	@result If validation succeeds, errSecSuccess. If validation fails, an OSStatus value
b1ab9ed8 A	137	documented in CSCommon.h or certain other Security framework headers.
	138	*/
	139	enum {
	140	kSecCSCheckAllArchitectures = 1 << 0,
	141	kSecCSDoNotValidateExecutable = 1 << 1,
	142	kSecCSDoNotValidateResources = 1 << 2,
	143	kSecCSBasicValidateOnly = kSecCSDoNotValidateExecutable \| kSecCSDoNotValidateResources,
	144	kSecCSCheckNestedCode = 1 << 3,
	145	};
	146
	147	OSStatus SecStaticCodeCheckValidity(SecStaticCodeRef staticCode, SecCSFlags flags,
	148	SecRequirementRef requirement);
	149
	150	OSStatus SecStaticCodeCheckValidityWithErrors(SecStaticCodeRef staticCode, SecCSFlags flags,
	151	SecRequirementRef requirement, CFErrorRef *errors);
	152
	153
	154	#ifdef __cplusplus
	155	}
	156	#endif
	157
	158	#endif //_H_SECSTATICCODE