~ubuntu-branches/ubuntu/saucy/xorg-docs/saucy

<para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.</para>

</legalnotice>

<para>The X Access Control Extension (XACE) is a set of generic "hooks" that can be used by other X extensions to perform access checks. The goal of XACE is to prevent clutter in the core dix/os code by providing a common mechanism for doing these sorts of checks. The concept is identical to the Linux Security Module (LSM) in the Linux Kernel.</para>

<para>XACE is a generalization of the "Security" extension, which provides a simple on/off trust model, with untrusted windows being restricted in certain areas. Most of XACE consists simply of replacing the Security-specific checks in the dix/os layer with generic callback lists. However, the framework is flexible enough to allow for hooks to be added or deprecated in the future.</para>

<para>This paper describes the implementation of XACE, changes to the core server DIX and OS layers that have been made or are being considered, and each of the security hooks that XACE offers at the current time and their function. It is expected that changes to XACE be documented here. Please notify the authors of this document of any changes to XACE so that they may be properly documented.</para>

</abstract>

</articleinfo>

<title>Introduction</title>

<title>Prerequisites</title>

<para>This document is targeted to programmers who are writing security extensions for X. It is assumed that the reader is familiar with the C programming language. It is assumed that the reader understands the general workings of the X protocol and X server. It is highly recommended that the reader review the specifications for the SECURITY and APPGROUP extensions. The relevant documents are all available in the X.Org documentation package.</para>

</section>

<title>Purpose</title>

<para>XACE makes it easier to implement new security models for X by providing a set of pluggable hooks that extension writers can use. The idea is to provide an abstraction layer between security extensions and the core DIX/OS code of the X server. This prevents security extensions writers from having to understand the inner workings of the X server and it prevents X server maintainers from having to deal with multiple security subsystems, each with its own intrusive code.</para>

<para>For example, consider the X.Org X server's resource subsystem, which is used to track different types of server objects using ID numbers. The act of looking up an object by its ID number is a security-relevant operation which security extension writers would likely wish to control. For one or two security extensions it may be acceptable to simply insert the extension's code directly into the resource manager code, bracketed by <literal>ifdef</literal>'s. However for more extensions this approach leads to a tangle of code, particularly when results need to be logically combined, as in <literal>if</literal> statement conditions. Additionally, different extension writers might place their resource checking code in different places in the server, leading to difficulty in tracking down where exactly a particular lookup operation is being blocked. Finally, this approach may lead to unexpected interactions between the code of different extensions, since there is no collaboration between extension writers.</para>

<para>The solution employed by the X Access Control Extension is to place hooks (calls into XACE) at security-relevant places, such as the resource subsystem mentioned above. Other extensions, typically in their initialization routines, can register callback functions on these hooks. When the hook is called from the server code, each callback function registered on it is called in turn. The callback function is provided with necessary arguments needed to make a security decision, including a return value argument which can be set to indicate the result. XACE itself does not make security decisions, or even know or care how such decisions are made. XACE merely enforces the result of the decision, such as by returning a <errorname>BadAccess</errorname> error to the requesting client.</para>

<para>This separation between the decision-making logic and the enforcement logic is advantageous because it allows a great variety of security models to be developed without resorting to intrusive modifications to the core systems being secured. The challenge is to ensure that the hook framework itself provides hooks everywhere they need to be provided. Once created, however, a hook can be used by everyone, leading to less duplication of effort.</para>

</section>

<title>Prior Work</title>

<title>Security Extension</title>

<para>XACE is primarily based on the SECURITY extension. This extension introduced the concept of "trusted" and "untrusted" client connections, with the trust level established by the authorization token used in the initial client connection. Untrusted clients are restricted in several areas, notably in the use of background "None" windows, access to server resources owned by trusted clients, and certain keyboard input operations. Server extensions are also declared "trusted" or "untrusted," with only untrusted extensions being visible to untrusted client connections.</para>

<para>The primary limitation of the SECURITY extension is a lack of granularity. The trust level of client connections is set at connection time and is not changed. Creating untrusted clients is cumbersome since untrusted authorizations must be generated dynamically (they cannot be specified in the authorization file used by the server at startup time), and the default trusted behavior is not restricted in any way. The author of the SECURITY extension did anticipate the need for flexibility in some areas, but the XACE modifications introduce a much broader level of generalization.</para>

