libsecurity_authorization/lib/AuthorizationDB.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, 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 /*!
  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 */
 109 OSStatus 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 */
 133 OSStatus 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 */
 151 OSStatus AuthorizationRightRemove(AuthorizationRef authRef,
 152         const char *rightName);
 153
 154
 155 #if defined(__cplusplus)
 156 }
 157 #endif
 158
 159 #endif /* !_SECURITY_AUTHORIZATIONDB_H_ */
 160