1/*
2 * Copyright (c) 2004 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 SecManifest
26	The functions and data types in SecManifest implement file, directory, and
27	data signing.
28*/
29
30#ifndef _SECURITY_SECMANIFEST_H_
31#define _SECURITY_SECMANIFEST_H_
32
33#include <Security/SecTrust.h>
34#include <Security/SecIdentity.h>
35#include <Security/SecBase.h>
36
37
38#if defined(__cplusplus)
39extern "C" {
40#endif
41
42enum {
43	errSecManifestNotSupported   = -22040,  /* The specified object can't be placed in a manifest */
44	errSecManifestNoSigners		 = -22041,  /* There must be at least one signer for a manifest */
45	errSecManifestCMSFailure	 = -22042,  /* A problem occurred with CMS */
46	errSecManifestIsNotEmpty	 = -20043,  /* The manifest was not empty before create from external representation */
47	errSecManifestDidNotVerify   = -20044,  /* The manifest did not verify */
48	errSecManifestDamaged		 = -20045,  /* The manifest was damaged */
49	errSecManifestNotEqual		 = -20046,  /* The manifests were not equal */
50	errSecManifestBadResult		 = -20057,  /* A manifest callback returned an invalid result */
51	errSecManifestNoPolicy		 = -20058,  /* Couldn't find the default policy */
52	errSecManifestInvalidException  = -20059,  /* Exception list members must be CFStrings */
53	errSecManifestNoSignersFound = -20060,	/* No signers were found in the manifest */
54};
55
56typedef UInt32 SecManifestCompareOptions;
57enum {kSecManifestVerifyOwnerAndGroup = 0x1};
58
59/*!
60	@typedef SecManifestRef
61	@abstract A pointer to an opaque manifest structure
62*/
63typedef struct OpaqueSecManifestRef *SecManifestRef;
64
65/*!
66	@function SecManifestGetVersion
67	@abstract Determines the version of the SecManifest API installed on the
68			  user's system.
69	@param version On return, a pointer to the version number of the SecManifest
70				   API installed on the system.
71	@result A result code.
72*/
73OSStatus SecManifestGetVersion(UInt32 *version);
74
75/*!
76	@function SecManifestCreate
77	@abstract Creates a new manifest object for signing.
78	@param manifest On return, a porinter to a manifest reference.  The memory
79					that manifest occupies must be released by calling
80					SecManifestRelease when you are finished with it.
81	@result A result code.
82*/
83OSStatus SecManifestCreate(SecManifestRef *manifest);
84
85/*!
86	@function SecManifestRelease
87	@abstract Destroys a manifest object
88	@param manifest The manifest to destroy.
89*/
90
91void SecManifestRelease(SecManifestRef manifest);
92
93typedef enum _SecManifestTrustCallbackResult
94{
95	kSecManifestDoNotVerify,
96	kSecManifestSignerVerified,
97	kSecManifestContinue,
98	kSecManifestFailed
99} SecManifestTrustCallbackResult;
100
101typedef SecManifestTrustCallbackResult(*SecManifestTrustSetupCallback)
102			(SecTrustRef trustRef, void* setupContext);
103typedef SecManifestTrustCallbackResult(*SecManifestTrustEvaluateCallback)
104			(SecTrustRef trustRef, SecTrustResultType result,
105			 void *evaluateContext);
106
107/*!
108	@function SecManifestVerifySignature
109	@abstract Verifies a signature created with SecManifestCreateSignature,
110	@param data The signature to verify.
111	@param setupCallback Called before trust is verified for a signer.  This
112						 allows the user to modify the SecTrustRef if needed
113						 (see the SecTrust documentation).
114	@param setupContext User defined.
115	@param evaluateCallback Called after SecTrustEvaluate has been called for a
116							signer if the result was not trusted. This allows
117							the developer to query the user as to whether or not
118							to trust the signer.
119	@param evaluateContext User defined.
120	@param manifest Optional return of the verified manifest
121*/
122
123OSStatus SecManifestVerifySignature(CFDataRef data,
124									SecManifestTrustSetupCallback setupCallback,
125									void* setupContext,
126									SecManifestTrustEvaluateCallback evaluateCallback,
127									void* evaluateContext,
128									SecManifestRef *manifest);
129
130/*!
131	@function SecManifestVerifySignature
132	@abstract Verifies a signature created with SecManifestCreateSignature,
133	@param data The signature to verify.
134	@param setupCallback Called before trust is verified for a signer.  This
135						 allows the user to modify the SecTrustRef if needed
136						 (see the SecTrust documentation).
137	@param setupContext User defined.
138	@param evaluateCallback Called after SecTrustEvaluate has been called for a
139							signer if the result was not trusted. This allows
140							the developer to query the user as to whether or not
141							to trust the signer.
142	@param evaluateContext User defined.
143	@param policyRef A SecPolicyRef used to evaluate the signature.  Pass NULL to use the default policy
144	@param manifest Optional return of the verified manifest
145*/
146OSStatus SecManifestVerifySignatureWithPolicy(CFDataRef data,
147											  SecManifestTrustSetupCallback setupCallback,
148											  void* setupContext,
149											  SecManifestTrustEvaluateCallback evaluateCallback,
150											  void* evaluateContext,
151											  SecPolicyRef policyRef,
152											  SecManifestRef *manifest);
153/*!
154	@function SecManifestCreateSignature
155	@abstract Creates a signature.
156	@param manifest The manifest from which to create the signature.
157	@param options Reserved for future use.
158	@param data On return, the external representation.  The memory that data
159				occupies must be released by calling CFRelease when finished
160				with it.
161	@result A result code.
162*/
163OSStatus SecManifestCreateSignature(SecManifestRef manifest,
164									UInt32 options,
165									CFDataRef *data);
166
167/*!
168	@function SecManifestAddObject
169	@abstract Adds data to be signed or verified to the manifest object.
170	@param manifest The manifest object.
171	@param object The object to add.
172	@param exceptionList If data points to a directory, this contains an
173						 optional list of CFStrings, relative to object, that will
174						 not be included in the manifest.
175	@result A result code.
176	@discussion object may either be a CFURL that points to a file URL, or a
177				SecManifestData, which points to arbitrary data.
178*/
179OSStatus SecManifestAddObject(SecManifestRef manifest,
180							  CFTypeRef object,
181							  CFArrayRef exceptionList);
182
183/*!
184	@function SecManifestCompare
185	@abstraact Compare one manifest to another.
186	@param manifest1 A manifest to be compared for equality.
187	@param manifest2 A manifest to be compared for equality.
188	@param verifyOwnerAndGroup If true, owner and group ID's will be checked as
189							   part of the verification process.
190	@result A result code.
191*/
192OSStatus SecManifestCompare(SecManifestRef manifest1,
193							SecManifestRef manifest2,
194							SecManifestCompareOptions options);
195
196/*!
197	@function SecManifestAddSigner
198	@abstract Add an identity to the list of identities that will sign the
199			  manifest.
200	@param manifest The manifest to sign.
201	@param identity The identity to be used to sign the manifest.
202	@result A result code.
203	@discussion Multiple signers are supported.  The actual signing does not
204				take place until SecManifestCreateExternalRepresentation is
205				called.
206*/
207OSStatus SecManifestAddSigner(SecManifestRef manifest,
208							  SecIdentityRef identity);
209
210#if defined(__cplusplus)
211}
212#endif
213
214#endif /* ! _SECURITY_SECMANIFEST_H_ */
215
216