OSX/sec/Security/SecAccessControlPriv.h

   1 /*
   2  * Copyright (c) 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 SecAccessControlPriv
  26  SecAccessControl defines access rights for items.
  27  */
  28
  29 #ifndef _SECURITY_SECACCESSCONTROLPRIV_H_
  30 #define _SECURITY_SECACCESSCONTROLPRIV_H_
  31
  32 #include <Security/SecBase.h>
  33 #include <CoreFoundation/CFError.h>
  34 #include <CoreFoundation/CFData.h>
  35 #include <CoreFoundation/CFDictionary.h>
  36
  37 __BEGIN_DECLS
  38
  39 /*! Creates new empty access control object. */
  40 SecAccessControlRef SecAccessControlCreate(CFAllocatorRef allocator, CFErrorRef *error);
  41
  42 // Protection, currently only kSecAttrAccessible* constants are allowed.  In future, another probable protection type might be CTK key object ID.
  43 CFTypeRef SecAccessControlGetProtection(SecAccessControlRef access_control);
  44 bool SecAccessControlSetProtection(SecAccessControlRef access_control, CFTypeRef protection, CFErrorRef *error);
  45
  46 /*! Represents constraint of the operation. */
  47 typedef CFTypeRef SecAccessConstraintRef;
  48
  49 /*! Creates constraint based on specified policy.
  50     @param policy Identification of policy to be used.
  51  */
  52 SecAccessConstraintRef SecAccessConstraintCreatePolicy(CFAllocatorRef allocator, CFTypeRef policy, CFErrorRef *error);
  53
  54 /*! Creates constraint which requires passcode verification. */
  55 SecAccessConstraintRef SecAccessConstraintCreatePasscode(CFAllocatorRef allocator);
  56
  57 /*! Creates constraint which requires Touch ID or Face ID verification.*/
  58 SecAccessConstraintRef SecAccessConstraintCreateBiometryAny(CFAllocatorRef allocator, CFDataRef catacombUUID);
  59
  60 /*! Creates constraint which requires Touch ID verification.*/
  61 SecAccessConstraintRef SecAccessConstraintCreateTouchIDAny(CFAllocatorRef allocator, CFDataRef catacombUUID)
  62 API_DEPRECATED_WITH_REPLACEMENT("SecAccessConstraintCreateBiometryAny", macos(10.12.1, 10.13.4), ios(9.0, 11.3));
  63
  64 /*! Creates constraint which requires Touch ID or Face ID verification.*/
  65 SecAccessConstraintRef SecAccessConstraintCreateBiometryCurrentSet(CFAllocatorRef allocator, CFDataRef catacombUUID, CFDataRef bioDbHash);
  66
  67 /*! Creates constraint which requires Touch ID verification.*/
  68 SecAccessConstraintRef SecAccessConstraintCreateTouchIDCurrentSet(CFAllocatorRef allocator, CFDataRef catacombUUID, CFDataRef bioDbHash)
  69 API_DEPRECATED_WITH_REPLACEMENT("SecAccessConstraintCreateBiometryCurrentSet", macos(10.12.1, 10.13.4), ios(9.0, 11.3));
  70
  71 /*! Creates constraint which requires watch verification. */
  72 SecAccessConstraintRef SecAccessConstraintCreateWatch(CFAllocatorRef allocator) API_AVAILABLE(macos(10.14), ios(12.0));
  73
  74 /*! Creates constraint composed of other constraints.
  75     @param numRequired Number of constraints required to be satisfied in order to consider overal constraint satisfied.
  76     @param constraints Array of constraints to be chosen from.
  77  */
  78 SecAccessConstraintRef SecAccessConstraintCreateKofN(CFAllocatorRef allocator, size_t numRequired, CFArrayRef constraints, CFErrorRef *error);
  79
  80 /*! Adds new constraint for specified operation.
  81     @param access_control Instance of access control object to add constraint to.
  82     @param operation Operation type.
  83     @param constraint Constraint object, created by one of SecAccessControlConstraintCreate() functions or kCFBooleanTrue
  84                       meaning that operation will be always allowed.
  85  */
  86 bool SecAccessControlAddConstraintForOperation(SecAccessControlRef access_control, CFTypeRef operation,
  87                                                SecAccessConstraintRef constraint, CFErrorRef *error);
  88
  89 /*! Retrieves dictionary with constraint applicable for specified operation.
  90     @param access_control Instance of access control object to query.
  91     @param operation Operation type.
  92     @return Dictionary or kCFBooleanTrue representing constraint applied for requested operation.  If the operation
  93             is not allowed at all, NULL is returned.
  94  */
  95 SecAccessConstraintRef SecAccessControlGetConstraint(SecAccessControlRef access_control, CFTypeRef operation);
  96
  97 /*! Serializes constraint applicable for specified operation into binary data form.
  98  @param access_control Instance of access control object to query.
  99  @param operation Operation type.
 100  @return Binary data representing constraint applied for requested operation
 101  */
 102 CFDataRef SecAccessControlCopyConstraintData(SecAccessControlRef access_control, CFTypeRef operation);
 103
 104 /*! Retrieves dictionary with constraints keyed by operations (i.e. the ACL part of access control object).
 105     @return Dictionary with all constraints keyed by operation types.  Returns NULL if no operations are constrained.
 106  */
 107 CFDictionaryRef SecAccessControlGetConstraints(SecAccessControlRef access_control);
 108
 109 /*! Sets dictionary with constraints for access control object.
 110  @param access_control Instance of access control object to set default access group to.
 111  @param constraints Constraint with all constraints.
 112  */
 113 void SecAccessControlSetConstraints(SecAccessControlRef access_control, CFDictionaryRef constraints);
 114
 115 /*! Sets if application passwor is required.
 116 @param require Indicate if password is required or not.
 117 */
 118 void SecAccessControlSetRequirePassword(SecAccessControlRef access_control, bool require);
 119
 120 /*! Gets boolean value if application password is required.*/
 121 bool SecAccessControlGetRequirePassword(SecAccessControlRef access_control);
 122
 123 /*! Sets if acl is bound.
 124  @param bound Indicate if password is bound or not.
 125  */
 126 void SecAccessControlSetBound(SecAccessControlRef access_control, bool bound);
 127
 128 /*! Gets boolean value if acl is bound.*/
 129 bool SecAccessControlIsBound(SecAccessControlRef access_control);
 130
 131 /*! Creates Access control instance from data serialized by SecAccessControlCopyData(). */
 132 SecAccessControlRef SecAccessControlCreateFromData(CFAllocatorRef allocator, CFDataRef data, CFErrorRef *error);
 133
 134 /*! Serializes all access control object into binary data form. */
 135 CFDataRef SecAccessControlCopyData(SecAccessControlRef access_control);
 136
 137 __END_DECLS
 138
 139 #endif // _SECURITY_SECACCESSCONTROLPRIV_H_