You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
193 lines
7.7 KiB
193 lines
7.7 KiB
9 years ago
|
/*
|
||
|
|
* Copyright (c) 2000-2003,2011,2013-2014 Apple Inc. All Rights Reserved.
|
||
|
|
*
|
||
|
|
* @APPLE_LICENSE_HEADER_START@
|
||
|
|
*
|
||
|
|
* This file contains Original Code and/or Modifications of Original Code
|
||
|
|
* as defined in and that are subject to the Apple Public Source License
|
||
|
|
* Version 2.0 (the 'License'). You may not use this file except in
|
||
|
|
* compliance with the License. Please obtain a copy of the License at
|
||
|
|
* http://www.opensource.apple.com/apsl/ and read it before using this
|
||
|
|
* file.
|
||
|
|
*
|
||
|
|
* The Original Code and all software distributed under the License are
|
||
|
|
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
|
||
|
|
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
|
||
|
|
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
|
||
|
|
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
|
||
|
|
* Please see the License for the specific language governing rights and
|
||
|
|
* limitations under the License.
|
||
|
|
*
|
||
|
|
* @APPLE_LICENSE_HEADER_END@
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* AuthSession.h
|
||
|
|
* AuthSession - APIs for managing login, authorization, and security Sessions.
|
||
|
|
*/
|
||
|
|
#if !defined(__AuthSession__)
|
||
|
|
#define __AuthSession__ 1
|
||
|
|
|
||
|
|
#include <Security/Authorization.h>
|
||
|
|
|
||
|
|
#if defined(__cplusplus)
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
CF_ASSUME_NONNULL_BEGIN
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@header AuthSession
|
||
|
|
|
||
|
|
The Session API provides specialized applications access to Session management and inquiry
|
||
|
|
functions. This is a specialized API that should not be of interest to most people.
|
||
|
|
|
||
|
|
The Security subsystem separates all processes into Security "sessions". Each process is in
|
||
|
|
exactly one session, and session membership inherits across fork/exec. Sessions form boundaries
|
||
|
|
for security-related state such as authorizations, keychain lock status, and the like.
|
||
|
|
Typically, each successful login (whether graphical or through ssh & friends) creates
|
||
|
|
a separate session. System daemons (started at system startup) belong to the "root session"
|
||
|
|
which has no user nor graphics access.
|
||
|
|
|
||
|
|
Sessions are identified with SecuritySessionIds. A session has a set of attributes
|
||
|
|
that are set on creation and can be retrieved with SessionGetInfo().
|
||
|
|
|
||
|
|
There are similar session concepts in the system, related but not necessarily
|
||
|
|
completely congruous. In particular, graphics sessions track security sessions
|
||
|
|
(but only for graphic logins).
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@typedef SecuritySessionId
|
||
|
|
These are externally visible identifiers for authorization sessions.
|
||
|
|
Different sessions have different identifiers; beyond that, you can't
|
||
|
|
tell anything from these values.
|
||
|
|
SessionIds can be compared for equality as you'd expect, but you should be careful
|
||
|
|
to use attribute bits wherever appropriate.
|
||
|
|
*/
|
||
|
|
typedef UInt32 SecuritySessionId;
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum SecuritySessionId
|
||
|
|
Here are some special values for SecuritySessionId. You may specify those
|
||
|
|
on input to SessionAPI functions. They will never be returned from such
|
||
|
|
functions.
|
||
|
|
|
||
|
|
Note: -2 is reserved (see 4487137).
|
||
|
|
*/
|
||
|
|
CF_ENUM(SecuritySessionId) {
|
||
|
|
noSecuritySession = 0, /* definitely not a valid SecuritySessionId */
|
||
|
|
callerSecuritySession = ((SecuritySessionId)-1) /* the Session I (the caller) am in */
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum SessionAttributeBits
|
||
|
|
Each Session has a set of attribute bits. You can get those from the
|
||
|
|
SessionGetInfo API function.
|
||
|
|
*/
|
||
|
|
typedef CF_OPTIONS(UInt32, SessionAttributeBits) {
|
||
|
|
sessionIsRoot = 0x0001, /* is the root session (startup/system programs) */
|
||
|
|
sessionHasGraphicAccess = 0x0010, /* graphic subsystem (CoreGraphics et al) available */
|
||
|
|
sessionHasTTY = 0x0020, /* /dev/tty is available */
|
||
|
|
sessionIsRemote = 0x1000, /* session was established over the network */
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum SessionCreationFlags
|
||
|
|
These flags control how a new session is created by SessionCreate.
|
||
|
|
They have no permanent meaning beyond that.
|
||
|
|
*/
|
||
|
|
typedef CF_OPTIONS(UInt32, SessionCreationFlags) {
|
||
|
|
sessionKeepCurrentBootstrap = 0x8000 /* caller has allocated sub-bootstrap (expert use only) */
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum SessionStatus
|
||
|
|
Error codes returned by AuthSession API.
|
||
|
|
Note that the AuthSession APIs can also return Authorization API error codes.
|
||
|
|
*/
|
||
|
|
CF_ENUM(OSStatus) {
|
||
|
|
errSessionSuccess = 0, /* all is well */
|
||
|
|
errSessionInvalidId = -60500, /* invalid session id specified */
|
||
|
|
errSessionInvalidAttributes = -60501, /* invalid set of requested attribute bits */
|
||
|
|
errSessionAuthorizationDenied = -60502, /* you are not allowed to do this */
|
||
|
|
errSessionValueNotSet = -60503, /* the session attribute you requested has not been set */
|
||
|
|
|
||
|
|
errSessionInternal = errAuthorizationInternal, /* internal error */
|
||
|
|
errSessionInvalidFlags = errAuthorizationInvalidFlags /* invalid flags/options */
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SessionGetInfo
|
||
|
|
Obtain information about a session. You can ask about any session whose
|
||
|
|
identifier you know. Use the callerSecuritySession constant to ask about
|
||
|
|
your own session (the one your process is in).
|
||
|
|
|
||
|
|
@param session (input) The Session you are asking about. Can be one of the
|
||
|
|
special constants defined above.
|
||
|
|
|
||
|
|
@param sessionId (output/optional) The actual SecuritySessionId for the session you asked about.
|
||
|
|
Will never be one of those constants.
|
||
|
|
|
||
|
|
@param attributes (output/optional) Receives the attribute bits for the session.
|
||
|
|
|
||
|
|
@result An OSStatus indicating success (errSecSuccess) or an error cause.
|
||
|
|
|
||
|
|
errSessionInvalidId -60500 Invalid session id specified
|
||
|
|
|
||
|
|
*/
|
||
|
|
OSStatus SessionGetInfo(SecuritySessionId session,
|
||
|
|
SecuritySessionId * __nullable sessionId,
|
||
|
|
SessionAttributeBits * __nullable attributes);
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SessionCreate
|
||
|
|
This (very specialized) function creates a security session.
|
||
|
|
Upon completion, the new session contains the calling process (and none other).
|
||
|
|
You cannot create a session for someone else, and cannot avoid being placed
|
||
|
|
into the new session. This is (currently) the only call that changes a process's
|
||
|
|
session membership.
|
||
|
|
By default, a new bootstrap subset port is created for the calling process. The process
|
||
|
|
acquires this new port as its bootstrap port, which all its children will inherit.
|
||
|
|
If you happen to have created the subset port on your own, you can pass the
|
||
|
|
sessionKeepCurrentBootstrap flag, and SessionCreate will use it. Note however that
|
||
|
|
you cannot supersede a prior SessionCreate call that way; only a single SessionCreate
|
||
|
|
call is allowed for each Session (however made).
|
||
|
|
This call will discard any security information established for the calling process.
|
||
|
|
In particular, any authorization handles acquired will become invalid, and so will any
|
||
|
|
keychain related information. We recommend that you call SessionCreate before
|
||
|
|
making any other security-related calls that establish rights of any kind, to the
|
||
|
|
extent this is practical. Also, we strongly recommend that you do not perform
|
||
|
|
security-related calls in any other threads while calling SessionCreate.
|
||
|
|
|
||
|
|
@param flags Flags controlling how the session is created.
|
||
|
|
|
||
|
|
@param attributes The set of attribute bits to set for the new session.
|
||
|
|
Not all bits can be set this way.
|
||
|
|
|
||
|
|
@result An OSStatus indicating success (errSecSuccess) or an error cause.
|
||
|
|
|
||
|
|
errSessionInvalidAttributes -60501 Attempt to set invalid attribute bits
|
||
|
|
errSessionAuthorizationDenied -60502 Attempt to re-initialize a session
|
||
|
|
errSessionInvalidFlags -60011 Attempt to specify unsupported flag bits
|
||
|
|
|
||
|
|
*/
|
||
|
|
OSStatus SessionCreate(SessionCreationFlags flags,
|
||
|
|
SessionAttributeBits attributes);
|
||
|
|
|
||
|
|
CF_ASSUME_NONNULL_END
|
||
|
|
|
||
|
|
#if defined(__cplusplus)
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* ! __AuthSession__ */
|