OSX/libsecurity_keychain/lib/SecTrustedApplicationPriv.h

   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);
  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);
  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);
  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);
 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);
 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);
 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);
 150
 151 OSStatus
 152 SecTrustedApplicationRemoveEquivalence(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  */
 159 OSStatus
 160 SecTrustedApplicationIsUpdateCandidate(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  */
 167 OSStatus
 168 SecTrustedApplicationUseAlternateSystem(const char *systemRoot);
 169
 170
 171 #if defined(__cplusplus)
 172 }
 173 #endif
 174
 175 #endif /* !_SECURITY_SECTRUSTEDAPPLICATIONPRIV_H_ */