SecurityServer/Authorization/AuthSession.h

   1 /*
   2  * Copyright (c) 2000-2001 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 /*
  20  *  AuthSession.h
  21  *  AuthSession - APIs for managing login, authorization, and security Sessions.
  22  */
  23 #if !defined(__AuthSession__)
  24 #define __AuthSession__ 1
  25
  26 #include <Security/Authorization.h>
  27
  28 #if defined(__cplusplus)
  29 extern "C" {
  30 #endif
  31
  32
  33 /*!
  34         @header AuthSession
  35
  36         The Session API provides specialized applications access to Session management and inquiry
  37     functions. This is a specialized API that should not be of interest to most people.
  38
  39     If you do not know what "Session" means in the context of MacOS Authorization and security,
  40     please check with your documentation and come back when you have figured it out - we won't
  41     explain it here.
  42
  43     This API is tentative, preliminary, incomplete, internal, and subject to change.
  44     You have been warned.
  45 */
  46
  47
  48 /*!
  49         @typedef SecuritySessionId
  50         These are externally visible identifiers for authorization sessions.
  51         Different sessions have different identifiers; beyond that, you can't
  52         tell anything from these values.
  53     SessionIds can be compared for equality as you'd expect, but you should be careful
  54         to use attribute bits wherever appropriate. For example, don't rely on there being
  55         "the" graphical login session - some day, we may have more than one...
  56 */
  57 typedef UInt32 SecuritySessionId;
  58
  59
  60 /*!
  61     @enum SecuritySessionId
  62     Here are some special values for SecuritySessionId. You may specify those
  63         on input to SessionAPI functions. They will never be returned from such
  64         functions.
  65 */
  66 enum {
  67     noSecuritySession                      = 0,     /* definitely not a valid SecuritySessionId */
  68     callerSecuritySession                  = -1     /* the Session I (the caller) am in */
  69 };
  70
  71
  72 /*!
  73     @enum SessionAttributeBits
  74     Each Session has a set of attribute bits. You can get those from the
  75         SessionGetInfo API function.
  76  */
  77 typedef UInt32 SessionAttributeBits;
  78
  79 enum {
  80     sessionIsRoot                          = 0x0001, /* is the root session (startup/system programs) */
  81     sessionHasGraphicAccess                = 0x0010, /* graphic subsystem (CoreGraphics et al) available */
  82     sessionHasTTY                          = 0x0020, /* /dev/tty is available */
  83     sessionIsRemote                        = 0x1000, /* session was established over the network */
  84
  85     sessionWasInitialized                  = 0x8000  /* session has been set up by its leader */
  86 };
  87
  88
  89 /*!
  90     @enum SessionCreationFlags
  91     These flags control how a new session is created by SessionCreate.
  92         They have no permanent meaning beyond that.
  93  */
  94 typedef UInt32 SessionCreationFlags;
  95
  96 enum {
  97     sessionKeepCurrentBootstrap             = 0x8000 /* caller has allocated sub-bootstrap (expert use only) */
  98 };
  99
 100
 101 /*!
 102         @enum SessionStatus
 103         Error codes returned by AuthSession API.
 104     Note that the AuthSession APIs can also return Authorization API error codes.
 105 */
 106 enum {
 107     errSessionSuccess                       = 0,      /* all is well */
 108     errSessionInvalidId                     = -60500, /* invalid session id specified */
 109     errSessionInvalidAttributes             = -60501, /* invalid set of requested attribute bits */
 110     errSessionAuthorizationDenied           = -60502, /* you are not allowed to do this */
 111
 112     errSessionInternal                      = errAuthorizationInternal, /* internal error */
 113         errSessionInvalidFlags                  = errAuthorizationInvalidFlags /* invalid flags/options */
 114 };
 115
 116
 117 /*!
 118     @function SessionGetInfo
 119     Obtain information about a session.
 120
 121     @param session (input) The Session you are asking about. Can be one of the
 122         special constants defined above.
 123
 124         @param sessionId (output/optional) The actual SecuritySessionId for the session you asked about.
 125         Will never be one of those constants.
 126
 127     @param attributes (output/optional) Receives the attribute bits for the session.
 128
 129     @result An OSStatus indicating success (noErr) or an error cause.
 130
 131     errSessionInvalidId -60500 Invalid session id specified
 132
 133 */
 134 OSStatus SessionGetInfo(SecuritySessionId session,
 135     SecuritySessionId *sessionId,
 136     SessionAttributeBits *attributes);
 137
 138
 139 /*!
 140     @function SessionCreate
 141     This (very specialized) function creates and/or initializes a security session.
 142         It always sets up the session that the calling process belongs to - you cannot
 143         create a session for someone else.
 144     By default, a new bootstrap subset port is created for the calling process. The process
 145         acquires this new port as its bootstrap port, which all its children will inherit.
 146         If you happen to have created the subset port on your own, you can pass the
 147         sessionKeepCurrentBootstrap flag, and SessionCreate will use it. Note however that
 148         you cannot supersede a prior SessionCreate call that way; only a single SessionCreate
 149         call is allowed for each Session (however made).
 150
 151     @param flags Flags controlling how the session is created.
 152
 153     @param attributes The set of attribute bits to set for the new session.
 154         Not all bits can be set this way.
 155
 156     @result An OSStatus indicating success (noErr) or an error cause.
 157
 158     errSessionInvalidAttributes -60501 Attempt to set invalid attribute bits
 159     errSessionAuthorizationDenied -60502 Attempt to re-initialize a session
 160     errSessionInvalidFlags -60011 Attempt to specify unsupported flag bits
 161
 162 */
 163 OSStatus SessionCreate(SessionCreationFlags flags,
 164     SessionAttributeBits attributes);
 165
 166
 167 #if defined(__cplusplus)
 168 }
 169 #endif
 170
 171 #endif /* ! __AuthSession__ */