1/* 2 * Copyright (c) 2003-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 SecTrustedApplicationPriv 26 Not (yet?) public functions related to SecTrustedApplicationRef objects 27*/ 28 29#ifndef _SECURITY_SECTRUSTEDAPPLICATIONPRIV_H_ 30#define _SECURITY_SECTRUSTEDAPPLICATIONPRIV_H_ 31 32#include <Security/SecTrustedApplication.h> 33#include <Security/SecRequirementPriv.h> 34 35 36#if defined(__cplusplus) 37extern "C" { 38#endif 39 40 41/* 42 * Determine whether the application at path satisfies the trust expressed in appRef. 43 */ 44OSStatus 45SecTrustedApplicationValidateWithPath(SecTrustedApplicationRef appRef, const char *path); 46 47/*! 48 @function SecTrustedApplicationCreateFromRequirement 49 @abstract Creates a trusted application reference based on an application 50 URI description and a SecRequirementRef describing how it should be verified. 51 @param description A URI-formatted string describing the intended meaning of 52 the requirement being provided. This is for information purposes only 53 and does not affect any actual validation being performed as a result. 54 It may affect how the SecTrustedApplication is displayed or edited. 55 If NULL, a default generic description is used. 56 @param requirement A SecRequirementRef indicating what conditions an application 57 must satisfy to be considered a match for this SecTrustedApplicationRef. 58 @param app On return, contains a SecTrustedApplicationRef representing any 59 code that satisfies the requirement argument. 60 @result A result code. See SecBase.h and CSCommon.h. 61*/ 62OSStatus SecTrustedApplicationCreateFromRequirement(const char *description, 63 SecRequirementRef requirement, SecTrustedApplicationRef *app); 64 65/*! 66 @function SecTrustedApplicationCopyRequirement 67 @abstract If a SecTrustedApplicationRef contains a Code Signing requirement, 68 it can be retrieved with this call. If no requirement is recorded, requirement 69 is set to NULL and the call succeeds. 70 @param appRef A trusted application reference to retrieve data from 71 @param requirement Receives the SecRequirementRef contained in appRef, if any. 72 If no Code Signing requirement is contained in appRef, *requirement is set 73 to NULL and the call succeeds. This can happen if appRef was created from 74 an unsigned application, or from sources that do not record code signing 75 information such as keychain items made in version 10.4 or earlier of the 76 system. 77 @result A result code. See SecBase.h and CSCommon.h. It is not an error if 78 no SecRequirementRef could be obtained. 79 */ 80OSStatus SecTrustedApplicationCopyRequirement(SecTrustedApplicationRef appRef, 81 SecRequirementRef *requirement); 82 83 84/*! 85 @function SecTrustedApplicationCreateApplicationGroup 86 @abstract Create a SecTrustedApplication object that represents an application 87 group reference. It will match any application that has been marked as 88 a member of the named group and was signed by a particular authority (anchor). 89 Note that application groups are open-ended and more applications can be 90 signed as members (by holders of suitable signing authorities) at any time. 91 There is no way to reliably enumerate all members of an application group. 92 @param groupName The name of the application group. If you define your own 93 application group, use reverse domain notation (com.yourapp.yourgroup). 94 @param anchor The anchor certificate that is required to seal the group. 95 An application will be recognized as a member of the group only if it 96 was signed with an identity that draws to this group. If NULL, requires 97 signing by Apple. 98 @param app On return, contains a SecTrustedApplicationRef representing any 99 code that has been signed and marked as a member of the named application 100 group. 101 @result A result code. See SecBase.h and CSCommon.h. 102 */ 103OSStatus SecTrustedApplicationCreateApplicationGroup(const char *groupName, 104 SecCertificateRef anchor, SecTrustedApplicationRef *app); 105 106 107/*! 108 @function SecTrustedApplicationCopyExternalRepresentation 109 @abstract Create a pure-data form of a SecTrustedApplicationRef object suitable 110 for persistent storage anywhere. This data can later be fed to 111 SecTrustedApplicationCreateWithExternalRepresentation to create an equivalent 112 SecTrustedApplicationRef. The data is variable size, and should be considered 113 entirely opaque; its internal form is subject to change. 114 @param appRef A valid SecTrustedApplicationRef of any kind. 115 @param externalRef Upon successful return, contains a CFDataRef that can be 116 stored as required. 117 @result A result code. See SecBase.h and CSCommon.h. 118 */ 119OSStatus SecTrustedApplicationCopyExternalRepresentation( 120 SecTrustedApplicationRef appRef, 121 CFDataRef *externalRef); 122 123/*! 124 @function SecTrustedApplicationCreateWithExternalRepresentation 125 @abstract Create a SecTrustedApplicationRef from an external data representation 126 that was originally obtained with a call to SecTrustedApplicationCopyExternalRepresentation. 127 @param externalRef A CFDataRef containing data produced by 128 SecTrustedApplicationCopyExternalRepresentation. If this data was not obtained 129 from that function, the behavior is undefined. 130 @param appRef Upon successful return, a SecTrustedApplicationRef that is functionally 131 equivalent to the original one used to obtain externalRef. 132 @result A result code. See SecBase.h and CSCommon.h. 133 */ 134OSStatus SecTrustedApplicationCreateWithExternalRepresentation( 135 CFDataRef externalRef, 136 SecTrustedApplicationRef *appRef); 137 138 139/* 140 * Administrative editing of the system's application equivalence database 141 */ 142enum { 143 kSecApplicationFlagSystemwide = 0x1, 144 kSecApplicationValidFlags = kSecApplicationFlagSystemwide 145}; 146 147OSStatus 148SecTrustedApplicationMakeEquivalent(SecTrustedApplicationRef oldRef, 149 SecTrustedApplicationRef newRef, UInt32 flags); 150 151OSStatus 152SecTrustedApplicationRemoveEquivalence(SecTrustedApplicationRef appRef, UInt32 flags); 153 154 155/* 156 * Check to see if an application at a given path is a candidate for 157 * pre-emptive code equivalency establishment 158 */ 159OSStatus 160SecTrustedApplicationIsUpdateCandidate(const char *installroot, const char *path); 161 162 163/* 164 * Point the system at another system root for equivalence use. 165 * This is for system update installers (only)! 166 */ 167OSStatus 168SecTrustedApplicationUseAlternateSystem(const char *systemRoot); 169 170 171#if defined(__cplusplus) 172} 173#endif 174 175#endif /* !_SECURITY_SECTRUSTEDAPPLICATIONPRIV_H_ */ 176