1/*
2 * Copyright (c) 2003,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 *  AuthorizationDB.h -- APIs for managing the authorization policy database
26 *  and daemons.
27 */
28
29#ifndef _SECURITY_AUTHORIZATIONDB_H_
30#define _SECURITY_AUTHORIZATIONDB_H_
31
32#include <Security/Authorization.h>
33#include <CoreFoundation/CoreFoundation.h>
34
35#if defined(__cplusplus)
36extern "C" {
37#endif
38
39/*!
40	@header AuthorizationDB
41	Version 1.0
42
43	This API allows for any programs to get, modify, delete and add new right definitions to the policy database.  Meta-rights specify whether and what authorization is required to make these modifications.
44
45	AuthorizationRightSet(authRef, "com.ifoo.ifax.send", CFSTR(kRuleIsAdmin), CFSTR("You must authenticate to send a fax."), NULL, NULL)
46
47	add a rule for letting admins send faxes using a canned rule, delegating to a pre-specified rule that authorizes everyone who is an admin.
48
49	AuthorizationRightSet(authRef, "com.ifoo.ifax.send", [[CFSTR(kRightRule), CFSTR(kRuleIsAdmin)], [CFSTR(kRightComment), CFSTR("authorizes sending of 1 fax message")]], CFSTR("Authorize sending of a fax"), NULL, NULL)
50
51	add identical rule, but specify additional attributes this time.
52
53	Keep in mind while specifying a comment to be specific about what you need to authorize for (1 fax), in terms of a general message for user.  The means of proof required for kRuleIsAdmin (enter username/password for example) should not be included here, since it could be configured differently.  Also note that the "authRef" variable used in each of the above examples must be a vaild AuthorizationRef obtained from AuthorizationCreate().
54
55*/
56
57/*!	@define kRightRule
58	rule delegation key.  Instead of specifying exact behavior some canned rules
59   are shipped that may be switched by configurable security.
60*/
61#define kAuthorizationRightRule						"rule"
62
63/*! @defined kRuleIsAdmin
64	canned rule values for use with rule delegation definitions: require user to be an admin.
65*/
66#define kAuthorizationRuleIsAdmin					"is-admin"
67
68/*! @defined kRuleAuthenticateAsSessionUser
69	canned rule value for use with rule delegation definitions: require user to authenticate as the session owner (logged-in user).
70*/
71#define kAuthorizationRuleAuthenticateAsSessionUser	"authenticate-session-owner"
72
73/*! @defined kRuleAuthenticateAsAdmin
74	Canned rule value for use with rule delegation definitions: require user to authenticate as admin.
75*/
76#define kAuthorizationRuleAuthenticateAsAdmin		"authenticate-admin"
77
78/*! @defined kAuthorizationRuleClassAllow
79	Class that allows anything.
80*/
81#define kAuthorizationRuleClassAllow			"allow"
82
83/*! @defined kAuthorizationRuleClassDeny
84	Class that denies anything.
85*/
86#define kAuthorizationRuleClassDeny				"deny"
87
88/*! @defined kAuthorizationComment
89    comments for the administrator on what is being customized here;
90   as opposed to (localized) descriptions presented to the user.
91*/
92#define kAuthorizationComment	"comment"
93
94
95
96/*!
97	@function AuthorizationRightGet
98
99	Retrieves a right definition as a dictionary.  There are no restrictions to keep anyone from retrieving these definitions.
100
101	@param rightName (input) the rightname (ASCII).  Wildcard rightname definitions are okay.
102	@param rightDefinition (output/optional) the dictionary with all keys defining the right.  See documented keys.  Passing in NULL will just check if there is a definition.  The caller is responsible for releasing the returned dictionary.
103
104	@result errAuthorizationSuccess 0 No error.
105
106	errAuthorizationDenied -60005 No definition found.
107
108*/
109OSStatus AuthorizationRightGet(const char *rightName,
110	CFDictionaryRef *rightDefinition);
111
112/*!
113	@function AuthorizationRightSet
114
115	Create or update a right entry.  Only normal rights can be registered (wildcard rights are denied); wildcard rights are considered to be put in by an administrator putting together a site configuration.
116
117	@param authRef (input) authRef to authorize modifications.
118	@param rightName (input) the rightname (ASCII).  Wildcard rightnames are not okay.
119	@param rightDefinition (input) a CFString of the name of a rule to use (delegate) or CFDictionary containing keys defining one.
120	@param descriptionKey (input/optional) a CFString to use as a key for looking up localized descriptions.  If no localization is found this will be the description itself.
121	@param bundle (input/optional) a bundle to get localizations from if not the main bundle.
122	@param localeTableName (input/optional) stringtable name to get localizations from.
123
124	@result errAuthorizationSuccess 0 added right definition successfully.
125
126	errAuthorizationDenied -60005 Unable to create or update right definition.
127
128	errAuthorizationCanceled -60006 Authorization was canceled by user.
129
130	errAuthorizationInteractionNotAllowed -60007 Interaction was required but not possible.
131
132*/
133OSStatus AuthorizationRightSet(AuthorizationRef authRef,
134	const char *rightName,
135	CFTypeRef rightDefinition,
136	CFStringRef descriptionKey,
137	CFBundleRef bundle,
138	CFStringRef localeTableName);
139
140
141
142/*!
143	@function AuthorizationRightRemove
144
145	Request to remove a right from the policy database.
146
147	@param authRef (input) authRef, to be used to authorize this action.
148	@param rightName (input) the rightname (ASCII).  Wildcard rightnames are not okay.
149
150*/
151OSStatus AuthorizationRightRemove(AuthorizationRef authRef,
152	const char *rightName);
153
154
155#if defined(__cplusplus)
156}
157#endif
158
159#endif /* !_SECURITY_AUTHORIZATIONDB_H_ */
160
161