<para>The benefit of the SECURITY extension is that its authors already had identified the proper places in the core X server code to place their trust level checks. Thus, the only thing that needed to be done for XACE was to swap out these checks for more generic XACE hooks. The SECURITY authors also introduced several features into the core server code, such as the "Security" versions of the resource lookup functions, and the custom ProcVectors used to dispatch client requests.</para>

<para>With the introduction of XACE, the SECURITY extension has been rewritten to sit on top of XACE, thus maintaining backwards compatibility.</para>

</section>

<title>Solaris Trusted Extensions</title>

<para>Trusted Extensions for Solaris has an X extension (Xtsol) which adds security functionality. Some of the XACE hooks in the current set were derived from security checks made by the Xtsol code. In other places, where the Xtsol and SECURITY extensions both have checks, a single XACE hook replaces both.</para>

</section>

<title>Linux Security Modules</title>

<para>XACE is influenced by the Linux Security Modules project, which provides a similar framework of security hooks for the Linux kernel.</para>

</section>

<title>Future Work</title>

<title>Security Hooks</title>

<para>It is anticipated that the set of security hooks provided by XACE will change with time. Some of the current hooks provide legacy functionality for the SECURITY extension and may become deprecated. More hooks will likely be added as well, as more portions of the X server are subjected to security analysis. Existing hooks may be added in more places in the code, particularly protocol extensions. Currently, the only method XACE provides for restricting access to protocol extensions is to deny access to them entirely.</para>

<para>It should be noted that XACE includes hooks in the protocol dispatch table, which allow a security extension to examine any incoming protocol request (core or extension) and block the request before it is handled by the server (resulting in a <literal>BadAccess</literal> error). This functionality can be used as a stopgap measure for security checks that are not supported by the other XACE hooks. The end goal, however, is to have hooks integrated into the server proper, as the SECURITY extension has done.</para>

<para>In the future, it may be worthwhile to integrate XACE directly into the X server code, removing its status as an "extension" (XACE defines no new protocol). This would eliminate the <literal>ifdef</literal> directives that bracket the XACE hooks, and would allow for further integration with the surrounding code. It would also avoid the need to use the extension loader to initialize XACE. The use of modern coding techniques such as static inlining could also be used to improve performance in the hook mechanism.</para>

</section>

<title>X Authentication</title>

<para>The X server supports several authentication methods. Currently, they are implemented directly in the OS layer of the X server. However, with new improvements to the Pluggable Authentication Modules (PAM) library, it may be possible to move these authentication methods out of the server, implementing each one as a PAM module. This would separate security-specific code from the X server, as well allow the authentication code in the OS layer to be cleaned up significantly. However, the author has not studied the problem in great detail, so it's too early to tell whether this idea is workable.</para>

<para>Another area where the X authentication code could use some cleanup is the SECURITY extension's "Query Security" authentication pseudo-method. This method is used to determine whether or not an X server supports certain "site policies," identified via strings. This method can also be used to assert requirements about extension security. This part of the SECURITY extension was not refactored along with the rest of the extension as part of the XACE work. As part of the PAM project described above, it would be beneficial if this authentication method could be moved out to a PAM module or simply dropped. Doing this would allow the SECURITY extension to be loaded as a module instead of being built-in, since the auth code is the only remaining part of that extension that needs to be compiled in.</para>

</section>

<title>Core X Server</title>

<para>There are some minor improvements that could be made to the core X server itself outside of XACE. As will be discussed, security extension writers are expected to use the <literal>devPrivates</literal> mechanism to store security state with various server object. This mechanism is currently duplicated for each structure type that supports it; it may be possible to use macros to generate the functions for each supported structure type, at least reducing the code size. This would also make it easier to support more structures; only a new structure field would be required along with slight changes to the code that allocates the structure. Extending <literal>devPrivates</literal> support to other structures, or even generic resources, would be beneficial for security extension writers. The feasibility of doing this generalization is currently being investigated by the author. In addition, initialization and teardown callbacks are needed as described in <xref linkend="storing_dev"/>; support for them is currently spotty.</para>

