1  /*
  2   * Copyright (c) 2003-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 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)
 37  extern "C" {
 38  #endif
 39  
 40  
 41  /*
 42   * Determine whether the application at path satisfies the trust expressed in appRef.
 43   */
 44  OSStatus
 45  SecTrustedApplicationValidateWithPath(SecTrustedApplicationRef appRef, const char *path) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 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  */
 62  OSStatus SecTrustedApplicationCreateFromRequirement(const char *description,
 63  	SecRequirementRef requirement, SecTrustedApplicationRef *app) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 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   */
 80  OSStatus SecTrustedApplicationCopyRequirement(SecTrustedApplicationRef appRef,
 81  	SecRequirementRef *requirement) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 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   */
103  OSStatus SecTrustedApplicationCreateApplicationGroup(const char *groupName,
104  	SecCertificateRef anchor, SecTrustedApplicationRef *app) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
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   */
119  OSStatus SecTrustedApplicationCopyExternalRepresentation(
120  	SecTrustedApplicationRef appRef,
121  	CFDataRef *externalRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
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   */
134  OSStatus SecTrustedApplicationCreateWithExternalRepresentation(
135  	CFDataRef externalRef,
136  	SecTrustedApplicationRef *appRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
137  
138  
139  /*
140   * Administrative editing of the system's application equivalence database
141   */
142  enum {
143  	kSecApplicationFlagSystemwide =			0x1,
144  	kSecApplicationValidFlags =				kSecApplicationFlagSystemwide
145  };
146  
147  OSStatus
148  SecTrustedApplicationMakeEquivalent(SecTrustedApplicationRef oldRef,
149  	SecTrustedApplicationRef newRef, UInt32 flags) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
150  
151  OSStatus
152  SecTrustedApplicationRemoveEquivalence(SecTrustedApplicationRef appRef, UInt32 flags) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
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   */
159  OSStatus
160  SecTrustedApplicationIsUpdateCandidate(const char *installroot, const char *path) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
161  
162  
163  /*
164   * Point the system at another system root for equivalence use.
165   * This is for system update installers (only)!
166   */
167  OSStatus
168  SecTrustedApplicationUseAlternateSystem(const char *systemRoot) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
169  
170  
171  #if defined(__cplusplus)
172  }
173  #endif
174  
175  #endif /* !_SECURITY_SECTRUSTEDAPPLICATIONPRIV_H_ */