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