[apple/security.git] / OSX / libsecurity_codesigning / lib / SecRequirementPriv.h

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

/*!
	@header SecRequirement
	SecRequirementPriv is the private counter-part to SecRequirement. Its contents are not
	official API, and are subject to change without notice.
*/
#ifndef _H_SECREQUIREMENTPRIV
#define _H_SECREQUIREMENTPRIV

#include <Security/SecRequirement.h>
#include <Security/SecCertificatePriv.h>


#ifdef __cplusplus
extern "C" {
#endif


/*!
	@function SecRequirementsCreateFromRequirements
	Take a dictionary of requirement objects and package them up as a requirement set.
	
	@param requirements A dictionary of requirements to combine into a set.
	Dictionary keys are CFNumbers representing the index keys. Values are SecRequirementRefs.
	NULL requirements are not allowed in the dictionary.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param requirementSet Upon success, receives a CFData object 
	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecRequirementsCreateFromRequirements(CFDictionaryRef requirements, SecCSFlags flags,
	CFDataRef *requirementSet);


/*!
	@function SecRequirementsCopyRequirements
	Create a SecRequirement object from binary form obtained from a file.
	This call is functionally equivalent to reading the entire contents of a file
	into a CFDataRef and then calling SecRequirementCreateWithData with that.
	
	@param requirementSet A CFData containing a requirement set.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param requirements Upon success, a dictionary containing each requirement contained
	in requirementSet. The keys are CFNumbers indicating the requirement type.
	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecRequirementsCopyRequirements(CFDataRef requirementSet, SecCSFlags flags,
	CFDictionaryRef *requirements);


typedef CF_OPTIONS(uint32_t, SecCSFlagsPriv) {
    kSecCSParseRequirement = 0x0001,		// accept single requirements
    kSecCSParseRequirementSet = 0x0002,		// accept requirement sets
};

/*!
	@function SecRequirementsCreateWithString
	Create a SecRequirement object or requirement set based on the string provided.
	
	@param text A CFString containing the text form of a (single) Code Requirement.
	@param flags Optional flags. Pass kSecCSDefaultFlags to accept any supported input form.
	Pass a combination of individual flags to select what forms to accept; other forms will result
	in an error.
	@param result Upon success, a CoreFoundation object of some kind representing
	the result of parsing text. Depending on the input string and flags, the result
	can be a SecRequirementRef (for a single requirement) or a CFDataRef for a requirement set.
	@param errors An optional pointer to a CFErrorRef variable. If the call fails
	(and 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 Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecRequirementsCreateWithString(CFStringRef text, SecCSFlags flags,
	CFTypeRef *result, CFErrorRef *errors);


/*!
	@function SecRequirementsCopyString
	Converts a requirement object of some kind into text form.
	This is the effective inverse of SecRequirementsCreateWithString.

	This function can process individual requirements (SecRequirementRefs)
	and requirement sets (represented as CFDataRefs).
	
	Repeated application of this function may produce text that differs in
	formatting, may contain different source comments, and may perform its
	validation functions in different order. However, it is guaranteed that
	recompiling the text using SecRequirementCreateWithString will produce a
	SecRequirement object that behaves identically to the one you start with.
	
	@param input A SecRequirementRef, or a CFDataRef containing a valid requirement set.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param text On successful return, contains a reference to a CFString object
	containing a text representation of the requirement.
	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecRequirementsCopyString(CFTypeRef input, SecCSFlags flags, CFStringRef *text);
	

/*!
	@function SecRequirementCreateWithResource
	Create a SecRequirement object from binary form obtained from a file.
	This call is functionally equivalent to reading the entire contents of a file
	into a CFDataRef and then calling SecRequirementCreateWithData with that.
	
	@param resource A CFURL identifying a file containing a (binary) requirement blob.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param requirement On successful return, contains a reference to a SecRequirement
	object that behaves identically to the one the data blob was obtained from.
	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecRequirementCreateWithResource(CFURLRef resource, SecCSFlags flags,
	SecRequirementRef *requirement);

	
/*!
	@function SecRequirementCreateGroup
	Create a SecRequirement object that represents membership in a developer-defined
	application	group. Group membership is defined by an entry in the code's
	Info.plist, and sealed to a particular signing authority.

	This is not an API-track function. Don't call it if you don't already do.
	
	@param groupName A CFString containing the name of the desired application group.
	@param anchor A reference to a digital certificate representing the signing
	authority that asserts group membership. If NULL, indicates Apple's authority.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@param requirement On successful return, contains a reference to a SecRequirement
	object that requires group membership to pass validation.
	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
	CSCommon.h or certain other Security framework headers.
*/
OSStatus SecRequirementCreateGroup(CFStringRef groupName, SecCertificateRef anchor,
	SecCSFlags flags, SecRequirementRef *requirement);


extern CFStringRef kSecRequirementKeyInfoPlist;
extern CFStringRef kSecRequirementKeyEntitlements;
extern CFStringRef kSecRequirementKeyIdentifier;
/*!
	@function SecRequirementEvaluate
	Explicitly evaluate a SecRequirementRef against context provided in the call.
	This allows evaluation of a code requirement outside the context of a code signature.

	@param requirement A valid SecRequirement object.
	@param certificateChain A CFArray of SecCertificate objects describing the certificate
	chain of the object being validated. This must be a full chain terminating in an anchor
	certificate that is cryptographically valid.
	@param context An optional CFDictionary containing additional context made available
	to the requirement program's evaluation. NULL is equivalent to an empty dictionary.
	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	@result Upon success, errSecSuccess. Failure to pass the check returns errSecCSReqFailed.
	All other returns indicate errors as documented in CSCommon.h or certain other
	Security framework headers.
	
	@constant kSecRequirementKeyInfoPlist A context key providing an CFDictionary denoting
	an Info.plist. If this key is missing, all references to Info.plist contents will fail.
	@constant kSecRequirementKeyEntitlements A context key providing an CFDictionary describing
	an entitlement dictionary. If this key is missing, all references to entitlements will fail.
	@constant kSecRequirementKeyIdentifier A context key providing the signing identifier as a CFString.
*/
OSStatus SecRequirementEvaluate(SecRequirementRef requirement,
	CFArrayRef certificateChain, CFDictionaryRef context,
	SecCSFlags flags);


#ifdef __cplusplus
}
#endif

