]>
Commit | Line | Data |
---|---|---|
b1ab9ed8 | 1 | /* |
d8f41ccd | 2 | * Copyright (c) 2006,2011,2013-2014 Apple Inc. All Rights Reserved. |
b1ab9ed8 A |
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 | ||
5c19dc3a | 48 | CF_ASSUME_NONNULL_BEGIN |
b1ab9ed8 A |
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. | |
427c49bc | 68 | @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in |
b1ab9ed8 A |
69 | CSCommon.h or certain other Security framework headers. |
70 | */ | |
71 | OSStatus SecRequirementCreateWithData(CFDataRef data, SecCSFlags flags, | |
5c19dc3a | 72 | SecRequirementRef * __nonnull CF_RETURNS_RETAINED requirement); |
b1ab9ed8 A |
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 | @param errors An optional pointer to a CFErrorRef variable. If the call fails | |
427c49bc | 85 | (and something other than errSecSuccess is returned), and this argument is non-NULL, |
b1ab9ed8 A |
86 | a CFErrorRef is stored there further describing the nature and circumstances |
87 | of the failure. The caller must CFRelease() this error object when done with it. | |
427c49bc | 88 | @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in |
b1ab9ed8 A |
89 | CSCommon.h or certain other Security framework headers. |
90 | */ | |
91 | OSStatus SecRequirementCreateWithString(CFStringRef text, SecCSFlags flags, | |
5c19dc3a | 92 | SecRequirementRef * __nonnull CF_RETURNS_RETAINED requirement); |
b1ab9ed8 A |
93 | |
94 | OSStatus SecRequirementCreateWithStringAndErrors(CFStringRef text, SecCSFlags flags, | |
5c19dc3a | 95 | CFErrorRef *errors, SecRequirementRef * __nonnull CF_RETURNS_RETAINED requirement); |
b1ab9ed8 A |
96 | |
97 | ||
98 | /*! | |
99 | @function SecRequirementCopyData | |
100 | Extracts a stable, persistent binary form of a SecRequirement. | |
101 | This is the effective inverse of SecRequirementCreateWithData. | |
102 | ||
103 | @param requirement A valid SecRequirement object. | |
104 | @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. | |
105 | @param data On successful return, contains a reference to a CFData object | |
106 | containing a binary blob that can be fed to SecRequirementCreateWithData | |
107 | to recreate a SecRequirement object with identical behavior. | |
427c49bc | 108 | @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in |
b1ab9ed8 A |
109 | CSCommon.h or certain other Security framework headers. |
110 | */ | |
111 | OSStatus SecRequirementCopyData(SecRequirementRef requirement, SecCSFlags flags, | |
5c19dc3a | 112 | CFDataRef * __nonnull CF_RETURNS_RETAINED data); |
b1ab9ed8 A |
113 | |
114 | ||
115 | /*! | |
116 | @function SecRequirementCopyString | |
117 | Converts a SecRequirement object into text form. | |
118 | This is the effective inverse of SecRequirementCreateWithString. | |
119 | ||
120 | Repeated application of this function may produce text that differs in | |
121 | formatting, may contain different source comments, and may perform its | |
122 | validation functions in different order. However, it is guaranteed that | |
123 | recompiling the text using SecRequirementCreateWithString will produce a | |
124 | SecRequirement object that behaves identically to the one you start with. | |
125 | ||
126 | @param requirement A valid SecRequirement object. | |
127 | @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior. | |
128 | @param text On successful return, contains a reference to a CFString object | |
129 | containing a text representation of the requirement. | |
427c49bc | 130 | @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in |
b1ab9ed8 A |
131 | CSCommon.h or certain other Security framework headers. |
132 | */ | |
133 | OSStatus SecRequirementCopyString(SecRequirementRef requirement, SecCSFlags flags, | |
5c19dc3a | 134 | CFStringRef * __nonnull CF_RETURNS_RETAINED text); |
b1ab9ed8 | 135 | |
5c19dc3a | 136 | CF_ASSUME_NONNULL_END |
b1ab9ed8 A |
137 | |
138 | #ifdef __cplusplus | |
139 | } | |
140 | #endif | |
141 | ||
142 | #endif //_H_SECREQUIREMENT |