1/* 2 * Copyright (c) 2002-2010 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 SecACL 26 The functions provided in SecACL are for managing entries in the access control list. 27 */ 28 29#ifndef _SECURITY_SECACL_H_ 30#define _SECURITY_SECACL_H_ 31 32#include <Security/SecBase.h> 33#include <Security/cssmtype.h> 34#include <Security/cssmapple.h> 35#include <Security/SecAccess.h> 36#include <CoreFoundation/CoreFoundation.h> 37 38 39#if defined(__cplusplus) 40extern "C" { 41#endif 42 43 typedef uint16 SecKeychainPromptSelector; 44 enum 45 { 46 kSecKeychainPromptRequirePassphase = 0x0001, /* require re-entering of passphrase */ 47 /* the following bits are ignored by 10.4 and earlier */ 48 kSecKeychainPromptUnsigned = 0x0010, /* prompt for unsigned clients */ 49 kSecKeychainPromptUnsignedAct = 0x0020, /* UNSIGNED bit overrides system default */ 50 kSecKeychainPromptInvalid = 0x0040, /* prompt for invalid signed clients */ 51 kSecKeychainPromptInvalidAct = 0x0080, 52 }; 53 54 55 /*! 56 @function SecACLGetTypeID 57 @abstract Returns the type identifier of SecACL instances. 58 @result The CFTypeID of SecACL instances. 59 */ 60 CFTypeID SecACLGetTypeID(void) 61 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA); 62 63 /*! 64 @function SecACLCreateFromSimpleContents 65 @abstract Creates a new access control list entry from the application list, description, and prompt selector provided and adds it to an item's access. 66 @param access An access reference. 67 @param applicationList An array of SecTrustedApplication instances that will be allowed access without prompting. 68 @param description The human readable name that will be used to refer to this item when the user is prompted. 69 @param promptSelector A pointer to a CSSM prompt selector. 70 @param newAcl A pointer to an access control list entry. On return, this points to the reference of the new access control list entry. 71 @result A result code. See "Security Error Codes" (SecBase.h). 72 @discussion This function is deprecated in 10.7 and later; 73 use SecACLCreateWithSimpleContents instead. 74 */ 75 OSStatus SecACLCreateFromSimpleContents(SecAccessRef access, 76 CFArrayRef applicationList, 77 CFStringRef description, const CSSM_ACL_KEYCHAIN_PROMPT_SELECTOR *promptSelector, 78 SecACLRef *newAcl) 79 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 80 81 /*! 82 @function SecACLCreateWithSimpleContents 83 @abstract Creates a new access control list entry from the application list, description, and prompt selector provided and adds it to an item's access. 84 @param access An access reference. 85 @param applicationList An array of SecTrustedApplication instances that will be allowed access without prompting. 86 @param description The human readable name that will be used to refer to this item when the user is prompted. 87 @param promptSelector A SecKeychainPromptSelector selector. 88 @param newAcl A pointer to an access control list entry. On return, this points to the reference of the new access control list entry. 89 @result A result code. See "Security Error Codes" (SecBase.h). 90 */ 91 OSStatus SecACLCreateWithSimpleContents(SecAccessRef access, 92 CFArrayRef applicationList, 93 CFStringRef description, 94 SecKeychainPromptSelector promptSelector, 95 SecACLRef *newAcl) 96 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 97 98 /*! 99 @function SecACLRemove 100 @abstract Removes the access control list entry specified. 101 @param aclRef The reference to the access control list entry to remove. 102 @result A result code. See "Security Error Codes" (SecBase.h). 103 */ 104 OSStatus SecACLRemove(SecACLRef aclRef) 105 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA); 106 107 /*! 108 @function SecACLCopySimpleContents 109 @abstract Returns the application list, description, and CSSM prompt selector for a given access control list entry. 110 @param acl An access control list entry reference. 111 @param applicationList On return, An array of SecTrustedApplication instances that will be allowed access without prompting, for the given access control list entry. The caller needs to call CFRelease on this array when it's no longer needed. 112 @param description On return, the human readable name that will be used to refer to this item when the user is prompted, for the given access control list entry. The caller needs to call CFRelease on this string when it's no longer needed. 113 @param promptSelector A pointer to a CSSM prompt selector. On return, this points to the CSSM prompt selector for the given access control list entry. 114 @result A result code. See "Security Error Codes" (SecBase.h). 115 @discussion This function is deprecated in 10.7 and later; 116 use SecACLCopyContents instead. 117 */ 118 OSStatus SecACLCopySimpleContents(SecACLRef acl, 119 CFArrayRef *applicationList, 120 CFStringRef *description, CSSM_ACL_KEYCHAIN_PROMPT_SELECTOR *promptSelector) 121 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 122 123 /*! 124 @function SecACLCopyContents 125 @abstract Returns the application list, description, and prompt selector for a given access control list entry. 126 @param acl An access control list entry reference. 127 @param applicationList On return, An array of SecTrustedApplication instances that will be allowed access without prompting, for the given access control list entry. The caller needs to call CFRelease on this array when it's no longer needed. 128 @param description On return, the human readable name that will be used to refer to this item when the user is prompted, for the given access control list entry. The caller needs to call CFRelease on this string when it's no longer needed. 129 @param promptSelector A pointer to a SecKeychainPromptSelector. On return, this points to the SecKeychainPromptSelector for the given access control list entry. 130 @result A result code. See "Security Error Codes" (SecBase.h). 131 */ 132 OSStatus SecACLCopyContents(SecACLRef acl, 133 CFArrayRef *applicationList, 134 CFStringRef *description, 135 SecKeychainPromptSelector *promptSelector) 136 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 137 /*! 138 @function SecACLSetSimpleContents 139 @abstract Sets the application list, description, and CSSM prompt selector for a given access control list entry. 140 @param acl A reference to the access control list entry to edit. 141 @param applicationList An application list reference. 142 @param description The human readable name that will be used to refer to this item when the user is prompted. 143 @param promptSelector A pointer to a CSSM prompt selector. 144 @result A result code. See "Security Error Codes" (SecBase.h). 145 @discussion This function is deprecated in 10.7 and later; 146 use SecACLSetContents instead. 147 */ 148 OSStatus SecACLSetSimpleContents(SecACLRef acl, 149 CFArrayRef applicationList, 150 CFStringRef description, const CSSM_ACL_KEYCHAIN_PROMPT_SELECTOR *promptSelector) 151 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 152 153 /*! 154 @function SecACLSetContents 155 @abstract Sets the application list, description, and prompt selector for a given access control list entry. 156 @param acl A reference to the access control list entry to edit. 157 @param applicationList An application list reference. 158 @param description The human readable name that will be used to refer to this item when the user is prompted. 159 @param promptSelector A SecKeychainPromptSelector selector. 160 @result A result code. See "Security Error Codes" (SecBase.h). 161 */ 162 OSStatus SecACLSetContents(SecACLRef acl, 163 CFArrayRef applicationList, 164 CFStringRef description, 165 SecKeychainPromptSelector promptSelector) 166 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 167 168 /*! 169 @function SecACLGetAuthorizations 170 @abstract Retrieve the CSSM authorization tags of a given access control list entry. 171 @param acl An access control list entry reference. 172 @param tags On return, this points to the first item in an array of CSSM authorization tags. 173 @param tagCount On return, this points to the number of tags in the CSSM authorization tag array. 174 @result A result code. See "Security Error Codes" (SecBase.h). 175 @discussion This function is deprecated in 10.7 and later; 176 use SecACLCopyAuthorizations instead. 177 */ 178 OSStatus SecACLGetAuthorizations(SecACLRef acl, 179 CSSM_ACL_AUTHORIZATION_TAG *tags, uint32 *tagCount) 180 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 181 182 /*! 183 @function SecACLCopyAuthorizations 184 @abstract Retrieve the authorization tags of a given access control list entry. 185 @param acl An access control list entry reference. 186 @result On return, a CFArrayRef of the authorizations for this ACL. 187 */ 188 CFArrayRef SecACLCopyAuthorizations(SecACLRef acl) 189 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 190 191 /*! 192 @function SecACLSetAuthorizations 193 @abstract Sets the CSSM authorization tags of a given access control list entry. 194 @param acl An access control list entry reference. 195 @param tags A pointer to the first item in an array of CSSM authorization tags. 196 @param tagCount The number of tags in the CSSM authorization tag array. 197 @result A result code. See "Security Error Codes" (SecBase.h). 198 @discussion This function is deprecated in 10.7 and later; 199 use SecACLUpdateAuthorizations instead. 200 */ 201 OSStatus SecACLSetAuthorizations(SecACLRef acl, 202 CSSM_ACL_AUTHORIZATION_TAG *tags, uint32 tagCount) 203 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 204 205 206 /*! 207 @function SecACLUpdateAuthorizations 208 @abstract Sets the authorization tags of a given access control list entry. 209 @param acl An access control list entry reference. 210 @param authorizations A pointer to an array of authorization tags. 211 @result A result code. See "Security Error Codes" (SecBase.h). 212 */ 213 OSStatus SecACLUpdateAuthorizations(SecACLRef acl, CFArrayRef authorizations) 214 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 215 216#if defined(__cplusplus) 217} 218#endif 219 220#endif /* !_SECURITY_SECACL_H_ */ 221