libsecurity_codesigning/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 #include <Security/CSCommon.h>
  42 #include <Security/SecCertificate.h>
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  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, errSecSuccess. 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 /*!
  75         @function SecRequirementCreateWithString
  76         Create a SecRequirement object by compiling a valid text representation
  77         of a requirement.
  78
  79         @param text A CFString containing the text form of a (single) Code Requirement.
  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 implements the conditions described in text.
  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 */
  90 OSStatus SecRequirementCreateWithString(CFStringRef text, SecCSFlags flags,
  91         SecRequirementRef *requirement);
  92
  93 OSStatus SecRequirementCreateWithStringAndErrors(CFStringRef text, SecCSFlags flags,
  94         CFErrorRef *errors, SecRequirementRef *requirement);
  95
  96
  97 /*!
  98         @function SecRequirementCopyData
  99         Extracts a stable, persistent binary form of a SecRequirement.
 100         This is the effective inverse of SecRequirementCreateWithData.
 101
 102         @param requirement A valid SecRequirement object.
 103         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 104         @param data On successful return, contains a reference to a CFData object
 105         containing a binary blob that can be fed to SecRequirementCreateWithData
 106         to recreate a SecRequirement object with identical behavior.
 107         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 108         CSCommon.h or certain other Security framework headers.
 109 */
 110 OSStatus SecRequirementCopyData(SecRequirementRef requirement, SecCSFlags flags,
 111         CFDataRef *data);
 112
 113
 114 /*!
 115         @function SecRequirementCopyString
 116         Converts a SecRequirement object into text form.
 117         This is the effective inverse of SecRequirementCreateWithString.
 118
 119         Repeated application of this function may produce text that differs in
 120         formatting, may contain different source comments, and may perform its
 121         validation functions in different order. However, it is guaranteed that
 122         recompiling the text using SecRequirementCreateWithString will produce a
 123         SecRequirement object that behaves identically to the one you start with.
 124
 125         @param requirement A valid SecRequirement object.
 126         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 127         @param text On successful return, contains a reference to a CFString object
 128         containing a text representation of the requirement.
 129         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 130         CSCommon.h or certain other Security framework headers.
 131 */
 132 OSStatus SecRequirementCopyString(SecRequirementRef requirement, SecCSFlags flags,
 133         CFStringRef *text);
 134
 135
 136 #ifdef __cplusplus
 137 }
 138 #endif
 139
 140 #endif //_H_SECREQUIREMENT