<para>The module loader should be looked at to see if the extension loading sequence could be improved. There are comments to that effect in the module loading code, which read (paraphrasing): "Please make extension loading not suck." Right now, there are two intialization functions that extensions can use: a "setup" function which is called first, before any <type>ExtensionEntry</type> structures are created, and an "init" function which is called when the structure is created. This is OK, but the order in which the setup functions are called is odd: loadable extensions are called first, before built-in extensions. The calls also happen from totally different places in the code, with loadables being set up from the <function>InitOutput</function> function which is nonintuitive. Finally, the extension support code has large, cumbersome lists of extensions bracketed by <literal>ifdef</literal>'s, along with boolean variables meant to be used for dynamic configuration of extensions which are in practice unused. Perhaps autotools could be used to build the list of extensions to load, instead of having a hard-coded list. The author is investigating possibilities for work in this area.</para>

</section>

<title>Usage</title>

<title>Storing Security State</title>

<para>The first thing you, the security extension writer, should decide on is the state information that your extension will be storing and how it will be stored. XACE itself does not provide any mechanism for storing state. Two methods of storing security state are discussed here.</para>

<title>Global Variables</title>

<para>One method of storing state is simply to use global variables in the extension code. Tables can be kept corresponding to internal server structures, updated to stay synchronized with the structures themselves.</para>

</section>

<title>Device Privates</title>

<para>Another method of storing state is to attach your extension's security data directly to the server structures. This method is possible via the <literal>devPrivates</literal> mechanism provide by the DIX layer. However, only the server structures listed in <xref linkend="storing_tab"/> currently support this mechanism; work is in progress to add other structure types (see <xref linkend="future_core"/>).</para>

100

<title>Current <literal>devPrivates</literal> support in DIX.</title>

101

102

<thead>

103

<row>

104

<entry>Structure</entry>

105

<entry>Supports Pre-Allocation</entry>

106

<entry>Cleared to Zero</entry>

107

<entry>Callbacks Available</entry>

108

</row>

109

</thead>

110

<tbody>

111

<row>

112

<entry><type>ClientRec</type></entry>

113

114

115

116

</row>

117

<row>

118

<entry><type>ExtensionEntry</type></entry>

119

120

121

122

</row>

123

<row>

124

<entry><type>ScreenRec</type></entry>

125

126

127

128

</row>

129

<row>

130

<entry><type>WindowRec</type></entry>

131

132

133

134

</row>

135

<row>

136

<entry><type>GCRec</type></entry>

137

138

139

140

</row>

141

<row>

142

<entry><type>PixmapRec</type></entry>

143

144

145

146

</row>

147

<row>

148

<entry><type>ColormapRec</type></entry>

149

150

151

152

</row>

153

<row>

154

<entry><type>DeviceIntRec</type></entry>

155

156

157

158

</row>

159

</tbody>

160

</tgroup>

161

</table>

162

<para>For an example of how to use <literal>devPrivates</literal>, refer to the SECURITY extension source code in <filename>Xext/security.c</filename> which makes use of them for storing state in the <type>ClientRec</type> and <type>ExtensionEntry</type> structures. Basically, your extension must register for space in each structure type. This is done slightly differently depending on the structure; see the SECURITY example as well as <filename>dix/privates.c</filename>, which contains the implementation. All structures provide an instance of <type>DevUnion</type>, indexed by a number that is returned to you in the <structfield>devPrivates</structfield> array member of the structure. This union can be used as a long value or a pointer. Some structures allow a byte count to be provided at registration time, which will be automatically allocated and returned through the pointer member of the union.</para>

163

<para>The registration must be done in the extension setup routine for the <type>ExtensionEntry</type> structure only; for all other structures it can be performed in the extension init routine. See the SECURITY code for registration examples.</para>

164

<para>When a structure having <literal>devPrivates</literal> support is allocated, the space requested by all registrants is allocated along with it. In some cases, the newly allocated memory is cleared to zero. Work is underway to make sure that all supported structures have the memory cleared; the ones that currently do are listed in <xref linkend="storing_tab"/>. However, your security extension may need to take further action to initialize the newly created data. How exactly this is done depends on the structure. Again, some structures don't currently provide a way for your extension to be called immediately when a structure instance is created. The <type>ClientRec</type> and <type>WindowRec</type> structures do have support for this, as indicated in <xref linkend="storing_tab"/>. Examine the SECURITY source for more information. The eventual goal is to have a callback, XACE or otherwise, notifying when each supported structure is initialized.</para>

