]> git.saurik.com Git - apple/security.git/blob - OSX/libsecurity_codesigning/lib/SecCodePriv.h
Security-59306.101.1.tar.gz
[apple/security.git] / OSX / libsecurity_codesigning / lib / SecCodePriv.h
1 /*
2 * Copyright (c) 2006-2007,2011,2013 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 SecCodePriv
26 SecCodePriv is the private counter-part to SecCode. Its contents are not
27 official API, and are subject to change without notice.
28 */
29 #ifndef _H_SECCODEPRIV
30 #define _H_SECCODEPRIV
31
32 #include <Security/SecCode.h>
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38
39 /*
40 * Private constants for SecCodeCopySigningInformation.
41 */
42 extern const CFStringRef kSecCodeInfoCdHashesFull; /* Internal */
43 extern const CFStringRef kSecCodeInfoCodeDirectory; /* Internal */
44 extern const CFStringRef kSecCodeInfoCodeOffset; /* Internal */
45 extern const CFStringRef kSecCodeInfoDiskRepInfo; /* Internal */
46 extern const CFStringRef kSecCodeInfoResourceDirectory; /* Internal */
47 extern const CFStringRef kSecCodeInfoNotarizationDate; /* Internal */
48 extern const CFStringRef kSecCodeInfoCMSDigestHashType; /* Internal */
49 extern const CFStringRef kSecCodeInfoCMSDigest; /* Internal */
50
51 extern const CFStringRef kSecCodeInfoDiskRepVersionPlatform; /* Number */
52 extern const CFStringRef kSecCodeInfoDiskRepVersionMin; /* Number */
53 extern const CFStringRef kSecCodeInfoDiskRepVersionSDK; /* Number */
54 extern const CFStringRef kSecCodeInfoDiskRepNoLibraryValidation; /* String */
55
56 /*!
57 @function SecCodeGetStatus
58 Retrieves the dynamic status for a SecCodeRef.
59
60 The dynamic status of a code can change at any time; the value returned is a snapshot
61 in time that is inherently stale by the time it is received by the caller. However,
62 since the status bits can only change in certain ways, some information is indefinitely
63 valid. For example, an indication of invalidity (kSecCodeStatusValid bit off) is permanent
64 since the valid bit cannot be set once clear, while an indication of validity (bit set)
65 may already be out of date.
66 Use this call with caution; it is usually wiser to call the validation API functions
67 and let then consider the status as part of their holistic computation. However,
68 SecCodeGetStatus is useful at times to capture persistent (sticky) status configurations.
69
70 @param code A valid SecCode object reference representing code running
71 on the system.
72 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
73 @param status Upon successful return, contains the dynamic status of code as
74 determined by its host.
75
76 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
77 CSCommon.h or certain other Security framework headers.
78 */
79 OSStatus SecCodeGetStatus(SecCodeRef code, SecCSFlags flags, SecCodeStatus *status);
80
81 typedef uint32_t SecCodeStatusOperation;
82 enum {
83 kSecCodeOperationNull = 0,
84 kSecCodeOperationInvalidate = 1,
85 kSecCodeOperationSetHard = 2,
86 kSecCodeOperationSetKill = 3,
87 };
88
89 /*!
90 @function SecCodeSetStatus
91 Change the dynamic status of a SecCodeRef.
92
93 @param code A valid SecCode object reference representing code running
94 on the system.
95 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
96
97 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
98 CSCommon.h or certain other Security framework headers.
99 */
100 OSStatus SecCodeSetStatus(SecCodeRef code, SecCodeStatusOperation operation,
101 CFDictionaryRef arguments, SecCSFlags flags);
102
103
104 /*!
105 @function SecCodeCopyInternalRequirement
106 For a given Code or StaticCode object, retrieves a particular kind of internal
107 requirement that was sealed during signing.
108
109 This function will always fail for unsigned code. Requesting a type of internal
110 requirement that was not given during signing is not an error.
111
112 Specifying a type of kSecDesignatedRequirementType is not the same as calling
113 SecCodeCopyDesignatedRequirement. This function will only return an explicit
114 Designated Requirement if one was specified during signing. SecCodeCopyDesignatedRequirement
115 will synthesize a suitable Designated Requirement if one was not given explicitly.
116
117 @param code The Code or StaticCode object to be interrogated. For a Code
118 argument, its StaticCode is processed as per SecCodeCopyStaticCode.
119 @param type A SecRequirementType specifying which internal requirement is being
120 requested.
121 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
122 @param requirement On successful return, contains a copy of the internal requirement
123 of the given type included in the given code. If the code has no such internal
124 requirement, this argument is set to NULL (with no error).
125 @result On success, errSecSuccess. On error, an OSStatus value
126 documented in CSCommon.h or certain other Security framework headers.
127 */
128 OSStatus SecCodeCopyInternalRequirement(SecStaticCodeRef code, SecRequirementType type,
129 SecCSFlags flags, SecRequirementRef *requirement);
130
131
132 #if TARGET_OS_OSX
133 /*!
134 @function SecCodeCreateWithAuditToken
135 Asks the kernel to return a SecCode object for a process identified
136 by a UNIX audit token. This is a shorthand for asking SecGetRootCode()
137 for a guest whose "audit" attribute has the given audit token.
138
139 @param audit A process audit token for an existing UNIX process on the system.
140 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
141 @param process On successful return, a SecCode object reference identifying
142 the requesteed process.
143 @result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
144 CSCommon.h or certain other Security framework headers.
145 */
146 OSStatus SecCodeCreateWithAuditToken(const audit_token_t *audit,
147 SecCSFlags flags, SecCodeRef *process)
148 AVAILABLE_MAC_OS_X_VERSION_10_15_AND_LATER;
149
150 /* Deprecated and unsafe, DO NOT USE. */
151 OSStatus SecCodeCreateWithPID(pid_t pid, SecCSFlags flags, SecCodeRef *process)
152 AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
153 #endif
154
155
156 /*
157 @function SecCodeSetDetachedSignature
158 For a given Code or StaticCode object, explicitly specify the detached signature
159 data used to verify it.
160 This call unconditionally overrides any signature embedded in the Code and any
161 previously specified detached signature; only the signature data specified here
162 will be used from now on for this Code object. If NULL data is specified, the
163 code object is returned to its natural signing state (before a detached
164 signature was first attached to it).
165 Any call to this function voids all cached validations for the Code object.
166 Validations will be performed again as needed in the future. This call does not,
167 by itself, perform or trigger any validations.
168 Please note that it is possible to have multiple Code objects for the same static
169 or dynamic code entity in the system. This function only attaches signature data
170 to the particular SecStaticCodeRef involved. It is your responsibility to understand
171 the object graph and pick the right one(s).
172
173 @param code A Code or StaticCode object whose signature information is to be changed.
174 @param signature A CFDataRef containing the signature data to be used for validating
175 the given Code. This must be exactly the data previously generated as a detached
176 signature by the SecCodeSignerAddSignature API or the codesign(1) command with
177 the -D/--detached option.
178 If signature is NULL, discards any previously set signature data and reverts
179 to using the embedded signature, if any. If not NULL, the data is retained and used
180 for future validation operations.
181 The data may be retained or copied. Behavior is undefined if this object
182 is modified after this call before it is replaced through another call to this
183 function).
184 @param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
185 */
186 OSStatus SecCodeSetDetachedSignature(SecStaticCodeRef code, CFDataRef signature,
187 SecCSFlags flags);
188
189
190
191 /*
192 @function SecCodeCopyComponent
193 For a SecStaticCodeRef, directly retrieve the binary blob for a special slot,
194 optionally checking that its native hash is the one given.
195
196 @param code A code or StaticCode object.
197 @param slot The (positive) special slot number requested.
198 @param hash A CFDataRef containing the native slot hash for the slot requested.
199 @result NULL if anything went wrong (including a missing slot), or a CFDataRef
200 containing the slot data.
201 */
202 CFDataRef SecCodeCopyComponent(SecCodeRef code, int slot, CFDataRef hash);
203
204
205 /*
206 @function SecCodeValidateFileResource
207 For a SecStaticCodeRef, check that a given CFData object faithfully represents
208 a plain-file resource in its resource seal.
209 This call will fail if the file is missing in the bundle, even if it is optional.
210
211 @param code A code or StaticCode object.
212 @param relativePath A CFStringRef containing the relative path to a sealed resource
213 file. This path is relative to the resource base, which is either Contents or
214 the bundle root, depending on bundle format.
215 @param fileData A CFDataRef containing the exact contents of that resource file.
216 @param flags Pass kSecCSDefaultFlags.
217 @result noErr if fileData is the exact content of the file at relativePath at the
218 time it was signed. Various error codes if it is different, there was no such file,
219 it was not a plain file, or anything is irregular.
220 */
221 OSStatus SecCodeValidateFileResource(SecStaticCodeRef code, CFStringRef relativePath, CFDataRef fileData, SecCSFlags flags);
222
223
224 /*
225 @constant kSecCSStrictValidateStructure
226 A subset of the work kSecCSStrictValidate performs, omitting work that
227 is unnecessary on some platforms. Since the definition of what can be
228 omitted is in flux, and since we would like to remove that notion
229 entirely eventually, we makes this a private flag.
230 */
231 CF_ENUM(uint32_t) {
232 kSecCSStrictValidateStructure = 1 << 13,
233 };
234
235 #if TARGET_OS_OSX
236 /* Here just to make TAPI happy. */
237 extern int GKBIS_DS_Store_Present;
238 extern int GKBIS_Dot_underbar_Present;
239 extern int GKBIS_Num_localizations;
240 extern int GKBIS_Num_files;
241 extern int GKBIS_Num_dirs;
242 extern int GKBIS_Num_symlinks;
243 #endif /* TARGET_OS_OSX */
244
245 #ifdef __cplusplus
246 }
247 #endif
248
249 #endif //_H_SECCODE