1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4 <!--translated from security.tex, on 2010-06-27 15:29:00,
5 by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)
6 xhtml,docbook,html,refcaption -->
11 <title>Security Extension Specification</title>
12 <subtitle>X Consortium Standard</subtitle>
13 <releaseinfo>X Version 11, Release 6.8</releaseinfo>
14 <date>November 15, 1996</date>
17 <firstname>David</firstname><surname>Wiggins</surname>
20 <corpname>X Consortium Standard</corpname>
21 <copyright><year>1996</year><holder>X Consortium</holder></copyright>
22 <releaseinfo>Version 7.1</releaseinfo>
23 <affiliation><orgname>X Consortium</orgname></affiliation>
24 <productnumber>X Version 11, Release 6.8</productnumber>
28 <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>
30 <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>
36 <chapter id="introduction">
37 <title>Introduction</title>
40 The Security extension contains new protocol needed to provide enhanced X
41 server security. The Security extension should not be exposed to untrusted
42 clients (defined below).
47 <chapter id="requests">
48 <title>Requests</title>
50 <sect1 id="securityqueryversion">
51 <title>SecurityQueryVersion</title>
53 This request returns the major and minor version numbers of this extension.
56 <para>SecurityQueryVersion</para>
63 <para>client-major-version</para>
71 <para>client-minor-version</para>
84 <para>server-major-version</para>
92 <para>server-minor-version</para>
108 The client-major-version and client-minor-version numbers indicate what
109 version of the protocol the client wants the server to implement. The
110 server-major-version and the server-minor-version numbers returned
111 indicate the protocol this extension actually supports. This might not
112 equal the version sent by the client. An implementation can (but need not)
113 support more than one version simultaneously. The server-major-version
114 and server-minor-version allow the creation of future revisions of the
115 Security protocol that may be necessary. In general, the major version
116 would increment for incompatible changes, and the minor version would
117 increment for small, upward-compatible changes. Servers that support
118 the protocol defined in this document will return a server-major-version
119 of one (1), and a server-minor-version of zero (0).
123 Clients using the Security extension must issue a SecurityQueryVersion
124 request before any other Security request in order to negotiate a compatible
125 protocol version; otherwise, the client will get undefined behavior
126 (Security may or may not work).
130 <sect1 id="securitygenerateauthentication">
131 <title>SecurityGenerateAuthorization</title>
134 This request causes the server to create and return a new authorization with
135 specific characteristics. Clients can subsequently connect using the new
136 authorization and will inherit some of the characteristics of the
141 SecurityGenerateAuthorization
148 <para>authorization-protocol-name</para>
156 <para>authorization-protocol-data</para>
164 <para>value-mask</para>
172 <para>value-list</para>
175 <para>LISTofVALUE</para>
187 <para>authorization-id</para>
195 <para>authorization-data-return</para>
213 Errors: <function>AuthorizationProtocol</function>, <function>Value</function>, <function>Alloc</function>
217 authorization-protocol-name is the name of the authorization method for
218 which the server should generate a new authorization that subsequent
219 clients can use to connect to the server. If the authorization-protocol-name
220 is not one that the server supports, or if authorization-protocol-data
221 does not make sense for the given authorization-protocol-name, an
222 AuthorizationProtocol error results.
226 authorization-protocol-data is authorization-method specific data that can
227 be used in some way to generate the authorization.
231 In this version of the extension, the only authorization method
232 required to be supported is "MIT-MAGIC-COOKIE-1" with any amount
233 of authorization-protocol-data (including none). The server may use the
234 authorization-protocol-data as an additional source of randomness used
235 to generate the authorization. Other authorization methods can supply
236 their own interpretation of authorization-protocol-data.
240 The value-mask and value-list specify attributes of the authorization
241 that are to be explicitly initialized. The possible values are:
254 <para>Attribute</para>
279 <para>XID or None</para>
287 <para>trust-level</para>
290 <para>{SecurityClientTrusted,</para>
298 <para>SecurityClientUntrusted}</para>
301 <para>SecurityClientUntrusted</para>
306 <para>event-mask</para>
309 <para>SecurityAuthorizationRevoked,</para>
338 timeout is the timeout period in seconds for this authorization. A
339 timeout value of zero means this authorization will never expire. For
340 non-zero timeout values, when timeout seconds have elapsed since the
341 last time that the authorization entered the state of having no
342 connections authorized by it, and if no new connections used the
343 authorization during that time, the authorization is automatically purged.
344 (Note that when an authorization is created, it enters the state of having no
345 connections authorized by it.) Subsequent connection attempts using that
346 authorization will fail. This is to facilitate "fire and forget" launching of
351 group is an application group ID as defined by the Application Group
352 extension, or None. Any other values will cause a Value error. When a
353 group is destroyed, all authorizations specifying that group are revoked
354 as described under the SecurityRevokeAuthorization request. The Application
355 Group extension attaches additional semantics to the group.
359 trust-level tells whether clients using the authorization are trusted or
360 untrusted. If trust-level is not one of the constants SecurityClientTrusted
361 or SecurityClientUntrusted, a Value error results.
365 event-mask defines which events the client is interested in for this
366 authorization. When the authorization expires or is revoked if event-mask
367 contains SecurityAuthorizationRevoked a SecurityAuthorizationRevoked event
368 is reported to the client.
372 The SecurityAuthorizationRevoked event contains the following field:
393 <para>authorization-id</para>
414 where authorization-id is the identification of the authorization that was
418 If an invalid value-mask is specified, a Value error occurs.
422 The returned authorization-id is a non-zero value that uniquely identifies
423 this authorization for use in other requests. The value space for type
424 AUTHID is not required to be disjoint from values spaces of other core
425 X types, e.g. resource ids, atoms, visual ids, and keysyms. Thus, a given
426 numeric value might be both a valid AUTHID and a valid atom, for example.
430 authorization-data-return is the data that a client should use in some
431 authorization-method-specific way to make a connection with this
432 authorization. For "MIT-MAGIC-COOKIE-1," authorization-data-return should
433 be sent as the authorization-protocol-data in the connection setup message.
434 It is not required that other authorization methods use
435 authorization-data-return this way.
440 <sect1 id="securityrevokeauthorization">
441 <title>SecurityRevokeAuthorization</title>
444 This request deletes an authorization created by SecurityGenerateAuthorization.
448 SecurityRevokeAuthorization
456 <para><emphasis remap='I'>authorization-id</emphasis></para>
472 Errors: <function>Authorization</function>
476 If authorization-id does not name a valid authorization, an Authorization
477 error occurs. Otherwise, this request kills all clients currently connected
478 using the authorization specified by authorization-id. The authorization is
479 deleted from the server's database, so future attempts by clients to connect
480 with this authorization will fail.
486 <chapter id="changes_to_core_requests">
487 <title>Changes to Core Requests</title>
490 A server supporting this extension modifies the handling of some core
491 requests in the following ways.
493 <sect1 id="resource_id_usage">
494 <title>Resource ID Usage</title>
497 If an untrusted client makes a request that specifies a resource ID that is
498 not owned by another untrusted client, a protocol error is sent to the
499 requesting client indicating that the specified resource does not exist.
500 The following exceptions apply. An untrusted client can:
506 use the QueryTree, GetGeometry, and TranslateCoordinates requests
512 use colormap IDs that are returned in the default-colormap field of its
513 connection setup information in any colormap requests.
517 <para>specify a root window as:</para>
521 the drawable field of CreatePixmap, CreateGC, and QueryBestSize.
525 <para>the parent field of CreateWindow.</para>
529 the window field of CreateColormap, ListProperties, and GetWindowAttributes.
533 <para>the grab-window or confine-to fields of GrabPointer.
537 <para>the grab-window field of UngrabButton.</para>
541 the destination of SendEvent, but only if all of the following are true.
542 (These conditions cover all the events that the ICCCM specifies with
543 a root window destination.)
547 <para>The propogate field of SendEvent is False.</para>
551 The event-mask field of SendEvent is ColormapChange,
552 StructureNotify, or the logical OR of SubstructureRedirect with
558 The event type being sent is UnmapNotify, ConfigureRequest, or
566 the window field of ChangeWindowAttributes, but only if the value-mask
567 contains only event-mask and the corresponding value is StructureNotify,
568 PropertyChange, or the logical OR of both.
577 ISSUE: are root window exceptions needed for these? WarpPointer, ReparentWindow
578 (parent), CirculateWindow, QueryPointer (emacs does this), GetMotionEvents.
583 <sect1 id="extension_security">
584 <title>Extension Security</title>
587 This extension introduces the notion of secure and insecure extensions. A
588 secure extension is believed to be safe to use by untrusted clients; that
589 is, there are no significant security concerns known that an untrusted
590 client could use to destroy, modify, or steal data of trusted clients. This
591 belief may be founded on a careful analysis of the extension protocol,
592 its implementation, and measures taken to "harden" the extension to close
593 security weaknesses. All extensions not considered secure are called
594 insecure. The implementation details of how an extension is identified as
595 secure or insecure are beyond the scope of this specification.
599 <function>ListExtensions</function> will only return names of secure
600 extensions to untrusted clients.
604 If an untrusted client uses <function>QueryExtension</function> on an
605 insecure extension that the server supports, the reply will have the
606 present field set to False and the major-opcode field set to zero to
607 indicate that the extension is not supported.
611 If an untrusted client successfully guesses the major opcode of an
612 insecure extension, attempts by it to execute requests with that major
613 opcode will fail with a Request error.
618 <sect1 id="keyboard_security">
619 <title>Keyboard Security</title>
623 The protocol interpretation changes in this section are intended to prevent
624 untrusted applications from stealing keyboard input that was meant for
625 trusted clients and to prevent them from interfering with the use of the
630 The behavior of some keyboard-related requests and events is modified when
631 the client is untrusted depending on certain server state at the time of
632 request execution or event generation. Specifically, if a hypothetical
633 keyboard event were generated given the current input focus, pointer
634 position, keyboard grab state, and window event selections, and if that
635 keyboard event would not be delivered to any untrusted client, the
636 following changes apply:
642 The bit vector representing the up/down state of the keys returned by
643 <function>QueryKeymap</function> and
644 <function>KeymapNotify</function> is all zeroes.
648 <para>GrabKeyboard returns a status of AlreadyGrabbed.</para>
652 <function>SetInputFocus</function> does nothing. Note that this means the
654 Input and WM_TAKE_FOCUS mechanisms specified in the ICCCM will
655 not work with untrusted clients.
660 Passive grabs established by GrabKey that would otherwise have activated
667 If an untrusted client attempts to use any of the following requests, the
668 only effect is that the client receives an Access error: SetModifierMapping,
669 ChangeKeyboardMapping, ChangeKeyboardControl.
673 If an InputOnly window owned by an untrusted client has a parent owned by a
674 trusted client, all attempts to map the window will be ignored. This includes
675 mapping attempts resulting from MapWindow, MapSubwindows, ReparentWindow,
676 and save-set processing.
679 However, if the parent of an InputOnly window owned by an untrusted client
680 is the root window, attempts to map that window will be performed as
681 expected. This is in line with the root window exceptions above.
685 <sect1 id="image_security">
686 <title>Image Security</title>
689 It should be impossible for an untrusted client to retrieve the image
690 contents of a trusted window unless a trusted client takes action to allow
691 this. We introduce the following defenses in support of this requirement.
695 The restrictions on resource ID usage listed above prevent untrusted clients
696 from using GetImage directly on windows not belonging to trusted clients.
700 If an untrusted client tries to set the background-pixmap attribute of an
701 untrusted window to None, the server will instead use a server-dependent
702 background which must be different than None.
706 The X protocol description of <function>GetImage</function> states that the
707 returned contents of regions of a window obscured by noninferior windows are
708 undefined if the window has no backing store. Some implementations return the
709 contents of the obscuring windows in these regions. When an untrusted client
710 uses <function>GetImage</function>, this behavior is forbidden; the server must
711 fill the obscured regions in the returned image with a server-dependent pattern.
715 If an untrusted window has trusted inferiors, their contents are vulnerable
716 to theft via <function>GetImage</function> on the untrusted parent, as well
717 as being vulnerable to destruction via drawing with subwindow-mode
718 IncludeInferiors on the untrusted parent. An untrusted window having trusted
719 inferiors can only occur at the request of a trusted client. It is expected
720 to be an unusual configuration.
725 <sect1 id="property_security">
727 <title>Property Security</title>
730 Unlike the other security provisions described in this document, security for
731 property access is not amenable to a fixed policy because properties are
732 used for inter-client communication in diverse ways and may contain data of
733 varying degrees of sensitivity. Therefore, we only list the possible
734 restrictions the server may decide to impose on use of properties on trusted
735 windows by untrusted clients. How the server chooses which restrictions from
736 this list to apply to a particular property access is implementation dependent
738 In the X Consortium server implementation, property access is controlled by
739 a configuration file; see the -sp option in the Xserver(1) manual page.
743 <para>The X Protocol property requests are
744 <function>ChangeProperty</function>,
745 <function>GetProperty</function>,
746 <function>DeleteProperty</function>,
747 <function>RotateProperties</function>, and
748 <function>ListProperties</function>. For these requests, the server can
749 allow the request to execute normally (as if it had been issued by a
750 trusted client), ignore the request completely (as if it were a NoOperation),
751 or ignore the request except to send an Atom error to the client. Ignoring
752 a <function>ListProperties</function> request means replying that
753 the window has no properties. <function>ListProperties</function> may also
754 reply with a subset of the existing properties if the server is doing
755 property hiding; see below. An ignored <function>GetProperty</function>
756 request may reply that the property does not exist, or that it exists but
761 The server may decide to hide certain properties on certain windows from
764 The X Consortium server implementation does not currently provide a way to
767 If a property is to be hidden, it must be done consistently to avoid
768 confusing clients. This means that for untrusted clients:
774 That property should not be returned by
775 <function>ListProperties</function>.
780 <function>PropertyNotify</function> events should not be sent for that
785 <function>GetProperty</function> on that property should reply that the
786 property does not exist (the return type is None, the format and
787 bytes-after are zero, and the value is empty).
793 For a property that the server is protecting but not hiding, consistency
794 must also be maintained:
800 That property should be returned by <function>ListProperties</function>.
805 <function>PropertyNotify</function> events should be sent for that property.
810 <function>GetProperty</function> on that property should reply that the
811 property exists (if it really does) but the value is empty
812 (return type and format are their real values, and the "length of value"
813 field in the reply is zero).
820 <sect1 id="miscellaneous_security">
821 <title>Miscellaneous Security</title>
824 If an untrusted client attempts to use
825 <function>ChangeHosts</function>,
826 <function>ListHosts</function>, or
827 <function>SetAccessControl</function>,
828 the only effect is that the client receives an Access error.
832 If an untrusted client attempts to use <function>ConvertSelection</function>
833 on a selection with a trusted selection owner window, the server generates
834 a SelectionNotify event to the requestor with property None.
839 <chapter id="new_authorization_method">
840 <title>New Authorization Method</title>
843 This extension includes a new authorization method named
844 "XC-QUERY-SECURITY-1". Its purpose is to allow an external agent such as
845 the X firewall proxy to probe an X server to determine whether that server
846 meets certain security criteria without requiring the agent to have its
847 own authorization for that server. The agent may use the returned information
848 to make a decision. For example, the X firewall proxy may choose not to
849 forward client connections to servers that do not meet the criteria.
853 To use this authorization method, the client (or proxy) sends
854 "XC-QUERY-SECURITY-1" as the authorization-protocol-name in the initial
855 connection setup message. The authorization-protocol-data may be empty or
856 may contain additional security criteria desribed below. If the success
857 field of the server's reply is Authenticate, the server supports the
858 security extension, and the server meets all specified additional security
859 criteria. In this case, the client should resend the initial connection
860 setup message substituting the authorization protocol name and data
861 that should be used to authorize the connection. If the success field of the
862 server's reply is anything other than Authenticate, either the server does not
863 support the security extension, does not meet (or cannot determine if it
864 meets) all of the additional security criteria, or chooses for internal reasons
865 not to answer with Authenticate. In this case, the client should close the
870 If the authorization-protocol-data sent with "XC-QUERY-SECURITY-1" is not
871 empty, it specifies additional security criteria for the server to check, as
876 <function>authorization-protocol-data</function>
884 <para>policy-mask</para>
892 <para>policies</para>
895 <para>LISTofSECURITYPOLICY</para>
908 The policy-mask field is any logical-OR combination of the constants
909 Extensions and SitePolicies. For each bit set in policy-mask, there is a
910 SECURITYPOLICY element in policies. The nth element in policies corresponds
911 to the nth 1-bit in policy-mask, counting upward from bit 0.
914 <para><function>SECURITYPOLICY</function></para>
921 <para>policy-type</para>
924 <para>{Disallow, Permit}</para>
932 <para>LISTofSTR</para>
945 For a SECURITYPOLICY corresponding to policy-mask Extensions, if
946 policy-type is Disallow the server is required to consider as insecure
947 all extensions given in names. No policy is specified for extensions
948 not listed in names. If policy-type is Permit the server may consider
949 only those extensions given in names to be secure; all other extensions
950 must be treated as insecure. If these constraints are not met, the server
951 should not return Authenticate in the success field of the reply.
952 Servers can but need not dynamically configure themselves in response
953 to an Extensions SECURITYPOLICY; a conforming server might simply compare
954 the policy with a compiled-in table of extensions and their security status.
958 For a SECURITYPOLICY corresponding to policy-mask SitePolicies, policy-type
959 Disallow means the server must not have been configured with any of the site
960 policies given in names. Policy-type Permit means the server must have
961 been configured with at least one of the site policies given in names. If
962 these constraints are not met, the server should not return Authenticate in
963 the success field of the reply.
967 SitePolicies provide a way to express new forms of security-relevant
968 information that could not be anticipated at the time of this writing.
969 For example, suppose the server is found to have a critical security defect.
970 When a fix is developed, a site policy string could be associated with the
971 fix. Servers with the fix would advertise that site policy, and the X
972 firewall proxy would specify that site policy in a SECURITYPOLICY with
978 <chapter id="encoding">
979 <title>Encoding</title>
982 Please refer to the X11 Protocol Encoding document as this section
983 uses syntactic conventions and data types established there.
987 The name of this extension is "SECURITY".
997 <sect1 id="request_encoding">
998 <title>Request Encoding</title>
1001 SecurityQueryVersion
1003 <literallayout remap='FD'>
1004 1 CARD8 major-opcode
1007 2 CARD16 client-major-version
1008 2 CARD16 client-minor-version
1012 2 CARD16 sequence number
1014 2 CARD16 server-major-version
1015 2 CARD16 server-minor-version
1020 <function>SecurityRevokeAuthorization</function>
1023 <literallayout remap='FD'>
1024 1 CARD8 major-opcode
1027 4 AUTHID authorization-id
1031 SecurityGenerateAuthorization
1034 <literallayout remap='FD'>
1035 1 CARD8 major-opcode
1037 2 3 + (m+n+3)/4 + s request length
1038 2 CARD16 m, number of bytes in authorization protocol name
1039 2 CARD16 n, number of bytes in authorization data
1040 m STRING8 authorization protocol name
1041 n STRING8 authorization protocol data
1042 p unused, p=pad(m+n)
1043 4 BITMASK value-mask (has s bits set to 1)
1045 #x00000002 trust-level
1047 #x00000008 event-mask
1048 4s LISTofVALUE value-list
1054 <literallayout remap='FD'>
1057 0 SecurityClientTrusted
1058 1 SecurityClientUntrusted
1062 #x00000001 SecurityAuthorizationRevoked
1066 2 CARD16 sequence number
1067 4 (q+3)/4 reply length
1068 4 AUTHID authorization-id
1069 2 CARD16 data-length
1071 q STRING8 authorization-data-return
1077 <sect1 id="event_encoding">
1078 <title>Event Encoding</title>
1080 <function>SecurityAuthorizationRevoked</function>
1083 <literallayout remap='FD'>
1084 1 0+extension event base code
1086 2 CARD16 sequence number
1087 4 AUTHID authorization id
1093 <sect1 id="authorization_method_encoding">
1094 <title>Authorization Method Encoding</title>
1097 For authorization-protocol-name "XC-QUERY-SECURITY-1", the
1098 authorization-protocol-data is interpreted as follows:
1102 <function>authorization-protocol-data</function>
1104 <literallayout remap='FD'>
1105 1 BITMASK policy-mask
1106 #x00000001 Extensions
1107 #x00000002 SitePolicies
1108 m LISTofSECURITYPOLICY policies
1112 <function>SECURITYPOLICY</function>
1115 <literallayout remap='FD'>
1119 1 CARD8 number of STRs in names
1124 LISTofSTR has the same encoding as in the X protocol: each STR is a single
1125 byte length, followed by that many characters, and there is no padding or
1126 termination between STRs.
1131 <chapter id="c_language_binding">
1132 <title>C Language Binding</title>
1135 The header for this extension is <X11/extensions/security.h>. All
1136 identifier names provided by this header begin with XSecurity.
1140 All functions that have return type Status will return nonzero for
1141 success and zero for failure.
1146 <funcdef>Status <function>XSecurityQueryExtension</function></funcdef>
1147 <paramdef>Display <parameter> *dpy</parameter></paramdef>
1148 <paramdef>int <parameter> *major_version_return</parameter></paramdef>
1149 <paramdef>int <parameter> *minor_version_return</parameter></paramdef>
1154 <function>XSecurityQueryExtension</function> sets major_version_return and
1155 minor_version_return to the major and minor Security protocol version
1156 supported by the server. If the Security library is compatible with the
1157 version returned by the server, it returns nonzero. If dpy does not support
1158 the Security extension, or if there was an error during communication with
1159 the server, or if the server and library protocol versions are incompatible,
1160 it returns zero. No other XSecurity functions may be called before this
1161 function. If a client violates this rule, the effects of all subsequent
1162 XSecurity calls that it makes are undefined.
1167 <funcdef>Xauth *<function>XSecurityAllocXauth</function></funcdef>
1168 <paramdef><parameter>void</parameter></paramdef>
1172 In order to provide for future evolution, Xauth structures are used to
1173 pass and return authorization data, and the library provides ways to
1174 allocate and deallocate them.
1178 <function>XSecurityAllocXauth</function> must be used to allocate the
1179 Xauth structure that is passed to
1180 <function>XSecurityGenerateAuthorization</function>.
1184 For the purposes of the Security extension, the Xauth structure has
1185 the following fields:
1192 <entry align="left">
1197 <entry align="left">
1200 <entry align="left">
1201 <para>Field name</para>
1203 <entry align="left">
1204 <para>Description</para>
1208 <entry align="left">
1209 <para>unsigned short</para>
1211 <entry align="left">
1212 <para>name_length</para>
1214 <entry align="left">
1215 <para>number of bytes in name</para>
1219 <entry align="left">
1222 <entry align="left">
1225 <entry align="left">
1226 <para>authorization protocol name</para>
1230 <entry align="left">
1231 <para>unsigned short</para>
1233 <entry align="left">
1234 <para>data_length</para>
1236 <entry align="left">
1237 <para>number of bytes in data</para>
1241 <entry align="left">
1244 <entry align="left">
1247 <entry align="left">
1248 <para>authorization protocol data</para>
1252 <entry align="left">
1257 <entry align="left">
1265 The Xauth structure returned by this function is initialized as follows:
1266 name_length and data_length are zero, and name and data are NULL.
1271 <funcdef>void <function>XSecurityFreeXauth</function></funcdef>
1272 <paramdef>Xauth<parameter> *auth</parameter></paramdef>
1277 <function>XSecurityFreeXauth</function> must be used to free Xauth
1278 structures allocated by
1279 <function>XSecurityAllocXauth</function> or returned by
1280 <function>XSecurityGenerateAuthorization</function>. It is the
1281 caller's responsibility to fill in the name and data fields of Xauth structures
1282 allocated with <function>XSecurityAllocXauth</function>, so this function
1283 will not attempt to free them. In contrast, all storage associated with
1284 Xauth structures returned from
1285 <function>XSecurityGenerateAuthorization</function> will be freed by this
1286 function, including the name and data fields.
1292 <funcdef>Bool <function>XSecurityRevokeAuthorization</function></funcdef>
1293 <paramdef>Display<parameter> *dpy</parameter></paramdef>
1294 <paramdef>XSecurityAuthorization<parameter> auth_id</parameter></paramdef>
1299 <function>XSecurityRevokeAuthorization</function> deletes the authorization
1300 specified by auth_id, which must be a value returned in the auth_id_return
1301 parameter of <function>XSecurityGenerateAuthorization</function>. All
1302 clients that connected with that authorization are be killed. Subsequently,
1303 clients that attempt to connect using that authorization will be refused.
1309 <funcdef>Xauth *<function>XSecurityGenerateAuthorization</function></funcdef>
1310 <paramdef>Display<parameter> *dpy</parameter></paramdef>
1311 <paramdef>Xauth<parameter> *auth_in</parameter></paramdef>
1312 <paramdef>unsigned long<parameter> valuemask</parameter></paramdef>
1313 <paramdef>XSecurityAutorizationAttributes <parameter> *attributes</parameter></paramdef>
1314 <paramdef>XSecurityAutorization<parameter> *auth_id_return</parameter></paramdef>
1319 <function>XSecurityGenerateAuthorization</function> creates a new
1320 authorization with the specified attributes. The auth_in argument must be
1321 allocated by <function>XSecurityAllocXauth</function>. The
1322 name and name_length fields of auth_in should be initialized to the
1323 authorization protocol name and its length in characters respectively.
1324 If there is authorization data, the data and data_length fields of
1325 auth_in should be initialized to the data and its length in characters
1326 respectivley. The library does not assume that name and data are
1327 null-terminated strings. The auth_in argument must be freed with
1328 <function>XSecurityFreeXauth</function>.
1332 The XSecurityAuthorizationAttributes structure has the following fields:
1339 <entry align="left">
1344 <entry align="left">
1347 <entry align="left">
1348 <para>Field name</para>
1350 <entry align="left">
1355 <entry align="left">
1356 <para>unsigned int</para>
1358 <entry align="left">
1359 <para>trust_level</para>
1361 <entry align="left">
1362 <para>XSecurityTrustLevel</para>
1366 <entry align="left">
1367 <para>unsigned int</para>
1369 <entry align="left">
1370 <para>timeout</para>
1372 <entry align="left">
1373 <para>XSecurityTimeout</para>
1377 <entry align="left">
1380 <entry align="left">
1383 <entry align="left">
1384 <para>XSecurityGroup</para>
1388 <entry align="left">
1391 <entry align="left">
1392 <para>event_mask</para>
1394 <entry align="left">
1395 <para>XSecurityEventMask</para>
1399 <entry align="left">
1404 <entry align="left">
1413 These correspond to the trust-level, timeout, group, and event-mask
1414 described in the SecurityGenerateAuthorization protocol request. The
1415 caller can fill in values for any subset of these attributes. The valuemask
1416 argument must be the bitwise OR of the symbols listed in the Mask column
1417 for all supplied attributes. The event_mask attribute can be None,
1418 XSecurityAuthorizationRevokedMask, or XSecurityAllEventMasks. In this
1419 revision of the protocol specification XSecurityAllEventMasks is equivalent
1420 to XSecurityAuthorizationRevokedMask. If the caller does not need to
1421 specify any attributes, the attributes argument can be NULL, and the
1422 valuemask argument must be zero.
1425 If the function fails, NULL is returned and auth_id_return is filled in
1426 with zero. Otherwise, a pointer to an Xauth structure is returned. The name
1427 and name_length fields of the returned Xauth structure will be copies of the
1428 name that was passed in, and the data and data_length fields will be set to
1429 the authorization data returned by the server. The caller should not assume
1430 that name and data are null-terminated strings. If no authorization data was
1431 returned by the server, the data and data_length fields will be set to NULL
1432 and zero repectively. The returned Xauth structure must be freed with
1433 <function>XSecurityFreeXauth</function>; the caller should not use any other
1434 means free the structure or any of its components. The auth_id_return
1435 argument will be filled in with the non-zero authorization id of the created
1440 The XSecurityAuthorizationRevokedEvent structure has the following fields:
1447 <entry align="left">
1452 <entry align="left">
1455 <entry align="left">
1456 <para>Field name</para>
1458 <entry align="left">
1459 <para>Description</para>
1464 <entry align="left">
1467 <entry align="left">
1470 <entry align="left">
1471 <para>event base + XSecurityAuthorizationRevoked</para>
1475 <entry align="left">
1476 <para>unsigned long</para>
1478 <entry align="left">
1481 <entry align="left">
1482 <para># of last request processed by server</para>
1486 <entry align="left">
1489 <entry align="left">
1490 <para>send_event</para>
1492 <entry align="left">
1493 <para>true if this came from SendEvent</para>
1497 <entry align="left">
1498 <para>Display*</para>
1500 <entry align="left">
1501 <para>display</para>
1503 <entry align="left">
1504 <para>Display the event was read from</para>
1508 <entry align="left">
1509 <para>XSecurityAuthorization</para>
1511 <entry align="left">
1512 <para>auth_id</para>
1514 <entry align="left">
1515 <para>revoked authorization id</para>
1519 <entry align="left">
1524 <entry align="left">