SecurityServer/Authorization/AuthorizationDB.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*
  19  *  AuthorizationDB.h -- APIs for managing the authorization policy database
  20  *  and daemons.
  21  */
  22
  23 #ifndef _SECURITY_AUTHORIZATIONDB_H_
  24 #define _SECURITY_AUTHORIZATIONDB_H_
  25
  26 #include <Security/Authorization.h>
  27 #include <CoreFoundation/CoreFoundation.h>
  28
  29 #if defined(__cplusplus)
  30 extern "C" {
  31 #endif
  32
  33 /*!
  34         @header AuthorizationDB
  35         Version 1.0
  36
  37         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.
  38
  39         AuthorizationRightSet(NULL, "com.ifoo.ifax.send", CFSTR(kRuleIsAdmin), CFSTR("You must authenticate to send a fax."), NULL, NULL)
  40
  41         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.
  42
  43         AuthorizationRightSet(NULL, "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)
  44
  45         add identical rule, but specify additional attributes this time.
  46
  47         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.
  48
  49 */
  50
  51 /*!     @define kRightRule
  52         rule delegation key.  Instead of specifying exact behavior some canned rules
  53    are shipped that may be switched by configurable security.
  54 */
  55 #define kAuthorizationRightRule                                         "rule"
  56
  57 /*! @defined kRuleIsAdmin
  58         canned rule values for use with rule delegation definitions: require user to be an admin.
  59 */
  60 #define kAuthorizationRuleIsAdmin                                       "is-admin"
  61
  62 /*! @defined kRuleAuthenticateAsSessionUser
  63         canned rule value for use with rule delegation definitions: require user to authenticate as the session owner (logged-in user).
  64 */
  65 #define kAuthorizationRuleAuthenticateAsSessionUser     "authenticate-session-user"
  66
  67 /*! @defined kRuleAuthenticateAsAdmin
  68         Canned rule value for use with rule delegation definitions: require user to authenticate as admin.
  69 */
  70 #define kAuthorizationRuleAuthenticateAsAdmin           "authenticate-admin"
  71
  72 /*! @defined kAuthorizationRuleClassAllow
  73         Class that allows anything.
  74 */
  75 #define kAuthorizationRuleClassAllow                    "allow"
  76
  77 /*! @defined kAuthorizationRuleClassDeny
  78         Class that denies anything.
  79 */
  80 #define kAuthorizationRuleClassDeny                             "deny"
  81
  82 /*! @defined kAuthorizationComment
  83     comments for the administrator on what is being customized here;
  84    as opposed to (localized) descriptions presented to the user.
  85 */
  86 #define kAuthorizationComment   "comment"
  87
  88
  89
  90 /*!
  91         @function AuthorizationRightGet
  92
  93         Retrieves a right definition as a dictionary.  There are no restrictions to keep anyone from retrieving these definitions.
  94
  95         @param rightName (input) the rightname (ASCII).  Wildcard rightname definitions are okay.
  96         @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.
  97
  98         @result errAuthorizationSuccess 0 No error.
  99
 100         errAuthorizationDenied -60005 No definition found.
 101
 102 */
 103 OSStatus AuthorizationRightGet(const char *rightName,
 104         CFDictionaryRef *rightDefinition);
 105
 106 /*!
 107         @function AuthorizationRightSet
 108
 109         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.
 110
 111         @param authRef (input) authRef to authorize modifications.
 112         @param rightName (input) the rightname (ASCII).  Wildcard rightnames are not okay.
 113         @param rightDefinition (input) a CFString of the name of a rule to use (delegate) or CFDictionary containing keys defining one.
 114         @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.
 115         @param bundle (input/optional) a bundle to get localizations from if not the main bundle.
 116         @param localeTableName (input/optional) stringtable name to get localizations from.
 117
 118         @result errAuthorizationSuccess 0 added right definition successfully.
 119
 120         errAuthorizationDenied -60005 Unable to create or update right definition.
 121
 122         errAuthorizationCanceled -60006 Authorization was canceled by user.
 123
 124         errAuthorizationInteractionNotAllowed -60007 Interaction was required but not possible.
 125
 126 */
 127 OSStatus AuthorizationRightSet(AuthorizationRef authRef,
 128         const char *rightName,
 129         CFTypeRef rightDefinition,
 130         CFStringRef descriptionKey,
 131         CFBundleRef bundle,
 132         CFStringRef localeTableName);
 133
 134
 135
 136 /*!
 137         @function AuthorizationRightRemove
 138
 139         Request to remove a right from the policy database.
 140
 141         @param authRef (input) authRef, to be used to authorize this action.
 142         @param rightName (input) the rightname (ASCII).  Wildcard rightnames are not okay.
 143
 144 */
 145 OSStatus AuthorizationRightRemove(AuthorizationRef authRef,
 146         const char *rightName);
 147
 148
 149 #if defined(__cplusplus)
 150 }
 151 #endif
 152
 153 #endif /* !_SECURITY_AUTHORIZATIONDB_H_ */
 154