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