165

<para>The same applies to freeing memory or otherwise tearing down your security state when an object is being destroyed. Some structures don't currently have callbacks associated with this event which would allow a security extension to gain control. The <type>ClientRec</type> structure does have support. The eventual goal is to provide a mechanism for this purpose.</para>

166

<note><para>Memory allocated through the <literal>devPrivates</literal> mechanism itself will be freed automatically.</para></note>

167

</section>

168

</section>

169

170

171

<title>Using Hooks</title>

172

173

174

<title>Overview</title>

175

<para>XACE has two header files that security extension code may need to include. Include <filename>Xext/xacestr.h</filename> if you need the structure definitions for the XACE hooks. Otherwise, include <filename>Xext/xace.h</filename>, which contains everything else including constants and function declarations.</para>

176

<para>XACE hooks use the standard X server callback mechanism. Your security extension's callback functions should all use the following prototype:

177

178

179

<funcprototype><funcdef>void <function>MyCallback</function></funcdef>

180

181

<parameter>CallbackListPtr *pcbl</parameter>

182

<parameter>pointer userdata</parameter>

183

<parameter>pointer calldata</parameter>

184

</paramdef>

185

</funcprototype>

186

</funcsynopsis>

187

</blockquote>

188

When the callback is called, <parameter>pcbl</parameter> points to the callback list itself. The X callback mechanism allows the list to be manipulated in various ways, but XACE callbacks should not do this. Remember that other security extensions may be registered on the same hook. <parameter>userdata</parameter> is set to the data argument that was passed to <function>XaceRegisterCallback</function> at registration time; this can be used by your extension to pass data into the callback. <parameter>calldata</parameter> points to a value or structure which is specific to each XACE hook. These are discussed in the documentation for each specific hook, below. Your extension must cast this argument to the appropriate pointer type.</para>

189

<para>To register a callback on a given hook, use <function>XaceRegisterCallback</function>:

190

191

192

<funcprototype><funcdef>Bool <function>XaceRegisterCallback</function></funcdef>

193

194

195

<parameter>CallbackProcPtr callback</parameter>

196

<parameter>pointer userdata</parameter>

197

</paramdef>

198

</funcprototype>

199

</funcsynopsis>

200

</blockquote>

201

Where <parameter>hook</parameter> is the XACE hook you wish to register on, <parameter>callback</parameter> is the callback function you wish to register, and <parameter>userdata</parameter> will be passed through to the callback as its second argument, as described above. See <xref linkend="hooks_tab"/> for the list of XACE hook codes. <function>XaceRegisterCallback</function> is typically called from the extension initialization code; see the SECURITY source for examples. The return value is <literal>TRUE</literal> for success, <literal>FALSE</literal> otherwise.</para>

202

<para>To unregister a callback, use <function>XaceDeleteCallback</function>:

203

204

205

<funcprototype><funcdef>Bool <function>XaceDeleteCallback</function></funcdef>

206

207

208

<parameter>CallbackProcPtr callback</parameter>

209

<parameter>pointer userdata</parameter>

210

</paramdef>

211

</funcprototype>

212

</funcsynopsis>

213

</blockquote>

214

where the three arguments are identical to those used in the call to <function>XaceRegisterCallback</function>. The return value is <literal>TRUE</literal> for success, <literal>FALSE</literal> otherwise.</para>

215

</section>

216

217

218

<title>Hooks</title>

219

<para>The currently defined set of XACE hooks is shown in <xref linkend="hooks_tab"/>. As discussed in <xref linkend="future_hooks"/>, the set of hooks is likely to change in the future as XACE is adopted and further security analysis of the X server is performed.</para>

220

221

<title>XACE security hooks.</title>

222

223

<thead>

224

<row>

225

<entry>Hook Identifier</entry>

226

<entry>Callback Argument Type</entry>

227

<entry>Refer to</entry>

228

</row>

229

</thead>

230

