OSX/libsecurity_manifest/lib/SecManifest.h

   1 /*
   2  * Copyright (c) 2004,2011,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 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)
  39 extern "C" {
  40 #endif
  41
  42 enum {
  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
  56 typedef UInt32 SecManifestCompareOptions;
  57 enum {kSecManifestVerifyOwnerAndGroup = 0x1};
  58
  59 /*!
  60         @typedef SecManifestRef
  61         @abstract A pointer to an opaque manifest structure
  62 */
  63 typedef 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 */
  73 OSStatus 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 */
  83 OSStatus SecManifestCreate(SecManifestRef *manifest);
  84
  85 /*!
  86         @function SecManifestRelease
  87         @abstract Destroys a manifest object
  88         @param manifest The manifest to destroy.
  89 */
  90
  91 void SecManifestRelease(SecManifestRef manifest);
  92
  93 typedef enum _SecManifestTrustCallbackResult
  94 {
  95         kSecManifestDoNotVerify,
  96         kSecManifestSignerVerified,
  97         kSecManifestContinue,
  98         kSecManifestFailed
  99 } SecManifestTrustCallbackResult;
 100
 101 typedef SecManifestTrustCallbackResult(*SecManifestTrustSetupCallback)
 102                         (SecTrustRef trustRef, void* setupContext);
 103 typedef 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
 123 OSStatus 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 */
 146 OSStatus 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 */
 163 OSStatus 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 */
 179 OSStatus 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         @result A result code.
 189 */
 190 OSStatus SecManifestCompare(SecManifestRef manifest1,
 191                                                         SecManifestRef manifest2,
 192                                                         SecManifestCompareOptions options);
 193
 194 /*!
 195         @function SecManifestAddSigner
 196         @abstract Add an identity to the list of identities that will sign the
 197                           manifest.
 198         @param manifest The manifest to sign.
 199         @param identity The identity to be used to sign the manifest.
 200         @result A result code.
 201         @discussion Multiple signers are supported.  The actual signing does not
 202                                 take place until SecManifestCreateExternalRepresentation is
 203                                 called.
 204 */
 205 OSStatus SecManifestAddSigner(SecManifestRef manifest,
 206                                                           SecIdentityRef identity);
 207
 208 #if defined(__cplusplus)
 209 }
 210 #endif
 211
 212 #endif /* ! _SECURITY_SECMANIFEST_H_ */
 213