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) 35extern "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*/ 69typedef 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*/ 80enum { 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 */ 91typedef UInt32 SessionAttributeBits; 92 93enum { 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 */ 106typedef UInt32 SessionCreationFlags; 107 108enum { 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*/ 118enum { 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*/ 149OSStatus 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*/ 186OSStatus SessionCreate(SessionCreationFlags flags, 187 SessionAttributeBits attributes); 188 189 190#if defined(__cplusplus) 191} 192#endif 193 194#endif /* ! __AuthSession__ */ 195