VirtualBox

source: vbox/trunk/include/VBox/VBoxAuth.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.4 KB
Line 
1/** @file
2 * VirtualBox External Authentication Library Interface.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_VBoxAuth_h
37#define VBOX_INCLUDED_VBoxAuth_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42/** @defgroup grp_vboxauth VirtualBox External Authentication Library Interface
43 * @{
44 */
45
46/* The following 2 enums are 32 bits values.*/
47typedef enum AuthResult
48{
49 AuthResultAccessDenied = 0,
50 AuthResultAccessGranted = 1,
51 AuthResultDelegateToGuest = 2,
52 AuthResultSizeHack = 0x7fffffff
53} AuthResult;
54
55typedef enum AuthGuestJudgement
56{
57 AuthGuestNotAsked = 0,
58 AuthGuestAccessDenied = 1,
59 AuthGuestNoJudgement = 2,
60 AuthGuestAccessGranted = 3,
61 AuthGuestNotReacted = 4,
62 AuthGuestSizeHack = 0x7fffffff
63} AuthGuestJudgement;
64
65/** UUID memory representation. Array of 16 bytes.
66 *
67 * @note VirtualBox uses a consistent binary representation of UUIDs on all platforms. For this reason
68 * the integer fields comprising the UUID are stored as little endian values. If you want to pass such
69 * UUIDs to code which assumes that the integer fields are big endian (often also called network byte
70 * order), you need to adjust the contents of the UUID to e.g. achieve the same string representation.
71 *
72 * The required changes are:
73 * - reverse the order of byte 0, 1, 2 and 3
74 * - reverse the order of byte 4 and 5
75 * - reverse the order of byte 6 and 7.
76 *
77 * Using this conversion you will get identical results when converting the binary UUID to the string
78 * representation.
79 */
80typedef unsigned char AUTHUUID[16];
81typedef AUTHUUID *PAUTHUUID;
82
83/** The library entry point calling convention. */
84#ifdef _MSC_VER
85# define AUTHCALL __cdecl
86#elif defined(__GNUC__)
87# define AUTHCALL
88#else
89# error "Unsupported compiler"
90#endif
91
92
93/**
94 * Authentication library entry point.
95 *
96 * @param pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL.
97 * @param guestJudgement Result of the guest authentication.
98 * @param pszUser User name passed in by the client (UTF8).
99 * @param pszPassword Password passed in by the client (UTF8).
100 * @param pszDomain Domain passed in by the client (UTF8).
101 *
102 * Return code:
103 *
104 * @retval AuthAccessDenied Client access has been denied.
105 * @retval AuthAccessGranted Client has the right to use the virtual machine.
106 * @retval AuthDelegateToGuest Guest operating system must
107 * authenticate the client and the
108 * library must be called again with
109 * the result of the guest
110 * authentication.
111 */
112typedef AuthResult AUTHCALL FNAUTHENTRY(PAUTHUUID pUuid,
113 AuthGuestJudgement guestJudgement,
114 const char *pszUser,
115 const char *pszPassword,
116 const char *pszDomain);
117/** Pointer to a FNAUTHENTRY function. */
118typedef FNAUTHENTRY *PFNAUTHENTRY;
119/** @deprecated */
120typedef FNAUTHENTRY AUTHENTRY;
121/** @deprecated */
122typedef PFNAUTHENTRY PAUTHENTRY;
123/** Name of the FNAUTHENTRY entry point. */
124#define AUTHENTRY_NAME "VRDPAuth"
125
126/**
127 * Authentication library entry point version 2.
128 *
129 * @param pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL.
130 * @param guestJudgement Result of the guest authentication.
131 * @param pszUser User name passed in by the client (UTF8).
132 * @param pszPassword Password passed in by the client (UTF8).
133 * @param pszDomain Domain passed in by the client (UTF8).
134 * @param fLogon Boolean flag. Indicates whether the entry point is
135 * called for a client logon or the client disconnect.
136 * @param clientId Server side unique identifier of the client.
137 *
138 * @retval AuthAccessDenied Client access has been denied.
139 * @retval AuthAccessGranted Client has the right to use the virtual machine.
140 * @retval AuthDelegateToGuest Guest operating system must
141 * authenticate the client and the
142 * library must be called again with
143 * the result of the guest authentication.
144 *
145 * @note When @a fLogon is 0, only @a pUuid and @a clientId are valid and the
146 * return code is ignored.
147 */
148typedef AuthResult AUTHCALL FNAUTHENTRY2(PAUTHUUID pUuid,
149 AuthGuestJudgement guestJudgement,
150 const char *pszUser,
151 const char *pszPassword,
152 const char *pszDomain,
153 int fLogon,
154 unsigned clientId);
155/** Pointer to a FNAUTHENTRY2 function. */
156typedef FNAUTHENTRY2 *PFNAUTHENTRY2;
157/** @deprecated */
158typedef FNAUTHENTRY2 AUTHENTRY2;
159/** @deprecated */
160typedef PFNAUTHENTRY2 PAUTHENTRY2;
161/** Name of the FNAUTHENTRY2 entry point. */
162#define AUTHENTRY2_NAME "VRDPAuth2"
163
164/**
165 * Authentication library entry point version 3.
166 *
167 * @param pszCaller The name of the component which calls the library (UTF8).
168 * @param pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL.
169 * @param guestJudgement Result of the guest authentication.
170 * @param pszUser User name passed in by the client (UTF8).
171 * @param pszPassword Password passed in by the client (UTF8).
172 * @param pszDomain Domain passed in by the client (UTF8).
173 * @param fLogon Boolean flag. Indicates whether the entry point is
174 * called for a client logon or the client disconnect.
175 * @param clientId Server side unique identifier of the client.
176 *
177 * @retval AuthResultAccessDenied Client access has been denied.
178 * @retval AuthResultAccessGranted Client has the right to use the
179 * virtual machine.
180 * @retval AuthResultDelegateToGuest Guest operating system must
181 * authenticate the client and the
182 * library must be called again with
183 * the result of the guest
184 * authentication.
185 *
186 * @note When @a fLogon is 0, only @a pszCaller, @a pUuid and @a clientId are
187 * valid and the return code is ignored.
188 */
189typedef AuthResult AUTHCALL FNAUTHENTRY3(const char *pszCaller,
190 PAUTHUUID pUuid,
191 AuthGuestJudgement guestJudgement,
192 const char *pszUser,
193 const char *pszPassword,
194 const char *pszDomain,
195 int fLogon,
196 unsigned clientId);
197/** Pointer to a FNAUTHENTRY3 function. */
198typedef FNAUTHENTRY3 *PFNAUTHENTRY3;
199/** @deprecated */
200typedef FNAUTHENTRY3 AUTHENTRY3;
201/** @deprecated */
202typedef PFNAUTHENTRY3 PAUTHENTRY3;
203
204/** Name of the FNAUTHENTRY3 entry point. */
205#define AUTHENTRY3_NAME "AuthEntry"
206
207/** @} */
208
209#endif /* !VBOX_INCLUDED_VBoxAuth_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette