OSX/libsecurity_codesigning/lib/SecRequirementPriv.h

   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 #include <Security/SecCertificatePriv.h>
  34
  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
  50         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  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.
  67         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  68         CSCommon.h or certain other Security framework headers.
  69 */
  70 OSStatus SecRequirementsCopyRequirements(CFDataRef requirementSet, SecCSFlags flags,
  71         CFDictionaryRef *requirements);
  72
  73
  74
  75 typedef CF_OPTIONS(uint32_t, SecCSFlagsPriv) {
  76     kSecCSParseRequirement = 0x0001,            // accept single requirements
  77     kSecCSParseRequirementSet = 0x0002,         // accept requirement sets
  78 };
  79
  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
  92         (and something other than errSecSuccess is returned), and this argument is non-NULL,
  93         a CFErrorRef is stored there further describing the nature and circumstances
  94         of the failure. The caller must CFRelease() this error object when done with it.
  95         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  96         CSCommon.h or certain other Security framework headers.
  97 */
  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
 116         @param input A SecRequirementRef, or a CFDataRef containing a valid requirement set.
 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.
 120         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 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.
 136         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 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.
 157         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 158         CSCommon.h or certain other Security framework headers.
 159 */
 160 OSStatus SecRequirementCreateGroup(CFStringRef groupName, SecCertificateRef anchor,
 161         SecCSFlags flags, SecRequirementRef *requirement);
 162
 163
 164 extern CFStringRef kSecRequirementKeyInfoPlist;
 165 extern CFStringRef kSecRequirementKeyEntitlements;
 166 extern CFStringRef kSecRequirementKeyIdentifier;
 167 extern CFStringRef kSecRequirementKeyPackageChecksum;
 168 extern CFStringRef kSecRequirementKeyChecksumAlgorithm;
 169 extern CFStringRef kSecRequirementKeySecureTimestamp;
 170 extern CFStringRef kSecRequirementKeyTeamIdentifier;
 171
 172 /*!
 173         @function SecRequirementEvaluate
 174         Explicitly evaluate a SecRequirementRef against context provided in the call.
 175         This allows evaluation of a code requirement outside the context of a code signature.
 176
 177         @param requirement A valid SecRequirement object.
 178         @param certificateChain A CFArray of SecCertificate objects describing the certificate
 179         chain of the object being validated. This must be a full chain terminating in an anchor
 180         certificate that is cryptographically valid.
 181         @param context An optional CFDictionary containing additional context made available
 182         to the requirement program's evaluation. NULL is equivalent to an empty dictionary.
 183         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 184         @result Upon success, errSecSuccess. Failure to pass the check returns errSecCSReqFailed.
 185         All other returns indicate errors as documented in CSCommon.h or certain other
 186         Security framework headers.
 187
 188         @constant kSecRequirementKeyInfoPlist A context key providing an CFDictionary denoting
 189         an Info.plist. If this key is missing, all references to Info.plist contents will fail.
 190         @constant kSecRequirementKeyEntitlements A context key providing an CFDictionary describing
 191         an entitlement dictionary. If this key is missing, all references to entitlements will fail.
 192         @constant kSecRequirementKeyIdentifier A context key providing the signing identifier as a CFString.
 193 */
 194 OSStatus SecRequirementEvaluate(SecRequirementRef requirement,
 195         CFArrayRef certificateChain, CFDictionaryRef context,
 196         SecCSFlags flags);
 197
 198
 199 #ifdef __cplusplus
 200 }
 201 #endif
 202
 203 #endif //_H_SECREQUIREMENTPRIV