<tbody>

231

<row>

232

<entry><literal>XACE_CORE_DISPATCH</literal></entry>

233

<entry><type>XaceCoreDispatchRec</type></entry>

234

235

</row>

236

<row>

237

<entry><literal>XACE_EXT_DISPATCH</literal></entry>

238

<entry><type>XaceExtAccessRec</type></entry>

239

240

</row>

241

<row>

242

<entry><literal>XACE_RESOURCE_ACCESS</literal></entry>

243

<entry><type>XaceResourceAccessRec</type></entry>

244

245

</row>

246

<row>

247

<entry><literal>XACE_PROPERTY_ACCESS</literal></entry>

248

<entry><type>XacePropertyAccessRec</type></entry>

249

250

</row>

251

<row>

252

<entry><literal>XACE_MAP_ACCESS</literal></entry>

253

<entry><type>XaceMapAccessRec</type></entry>

254

255

</row>

256

<row>

257

<entry><literal>XACE_DRAWABLE_ACCESS</literal></entry>

258

<entry><type>XaceDrawableAccessRec</type></entry>

259

260

</row>

261

<row>

262

<entry><literal>XACE_BACKGRND_ACCESS</literal></entry>

263

<entry><type>XaceMapAccessRec</type></entry>

264

265

</row>

266

<row>

267

<entry><literal>XACE_DEVICE_ACCESS</literal></entry>

268

<entry><type>XaceDeviceAccessRec</type></entry>

269

270

</row>

271

<row>

272

<entry><literal>XACE_HOSTLIST_ACCESS</literal></entry>

273

<entry><type>XaceHostlistAccessRec</type></entry>

274

275

</row>

276

<row>

277

<entry><literal>XACE_EXT_ACCESS</literal></entry>

278

<entry><type>XaceExtAccessRec</type></entry>

279

280

</row>

281

<row>

282

<entry><literal>XACE_WINDOW_INIT</literal></entry>

283

<entry><type>XaceWindowRec</type></entry>

284

285

</row>

286

<row>

287

<entry><literal>XACE_AUTH_AVAIL</literal></entry>

288

<entry><type>XaceAuthAvailRec</type></entry>

289

290

</row>

291

<row>

292

<entry><literal>XACE_KEY_AVAIL</literal></entry>

293

<entry><type>XaceKeyAvailRec</type></entry>

294

295

</row>

296

<row>

297

<entry><literal>XACE_AUDIT_BEGIN</literal></entry>

298

<entry><type>XaceAuditRec</type></entry>

299

300

</row>

301

<row>

302

<entry><literal>XACE_AUDIT_END</literal></entry>

303

<entry><type>XaceAuditRec</type></entry>

304

305

</row>

306

</tbody>

307

</tgroup>

308

</table>

309

<para>In the descriptions that follow, it is helpful to have a listing of <filename>Xext/xacestr.h</filename> available for reference.</para>

310

311

312

<title>Core Dispatch</title>

313

<para>This hook allows security extensions to examine all incoming core protocol requests before they are dispatched. The hook argument is a pointer to a structure of type <type>XaceCoreDispatchRec</type>. This structure contains a

314

<structfield>client</structfield> field of type <type>ClientPtr</type>

315

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

316

<para>The <structfield>client</structfield> field refers to the client making the incoming request. Note that the complete request is accessible via the <structfield>requestBuffer</structfield> member of the client structure. The <function>REQUEST</function> family of macros, located in <filename>include/dix.h</filename>, are useful in verifying and reading from this member.</para>

317

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the request is to be denied. The result of a denied request is a <errorcode>BadAccess</errorcode> error, which is delivered to the client.</para>

318

</section>

319

320

321

<title>Extension Dispatch</title>

322

<para>This hook allows security extensions to examine all incoming extension protocol requests before they are dispatched. The hook argument is a pointer to a structure of type <type>XaceExtAccessRec</type>. This structure contains a

323

<structfield>client</structfield> field of type <type>ClientPtr</type>,

324

a <structfield>ext</structfield> field of type <type>ExtensionEntry*</type>,

325

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

326

327

<para>The <structfield>ext</structfield> field refers to the extension being accessed. This is required information since extensions are not associated with any particular major number.</para>

