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. */
40SecAccessControlRef 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.
43CFTypeRef SecAccessControlGetProtection(SecAccessControlRef access_control);
44bool SecAccessControlSetProtection(SecAccessControlRef access_control, CFTypeRef protection, CFErrorRef *error);
45
46/*! Represents constraint of the operation. */
47typedef CFTypeRef SecAccessConstraintRef;
48
49/*! Creates constraint based on specified policy.
50    @param policy Identification of policy to be used.
51 */
52SecAccessConstraintRef SecAccessConstraintCreatePolicy(CFTypeRef policy, CFErrorRef *error);
53
54/*! Creates constraint which requires passcode verification.
55    @param systemPasscode If true, system passcode (device-specific) will be used, otehrwise application-specific passcode will be used.
56 */
57SecAccessConstraintRef SecAccessConstraintCreatePasscode(bool systemPasscode);
58
59/*! Creates constraint which requires TouchID verification.
60    @param uuid Identification of finger to be verified, or NULL if any enrolled finger can be used for verification.
61 */
62SecAccessConstraintRef SecAccessConstraintCreateTouchID(CFDataRef uuid, CFErrorRef *error);
63
64/*! Creates constraint composed of other constraints.
65    @param numRequired Number of constraints required to be satisfied in order to consider overal constraint satisfied.
66    @param constraints Array of constraints to be chosen from.
67 */
68SecAccessConstraintRef SecAccessConstraintCreateKofN(size_t numRequired, CFArrayRef constraints, CFErrorRef *error);
69
70/*! Sets additional option on the constraint. */
71bool SecAccessConstraintSetOption(SecAccessConstraintRef constraint, CFTypeRef option, CFTypeRef value, CFErrorRef *error);
72
73/*! Adds new constraint for specified operation.
74    @param access_control Instance of access control object to add constraint to.
75    @param operation Operation type.
76    @param constraint Constraint object, created by one of SecAccessControlConstraintCreate() functions or kCFBooleanTrue
77                      meaning that operation will be always allowed.
78 */
79bool SecAccessControlAddConstraintForOperation(SecAccessControlRef access_control, CFTypeRef operation,
80                                               SecAccessConstraintRef constraint, CFErrorRef *error);
81
82/*! Removes constraint for specified operation.  Does nothing if no constraint exist for specified operation.
83    @param access_control Instance of access control object to remove constraint from.
84    @param operation Operation type.
85 */
86void SecAccessControlRemoveConstraintForOperation(SecAccessControlRef access_control, CFTypeRef operation);
87
88/*! Sets or removes default access groups for access control object.
89    @param access_control Instance of access control object to set default access group to.
90    @param access_groups Set of access groups used if constraint does not contain specific access group.
91 */
92void SecAccessControlSetAccessGroups(SecAccessControlRef access_control, CFArrayRef access_groups);
93
94/*! Retrieves set of access group which applies for specified operation.
95    @param access_control Instance of access control object to query.
96    @param operation Operation type.
97    @return Set of access groups valid for specified operation, or NULL if no applicable access group was specified.
98 */
99CFArrayRef SecAccessControlGetAccessGroups(SecAccessControlRef access_control, CFTypeRef operation);
100
101/*! Retrieves dictionary with constraint applicable for specified operation.
102    @param access_control Instance of access control object to query.
103    @param operation Operation type.
104    @return Dictionary or kCFBooleanTrue representing constraint applied for requested operation.  If the operation
105            is not allowed at all, NULL is returned.
106 */
107SecAccessConstraintRef SecAccessControlGetConstraint(SecAccessControlRef access_control, CFTypeRef operation);
108
109/*! Retrieves dictionary with constraints keyed by operations (i.e. the ACL part of access control object).
110    @return Dictionary with all constraints keyed by operation types.  Returns NULL if no operations are constrained.
111 */
112CFDictionaryRef SecAccessControlGetConstraints(SecAccessControlRef access_control);
113
114/*! Sets dictionary with constraints for access control object.
115 @param access_control Instance of access control object to set default access group to.
116 @param constraints Constraint with all constraints.
117 */
118void SecAccessControlSetConstraints(SecAccessControlRef access_control, CFDictionaryRef constraints);
119
120/*! Creates Access control instance from data serialized by SecAccessControlCopyData(). */
121SecAccessControlRef SecAccessControlCreateFromData(CFAllocatorRef allocator, CFDataRef data, CFErrorRef *error);
122
123/*! Serializes all access control object into binary data form. */
124CFDataRef SecAccessControlCopyData(SecAccessControlRef access_control);
125
126__END_DECLS
127
128#endif // _SECURITY_SECACCESSCONTROLPRIV_H_
129