Security/libsecurity_authorization/lib/AuthSession.h

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