#endif //_H_SECREQUIREMENTPRIV
Commit	Line	Data
b1ab9ed8	1	/*
d8f41ccd	2	* Copyright (c) 2006,2011-2014 Apple Inc. All Rights Reserved.
b1ab9ed8 A	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 SecRequirement
	26	SecRequirementPriv is the private counter-part to SecRequirement. Its contents are not
	27	official API, and are subject to change without notice.
	28	*/
	29	#ifndef _H_SECREQUIREMENTPRIV
	30	#define _H_SECREQUIREMENTPRIV
	31
	32	#include <Security/SecRequirement.h>
866f8763 A	33	#include <Security/SecCertificatePriv.h>
866f8763 A	34
b1ab9ed8 A	35
	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
	39
	40
	41	/*!
	42	@function SecRequirementsCreateFromRequirements
	43	Take a dictionary of requirement objects and package them up as a requirement set.
	44
	45	@param requirements A dictionary of requirements to combine into a set.
	46	Dictionary keys are CFNumbers representing the index keys. Values are SecRequirementRefs.
	47	NULL requirements are not allowed in the dictionary.
	48	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	49	@param requirementSet Upon success, receives a CFData object
427c49bc	50	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	51	CSCommon.h or certain other Security framework headers.
	52	*/
	53	OSStatus SecRequirementsCreateFromRequirements(CFDictionaryRef requirements, SecCSFlags flags,
	54	CFDataRef *requirementSet);
	55
	56
	57	/*!
	58	@function SecRequirementsCopyRequirements
	59	Create a SecRequirement object from binary form obtained from a file.
	60	This call is functionally equivalent to reading the entire contents of a file
	61	into a CFDataRef and then calling SecRequirementCreateWithData with that.
	62
	63	@param requirementSet A CFData containing a requirement set.
	64	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	65	@param requirements Upon success, a dictionary containing each requirement contained
	66	in requirementSet. The keys are CFNumbers indicating the requirement type.
427c49bc	67	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	68	CSCommon.h or certain other Security framework headers.
	69	*/
	70	OSStatus SecRequirementsCopyRequirements(CFDataRef requirementSet, SecCSFlags flags,
	71	CFDictionaryRef *requirements);
	72
6b200bc3 A	73
	74
	75	typedef CF_OPTIONS(uint32_t, SecCSFlagsPriv) {
	76	kSecCSParseRequirement = 0x0001, // accept single requirements
	77	kSecCSParseRequirementSet = 0x0002, // accept requirement sets
	78	};
	79
