OSX/libsecurity_manifest/lib/SecureDownload.h

   1 #ifndef __SECURE_DOWNLOAD__
   2 #define __SECURE_DOWNLOAD__
   3
   4 #if defined(__cplusplus)
   5 extern "C" {
   6 #endif
   7
   8 /*
   9  * Copyright (c) 2006,2011,2013-2014 Apple Inc. All Rights Reserved.
  10  *
  11  * @APPLE_LICENSE_HEADER_START@
  12  *
  13  * This file contains Original Code and/or Modifications of Original Code
  14  * as defined in and that are subject to the Apple Public Source License
  15  * Version 2.0 (the 'License'). You may not use this file except in
  16  * compliance with the License. Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_HEADER_END@
  29  */
  30
  31 /*!
  32         @header SecureDownload
  33         @abstract Used by clients to implement Apple's Verified Download System.
  34
  35                   Please note that a succesful check does not guarantee anything about
  36                           the safety of the file being downloaded. Rather, it simply checks to make sure
  37                           that the contents of the file being downloaded exactly matches the contents
  38                           of the file when the ticket was originally generated.
  39
  40                           To use, do the following:
  41                                 1:  Download the secure download ticket.
  42                                 2:  Pass the ticket to SecureDownloadCreateWithTicket.  On error, call
  43                                         SecureDownloadGetTrustRef to return data that will help you figure
  44                                         out why the ticket was bad.
  45                                 3:  If SecureDownloadCreateWithTicket returns errSecSuccess, call SecureDownloadCopyURLs
  46                                         to return a list of data download locations.  Begin downloading data from
  47                                         the first URL in the list.  If that download fails, try downloading from
  48                                         the second URL, and so forth.
  49                                 4:      Each time you receive data, call SecureDownloadReceivedData.
  50                                 5:  Once all data has been received, call SecureDownloadFinished.
  51                                 6:  Release the SecureDownloadRef by calling SecureDownloadRelease.
  52 */
  53
  54
  55
  56 #include <CoreFoundation/CoreFoundation.h>
  57 #include <Security/SecBase.h>
  58 #include <Security/SecTrust.h> /* SecTrustRef */
  59
  60
  61 typedef struct OpaqueSecureDownload *SecureDownloadRef;
  62
  63 enum {
  64         errSecureDownloadInvalidTicket = -20052,
  65         errSecureDownloadInvalidDownload = -20053
  66 };
  67
  68 /*!
  69         @enum _SecureDownloadSetupCallbackResult
  70         @discussion This type is used to indicate whether or not a
  71                                 signer should be evaluated.
  72         @constant kSecureDownloadDoNotEvaluateSigner Indicates that the signer should not be evaluated.
  73         @constant kSecureDownloadEvaluateSigner Indicates that the signer should be evaluated.
  74         @constant kSecureDownloadFailEvaluation Indicates that evaluation should fail immediately.
  75 */
  76
  77 typedef enum _SecureDownloadTrustCallbackResult
  78 {
  79         kSecureDownloadDoNotEvaluateSigner = 0,
  80         kSecureDownloadEvaluateSigner = 1,
  81         kSecureDownloadFailEvaluation = 2
  82 } SecureDownloadTrustCallbackResult;
  83
  84 /*!
  85         @typedef SecureDownloadTrustSetupCallback
  86         @discussion This callback is used to determine whether trust for a particular
  87                                 signer should be evaluated.
  88         @param trustRef The trustRef for this evaluation
  89         @param setupContext user defined.
  90         @result A SecureDownloadTrustCallbackResult (see).
  91 */
  92
  93 typedef SecureDownloadTrustCallbackResult(*SecureDownloadTrustSetupCallback)
  94                         (SecTrustRef trustRef, void* setupContext);
  95
  96 /*!
  97         @typedef SecureDownloadTrustEvaluateCallback
  98         @discussion This callback is used called after trust has been evaluated.
  99         @param trustRef The trustRef for this evaluation
 100         @param result The result of the evaluation (See the SecTrust documentation).
 101         @param evaluateContext user defined.
 102         @result A SecTrustResultType.  Return the value passed in result if you
 103                         do not want to change the evaluation result.
 104 */
 105
 106 typedef SecTrustResultType(*SecureDownloadTrustEvaluateCallback)
 107                         (SecTrustRef trustRef, SecTrustResultType result,
 108                          void *evaluateContext);
 109
 110 /*!
 111         @function SecureDownloadCreateWithTicket
 112         @abstract Create a SecureDownloadRef for use during the Secure Download process.
 113         @param ticket The download ticket.
 114         @param setup Called before trust is verified for each signer of the ticket.
 115                                                  This allows the user to modify the SecTrustRef if needed
 116                                                  (see the SecTrust documentation).  Returns a SecureDownloadTrustCallbackResult (see).
 117         @param setupContext User defined.  Passed as a parameter to the setupCallback.
 118         @param evaluate Called after SecTrustEvaluate has been called for a
 119                                                         signer if the result was not trusted. This allows
 120                                                         the developer to query the user as to whether or not
 121                                                         to trust the signer.  Returns a SecTrustResultType
 122         @param evaluateContext User defined.  Passed as a parameter to the evaluate callback.
 123         @param downloadRef The returned reference.
 124         @result Returns errSecureDownloadInvalidTicket if the ticket was invalid.  Otherwise
 125                         see "Security Error Codes" (SecBase.h).
 126 .
 127 */
 128
 129 OSStatus SecureDownloadCreateWithTicket (CFDataRef ticket,
 130                                                                                  SecureDownloadTrustSetupCallback setup,
 131                                                                                  void* setupContext,
 132                                                                                  SecureDownloadTrustEvaluateCallback evaluate,
 133                                                                                  void* evaluateContext,
 134                                                                                  SecureDownloadRef* downloadRef);
 135
 136 /*!
 137         @function SecureDownloadCopyURLs
 138         @abstract Return a list of URL's from which the data can be downloaded.  The first
 139                           URL in the list is the preferred download location.  The other URL's are
 140                           backup locations in case earlier locations in the list could not be
 141                           accessed.
 142         @param downloadRef A SecureDownloadRef instance.
 143         @param urls On return, the list of URL's to download.  Format is a CFArray of CFURL's.
 144         @result A result code.  See "Security Error Codes" (SecBase.h).
 145 */
 146
 147 OSStatus SecureDownloadCopyURLs (SecureDownloadRef downloadRef, CFArrayRef* urls);
 148
 149 /*!
 150         @function SecureDownloadCopyName
 151         @abstract Return the printable name of this download ticket.
 152         @param downloadRef A SecureDownloadRef instance.
 153         @param name On output, the download name.
 154         @result A result code.  See "Security Error Codes" (SecBase.h).
 155 */
 156
 157 OSStatus SecureDownloadCopyName (SecureDownloadRef downloadRef, CFStringRef* name);
 158
 159 /*!
 160         @function SecureDownloadCopyCreationDate
 161         @abstract Return the date the downlooad ticket was created.
 162         @param downloadRef A SecureDownloadRef instance.
 163         @result A result code.
 164 */
 165
 166 OSStatus SecureDownloadCopyCreationDate (SecureDownloadRef downloadRef, CFDateRef* date);
 167
 168 /*!
 169         @function SecureDownloadGetDownloadSize
 170         @abstract Return the size of the expected download.
 171         @param downloadRef A SecureDownloadRef instance.
 172         @param downloadSize On output, the size of the download.
 173         @result A result code.  See "Security Error Codes" (SecBase.h).
 174 */
 175
 176 OSStatus SecureDownloadGetDownloadSize (SecureDownloadRef downloadRef, SInt64 *downloadSize);
 177
 178 /*!
 179         @function SecureDownloadUpdateWithData
 180         @abstract Check data received during Secure Download for validity.
 181                           Call this function each time data is received.
 182         @param downloadRef A SecureDownloadRef instance.
 183         @param data The data to check.
 184         @result Returns errSecureDownloadInvalidDownload if data is invalid.  Otherwise
 185                         see "Security Error Codes" (SecBase.h).
 186 */
 187
 188 OSStatus SecureDownloadUpdateWithData (SecureDownloadRef downloadRef, CFDataRef data);
 189
 190 /*!
 191         @function SecureDownloadFinished
 192         @abstract Concludes the secure download process.  Call this after all data has been received.
 193         @param downloadRef A SecureDownloadRef instance.
 194         @result Returns errSecureDownloadInvalidDownload if data is invalid.  Otherwise
 195                         see "Security Error Codes" (SecBase.h).
 196 */
 197
 198 OSStatus SecureDownloadFinished (SecureDownloadRef downloadRef);
 199
 200 /*!
 201         @function SecureDownloadRelease
 202         @abstract Releases a SecureDownloadRef.
 203         @param downloadRef The SecureDownloadRef to release.
 204         @result A result code.  See "Security Error Codes" (SecBase.h).
 205 */
 206
 207 OSStatus SecureDownloadRelease (SecureDownloadRef downloadRef);
 208
 209 /*!
 210         @function SecureDownloadCopyTicketLocation
 211         @abstract Copies the ticket location from an x-securedownload URL.
 212         @param url The x-securedownload URL.
 213         @param ticketLocation On exit, the URL of the ticket.
 214         @result A result code.  See "Security Error Codes" (SecBase.h).
 215 */
 216
 217 OSStatus SecureDownloadCopyTicketLocation (CFURLRef url, CFURLRef *ticketLocation);
 218
 219 #if defined(__cplusplus)
 220 };
 221 #endif
 222
 223 #endif