lib/SecRequirement.h

   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 SecRequirement
  26         SecRequirement represents a condition or constraint (a "Code Requirement")
  27         that code must satisfy to be considered valid for some purpose.
  28         SecRequirement itself does not understand or care WHY such a constraint
  29         is appropriate or useful; it is purely a tool for formulating, recording,
  30         and evaluating it.
  31
  32         Code Requirements are usually stored and retrieved in the form of a variable-length
  33         binary Blob that can be encapsulated as a CFDataRef and safely stored in various
  34         data structures. They can be formulated in a text form that can be compiled
  35         into binary form and decompiled back into text form without loss of functionality
  36         (though comments and formatting are not preserved).
  37 */
  38 #ifndef _H_SECREQUIREMENT
  39 #define _H_SECREQUIREMENT
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #include <Security/CSCommon.h>
  46 #include <Security/SecCertificate.h>
  47
  48
  49 /*!
  50         @function SecRequirementGetTypeID
  51         Returns the type identifier of all SecRequirement instances.
  52 */
  53 CFTypeID SecRequirementGetTypeID(void);
  54
  55
  56 /*!
  57         @function SecRequirementCreateWithData
  58         Create a SecRequirement object from binary form.
  59         This is the effective inverse of SecRequirementCopyData.
  60
  61         @param data A binary blob obtained earlier from a valid SecRequirement object
  62         using the SecRequirementCopyData call. This is the only publicly supported
  63         way to get such a data blob.
  64         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  65         @param requirement On successful return, contains a reference to a SecRequirement
  66         object that behaves identically to the one the data blob was obtained from.
  67         @result Upon success, noErr. Upon error, an OSStatus value documented in
  68         CSCommon.h or certain other Security framework headers.
  69 */
  70 OSStatus SecRequirementCreateWithData(CFDataRef data, SecCSFlags flags,
  71         SecRequirementRef *requirement);
  72
  73 /*!
  74         @function SecRequirementCreateWithResource
  75         Create a SecRequirement object from binary form obtained from a file.
  76         This call is functionally equivalent to reading the entire contents of a file
  77         into a CFDataRef and then calling SecRequirementCreateWithData with that.
  78
  79         @param resource A CFURL identifying a file containing a (binary) requirement blob.
  80         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  81         @param requirement On successful return, contains a reference to a SecRequirement
  82         object that behaves identically to the one the data blob was obtained from.
  83         @result Upon success, noErr. Upon error, an OSStatus value documented in
  84         CSCommon.h or certain other Security framework headers.
  85 */
  86 OSStatus SecRequirementCreateWithResource(CFURLRef resource, SecCSFlags flags,
  87         SecRequirementRef *requirement);
  88
  89 /*!
  90         @function SecRequirementCreateWithString
  91         Create a SecRequirement object by compiling a valid text representation
  92         of a requirement.
  93
  94         @param text A CFString containing the text form of a (single) Code Requirement.
  95         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  96         @param requirement On successful return, contains a reference to a SecRequirement
  97         object that implements the conditions described in text.
  98         @param errors An optional pointer to a CFErrorRef variable. If the call fails
  99         (and something other than noErr is returned), and this argument is non-NULL,
 100         a CFErrorRef is stored there further describing the nature and circumstances
 101         of the failure. The caller must CFRelease() this error object when done with it.
 102         @result Upon success, noErr. Upon error, an OSStatus value documented in
 103         CSCommon.h or certain other Security framework headers.
 104 */
 105 OSStatus SecRequirementCreateWithString(CFStringRef text, SecCSFlags flags,
 106         SecRequirementRef *requirement);
 107
 108 OSStatus SecRequirementCreateWithStringAndErrors(CFStringRef text, SecCSFlags flags,
 109         CFErrorRef *errors, SecRequirementRef *requirement);
 110
 111 /*!
 112         @function SecRequirementCreateGroup
 113         Create a SecRequirement object that represents membership in a developer-defined
 114         application     group. Group membership is defined by an entry in the code's
 115         Info.plist, and sealed to a particular signing authority.
 116
 117         @param groupName A CFString containing the name of the desired application group.
 118         @param anchor A reference to a digital certificate representing the signing
 119         authority that asserts group membership. If NULL, indicates Apple's authority.
 120         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 121         @param requirement On successful return, contains a reference to a SecRequirement
 122         object that requires group membership to pass validation.
 123         @result Upon success, noErr. Upon error, an OSStatus value documented in
 124         CSCommon.h or certain other Security framework headers.
 125 */
 126 OSStatus SecRequirementCreateGroup(CFStringRef groupName, SecCertificateRef anchor,
 127         SecCSFlags flags, SecRequirementRef *requirement);
 128
 129 /*!
 130         @function SecRequirementCopyData
 131         Extracts a stable, persistent binary form of a SecRequirement.
 132         This is the effective inverse of SecRequirementCreateWithData.
 133
 134         @param requirement A valid SecRequirement object.
 135         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 136         @param data On successful return, contains a reference to a CFData object
 137         containing a binary blob that can be fed to SecRequirementCreateWithData
 138         to recreate a SecRequirement object with identical behavior.
 139         @result Upon success, noErr. Upon error, an OSStatus value documented in
 140         CSCommon.h or certain other Security framework headers.
 141 */
 142 OSStatus SecRequirementCopyData(SecRequirementRef requirement, SecCSFlags flags,
 143         CFDataRef *data);
 144
 145
 146 /*!
 147         @function SecRequirementCopyString
 148         Converts a SecRequirement object into text form.
 149         This is the effective inverse of SecRequirementCreateWithString.
 150
 151         Repeated application of this function may produce text that differs in
 152         formatting, may contain different source comments, and may perform its
 153         validation functions in different order. However, it is guaranteed that
 154         recompiling the text using SecRequirementCreateWithString will produce a
 155         SecRequirement object that behaves identically to the one you start with.
 156
 157         @param requirement A valid SecRequirement object.
 158         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 159         @param text On successful return, contains a reference to a CFString object
 160         containing a text representation of the requirement.
 161         @result Upon success, noErr. Upon error, an OSStatus value documented in
 162         CSCommon.h or certain other Security framework headers.
 163 */
 164 OSStatus SecRequirementCopyString(SecRequirementRef requirement, SecCSFlags flags,
 165         CFStringRef *text);
 166
 167
 168 #ifdef __cplusplus
 169 }
 170 #endif
 171
 172 #endif //_H_SECREQUIREMENT