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