OSX/libsecurity_keychain/lib/SecACL.h

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