328

329

</section>

330

331

332

<title>Resource Access</title>

333

<para>This hook allows security extensions to monitor all resource lookups. The hook argument is a pointer to a structure of type <type>XaceResourceAccessRec</type>. This structure contains a

334

<structfield>client</structfield> field of type <type>ClientPtr</type>,

335

a <structfield>id</structfield> field of type <type>XID</type>,

336

a <structfield>rtype</structfield> field of type <type>RESTYPE</type>,

337

a <structfield>access_mode</structfield> field of type <type>Mask</type>,

338

a <structfield>res</structfield> field of type <type>pointer</type>,

339

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

340

<para>The <structfield>client</structfield> field refers to the client on whose behalf the lookup is being performed. Note that this may be <varname>serverClient</varname> for server lookups.</para>

341

<para>The <structfield>id</structfield> field is the resource ID being looked up.</para>

342

<para>The <structfield>rtype</structfield> field is the resource type being looked up.</para>

343

<para>The <structfield>access_mode</structfield> field encodes the type of action being performed. The valid values are defined in <filename>include/resource.h</filename> (look for <literal>SecurityReadAccess</literal>). This field is a legacy of the SECURITY extension.</para>

344

<warning><para>The <structfield>access_mode</structfield> field is not widely used by the core server and is often the default "unknown" value. The semantics of this field may be changed in the future.</para></warning>

345

<para>The <structfield>res</structfield> field is the resource itself: the result of the lookup.</para>

346

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the lookup is to be denied. The result of a denied request is a lookup failure, which will have varying effects on the client (or server) depending on the type of resource.</para>

347

</section>

348

349

350

<title>Property Access</title>

351

<para>This hook allows security extensions to monitor all property accesses. The hook argument is a pointer to a structure of type <type>XacePropertyAccessRec</type>. This structure contains a

352

<structfield>client</structfield> field of type <type>ClientPtr</type>,

353

a <structfield>pWin</structfield> field of type <type>WindowPtr</type>,

354

a <structfield>propertyName</structfield> field of type <type>Atom</type>,

355

a <structfield>access_mode</structfield> field of type <type>Mask</type>,

356

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

357

<para>The <structfield>client</structfield> field refers to the client which is accessing the property. Note that this may be <varname>serverClient</varname> for server lookups.</para>

358

<para>The <structfield>pWin</structfield> field is the window on which the property is being accessed.</para>

359

<para>The <structfield>propertyName</structfield> field is the name of the property being accessed.</para>

360

361

<para>The <structfield>rval</structfield> field should be set to one of the Operation constants defined in <filename>Xext/xace.h</filename>. The options are to allow, deny, or ignore the request. The difference between denying and ignoring is that an ignored request returns successfully but either does nothing (for a write) or returns an empty string (for a read).</para>

362

<warning><para>The semantics of the <structfield>access_mode</structfield> field and the <structfield>rval</structfield> field may be changed in the future. See the warning in <xref linkend="resource_access_hook"/>.</para></warning>

363

</section>

364

365

366

<title>Map Access</title>

367

<para>This hook allows security extensions to approve or deny requests to map windows. The hook argument is a pointer to a structure of type <type>XaceMapAccessRec</type>. This structure contains a

368

<structfield>client</structfield> field of type <type>ClientPtr</type>,

369

a <structfield>pWin</structfield> field of type <type>WindowPtr</type>,

370

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

371

<para>The <structfield>client</structfield> field refers to the client making the request.</para>

372

<para>The <structfield>pWin</structfield> field refers to the window being mapped.</para>

373

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the request is to be denied. Currently, the result of a denied request is a successful return leaving the window unmapped. In the future, this may be changed to return a <errorcode>BadAccess</errorcode> error to the client.</para>

374

</section>

375

376

377

<title>Drawable Access</title>

378

<para>This hook allows security extensions to force censoring of overlapping windows when a <function>GetImage</function> request is made. Refer to the "Image Security" section of the SECURITY extension specification for more information. The hook argument is a pointer to a structure of type <type>XaceDrawableAccessRec</type>. This structure contains a

379

<structfield>client</structfield> field of type <type>ClientPtr</type>,

380

