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