+++ /dev/null
-#ifndef __SECURE_DOWNLOAD__
-#define __SECURE_DOWNLOAD__
-
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
-/*
- * Copyright (c) 2006 Apple Computer, Inc. All Rights Reserved.
- *
- * @APPLE_LICENSE_HEADER_START@
- *
- * This file contains Original Code and/or Modifications of Original Code
- * as defined in and that are subject to the Apple Public Source License
- * Version 2.0 (the 'License'). You may not use this file except in
- * compliance with the License. Please obtain a copy of the License at
- * http://www.opensource.apple.com/apsl/ and read it before using this
- * file.
- *
- * The Original Code and all software distributed under the License are
- * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
- * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
- * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
- * Please see the License for the specific language governing rights and
- * limitations under the License.
- *
- * @APPLE_LICENSE_HEADER_END@
- */
-
-/*!
- @header SecureDownload
- @abstract Used by clients to implement Apple's Verified Download System.
-
- Please note that a succesful check does not guarantee anything about
- the safety of the file being downloaded. Rather, it simply checks to make sure
- that the contents of the file being downloaded exactly matches the contents
- of the file when the ticket was originally generated.
-
- To use, do the following:
- 1: Download the secure download ticket.
- 2: Pass the ticket to SecureDownloadCreateWithTicket. On error, call
- SecureDownloadGetTrustRef to return data that will help you figure
- out why the ticket was bad.
- 3: If SecureDownloadCreateWithTicket returns errSecSuccess, call SecureDownloadCopyURLs
- to return a list of data download locations. Begin downloading data from
- the first URL in the list. If that download fails, try downloading from
- the second URL, and so forth.
- 4: Each time you receive data, call SecureDownloadReceivedData.
- 5: Once all data has been received, call SecureDownloadFinished.
- 6: Release the SecureDownloadRef by calling SecureDownloadRelease.
-*/
-
-
-
-#include <CoreFoundation/CoreFoundation.h>
-#include <Security/SecBase.h>
-
-
-
-typedef struct OpaqueSecureDownload *SecureDownloadRef;
-
-enum {
- errSecureDownloadInvalidTicket = -20052,
- errSecureDownloadInvalidDownload = -20053
-};
-
-/*!
- @enum _SecureDownloadSetupCallbackResult
- @discussion This type is used to indicate whether or not a
- signer should be evaluated.
- @constant kSecureDownloadDoNotEvaluateSigner Indicates that the signer should not be evaluated.
- @constant kSecureDownloadEvaluateSigner Indicates that the signer should be evaluated.
- @constant kSecureDownloadFailEvaluation Indicates that evaluation should fail immediately.
-*/
-
-typedef enum _SecureDownloadTrustCallbackResult
-{
- kSecureDownloadDoNotEvaluateSigner = 0,
- kSecureDownloadEvaluateSigner = 1,
- kSecureDownloadFailEvaluation = 2
-} SecureDownloadTrustCallbackResult;
-
-/*!
- @typedef SecureDownloadTrustSetupCallback
- @discussion This callback is used to determine whether trust for a particular
- signer should be evaluated.
- @param trustRef The trustRef for this evaluation
- @param setupContext user defined.
- @result A SecureDownloadTrustCallbackResult (see).
-*/
-
-typedef SecureDownloadTrustCallbackResult(*SecureDownloadTrustSetupCallback)
- (SecTrustRef trustRef, void* setupContext);
-
-/*!
- @typedef SecureDownloadTrustEvaluateCallback
- @discussion This callback is used called after trust has been evaluated.
- @param trustRef The trustRef for this evaluation
- @param result The result of the evaluation (See the SecTrust documentation).
- @param evaluateContext user defined.
- @result A SecTrustResultType. Return the value passed in result if you
- do not want to change the evaluation result.
-*/
-
-typedef SecTrustResultType(*SecureDownloadTrustEvaluateCallback)
- (SecTrustRef trustRef, SecTrustResultType result,
- void *evaluateContext);
-
-/*!
- @function SecureDownloadCreateWithTicket
- @abstract Create a SecureDownloadRef for use during the Secure Download process.
- @param ticket The download ticket.
- @param setupCallback Called before trust is verified for each signer of the ticket.
- This allows the user to modify the SecTrustRef if needed
- (see the SecTrust documentation). Returns a SecureDownloadTrustCallbackResult (see).
- @param setupContext User defined. Passed as a parameter to the setupCallback.
- @param evaluateCallback Called after SecTrustEvaluate has been called for a
- signer if the result was not trusted. This allows
- the developer to query the user as to whether or not
- to trust the signer. Returns a SecTrustResultType
- @param evaluateContext User defined. Passed as a parameter to the evaluate callback.
- @param downloadRef The returned reference.
- @result Returns errSecureDownloadInvalidTicket if the ticket was invalid. Otherwise
- see "Security Error Codes" (SecBase.h).
-.
-*/
-
-OSStatus SecureDownloadCreateWithTicket (CFDataRef ticket,
- SecureDownloadTrustSetupCallback setup,
- void* setupContext,
- SecureDownloadTrustEvaluateCallback evaluate,
- void* evaluateContext,
- SecureDownloadRef* downloadRef);
-
-/*!
- @function SecureDownloadCopyURLs
- @abstract Return a list of URL's from which the data can be downloaded. The first
- URL in the list is the preferred download location. The other URL's are
- backup locations in case earlier locations in the list could not be
- accessed.
- @param downloadRef A SecureDownloadRef instance.
- @param urls On return, the list of URL's to download. Format is a CFArray of CFURL's.
- @result A result code. See "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadCopyURLs (SecureDownloadRef downloadRef, CFArrayRef* urls);
-
-/*!
- @function SecureDownloadCopyName
- @abstract Return the printable name of this download ticket.
- @param downloadRef A SecureDownloadRef instance.
- @param name On output, the download name.
- @result A result code. See "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadCopyName (SecureDownloadRef downloadRef, CFStringRef* name);
-
-/*!
- @function SecureDownloadCopyCreationDate
- @abstract Return the date the downlooad ticket was created.
- @param downloadRef A SecureDownloadRef instance.
- @param name On output, the creation date.
- @result A result code.
-*/
-
-OSStatus SecureDownloadCopyCreationDate (SecureDownloadRef downloadRef, CFDateRef* date);
-
-/*!
- @function SecureDownloadGetDownloadSize
- @abstract Return the size of the expected download.
- @param downloadRef A SecureDownloadRef instance.
- @param size On output, the size of the download.
- @result A result code. See "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadGetDownloadSize (SecureDownloadRef downloadRef, SInt64 *downloadSize);
-
-/*!
- @function SecureDownloadUpdateWithData
- @abstract Check data received during Secure Download for validity.
- Call this function each time data is received.
- @param downloadRef A SecureDownloadRef instance.
- @param data The data to check.
- @result Returns errSecureDownloadInvalidDownload if data is invalid. Otherwise
- see "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadUpdateWithData (SecureDownloadRef downloadRef, CFDataRef data);
-
-/*!
- @function SecureDownloadFinished
- @abstract Concludes the secure download process. Call this after all data has been received.
- @param downloadRef A SecureDownloadRef instance.
- @result Returns errSecureDownloadInvalidDownload if data is invalid. Otherwise
- see "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadFinished (SecureDownloadRef downloadRef);
-
-/*!
- @function SecureDownloadRelease
- @abstract Releases a SecureDownloadRef.
- @param downloadRef The SecureDownloadRef to release.
- @result A result code. See "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadRelease (SecureDownloadRef downloadRef);
-
-/*!
- @function SecureDownloadCopyTicketLocation
- @abstract Copies the ticket location from an x-securedownload URL.
- @param url The x-securedownload URL.
- @param ticketLocation On exit, the URL of the ticket.
- @result A result code. See "Security Error Codes" (SecBase.h).
-*/
-
-OSStatus SecureDownloadCopyTicketLocation (CFURLRef url, CFURLRef *ticketLocation);
-
-#if defined(__cplusplus)
-};
-#endif
-
-#endif
projects / apple / security.git / blobdiff