b1ab9ed8 A	80	/*!
	81	@function SecRequirementsCreateWithString
	82	Create a SecRequirement object or requirement set based on the string provided.
	83
	84	@param text A CFString containing the text form of a (single) Code Requirement.
	85	@param flags Optional flags. Pass kSecCSDefaultFlags to accept any supported input form.
	86	Pass a combination of individual flags to select what forms to accept; other forms will result
	87	in an error.
	88	@param result Upon success, a CoreFoundation object of some kind representing
	89	the result of parsing text. Depending on the input string and flags, the result
	90	can be a SecRequirementRef (for a single requirement) or a CFDataRef for a requirement set.
	91	@param errors An optional pointer to a CFErrorRef variable. If the call fails
427c49bc	92	(and something other than errSecSuccess is returned), and this argument is non-NULL,
b1ab9ed8 A	93	a CFErrorRef is stored there further describing the nature and circumstances
b1ab9ed8 A	94	of the failure. The caller must CFRelease() this error object when done with it.
427c49bc	95	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	96	CSCommon.h or certain other Security framework headers.
b1ab9ed8 A	97	*/
b1ab9ed8 A	98	OSStatus SecRequirementsCreateWithString(CFStringRef text, SecCSFlags flags,
	99	CFTypeRef result, CFErrorRef errors);
	100
	101
	102	/*!
	103	@function SecRequirementsCopyString
	104	Converts a requirement object of some kind into text form.
	105	This is the effective inverse of SecRequirementsCreateWithString.
	106
	107	This function can process individual requirements (SecRequirementRefs)
	108	and requirement sets (represented as CFDataRefs).
	109
	110	Repeated application of this function may produce text that differs in
	111	formatting, may contain different source comments, and may perform its
	112	validation functions in different order. However, it is guaranteed that
	113	recompiling the text using SecRequirementCreateWithString will produce a
	114	SecRequirement object that behaves identically to the one you start with.
	115
fa7225c8	116	@param input A SecRequirementRef, or a CFDataRef containing a valid requirement set.
b1ab9ed8 A	117	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	118	@param text On successful return, contains a reference to a CFString object
	119	containing a text representation of the requirement.
427c49bc	120	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	121	CSCommon.h or certain other Security framework headers.
	122	*/
	123	OSStatus SecRequirementsCopyString(CFTypeRef input, SecCSFlags flags, CFStringRef *text);
	124
	125
	126	/*!
	127	@function SecRequirementCreateWithResource
	128	Create a SecRequirement object from binary form obtained from a file.
	129	This call is functionally equivalent to reading the entire contents of a file
	130	into a CFDataRef and then calling SecRequirementCreateWithData with that.
	131
	132	@param resource A CFURL identifying a file containing a (binary) requirement blob.
	133	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	134	@param requirement On successful return, contains a reference to a SecRequirement
	135	object that behaves identically to the one the data blob was obtained from.
427c49bc	136	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	137	CSCommon.h or certain other Security framework headers.
	138	*/
	139	OSStatus SecRequirementCreateWithResource(CFURLRef resource, SecCSFlags flags,
	140	SecRequirementRef *requirement);
	141
	142
	143	/*!
	144	@function SecRequirementCreateGroup
	145	Create a SecRequirement object that represents membership in a developer-defined
	146	application group. Group membership is defined by an entry in the code's
	147	Info.plist, and sealed to a particular signing authority.
	148
	149	This is not an API-track function. Don't call it if you don't already do.
	150
	151	@param groupName A CFString containing the name of the desired application group.
	152	@param anchor A reference to a digital certificate representing the signing
	153	authority that asserts group membership. If NULL, indicates Apple's authority.
	154	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
	155	@param requirement On successful return, contains a reference to a SecRequirement
	156	object that requires group membership to pass validation.
427c49bc	157	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
b1ab9ed8 A	158	CSCommon.h or certain other Security framework headers.
	159	*/
	160	OSStatus SecRequirementCreateGroup(CFStringRef groupName, SecCertificateRef anchor,
	161	SecCSFlags flags, SecRequirementRef *requirement);
	162
	163
fa7225c8 A	164	extern CFStringRef kSecRequirementKeyInfoPlist;
	165	extern CFStringRef kSecRequirementKeyEntitlements;
	166	extern CFStringRef kSecRequirementKeyIdentifier;
b1ab9ed8 A	167	/*!
	168	@function SecRequirementEvaluate
	169	Explicitly evaluate a SecRequirementRef against context provided in the call.
	170	This allows evaluation of a code requirement outside the context of a code signature.
	171
	172	@param requirement A valid SecRequirement object.
	173	@param certificateChain A CFArray of SecCertificate objects describing the certificate
	174	chain of the object being validated. This must be a full chain terminating in an anchor
	175	certificate that is cryptographically valid.
	176	@param context An optional CFDictionary containing additional context made available
	177	to the requirement program's evaluation. NULL is equivalent to an empty dictionary.
	178	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
427c49bc	179	@result Upon success, errSecSuccess. Failure to pass the check returns errSecCSReqFailed.
b1ab9ed8 A	180	All other returns indicate errors as documented in CSCommon.h or certain other
	181	Security framework headers.
	182
	183	@constant kSecRequirementKeyInfoPlist A context key providing an CFDictionary denoting
	184	an Info.plist. If this key is missing, all references to Info.plist contents will fail.
	185	@constant kSecRequirementKeyEntitlements A context key providing an CFDictionary describing
	186	an entitlement dictionary. If this key is missing, all references to entitlements will fail.
	187	@constant kSecRequirementKeyIdentifier A context key providing the signing identifier as a CFString.
	188	*/
b1ab9ed8 A	189	OSStatus SecRequirementEvaluate(SecRequirementRef requirement,
	190	CFArrayRef certificateChain, CFDictionaryRef context,
	191	SecCSFlags flags);
	192
	193
	194	#ifdef __cplusplus
	195	}
	196	#endif
	197
	198	#endif //_H_SECREQUIREMENTPRIV