a <structfield>pDraw</structfield> field of type <type>DrawablePtr</type>,

381

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

382

<para>The <structfield>client</structfield> field refers to the client making the request.</para>

383

<para>The <structfield>pDrawable</structfield> field refers to the subject of the <function>GetImage</function> request.</para>

384

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the drawable is to be checked for overlapping windows and censored appropriately.</para>

385

</section>

386

387

388

<title>Background Access</title>

389

<para>This hook allows security extensions to force censoring of background "None" windows, preventing contents of other windows from showing through. The hook argument is a pointer to a structure of type <type>XaceMapAccessRec</type>. This structure contains a

390

<structfield>client</structfield> field of type <type>ClientPtr</type>,

391

a <structfield>pWin</structfield> field of type <type>WindowPtr</type>,

392

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

393

<para>The <structfield>client</structfield> field refers to the client making the request, typically a <function>CreateWindow</function> request.</para>

394

<para>The <structfield>pWin</structfield> field refers to the window being created.</para>

395

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the background is to be censored.</para>

396

<warning><para>This hook may be merged with the drawable access hook at some point in the future.</para></warning>

397

</section>

398

399

400

<title>Device Access</title>

401

<para>This hook allows security extensions to restrict certain actions by clients related to keyboard input. For the specifics, refer to the "Input Security" section of the SECURITY extension specification. The hook argument is a pointer to a structure of type <type>XaceDeviceAccessRec</type>. This structure contains a

402

<structfield>client</structfield> field of type <type>ClientPtr</type>,

403

a <structfield>dev</structfield> field of type <type>DeviceIntPtr</type>,

404

a <structfield>fromRequest</structfield> field of type <type>Bool</type>,

405

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

406

<para>The <structfield>client</structfield> field refers to the client attempting to access the device (keyboard). Note that this may be <varname>serverClient</varname>.</para>

407

<para>The <structfield>dev</structfield> field refers to the input device being accessed.</para>

408

<para>The <structfield>fromRequest</structfield> field is <literal>TRUE</literal> if the access is the result of a client request; <literal>FALSE</literal> otherwise.</para>

409

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the client is to be restricted. The result of the return value varies depending on the context of the call.</para>

410

411

<para>This hook is a legacy of the SECURITY extension and covers only the core server. Extensions do exist, such as XEVIE, that allow clients to intercept and modify input events.</para>

412

<para>The input subsystem in X.Org is in a state of change and it is expected that input event security will not be fully addressed until later versions of XACE.</para>

413

</warning>

414

</section>

415

416

417

<title>Host List Access</title>

418

<para>This hook allows security extensions to approve or deny requests to read or change the host access list. The hook argument is a pointer to a structure of type <type>XaceHostlistAccessRec</type>. This structure contains a

419

<structfield>client</structfield> field of type <type>ClientPtr</type>,

420

a <structfield>access_mode</structfield> field of type <type>Mask</type>,

421

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

422

<para>The <structfield>client</structfield> field refers to the client making the request.</para>

423

<para>The <structfield>access_mode</structfield> field encodes the type of action being performed. The valid values are defined in <filename>include/resource.h</filename> (look for <literal>SecurityReadAccess</literal>). Currently this field is set to read access for <function>ProcListHosts</function> and write access otherwise.</para>

424

425

</section>

426

427

428

<title>Extension Access</title>

429

<para>This hook allows security extensions to approve or deny requests involving supported server extensions. The hook argument is a pointer to a structure of type <type>XaceExtAccessRec</type>. This structure contains a

430

<structfield>client</structfield> field of type <type>ClientPtr</type>,

431

a <structfield>ext</structfield> field of type <type>ExtensionEntry*</type>,

432

and a <structfield>rval</structfield> field of type <type>int</type>.</para>

433

<para>The <structfield>client</structfield> field refers to the client making the request.</para>

434

<para>The <structfield>ext</structfield> field refers to the extension being queried.</para>

435

<para>The <structfield>rval</structfield> field should be set to <literal>FALSE</literal> if the client is not to be made aware of the extension. For a <function>QueryExtension</function> request, a denial results in a response indicating the extension is not present. For a <function>ListExtensions</function> request, a denial results in the exclusion of the extension from the returned list.</para>

436

