OSX/libsecurity_codesigning/lib/SecRequirement.h

   1 /*
   2  * Copyright (c) 2006,2011,2013-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         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 CF_ASSUME_NONNULL_BEGIN
  49
  50 /*!
  51         @function SecRequirementGetTypeID
  52         Returns the type identifier of all SecRequirement instances.
  53 */
  54 CFTypeID SecRequirementGetTypeID(void);
  55
  56
  57 /*!
  58         @function SecRequirementCreateWithData
  59         Create a SecRequirement object from binary form.
  60         This is the effective inverse of SecRequirementCopyData.
  61
  62         @param data A binary blob obtained earlier from a valid SecRequirement object
  63         using the SecRequirementCopyData call. This is the only publicly supported
  64         way to get such a data blob.
  65         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  66         @param requirement On successful return, contains a reference to a SecRequirement
  67         object that behaves identically to the one the data blob was obtained from.
  68         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  69         CSCommon.h or certain other Security framework headers.
  70 */
  71 OSStatus SecRequirementCreateWithData(CFDataRef data, SecCSFlags flags,
  72         SecRequirementRef * __nonnull CF_RETURNS_RETAINED requirement);
  73
  74
  75 /*!
  76         @function SecRequirementCreateWithString
  77         Create a SecRequirement object by compiling a valid text representation
  78         of a requirement.
  79
  80         @param text A CFString containing the text form of a (single) Code Requirement.
  81         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
  82         @param requirement On successful return, contains a reference to a SecRequirement
  83         object that implements the conditions described in text.
  84         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
  85         CSCommon.h or certain other Security framework headers.
  86 */
  87 OSStatus SecRequirementCreateWithString(CFStringRef text, SecCSFlags flags,
  88         SecRequirementRef * __nonnull CF_RETURNS_RETAINED requirement);
  89
  90 OSStatus SecRequirementCreateWithStringAndErrors(CFStringRef text, SecCSFlags flags,
  91         CFErrorRef *errors, SecRequirementRef * __nonnull CF_RETURNS_RETAINED requirement);
  92
  93
  94 /*!
  95         @function SecRequirementCopyData
  96         Extracts a stable, persistent binary form of a SecRequirement.
  97         This is the effective inverse of SecRequirementCreateWithData.
  98
  99         @param requirement A valid SecRequirement object.
 100         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 101         @param data On successful return, contains a reference to a CFData object
 102         containing a binary blob that can be fed to SecRequirementCreateWithData
 103         to recreate a SecRequirement object with identical behavior.
 104         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 105         CSCommon.h or certain other Security framework headers.
 106 */
 107 OSStatus SecRequirementCopyData(SecRequirementRef requirement, SecCSFlags flags,
 108         CFDataRef * __nonnull CF_RETURNS_RETAINED data);
 109
 110
 111 /*!
 112         @function SecRequirementCopyString
 113         Converts a SecRequirement object into text form.
 114         This is the effective inverse of SecRequirementCreateWithString.
 115
 116         Repeated application of this function may produce text that differs in
 117         formatting, may contain different source comments, and may perform its
 118         validation functions in different order. However, it is guaranteed that
 119         recompiling the text using SecRequirementCreateWithString will produce a
 120         SecRequirement object that behaves identically to the one you start with.
 121
 122         @param requirement A valid SecRequirement object.
 123         @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
 124         @param text On successful return, contains a reference to a CFString object
 125         containing a text representation of the requirement.
 126         @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
 127         CSCommon.h or certain other Security framework headers.
 128 */
 129 OSStatus SecRequirementCopyString(SecRequirementRef requirement, SecCSFlags flags,
 130         CFStringRef * __nonnull CF_RETURNS_RETAINED text);
 131
 132 CF_ASSUME_NONNULL_END
 133
 134 #ifdef __cplusplus
 135 }
 136 #endif
 137
 138 #endif //_H_SECREQUIREMENT