1/* 2 * Copyright (c) 2002-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 SecAccess 26 SecAccess implements a way to set and manipulate access control rules and 27 restrictions on SecKeychainItems. 28*/ 29 30#ifndef _SECURITY_SECACCESS_H_ 31#define _SECURITY_SECACCESS_H_ 32 33#include <Security/SecBase.h> 34#include <Security/cssmtype.h> 35#include <CoreFoundation/CFArray.h> 36#include <CoreFoundation/CFError.h> 37#include <sys/types.h> 38#include <unistd.h> 39 40 41#if defined(__cplusplus) 42extern "C" { 43#endif 44 45 46 47typedef UInt32 SecAccessOwnerType; 48enum 49{ 50 kSecUseOnlyUID = 1, 51 kSecUseOnlyGID = 2, 52 kSecHonorRoot = 0x100, 53 kSecMatchBits = (kSecUseOnlyUID | kSecUseOnlyGID) 54}; 55 56/* No restrictions. Permission to perform all operations on 57 the resource or available to an ACL owner. */ 58extern CFTypeRef kSecACLAuthorizationAny 59 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 60 61extern CFTypeRef kSecACLAuthorizationLogin 62 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 63extern CFTypeRef kSecACLAuthorizationGenKey 64 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 65extern CFTypeRef kSecACLAuthorizationDelete 66 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 67extern CFTypeRef kSecACLAuthorizationExportWrapped 68 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 69extern CFTypeRef kSecACLAuthorizationExportClear 70 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 71extern CFTypeRef kSecACLAuthorizationImportWrapped 72 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 73extern CFTypeRef kSecACLAuthorizationImportClear 74 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 75extern CFTypeRef kSecACLAuthorizationSign 76 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 77extern CFTypeRef kSecACLAuthorizationEncrypt 78 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 79extern CFTypeRef kSecACLAuthorizationDecrypt 80 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 81extern CFTypeRef kSecACLAuthorizationMAC 82 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 83extern CFTypeRef kSecACLAuthorizationDerive 84 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 85 86/* Defined authorization tag values for Keychain */ 87extern CFTypeRef kSecACLAuthorizationKeychainCreate 88 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 89extern CFTypeRef kSecACLAuthorizationKeychainDelete 90 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 91extern CFTypeRef kSecACLAuthorizationKeychainItemRead 92 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 93extern CFTypeRef kSecACLAuthorizationKeychainItemInsert 94 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 95extern CFTypeRef kSecACLAuthorizationKeychainItemModify 96 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 97extern CFTypeRef kSecACLAuthorizationKeychainItemDelete 98 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 99 100extern CFTypeRef kSecACLAuthorizationChangeACL 101 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 102extern CFTypeRef kSecACLAuthorizationChangeOwner 103 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 104 105 106/*! 107 @function SecAccessGetTypeID 108 @abstract Returns the type identifier of SecAccess instances. 109 @result The CFTypeID of SecAccess instances. 110*/ 111CFTypeID SecAccessGetTypeID(void); 112 113/*! 114 @function SecAccessCreate 115 @abstract Creates a new SecAccessRef that is set to the currently designated system default 116 configuration of a (newly created) security object. Note that the precise nature of 117 this default may change between releases. 118 @param descriptor The name of the item as it should appear in security dialogs 119 @param trustedlist A CFArray of TrustedApplicationRefs, specifying which applications 120 should be allowed to access an item without triggering confirmation dialogs. 121 If NULL, defaults to (just) the application creating the item. To set no applications, 122 pass a CFArray with no elements. 123 @param accessRef On return, a pointer to the new access reference. 124 @result A result code. See "Security Error Codes" (SecBase.h). 125*/ 126OSStatus SecAccessCreate(CFStringRef descriptor, CFArrayRef trustedlist, SecAccessRef *accessRef); 127 128/*! 129 @function SecAccessCreateFromOwnerAndACL 130 @abstract Creates a new SecAccessRef using the owner and access control list you provide. 131 @param owner A pointer to a CSSM access control list owner. 132 @param aclCount An unsigned 32-bit integer representing the number of items in the access control list. 133 @param acls A pointer to the access control list. 134 @param On return, a pointer to the new access reference. 135 @result A result code. See "Security Error Codes" (SecBase.h). 136 @discussion For 10.7 and later please use the SecAccessCreateWithOwnerAndACL API 137*/ 138OSStatus SecAccessCreateFromOwnerAndACL(const CSSM_ACL_OWNER_PROTOTYPE *owner, uint32 aclCount, const CSSM_ACL_ENTRY_INFO *acls, SecAccessRef *accessRef) 139 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 140 141/*! 142 @function SecAccessCreateWithOwnerAndACL 143 @abstract Creates a new SecAccessRef using either for a user or a group with a list of ACLs 144 @param userId An user id that specifies the user to associate with this SecAccessRef. 145 @param groupId A group id that specifies the group to associate with this SecAccessRef. 146 @param ownerType Specifies the how the ownership of the new SecAccessRef is defined. 147 @param acls A CFArrayRef of the ACLs to associate with this SecAccessRef 148 @param error Optionally a pointer to a CFErrorRef to return any errors with may have occured 149 @result A pointer to the new access reference. 150*/ 151SecAccessRef SecAccessCreateWithOwnerAndACL(uid_t userId, gid_t groupId, SecAccessOwnerType ownerType, CFArrayRef acls, CFErrorRef *error) 152 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 153 154/*! 155 @function SecAccessGetOwnerAndACL 156 @abstract Retrieves the owner and the access control list of a given access. 157 @param accessRef A reference to the access from which to retrieve the information. 158 @param owner On return, a pointer to the access control list owner. 159 @param aclCount On return, a pointer to an unsigned 32-bit integer representing the number of items in the access control list. 160 @param acls On return, a pointer to the access control list. 161 @result A result code. See "Security Error Codes" (SecBase.h). 162 @discussion For 10.7 and later please use the SecAccessCopyOwnerAndACL API 163 */ 164OSStatus SecAccessGetOwnerAndACL(SecAccessRef accessRef, CSSM_ACL_OWNER_PROTOTYPE_PTR *owner, uint32 *aclCount, CSSM_ACL_ENTRY_INFO_PTR *acls) 165 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 166 167/*! 168 @function SecAccessCopyOwnerAndACL 169 @abstract Retrieves the owner and the access control list of a given access. 170 @param accessRef A reference to the access from which to retrieve the information. 171 @param userId On return, the user id of the owner 172 @param groupId On return, the group id of the owner 173 @param ownerType On return, the type of owner for this AccessRef 174 @param aclCount On return, a Boolean that if true specifies that the ownerId is a uid_t else it is a gid_t. 175 @param aclList On return, a pointer to a new created CFArray of SecACL instances. The caller is responsible for calling CFRelease on this array. 176 @result A result code. See "Security Error Codes" (SecBase.h). 177 */ 178OSStatus SecAccessCopyOwnerAndACL(SecAccessRef accessRef, uid_t* userId, gid_t* groupId, SecAccessOwnerType* ownerType, CFArrayRef* aclList) 179 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 180 181/*! 182 @function SecAccessCopyACLList 183 @abstract Copies all the access control lists of a given access. 184 @param accessRef A reference to the access from which to retrieve the information. 185 @param aclList On return, a pointer to a new created CFArray of SecACL instances. The caller is responsible for calling CFRelease on this array. 186 @result A result code. See "Security Error Codes" (SecBase.h). 187*/ 188OSStatus SecAccessCopyACLList(SecAccessRef accessRef, CFArrayRef *aclList); 189 190/*! 191 @function SecAccessCopySelectedACLList 192 @abstract Copies selected access control lists from a given access. 193 @param accessRef A reference to the access from which to retrieve the information. 194 @param action An authorization tag specifying what action with which to select the action control lists. 195 @param aclList On return, a pointer to the selected access control lists. 196 @result A result code. See "Security Error Codes" (SecBase.h). 197 @discussion For 10.7 and later please use the SecAccessCopyMatchingACLList API 198*/ 199OSStatus SecAccessCopySelectedACLList(SecAccessRef accessRef, CSSM_ACL_AUTHORIZATION_TAG action, CFArrayRef *aclList) 200 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; 201 202 203/*! 204 @function SecAccessCopyMatchingACLList 205 @abstract Copies selected access control lists from a given access. 206 @param accessRef A reference to the access from which to retrieve the information. 207 @param authorizationTag An authorization tag specifying what action with which to select the action control lists. 208 @result A pointer to the selected access control lists. 209*/ 210CFArrayRef SecAccessCopyMatchingACLList(SecAccessRef accessRef, CFTypeRef authorizationTag) 211 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 212 213#if defined(__cplusplus) 214} 215#endif 216 217#endif /* !_SECURITY_SECACCESS_H_ */ 218