</section>

437

438

439

<title>Window Initialization</title>

440

<para>This hook allows security extensions to set up security state for newly created windows. The hook argument is a pointer to a structure of type <type>XaceWindowRec</type>. This structure contains a

441

<structfield>client</structfield> field of type <type>ClientPtr</type>,

442

and a <structfield>pWin</structfield> field of type <type>WindowPtr</type>.</para>

443

<para>The <structfield>client</structfield> field refers to the client owning the window. Note that this may be <varname>serverClient</varname>.</para>

444

<para>The <structfield>pWin</structfield> field refers to the newly created window.</para>

445

<para>This hook has no return value.</para>

446

</section>

447

448

449

<title>Authorization Availability Hook</title>

450

<para>This hook allows security extensions to examine the authorization associated with a newly connected client. This can be used to set up client security state depending on the authorization method that was used. The hook argument is a pointer to a structure of type <type>XaceAuthAvailRec</type>. This structure contains a

451

<structfield>client</structfield> field of type <type>ClientPtr</type>,

452

and a <structfield>authId</structfield> field of type <type>XID</type>.</para>

453

<para>The <structfield>client</structfield> field refers to the newly connected client.</para>

454

<para>The <structfield>authId</structfield> field is the resource ID of the client's authorization.</para>

455

<para>This hook has no return value.</para>

456

<note>

457

<para>This hook is called after the client enters the initial state and before the client enters the running state. Keep this in mind if your security extension uses the <varname>ClientStateCallback</varname> list to keep track of clients.</para>

458

<para>This hook is a legacy of the APPGROUP Extension. In the future, this hook may be phased out in favor of a new client state, <literal>ClientStateAuthenticated</literal>.</para>

459

</note>

460

</section>

461

462

463

<title>Keypress Availability Hook</title>

464

<para>This hook allows security extensions to examine keypresses outside of the normal event mechanism. This could be used to implement server-side hotkey support. The hook argument is a pointer to a structure of type <type>XaceKeyAvailRec</type>. This structure contains a

465

<structfield>event</structfield> field of type <type>xEventPtr</type>,

466

a <structfield>keybd</structfield> field of type <type>DeviceIntPtr</type>,

467

and a <structfield>count</structfield> field of type <type>int</type>.</para>

468

<para>The <structfield>event</structfield> field refers to the keyboard event, typically a <literal>KeyPress</literal> or <literal>KeyRelease</literal>.</para>

469

<para>The <structfield>keybd</structfield> field refers to the input device that generated the event.</para>

470

<para>The <structfield>count</structfield> field is the number of repetitions of the event (not 100\% sure of this at present, however).</para>

471

<para>This hook has no return value.</para>

472

473

<para>The warning in <xref linkend="device_access_hook"/> applies to this hook. This hook is provided mainly for support of the Trusted Solaris extension.</para>

474

</warning>

475

</section>

476

477

478

<title>Auditing Hooks</title>

479

<para>Two hooks provide basic auditing support. The begin hook is called immediately before an incoming client request is dispatched and before the dispatch hook is called (refer to <xref linkend="core_dispatch_hook"/>). The end hook is called immedately after the processing of the request has finished. The hook argument is a pointer to a structure of type <type>XaceKeyAvailRec</type>. This structure contains a

480

<structfield>client</structfield> field of type <type>ClientPtr</type>,

481

and a <structfield>requestResult</structfield> field of type <type>int</type>.</para>

482

<para>The <structfield>client</structfield> field refers to client making the request.</para>

483

<para>The <structfield>requestResult</structfield> field contains the result of the request, either <literal>Success</literal> or one of the protocol error codes. Note that this field is significant only in the end hook.</para>

484

<para>These hooks have no return value.</para>

485

</section>

486

487

</section>

488

</section>

489

</section>

490

491

492

<title>Protocol</title>

493

494

<title>Requests</title>

495

<para>XACE does not define any X protocol.</para>

496

</section>

497

498

<title>Events</title>

499

<para>XACE does not define any X protocol.</para>

500

</section>

501

502

<title>Errors</title>

503

<para>XACE does not define any X protocol.</para>

504

</section>

505

</section>

506

</article>

b'\\ No newline at end of file'

Older »