Security/libsecurity_keychain/lib/SecAccess.h

   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)
  42 extern "C" {
  43 #endif
  44
  45
  46
  47 typedef UInt32  SecAccessOwnerType;
  48 enum
  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.  */
  58 extern  CFTypeRef kSecACLAuthorizationAny
  59         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  60
  61 extern CFTypeRef kSecACLAuthorizationLogin
  62         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  63 extern CFTypeRef kSecACLAuthorizationGenKey
  64         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  65 extern CFTypeRef kSecACLAuthorizationDelete
  66         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  67 extern CFTypeRef kSecACLAuthorizationExportWrapped
  68         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  69 extern CFTypeRef kSecACLAuthorizationExportClear
  70         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  71 extern CFTypeRef kSecACLAuthorizationImportWrapped
  72         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  73 extern CFTypeRef kSecACLAuthorizationImportClear
  74         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  75 extern CFTypeRef kSecACLAuthorizationSign
  76         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  77 extern CFTypeRef kSecACLAuthorizationEncrypt
  78         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  79 extern CFTypeRef kSecACLAuthorizationDecrypt
  80         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  81 extern CFTypeRef kSecACLAuthorizationMAC
  82         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  83 extern CFTypeRef kSecACLAuthorizationDerive
  84         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  85
  86 /* Defined authorization tag values for Keychain */
  87 extern CFTypeRef kSecACLAuthorizationKeychainCreate
  88         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  89 extern CFTypeRef kSecACLAuthorizationKeychainDelete
  90         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  91 extern CFTypeRef kSecACLAuthorizationKeychainItemRead
  92         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  93 extern CFTypeRef kSecACLAuthorizationKeychainItemInsert
  94         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  95 extern CFTypeRef kSecACLAuthorizationKeychainItemModify
  96         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  97 extern CFTypeRef kSecACLAuthorizationKeychainItemDelete
  98         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  99
 100 extern CFTypeRef kSecACLAuthorizationChangeACL
 101         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 102 extern 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 */
 111 CFTypeID 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 */
 126 OSStatus 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 */
 138 OSStatus 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 */
 151 SecAccessRef 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  */
 164 OSStatus 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  */
 178 OSStatus 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 */
 188 OSStatus 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 */
 199 OSStatus 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 */
 210 CFArrayRef 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_ */