OSX/libsecurity_authorization/lib/AuthorizationDB.h

   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