SecurityServer/Authorization/AuthSession.h

   1 /*
   2  * Copyright (c) 2000-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 /*
  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         The Security subsystem separates all processes into Security "sessions". Each process is in
  40         exactly one session, and session membership inherits across fork/exec. Sessions form boundaries
  41         for security-related state such as authorizations, keychain lock status, and the like.
  42         Typically, each successful login (whether graphical or through ssh & friends) creates
  43         a separate session. System daemons (started at system startup) belong to the "root session"
  44         which has no user nor graphics access.
  45
  46         Sessions are identified with SecuritySessionIds. A session has a set of attributes
  47         that are set on creation and can be retrieved with SessionGetInfo().
  48
  49         There are similar session concepts in the system, related but not necessarily
  50         completely congruous. In particular, graphics sessions track security sessions
  51         (but only for graphic logins).
  52 */
  53
  54
  55 /*!
  56         @typedef SecuritySessionId
  57         These are externally visible identifiers for authorization sessions.
  58         Different sessions have different identifiers; beyond that, you can't
  59         tell anything from these values.
  60     SessionIds can be compared for equality as you'd expect, but you should be careful
  61         to use attribute bits wherever appropriate.
  62 */
  63 typedef UInt32 SecuritySessionId;
  64
  65
  66 /*!
  67     @enum SecuritySessionId
  68     Here are some special values for SecuritySessionId. You may specify those
  69         on input to SessionAPI functions. They will never be returned from such
  70         functions.
  71 */
  72 enum {
  73     noSecuritySession                      = 0,     /* definitely not a valid SecuritySessionId */
  74     callerSecuritySession = ((SecuritySessionId)-1)     /* the Session I (the caller) am in */
  75 };
  76
  77
  78 /*!
  79     @enum SessionAttributeBits
  80     Each Session has a set of attribute bits. You can get those from the
  81         SessionGetInfo API function.
  82  */
  83 typedef UInt32 SessionAttributeBits;
  84
  85 enum {
  86     sessionIsRoot                          = 0x0001, /* is the root session (startup/system programs) */
  87     sessionHasGraphicAccess                = 0x0010, /* graphic subsystem (CoreGraphics et al) available */
  88     sessionHasTTY                          = 0x0020, /* /dev/tty is available */
  89     sessionIsRemote                        = 0x1000, /* session was established over the network */
  90
  91         // the following bits are used internally; do not try to set them
  92     sessionWasInitialized                  = 0x8000  /* session has been set up by its leader */
  93 };
  94
  95
  96 /*!
  97     @enum SessionCreationFlags
  98     These flags control how a new session is created by SessionCreate.
  99         They have no permanent meaning beyond that.
 100  */
 101 typedef UInt32 SessionCreationFlags;
 102
 103 enum {
 104     sessionKeepCurrentBootstrap             = 0x8000 /* caller has allocated sub-bootstrap (expert use only) */
 105 };
 106
 107
 108 /*!
 109         @enum SessionStatus
 110         Error codes returned by AuthSession API.
 111     Note that the AuthSession APIs can also return Authorization API error codes.
 112 */
 113 enum {
 114     errSessionSuccess                       = 0,      /* all is well */
 115     errSessionInvalidId                     = -60500, /* invalid session id specified */
 116     errSessionInvalidAttributes             = -60501, /* invalid set of requested attribute bits */
 117     errSessionAuthorizationDenied           = -60502, /* you are not allowed to do this */
 118
 119     errSessionInternal                      = errAuthorizationInternal, /* internal error */
 120         errSessionInvalidFlags                  = errAuthorizationInvalidFlags /* invalid flags/options */
 121 };
 122
 123
 124 /*!
 125     @function SessionGetInfo
 126     Obtain information about a session. You can ask about any session whose
 127         identifier you know. Use the callerSecuritySession constant to ask about
 128         your own session (the one your process is in).
 129
 130     @param session (input) The Session you are asking about. Can be one of the
 131         special constants defined above.
 132
 133         @param sessionId (output/optional) The actual SecuritySessionId for the session you asked about.
 134         Will never be one of those constants.
 135
 136     @param attributes (output/optional) Receives the attribute bits for the session.
 137
 138     @result An OSStatus indicating success (noErr) or an error cause.
 139
 140     errSessionInvalidId -60500 Invalid session id specified
 141
 142 */
 143 OSStatus SessionGetInfo(SecuritySessionId session,
 144     SecuritySessionId *sessionId,
 145     SessionAttributeBits *attributes);
 146
 147
 148 /*!
 149     @function SessionCreate
 150     This (very specialized) function creates a security session.
 151         Upon completion, the new session contains the calling process (and none other).
 152         You cannot create a session for someone else, and cannot avoid being placed
 153         into the new session. This is (currently) the only call that changes a process's
 154         session membership.
 155     By default, a new bootstrap subset port is created for the calling process. The process
 156     acquires this new port as its bootstrap port, which all its children will inherit.
 157     If you happen to have created the subset port on your own, you can pass the
 158     sessionKeepCurrentBootstrap flag, and SessionCreate will use it. Note however that
 159     you cannot supersede a prior SessionCreate call that way; only a single SessionCreate
 160     call is allowed for each Session (however made).
 161         This call will discard any security information established for the calling process.
 162         In particular, any authorization handles acquired will become invalid, and so will any
 163         keychain related information. We recommend that you call SessionCreate before
 164         making any other security-related calls that establish rights of any kind, to the
 165         extent this is practical. Also, we strongly recommend that you do not perform
 166         security-related calls in any other threads while calling SessionCreate.
 167
 168     @param flags Flags controlling how the session is created.
 169
 170     @param attributes The set of attribute bits to set for the new session.
 171         Not all bits can be set this way.
 172
 173     @result An OSStatus indicating success (noErr) or an error cause.
 174
 175     errSessionInvalidAttributes -60501 Attempt to set invalid attribute bits
 176     errSessionAuthorizationDenied -60502 Attempt to re-initialize a session
 177     errSessionInvalidFlags -60011 Attempt to specify unsupported flag bits
 178
 179 */
 180 OSStatus SessionCreate(SessionCreationFlags flags,
 181     SessionAttributeBits attributes);
 182
 183
 184 #if defined(__cplusplus)
 185 }
 186 #endif
 187
 188 #endif /* ! __AuthSession__ */