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