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