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)
 36  extern "C" {
 37  #endif
 38  
 39  CF_ASSUME_NONNULL_BEGIN
 40  
 41  /*!
 42  	@header AuthorizationDB
 43  	Version 1.0
 44  
 45  	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.
 46  	
 47  	AuthorizationRightSet(authRef, "com.ifoo.ifax.send", CFSTR(kRuleIsAdmin), CFSTR("You must authenticate to send a fax."), NULL, NULL)
 48  
 49  	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.
 50  	
 51  	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)
 52  
 53  	add identical rule, but specify additional attributes this time.
 54  
 55  	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().
 56  
 57  */
 58  
 59  /*!	@define kRightRule
 60  	rule delegation key.  Instead of specifying exact behavior some canned rules
 61     are shipped that may be switched by configurable security.
 62  */
 63  #define kAuthorizationRightRule						"rule"
 64  
 65  /*! @defined kRuleIsAdmin
 66  	canned rule values for use with rule delegation definitions: require user to be an admin.
 67  */
 68  #define kAuthorizationRuleIsAdmin					"is-admin"
 69  
 70  /*! @defined kRuleAuthenticateAsSessionUser
 71  	canned rule value for use with rule delegation definitions: require user to authenticate as the session owner (logged-in user).
 72  */
 73  #define kAuthorizationRuleAuthenticateAsSessionUser	"authenticate-session-owner"
 74  
 75  /*! @defined kRuleAuthenticateAsAdmin
 76  	Canned rule value for use with rule delegation definitions: require user to authenticate as admin.
 77  */
 78  #define kAuthorizationRuleAuthenticateAsAdmin		"authenticate-admin"
 79  
 80  /*! @defined kAuthorizationRuleClassAllow
 81  	Class that allows anything.
 82  */
 83  #define kAuthorizationRuleClassAllow			"allow"
 84  
 85  /*! @defined kAuthorizationRuleClassDeny
 86  	Class that denies anything. 
 87  */
 88  #define kAuthorizationRuleClassDeny				"deny"
 89  
 90  /*! @defined kAuthorizationComment
 91      comments for the administrator on what is being customized here;
 92     as opposed to (localized) descriptions presented to the user.
 93  */
 94  #define kAuthorizationComment	"comment"
 95  
 96  
 97  
 98  /*!
 99  	@function AuthorizationRightGet 
100  	
101  	Retrieves a right definition as a dictionary.  There are no restrictions to keep anyone from retrieving these definitions.  
102  
103  	@param rightName (input) the rightname (ASCII).  Wildcard rightname definitions are okay.
104  	@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.
105  
106  	@result errAuthorizationSuccess 0 No error.
107  
108  	errAuthorizationDenied -60005 No definition found.
109  
110  */
111  OSStatus AuthorizationRightGet(const char *rightName,
112  	CFDictionaryRef * __nullable CF_RETURNS_RETAINED rightDefinition);
113  
114  /*!
115  	@function AuthorizationRightSet
116  	
117  	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.
118  
119  	@param authRef (input) authRef to authorize modifications.
120  	@param rightName (input) the rightname (ASCII).  Wildcard rightnames are not okay.
121  	@param rightDefinition (input) a CFString of the name of a rule to use (delegate) or CFDictionary containing keys defining one.
122  	@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.
123  	@param bundle (input/optional) a bundle to get localizations from if not the main bundle.
124  	@param localeTableName (input/optional) stringtable name to get localizations from.
125  	
126  	@result errAuthorizationSuccess 0 added right definition successfully.
127  
128  	errAuthorizationDenied -60005 Unable to create or update right definition.
129  
130  	errAuthorizationCanceled -60006 Authorization was canceled by user.
131  
132  	errAuthorizationInteractionNotAllowed -60007 Interaction was required but not possible.
133  
134  */
135  OSStatus AuthorizationRightSet(AuthorizationRef authRef,
136  	const char *rightName,
137  	CFTypeRef rightDefinition,
138  	CFStringRef __nullable descriptionKey,
139  	CFBundleRef __nullable bundle,
140  	CFStringRef __nullable localeTableName);
141  
142  
143  
144  /*!
145  	@function AuthorizationRightRemove
146  
147  	Request to remove a right from the policy database.
148  
149  	@param authRef (input) authRef, to be used to authorize this action.
150  	@param rightName (input) the rightname (ASCII).  Wildcard rightnames are not okay.
151  	
152  */
153  OSStatus AuthorizationRightRemove(AuthorizationRef authRef,
154  	const char *rightName);
155  
156  CF_ASSUME_NONNULL_END
157  
158  #if defined(__cplusplus)
159  }
160  #endif
161  
162  #endif /* !_SECURITY_AUTHORIZATIONDB_H_ */
163