diff options
Diffstat (limited to 'specs/security.xml')
| -rw-r--r-- | specs/security.xml | 1532 |
1 files changed, 1532 insertions, 0 deletions
diff --git a/specs/security.xml b/specs/security.xml new file mode 100644 index 0000000..bcf0153 --- /dev/null +++ b/specs/security.xml @@ -0,0 +1,1532 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<!--translated from security.tex, on 2010-06-27 15:29:00, +by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) +xhtml,docbook,html,refcaption --> + +<book id="security"> + +<bookinfo> + <title>Security Extension Specification</title> + <subtitle>X Consortium Standard</subtitle> + <releaseinfo>X Version 11, Release 6.8</releaseinfo> + <date>November 15, 1996</date> + <authorgroup> + <author> + <firstname>David</firstname><surname>Wiggins</surname> + </author> + </authorgroup> + <corpname>X Consortium Standard</corpname> + <copyright><year>1996</year><holder>X Consortium</holder></copyright> + <releaseinfo>Version 7.1</releaseinfo> + <affiliation><orgname>X Consortium</orgname></affiliation> + <productnumber>X Version 11, Release 6.8</productnumber> + +<legalnotice> + +<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 X CONSORTIUM 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 OR OTHER DEALINGS IN THE SOFTWARE.</para> + +<para>Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.</para> + +</legalnotice> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +The Security extension contains new protocol needed to provide enhanced X +server security. The Security extension should not be exposed to untrusted +clients (defined below). +</para> + +</chapter> + +<chapter id="requests"> +<title>Requests</title> + +<sect1 id="securityqueryversion"> +<title>SecurityQueryVersion</title> +<para> +This request returns the major and minor version numbers of this extension. +</para> + +<para>SecurityQueryVersion</para> + +<informaltable> + <tgroup cols="2"> + <tbody> + <row> + <entry align="left"> + <para>client-major-version</para> + </entry> + <entry align="left"> + <para>CARD16</para> + </entry> + </row> + <row> + <entry align="left"> + <para>client-minor-version</para> + </entry> + <entry align="left"> + <para>CARD16</para> + </entry> + </row> + <row> + <entry align="left"> + <para>=></para> + </entry> + </row> + <row> + <entry align="left"> + <para>server-major-version</para> + </entry> + <entry align="left"> + <para>CARD16</para> + </entry> + </row> + <row> + <entry align="left"> + <para>server-minor-version</para> + </entry> + <entry align="left"> + <para>CARD16</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The client-major-version and client-minor-version numbers indicate what +version of the protocol the client wants the server to implement. The +server-major-version and the server-minor-version numbers returned +indicate the protocol this extension actually supports. This might not +equal the version sent by the client. An implementation can (but need not) +support more than one version simultaneously. The server-major-version +and server-minor-version allow the creation of future revisions of the +Security protocol that may be necessary. In general, the major version +would increment for incompatible changes, and the minor version would +increment for small, upward-compatible changes. Servers that support +the protocol defined in this document will return a server-major-version +of one (1), and a server-minor-version of zero (0). +</para> + +<para> +Clients using the Security extension must issue a SecurityQueryVersion +request before any other Security request in order to negotiate a compatible +protocol version; otherwise, the client will get undefined behavior +(Security may or may not work). +</para> +</sect1> + +<sect1 id="securitygenerateauthentication"> +<title>SecurityGenerateAuthorization</title> + +<para> +This request causes the server to create and return a new authorization with +specific characteristics. Clients can subsequently connect using the new +authorization and will inherit some of the characteristics of the +authorization. +</para> + +<para> +SecurityGenerateAuthorization +</para> +<informaltable> + <tgroup cols="2"> + <tbody> + <row> + <entry align="left"> + <para>authorization-protocol-name</para> + </entry> + <entry align="left"> + <para>STRING8</para> + </entry> + </row> + <row> + <entry align="left"> + <para>authorization-protocol-data</para> + </entry> + <entry align="left"> + <para>STRING8</para> + </entry> + </row> + <row> + <entry align="left"> + <para>value-mask</para> + </entry> + <entry align="left"> + <para>BITMASK</para> + </entry> + </row> + <row> + <entry align="left"> + <para>value-list</para> + </entry> + <entry align="left"> + <para>LISTofVALUE</para> + </entry> + </row> + <row> + <entry align="left"> + <para>=></para> + </entry> + <entry> + </entry> + </row> + <row> + <entry align="left"> + <para>authorization-id</para> + </entry> + <entry align="left"> + <para>AUTHID</para> + </entry> + </row> + <row> + <entry align="left"> + <para>authorization-data-return</para> + </entry> + <entry align="left"> + <para>STRING8</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + <entry> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +Errors: <function>AuthorizationProtocol</function>, <function>Value</function>, <function>Alloc</function> +</para> + +<para> +authorization-protocol-name is the name of the authorization method for +which the server should generate a new authorization that subsequent +clients can use to connect to the server. If the authorization-protocol-name +is not one that the server supports, or if authorization-protocol-data +does not make sense for the given authorization-protocol-name, an +AuthorizationProtocol error results. +</para> + +<para> +authorization-protocol-data is authorization-method specific data that can +be used in some way to generate the authorization. +</para> + +<note><para> +In this version of the extension, the only authorization method +required to be supported is "MIT-MAGIC-COOKIE-1" with any amount +of authorization-protocol-data (including none). The server may use the +authorization-protocol-data as an additional source of randomness used +to generate the authorization. Other authorization methods can supply +their own interpretation of authorization-protocol-data. +</para></note> + +<para> +The value-mask and value-list specify attributes of the authorization +that are to be explicitly initialized. The possible values are: +</para> + +<informaltable> + <tgroup cols="3"> + <tbody> + <row rowsep="1"> + <entry align="left"> + <para></para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>Attribute</para> + </entry> + <entry align="left"> + <para>Type</para> + </entry> + <entry align="left"> + <para>Default</para> + </entry> + </row> + <row> + <entry align="left"> + <para>timeout</para> + </entry> + <entry align="left"> + <para>CARD32</para> + </entry> + <entry align="left"> + <para>60</para> + </entry> + </row> + <row> + <entry align="left"> + <para>group</para> + </entry> + <entry align="left"> + <para>XID or None</para> + </entry> + <entry align="left"> + <para>None</para> + </entry> + </row> + <row> + <entry align="left"> + <para>trust-level</para> + </entry> + <entry align="left"> + <para>{SecurityClientTrusted,</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + <entry align="left"> + <para>SecurityClientUntrusted}</para> + </entry> + <entry align="left"> + <para>SecurityClientUntrusted</para> + </entry> + </row> + <row> + <entry align="left"> + <para>event-mask</para> + </entry> + <entry align="left"> + <para>SecurityAuthorizationRevoked,</para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para></para> + </entry> + <entry align="left"> + <para>or None</para> + </entry> + <entry align="left"> + <para>None</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +timeout is the timeout period in seconds for this authorization. A +timeout value of zero means this authorization will never expire. For +non-zero timeout values, when timeout seconds have elapsed since the +last time that the authorization entered the state of having no +connections authorized by it, and if no new connections used the +authorization during that time, the authorization is automatically purged. +(Note that when an authorization is created, it enters the state of having no +connections authorized by it.) Subsequent connection attempts using that +authorization will fail. This is to facilitate "fire and forget" launching of +applications. +</para> + +<para> +group is an application group ID as defined by the Application Group +extension, or None. Any other values will cause a Value error. When a +group is destroyed, all authorizations specifying that group are revoked +as described under the SecurityRevokeAuthorization request. The Application +Group extension attaches additional semantics to the group. +</para> + +<para> +trust-level tells whether clients using the authorization are trusted or +untrusted. If trust-level is not one of the constants SecurityClientTrusted +or SecurityClientUntrusted, a Value error results. +</para> + +<para> +event-mask defines which events the client is interested in for this +authorization. When the authorization expires or is revoked if event-mask +contains SecurityAuthorizationRevoked a SecurityAuthorizationRevoked event +is reported to the client. +</para> + +<para> +The SecurityAuthorizationRevoked event contains the following field: +</para> + +<informaltable> + <tgroup cols="2"> + <tbody> + <row rowsep="1"> + <entry align="left"> + <para></para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>Field</para> + </entry> + <entry align="left"> + <para>Type</para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>authorization-id</para> + </entry> + <entry align="left"> + <para>AUTHID</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +where authorization-id is the identification of the authorization that was +revoked. +</para> +<para> +If an invalid value-mask is specified, a Value error occurs. +</para> + +<para> +The returned authorization-id is a non-zero value that uniquely identifies +this authorization for use in other requests. The value space for type +AUTHID is not required to be disjoint from values spaces of other core +X types, e.g. resource ids, atoms, visual ids, and keysyms. Thus, a given +numeric value might be both a valid AUTHID and a valid atom, for example. +</para> + +<para> +authorization-data-return is the data that a client should use in some +authorization-method-specific way to make a connection with this +authorization. For "MIT-MAGIC-COOKIE-1," authorization-data-return should +be sent as the authorization-protocol-data in the connection setup message. +It is not required that other authorization methods use +authorization-data-return this way. +</para> + +</sect1> + +<sect1 id="securityrevokeauthorization"> +<title>SecurityRevokeAuthorization</title> + +<para> +This request deletes an authorization created by SecurityGenerateAuthorization. +</para> + +<para> +SecurityRevokeAuthorization +</para> + +<informaltable> + <tgroup cols="2"> + <tbody> + <row> + <entry align="left"> + <para><emphasis remap='I'>authorization-id</emphasis></para> + </entry> + <entry align="left"> + <para>AUTHID</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +Errors: <function>Authorization</function> +</para> + +<para> +If authorization-id does not name a valid authorization, an Authorization +error occurs. Otherwise, this request kills all clients currently connected +using the authorization specified by authorization-id. The authorization is +deleted from the server's database, so future attempts by clients to connect +with this authorization will fail. +</para> + +</sect1> +</chapter> + +<chapter id="changes_to_core_requests"> +<title>Changes to Core Requests</title> + +<para> +A server supporting this extension modifies the handling of some core +requests in the following ways. +</para> +<sect1 id="resource_id_usage"> +<title>Resource ID Usage</title> + +<para> +If an untrusted client makes a request that specifies a resource ID that is +not owned by another untrusted client, a protocol error is sent to the +requesting client indicating that the specified resource does not exist. +The following exceptions apply. An untrusted client can: +</para> + +<orderedlist> + <listitem> + <para> +use the QueryTree, GetGeometry, and TranslateCoordinates requests +without restriction. + </para> + </listitem> + <listitem> + <para> +use colormap IDs that are returned in the default-colormap field of its +connection setup information in any colormap requests. + </para> + </listitem> + <listitem> + <para>specify a root window as:</para> + <orderedlist> + <listitem> + <para> +the drawable field of CreatePixmap, CreateGC, and QueryBestSize. + </para> + </listitem> + <listitem> + <para>the parent field of CreateWindow.</para> + </listitem> + <listitem> + <para> +the window field of CreateColormap, ListProperties, and GetWindowAttributes. + </para> + </listitem> + <listitem> + <para>the grab-window or confine-to fields of GrabPointer. + </para> + </listitem> + <listitem> + <para>the grab-window field of UngrabButton.</para> + </listitem> + <listitem> + <para> +the destination of SendEvent, but only if all of the following are true. +(These conditions cover all the events that the ICCCM specifies with +a root window destination.) + </para> + <orderedlist> + <listitem> + <para>The propogate field of SendEvent is False.</para> + </listitem> + <listitem> + <para> +The event-mask field of SendEvent is ColormapChange, +StructureNotify, or the logical OR of SubstructureRedirect with +SubstructureNotify. + </para> + </listitem> + <listitem> + <para> +The event type being sent is UnmapNotify, ConfigureRequest, or +ClientMessage. + </para> + </listitem> + </orderedlist> + </listitem> + <listitem> + <para> +the window field of ChangeWindowAttributes, but only if the value-mask +contains only event-mask and the corresponding value is StructureNotify, +PropertyChange, or the logical OR of both. + </para> + </listitem> + </orderedlist> + </listitem> +</orderedlist> + +<note> +<para> +ISSUE: are root window exceptions needed for these? WarpPointer, ReparentWindow +(parent), CirculateWindow, QueryPointer (emacs does this), GetMotionEvents. +</para> +</note> + +</sect1> +<sect1 id="extension_security"> +<title>Extension Security</title> + +<para> +This extension introduces the notion of secure and insecure extensions. A +secure extension is believed to be safe to use by untrusted clients; that +is, there are no significant security concerns known that an untrusted +client could use to destroy, modify, or steal data of trusted clients. This +belief may be founded on a careful analysis of the extension protocol, +its implementation, and measures taken to "harden" the extension to close +security weaknesses. All extensions not considered secure are called +insecure. The implementation details of how an extension is identified as +secure or insecure are beyond the scope of this specification. +</para> + +<para> +<function>ListExtensions</function> will only return names of secure +extensions to untrusted clients. +</para> + +<para> +If an untrusted client uses <function>QueryExtension</function> on an +insecure extension that the server supports, the reply will have the +present field set to False and the major-opcode field set to zero to +indicate that the extension is not supported. +</para> + +<para> +If an untrusted client successfully guesses the major opcode of an +insecure extension, attempts by it to execute requests with that major +opcode will fail with a Request error. +</para> + +</sect1> + +<sect1 id="keyboard_security"> +<title>Keyboard Security</title> + + +<para> +The protocol interpretation changes in this section are intended to prevent +untrusted applications from stealing keyboard input that was meant for +trusted clients and to prevent them from interfering with the use of the +keyboard. +</para> + +<para> +The behavior of some keyboard-related requests and events is modified when +the client is untrusted depending on certain server state at the time of +request execution or event generation. Specifically, if a hypothetical +keyboard event were generated given the current input focus, pointer +position, keyboard grab state, and window event selections, and if that +keyboard event would not be delivered to any untrusted client, the +following changes apply: +</para> + +<orderedlist> + <listitem> + <para> +The bit vector representing the up/down state of the keys returned by +<function>QueryKeymap</function> and +<function>KeymapNotify</function> is all zeroes. + </para> + </listitem> + <listitem> + <para>GrabKeyboard returns a status of AlreadyGrabbed.</para> + </listitem> + <listitem> + <para> +<function>SetInputFocus</function> does nothing. Note that this means the +Globally Active +Input and WM_TAKE_FOCUS mechanisms specified in the ICCCM will +not work with untrusted clients. + </para> + </listitem> + <listitem> + <para> +Passive grabs established by GrabKey that would otherwise have activated +do not activate. + </para> + </listitem> +</orderedlist> + +<para> +If an untrusted client attempts to use any of the following requests, the +only effect is that the client receives an Access error: SetModifierMapping, +ChangeKeyboardMapping, ChangeKeyboardControl. +</para> + +<para> +If an InputOnly window owned by an untrusted client has a parent owned by a +trusted client, all attempts to map the window will be ignored. This includes +mapping attempts resulting from MapWindow, MapSubwindows, ReparentWindow, +and save-set processing. +</para> +<para> +However, if the parent of an InputOnly window owned by an untrusted client +is the root window, attempts to map that window will be performed as +expected. This is in line with the root window exceptions above. +</para> +</sect1> + +<sect1 id="image_security"> +<title>Image Security</title> + +<para> +It should be impossible for an untrusted client to retrieve the image +contents of a trusted window unless a trusted client takes action to allow +this. We introduce the following defenses in support of this requirement. +</para> + +<para> +The restrictions on resource ID usage listed above prevent untrusted clients +from using GetImage directly on windows not belonging to trusted clients. +</para> + +<para> +If an untrusted client tries to set the background-pixmap attribute of an +untrusted window to None, the server will instead use a server-dependent +background which must be different than None. +</para> + +<para> +The X protocol description of <function>GetImage</function> states that the +returned contents of regions of a window obscured by noninferior windows are +undefined if the window has no backing store. Some implementations return the +contents of the obscuring windows in these regions. When an untrusted client +uses <function>GetImage</function>, this behavior is forbidden; the server must +fill the obscured regions in the returned image with a server-dependent pattern. +</para> + +<para> +If an untrusted window has trusted inferiors, their contents are vulnerable +to theft via <function>GetImage</function> on the untrusted parent, as well +as being vulnerable to destruction via drawing with subwindow-mode +IncludeInferiors on the untrusted parent. An untrusted window having trusted +inferiors can only occur at the request of a trusted client. It is expected +to be an unusual configuration. +</para> + +</sect1> + +<sect1 id="property_security"> + +<title>Property Security</title> + +<para> +Unlike the other security provisions described in this document, security for +property access is not amenable to a fixed policy because properties are +used for inter-client communication in diverse ways and may contain data of +varying degrees of sensitivity. Therefore, we only list the possible +restrictions the server may decide to impose on use of properties on trusted +windows by untrusted clients. How the server chooses which restrictions from +this list to apply to a particular property access is implementation dependent + <footnote><para> +In the X Consortium server implementation, property access is controlled by +a configuration file; see the -sp option in the Xserver(1) manual page. + </para></footnote>. +</para> + +<para>The X Protocol property requests are +<function>ChangeProperty</function>, +<function>GetProperty</function>, +<function>DeleteProperty</function>, +<function>RotateProperties</function>, and +<function>ListProperties</function>. For these requests, the server can +allow the request to execute normally (as if it had been issued by a +trusted client), ignore the request completely (as if it were a NoOperation), +or ignore the request except to send an Atom error to the client. Ignoring +a <function>ListProperties</function> request means replying that +the window has no properties. <function>ListProperties</function> may also +reply with a subset of the existing properties if the server is doing +property hiding; see below. An ignored <function>GetProperty</function> +request may reply that the property does not exist, or that it exists but +contains no data. +</para> + +<para> +The server may decide to hide certain properties on certain windows from +untrusted clients + <footnote><para> +The X Consortium server implementation does not currently provide a way to +hide properties. + </para></footnote>. +If a property is to be hidden, it must be done consistently to avoid +confusing clients. This means that for untrusted clients: +</para> + +<itemizedlist> + <listitem> + <para> +That property should not be returned by +<function>ListProperties</function>. + </para> + </listitem> + <listitem> + <para> +<function>PropertyNotify</function> events should not be sent for that +property.</para> + </listitem> + <listitem> + <para> +<function>GetProperty</function> on that property should reply that the +property does not exist (the return type is None, the format and +bytes-after are zero, and the value is empty). + </para> + </listitem> +</itemizedlist> + +<para> +For a property that the server is protecting but not hiding, consistency +must also be maintained: +</para> + +<itemizedlist> + <listitem> + <para> +That property should be returned by <function>ListProperties</function>. + </para> + </listitem> + <listitem> + <para> +<function>PropertyNotify</function> events should be sent for that property. + </para> + </listitem> + <listitem> + <para> +<function>GetProperty</function> on that property should reply that the +property exists (if it really does) but the value is empty +(return type and format are their real values, and the "length of value" +field in the reply is zero). + </para> + </listitem> +</itemizedlist> + +</sect1> + +<sect1 id="miscellaneous_security"> +<title>Miscellaneous Security</title> + +<para> +If an untrusted client attempts to use +<function>ChangeHosts</function>, +<function>ListHosts</function>, or +<function>SetAccessControl</function>, +the only effect is that the client receives an Access error. +</para> + +<para> +If an untrusted client attempts to use <function>ConvertSelection</function> +on a selection with a trusted selection owner window, the server generates +a SelectionNotify event to the requestor with property None. +</para> +</sect1> +</chapter> + +<chapter id="new_authorization_method"> +<title>New Authorization Method</title> + +<para> +This extension includes a new authorization method named +"XC-QUERY-SECURITY-1". Its purpose is to allow an external agent such as +the X firewall proxy to probe an X server to determine whether that server +meets certain security criteria without requiring the agent to have its +own authorization for that server. The agent may use the returned information +to make a decision. For example, the X firewall proxy may choose not to +forward client connections to servers that do not meet the criteria. +</para> + +<para> +To use this authorization method, the client (or proxy) sends +"XC-QUERY-SECURITY-1" as the authorization-protocol-name in the initial +connection setup message. The authorization-protocol-data may be empty or +may contain additional security criteria desribed below. If the success +field of the server's reply is Authenticate, the server supports the +security extension, and the server meets all specified additional security +criteria. In this case, the client should resend the initial connection +setup message substituting the authorization protocol name and data +that should be used to authorize the connection. If the success field of the +server's reply is anything other than Authenticate, either the server does not +support the security extension, does not meet (or cannot determine if it +meets) all of the additional security criteria, or chooses for internal reasons +not to answer with Authenticate. In this case, the client should close the +connection. +</para> + +<para> +If the authorization-protocol-data sent with "XC-QUERY-SECURITY-1" is not +empty, it specifies additional security criteria for the server to check, as +follows. +</para> + +<para> +<function>authorization-protocol-data</function> +</para> + +<informaltable> + <tgroup cols="2"> + <tbody> + <row> + <entry align="left"> + <para>policy-mask</para> + </entry> + <entry align="left"> + <para>BITMASK</para> + </entry> + </row> + <row> + <entry align="left"> + <para>policies</para> + </entry> + <entry align="left"> + <para>LISTofSECURITYPOLICY</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The policy-mask field is any logical-OR combination of the constants +Extensions and SitePolicies. For each bit set in policy-mask, there is a +SECURITYPOLICY element in policies. The nth element in policies corresponds +to the nth 1-bit in policy-mask, counting upward from bit 0. +</para> + +<para><function>SECURITYPOLICY</function></para> + +<informaltable> + <tgroup cols="2"> + <tbody> + <row> + <entry align="left"> + <para>policy-type</para> + </entry> + <entry align="left"> + <para>{Disallow, Permit}</para> + </entry> + </row> + <row> + <entry align="left"> + <para>names</para> + </entry> + <entry align="left"> + <para>LISTofSTR</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +For a SECURITYPOLICY corresponding to policy-mask Extensions, if +policy-type is Disallow the server is required to consider as insecure +all extensions given in names. No policy is specified for extensions +not listed in names. If policy-type is Permit the server may consider +only those extensions given in names to be secure; all other extensions +must be treated as insecure. If these constraints are not met, the server +should not return Authenticate in the success field of the reply. +Servers can but need not dynamically configure themselves in response +to an Extensions SECURITYPOLICY; a conforming server might simply compare +the policy with a compiled-in table of extensions and their security status. +</para> + +<para> +For a SECURITYPOLICY corresponding to policy-mask SitePolicies, policy-type +Disallow means the server must not have been configured with any of the site +policies given in names. Policy-type Permit means the server must have +been configured with at least one of the site policies given in names. If +these constraints are not met, the server should not return Authenticate in +the success field of the reply. +</para> + +<para> +SitePolicies provide a way to express new forms of security-relevant +information that could not be anticipated at the time of this writing. +For example, suppose the server is found to have a critical security defect. +When a fix is developed, a site policy string could be associated with the +fix. Servers with the fix would advertise that site policy, and the X +firewall proxy would specify that site policy in a SECURITYPOLICY with +policy-type Permit. +</para> + +</chapter> + +<chapter id="encoding"> +<title>Encoding</title> + +<para> +Please refer to the X11 Protocol Encoding document as this section +uses syntactic conventions and data types established there. +</para> + +<para> +The name of this extension is "SECURITY". +</para> + +<sect1 id="types"> +<title>Types</title> +<para> +AUTHID: CARD32 +</para> +</sect1> + +<sect1 id="request_encoding"> +<title>Request Encoding</title> + +<para> +SecurityQueryVersion +</para> +<literallayout remap='FD'> +1 CARD8 major-opcode +1 0 minor-opcode +2 2 request length +2 CARD16 client-major-version +2 CARD16 client-minor-version +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 0 reply length +2 CARD16 server-major-version +2 CARD16 server-minor-version +20 unused +</literallayout> + +<para> +<function>SecurityRevokeAuthorization</function> +</para> + +<literallayout remap='FD'> +1 CARD8 major-opcode +1 2 minor-opcode +2 2 request length +4 AUTHID authorization-id +</literallayout> + +<para> +SecurityGenerateAuthorization +</para> + +<literallayout remap='FD'> +1 CARD8 major-opcode +1 1 minor-opcode +2 3 + (m+n+3)/4 + s request length +2 CARD16 m, number of bytes in authorization protocol name +2 CARD16 n, number of bytes in authorization data +m STRING8 authorization protocol name +n STRING8 authorization protocol data +p unused, p=pad(m+n) +4 BITMASK value-mask (has s bits set to 1) + #x00000001 timeout + #x00000002 trust-level + #x00000004 group + #x00000008 event-mask +4s LISTofVALUE value-list +</literallayout> + +<para> +VALUES +</para> +<literallayout remap='FD'> +4 CARD32 timeout +4 trust-level + 0 SecurityClientTrusted + 1 SecurityClientUntrusted +4 XID group +0 None +4 CARD32 event-mask + #x00000001 SecurityAuthorizationRevoked +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 (q+3)/4 reply length +4 AUTHID authorization-id +2 CARD16 data-length +18 unused +q STRING8 authorization-data-return +r unused, r=pad(q) +</literallayout> + +</sect1> + +<sect1 id="event_encoding"> +<title>Event Encoding</title> +<para> +<function>SecurityAuthorizationRevoked</function> +</para> + +<literallayout remap='FD'> +1 0+extension event base code +1 unused +2 CARD16 sequence number +4 AUTHID authorization id +24 unused +</literallayout> + +</sect1> + +<sect1 id="authorization_method_encoding"> +<title>Authorization Method Encoding</title> + +<para> +For authorization-protocol-name "XC-QUERY-SECURITY-1", the +authorization-protocol-data is interpreted as follows: +</para> + +<para> +<function>authorization-protocol-data</function> +</para> +<literallayout remap='FD'> +1 BITMASK policy-mask + #x00000001 Extensions + #x00000002 SitePolicies +m LISTofSECURITYPOLICY policies +</literallayout> + +<para> +<function>SECURITYPOLICY</function> +</para> + +<literallayout remap='FD'> +1 policy-type + 0 Permit + 1 Disallow +1 CARD8 number of STRs in names +n LISTofSTR names +</literallayout> + +<para> +LISTofSTR has the same encoding as in the X protocol: each STR is a single +byte length, followed by that many characters, and there is no padding or +termination between STRs. +</para> +</sect1> + +</chapter> +<chapter id="c_language_binding"> +<title>C Language Binding</title> + +<para> +The header for this extension is <X11/extensions/security.h>. All +identifier names provided by this header begin with XSecurity. +</para> + +<para> +All functions that have return type Status will return nonzero for +success and zero for failure. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Status <function>XSecurityQueryExtension</function></funcdef> + <paramdef>Display <parameter> *dpy</parameter></paramdef> + <paramdef>int <parameter> *major_version_return</parameter></paramdef> + <paramdef>int <parameter> *minor_version_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XSecurityQueryExtension</function> sets major_version_return and +minor_version_return to the major and minor Security protocol version +supported by the server. If the Security library is compatible with the +version returned by the server, it returns nonzero. If dpy does not support +the Security extension, or if there was an error during communication with +the server, or if the server and library protocol versions are incompatible, +it returns zero. No other XSecurity functions may be called before this +function. If a client violates this rule, the effects of all subsequent +XSecurity calls that it makes are undefined. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Xauth *<function>XSecurityAllocXauth</function></funcdef> + <paramdef><parameter>void</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<para> +In order to provide for future evolution, Xauth structures are used to +pass and return authorization data, and the library provides ways to +allocate and deallocate them. +</para> + +<para> +<function>XSecurityAllocXauth</function> must be used to allocate the +Xauth structure that is passed to +<function>XSecurityGenerateAuthorization</function>. +</para> + +<para> +For the purposes of the Security extension, the Xauth structure has +the following fields: +</para> + +<informaltable> + <tgroup cols="3"> + <tbody> + <row rowsep="1"> + <entry align="left"> + <para></para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>Type</para> + </entry> + <entry align="left"> + <para>Field name</para> + </entry> + <entry align="left"> + <para>Description</para> + </entry> + </row> + <row> + <entry align="left"> + <para>unsigned short</para> + </entry> + <entry align="left"> + <para>name_length</para> + </entry> + <entry align="left"> + <para>number of bytes in name</para> + </entry> + </row> + <row> + <entry align="left"> + <para>char *</para> + </entry> + <entry align="left"> + <para>name</para> + </entry> + <entry align="left"> + <para>authorization protocol name</para> + </entry> + </row> + <row> + <entry align="left"> + <para>unsigned short</para> + </entry> + <entry align="left"> + <para>data_length</para> + </entry> + <entry align="left"> + <para>number of bytes in data</para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>char *</para> + </entry> + <entry align="left"> + <para>data</para> + </entry> + <entry align="left"> + <para>authorization protocol data</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> +<para> +The Xauth structure returned by this function is initialized as follows: +name_length and data_length are zero, and name and data are NULL. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void <function>XSecurityFreeXauth</function></funcdef> + <paramdef>Xauth<parameter> *auth</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XSecurityFreeXauth</function> must be used to free Xauth +structures allocated by +<function>XSecurityAllocXauth</function> or returned by +<function>XSecurityGenerateAuthorization</function>. It is the +caller's responsibility to fill in the name and data fields of Xauth structures +allocated with <function>XSecurityAllocXauth</function>, so this function +will not attempt to free them. In contrast, all storage associated with +Xauth structures returned from +<function>XSecurityGenerateAuthorization</function> will be freed by this +function, including the name and data fields. +</para> + + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>XSecurityRevokeAuthorization</function></funcdef> + <paramdef>Display<parameter> *dpy</parameter></paramdef> + <paramdef>XSecurityAuthorization<parameter> auth_id</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XSecurityRevokeAuthorization</function> deletes the authorization +specified by auth_id, which must be a value returned in the auth_id_return +parameter of <function>XSecurityGenerateAuthorization</function>. All +clients that connected with that authorization are be killed. Subsequently, +clients that attempt to connect using that authorization will be refused. +</para> + + +<funcsynopsis> +<funcprototype> + <funcdef>Xauth *<function>XSecurityGenerateAuthorization</function></funcdef> + <paramdef>Display<parameter> *dpy</parameter></paramdef> + <paramdef>Xauth<parameter> *auth_in</parameter></paramdef> + <paramdef>unsigned long<parameter> valuemask</parameter></paramdef> + <paramdef>XSecurityAutorizationAttributes <parameter> *attributes</parameter></paramdef> + <paramdef>XSecurityAutorization<parameter> *auth_id_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XSecurityGenerateAuthorization</function> creates a new +authorization with the specified attributes. The auth_in argument must be +allocated by <function>XSecurityAllocXauth</function>. The +name and name_length fields of auth_in should be initialized to the +authorization protocol name and its length in characters respectively. +If there is authorization data, the data and data_length fields of +auth_in should be initialized to the data and its length in characters +respectivley. The library does not assume that name and data are +null-terminated strings. The auth_in argument must be freed with +<function>XSecurityFreeXauth</function>. +</para> + +<para> +The XSecurityAuthorizationAttributes structure has the following fields: +</para> + +<informaltable> + <tgroup cols="3"> + <tbody> + <row rowsep="1"> + <entry align="left"> + <para></para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>Type</para> + </entry> + <entry align="left"> + <para>Field name</para> + </entry> + <entry align="left"> + <para>Mask</para> + </entry> + </row> + <row> + <entry align="left"> + <para>unsigned int</para> + </entry> + <entry align="left"> + <para>trust_level</para> + </entry> + <entry align="left"> + <para>XSecurityTrustLevel</para> + </entry> + </row> + <row> + <entry align="left"> + <para>unsigned int</para> + </entry> + <entry align="left"> + <para>timeout</para> + </entry> + <entry align="left"> + <para>XSecurityTimeout</para> + </entry> + </row> + <row> + <entry align="left"> + <para>XID</para> + </entry> + <entry align="left"> + <para>group</para> + </entry> + <entry align="left"> + <para>XSecurityGroup</para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>long</para> + </entry> + <entry align="left"> + <para>event_mask</para> + </entry> + <entry align="left"> + <para>XSecurityEventMask</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +These correspond to the trust-level, timeout, group, and event-mask +described in the SecurityGenerateAuthorization protocol request. The +caller can fill in values for any subset of these attributes. The valuemask +argument must be the bitwise OR of the symbols listed in the Mask column +for all supplied attributes. The event_mask attribute can be None, +XSecurityAuthorizationRevokedMask, or XSecurityAllEventMasks. In this +revision of the protocol specification XSecurityAllEventMasks is equivalent +to XSecurityAuthorizationRevokedMask. If the caller does not need to +specify any attributes, the attributes argument can be NULL, and the +valuemask argument must be zero. +</para> +<para> +If the function fails, NULL is returned and auth_id_return is filled in +with zero. Otherwise, a pointer to an Xauth structure is returned. The name +and name_length fields of the returned Xauth structure will be copies of the +name that was passed in, and the data and data_length fields will be set to +the authorization data returned by the server. The caller should not assume +that name and data are null-terminated strings. If no authorization data was +returned by the server, the data and data_length fields will be set to NULL +and zero repectively. The returned Xauth structure must be freed with +<function>XSecurityFreeXauth</function>; the caller should not use any other +means free the structure or any of its components. The auth_id_return +argument will be filled in with the non-zero authorization id of the created +authorization. +</para> + +<para> +The XSecurityAuthorizationRevokedEvent structure has the following fields: +</para> + +<informaltable> + <tgroup cols="3"> + <tbody> + <row rowsep="1"> + <entry align="left"> + <para></para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>Type</para> + </entry> + <entry align="left"> + <para>Field name</para> + </entry> + <entry align="left"> + <para>Description</para> + </entry> + + </row> + <row> + <entry align="left"> + <para>int</para> + </entry> + <entry align="left"> + <para>type</para> + </entry> + <entry align="left"> + <para>event base + XSecurityAuthorizationRevoked</para> + </entry> + </row> + <row> + <entry align="left"> + <para>unsigned long</para> + </entry> + <entry align="left"> + <para>serial</para> + </entry> + <entry align="left"> + <para># of last request processed by server</para> + </entry> + </row> + <row> + <entry align="left"> + <para>Bool</para> + </entry> + <entry align="left"> + <para>send_event</para> + </entry> + <entry align="left"> + <para>true if this came from SendEvent</para> + </entry> + </row> + <row> + <entry align="left"> + <para>Display*</para> + </entry> + <entry align="left"> + <para>display</para> + </entry> + <entry align="left"> + <para>Display the event was read from</para> + </entry> + </row> + <row rowsep="1"> + <entry align="left"> + <para>XSecurityAuthorization</para> + </entry> + <entry align="left"> + <para>auth_id</para> + </entry> + <entry align="left"> + <para>revoked authorization id</para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + <row> + <entry align="left"> + <para></para> + </entry> + </row> + </tbody> + </tgroup> +</informaltable> +</chapter> +</book> |