Xsecure(3X11) SDK X11 R4.11MU05 Xsecure(3X11)
NAME
Xsecure, XsecureQueryExtension, XsecureSetInactivityTimeout,
XsecureKillAllClients, XsecureAllowUntrustedClients,
XsecureRestrictGrabs, XsecureAllowGrabs, XsecureGetResourceLabel,
XsecureChangeDisplayHeight, XsecureSetClearance,
XsecureGetInactivityTimeout, XsecureGetClientInfo,
XsecureSetClientCapabilities, XsecureCopyProperty,
XsecureGetPropertyLabel, XsecureChangePropertyLabel,
XsecureSetDisplayACL, XsecureFreeDisplayACL, XsecureGetDisplayACL,
XsecureSetResourceLabel, XsecureClearResetWindow -- Xsecure routines
in the X extension library (libXext)
SYNOPSIS
Xsecure - The Xsecure extension
DESCRIPTION
This manpage describes the new routines provided in the xsecurity
extension. It also describes two new events which are part of the
xsecurity extension. They are defined in
/usr/include/X11/extensions/Xsecure.h and are part of the libXext
library. Definitions of the other X specific types can be found in
/usr/include/X11/X.h and /usr/include/X11/Xlib.h.
Bool XsecureQueryExtension (
Display *display,
int *event_base,
int *error_base)
Status XsecureSetInactivityTimeout(
Display *display,
long timeout)
Status XsecureKillAllClients(
Display *display)
Status XsecureAllowUntrustedClients(
Display *display)
Status XsecureRestrictGrabs(
Display *display)
Status XsecureAllowGrabs(
Display *display)
Status XsecureGetResourceLabel(
Display *display,
XID resource,
Atom rtype,
Atom ltype,
long *plength,
unsigned char **plabel)
Status XsecureChangeDisplayHeight(
Display *display,
Window window,
long height,
long *new_height)
Status XsecureSetClearance(
Display *display,
long length,
unsigned char *plabel)
Status XsecureGetInactivityTimeout(
Display *display,
long *ptimeout,
long *ptimeleft)
Status XsecureGetClientInfo(
Display *display,
XID resource,
long *puid,
long *pcapabilities)
Status XsecureSetClientCapabilities(
Display *display,
long *pcapabilities)
Status XsecureCopyProperty(
Display *display,
Window source,
Window destination,
Atom property,
char mode,
Bool delete)
Status XsecureGetPropertyLabel(
Display *display,
Window window,
Atom property,
long *plength,
unsigned char **plabel)
Status XsecureChangePropertyLabel(
Display *display,
Window window,
Atom property,
long length,
unsigned char *plabel)
Status XsecureSetDisplayACL(
Display *display,
long entries,
struct XsecureDisplayACL *pacl)
Status XsecureFreeDisplayACL(
struct XsecureDisplayACL **pacl,
long nentries)
Status XsecureGetDisplayACL(
Display *display,
struct XsecureDisplayACL ***pacl,
long *pnentries,
long *penabled)
Status XsecureSetResourceLabel(
Display *display,
XID resource,
Atom rtype,
Atom ltype,
long length,
unsigned char *plabel)
Status XsecureClearResetWindow(
Display *display,
Window window)
DETAILS
SYNTAX
Bool XsecureQueryExtension (display, eventbase, errorbase)
Display *display;
int *eventbase;
int *errorbase;
ARGUMENTS
display specifies the connection to the X server
eventbase event base for this extension
errorbase error base for this extension
DESCRIPTION
XsecureQueryExtension does any initialization required by the
xsecurity extension. This should be the first call into the xsecurity
extension routines. The event_base should be subtracted from the
event code when comparing with the new events associated with the
xsecure extension. This is also true for the error_base and errors
resulting from the new extension routines. If the reply fails or
this extension is not supported by the Xserver, XsecureQueryExtension
will return False, otherwise True.
SYNTAX
Status XsecureSetInactivityTimeout(display, timeout)
Display *display;
long timeout;
ARGUMENTS
display specifies the connection to the X server
timeout specifies the time, in seconds, which must pass before
the server generates an inactivity timeout event.
DESCRIPTION
XsecureSetInactivityTimeout will set the new timeout interval for the
X server. If this time period passes without input from either the
keyboard or pointer, the server will generate a
SecureInactivityTimeout event. The event is reported to the root
window of the display. The client making this request must have the
dg_cap_xwindow_manager capability for it to be successful. If this
routine fails, or the extension is not supported by the Xserver,
XsecureSetInactivityTimeout will return False, otherwise True.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
SYNTAX
Status XsecureKillAllClients(display)
Display *display;
ARGUMENTS
display specifies the connection to the X server
DESCRIPTION
XsecureKillAllClients will cause the X server specified by the
display variable to kill all clients connected to the display, with
the exception of the client making the call. This call will fail if
the calling client does not have the dg_cap_xwindow_manager
capability.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
SYNTAX
Status XsecureKillAllClients(display)
Display *display;
ARGUMENTS
display specifies the connection to the X server
DESCRIPTION
XsecureAllowUntrustedClients allows non-trusted clients to display
windows on the specified display. Until a client with
dg_cap_xwindow_manager capabilities makes this call, only trusted
clients are allowed to display. Untrusted clients attempting to
connect before this routine is called will receive a message from the
server indicating that the server is not accepting connections from
untrusted clients. Clients making this call must have the
dg_cap_xwindow_manager capability.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
SYNTAX
Status XsecureRestrictGrabs(display)
Display *display;
ARGUMENTS
display specifies the connection to the X server
DESCRIPTION
XsecureRestrictGrabs restricts pointer and keyboard grabs on the
specified display to trusted clients. It has no effect on grabs which
already exist. The calling client must have the
dg_cap_xwindow_manager capability.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
SYNTAX
Status XsecureRestrictGrabs(display)
Display *display;
ARGUMENTS
display specifies the connection to the X server
DESCRIPTION
XsecureAllowGrabs allows non-trusted clients to grab the pointer and
keyboard. This is the reverse of XsecureRestrictGrabs. The calling
client must have the dg_cap_xwindow_manager capability.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
SYNTAX
Status XsecureGetResourceLabel(display, resource, rtype, ltype,
plength, plabel)
Display *display;
XID resource;
Atom rtype;
Atom ltype;
long *plength;
unsigned char **plabel;
ARGUMENTS
display specifies the connection to the X server
resource X resource for which the label should be changed
rtype type of the resource
ltype which type of label to get (XA_SENSITIVITY_LABEL)
plength pointer to the length, in bytes, of the label returned by
the server
plabel pointer to the label returned by the server
DESCRIPTION
XsecureGetResourceLabel returns the requested label along with its
length. The possible label type is only XA_SENSITIVITY_LABEL. The
label is in the format of the X server. Upon success the label is
returned in a buffer pointed to by plabel. This value should be
freed using XFree when it is no longer needed. The label of the
requesting client must dominate that of the resource, or the process
must have the dg_cap_xserver_mac_override capability. In addition,
for pixmaps, the requesting client must own the object or have the
dg_cap_xwindow_owner capability.
DIAGNOSTICS
BadAtom The value for ltype was invalid, or the resource type was
XA_ATOM, but the specified atom did not exist, or the
requesting client did not have sufficient privilege to
access the atom.
BadColor The resource was type XA_COLORMAP, but the process did
not have sufficient privilege to access the colormap or
the specified colormap was non-existent.
BadMatch The value for rtype was invalid.
BadPixmap The resource was type XA_PIXMAP, but the process did not
have sufficient privilege to access the pixmap or the
specified pixmap was non-existent.
BadWindow The resource was of type window, but the specified window
was non-existent or the requesting client did not have
sufficient privilege to access the window.
SYNTAX
Status XsecureGetResourceLabel(display, resource, rtype, ltype,
plength, plabel)
Display *display;
Window window;
long height;
long *newheight;
ARGUMENTS
display specifies the connection to the X server
window any child of the root window
height amount, in pixels, by which to reduce the height of the
screen
newheight new height of the display
DESCRIPTION
XsecureChangeDisplayHeight modifies the height of the display such
that DisplayHeight() will return a new height smaller (by height)
than the true height. Calls to this routine are not cumulative. This
is so that the window manager can create space for a trusted path
bar. This routine requires the dg_cap_xwindow_manager capability.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
BadValue The height is not less than the true height of the
display
BadWindow The specified window does not exist.
SYNTAX
Status XsecureSetClearance(display, length, plabel)
Display *display;
long length;
unsigned char *plabel;
ARGUMENTS
display specifies the connection to the X server
length length of the label in bytes
plabel pointer to the label
DESCRIPTION
XsecureSetClearance sets the maximum clearance label for the X
server. The server will restrict connections to clients whose
sensitivity label is dominated by the specified clearance label. The
clearance label is initially IMPL_HI. The label is in the server's
format and is pointed to by plabel. If length is 0, plabel should be
NULL and the clearance label will effectively be IMPL_HI; that is,
connections will be allowed at any clearance. This routine requires
the dg_cap_xwindow_manager capability to succeed.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
BadValue The length argument is invalid.
SYNTAX
Status XsecureSetClearance(display, length, plabel)
Display *display;
long *ptimeout;
long *ptimeleft;
ARGUMENTS
display specifies the connection to the X server
ptimeout current timeout value
ptimeleft time left until timeout event
DESCRIPTION
XsecureGetInactivityTimeout returns the current value of the timeout
value on the X server as well as the time remaining until a timeout
event is generated by the server.
SYNTAX
Status XsecureGetClientInfo(display, resource, puid, pcapabilities)
Display *display;
XID resource;
int *puid;
char *pcapabilities;
ARGUMENTS
display specifies the connection to the X server
resource X resource for which the information is requested
puid login uid of owning client
pcapabilities
capabilities vector
DESCRIPTION
XsecureGetClientInfo returns the user id of the owner of the
specified resource and the effective capabilities of the client who
owns the resource. The capabilities are eight bytes in length and are
stored in the location pointed to by pcapabilities. This space is
allocated by the calling process. If resource is 0, then the user id
and capabilities returned will be those of the requesting client.
The requesting client must have the dg_cap_xwindow_owner capability
in order to access the capabilities of another clients resource.
DIAGNOSTICS
BadAccess The client making the request did not have sufficient
privilege.
BadValue The specified resource does not exist.
SYNTAX
Status XsecureGetClientInfo(display, resource, puid, pcapabilities)
Display *display;
long *pcapabilities;
ARGUMENTS
display specifies the connection to the X server
pcapabilities
capabilities vector (X server format)
DESCRIPTION
XsecureSetClientCapabilities sets the effective capabilities
maintained by the server for the calling client. The capabilities
are in the format maintained by the server. The capabilites are eight
bytes in length and are stored in the location pointed to by
pcapabilities. This space is allocated by the calling process. This
call will fail with a BadValue error if the requested capabilities
are not dominated by the clients maximum privilege set.
DIAGNOSTICS
BadValue The maximum capabilities set of the client making the
request did not dominate the specified capabilities
SYNTAX
Status XsecureCopyProperty(display, source, destination, property,
mode, delete)
Display *display;
Window source;
Window destination;
Atom property;
char mode;
Bool delete;
ARGUMENTS
display specifies the connection to the X server
source resource from which the property is copied
destination resource to which the property is copied
property atom specifying property to be copied
mode PropModeReplace, PropModePrepend, PropModeAppend
delete delete property flag
DESCRIPTION
XsecureCopyProperty copies the specified property from the source
window to the destination window. If mode is PropModeReplace, the
previous value of the property on the destination window is replaced
with the new value. If the property already exists on the destination
window and mode is PropModePrepend or PropModeAppend, then the type
and format of the property on the source window must match those of
the property on the destination window; otherwise, a BadMatch error
results. If the property does not exist on either window, no action
is taken. If the property exists only on the destination window,
processing occurs as if a zero length property of matching type and
format exists on the source window. If delete is specified as True
and the property exists on the source window, it is deleted and a
PropertyNotify event is generated on that window. A PropertyNotify
event is delivered to the destination window if the property exists
on either window.
DIAGNOSTICS
BadAlloc The server could not allocate enough memory.
BadAtom The specified atom is not defined.
BadMatch The specified property exists on both windows but the
formats or types of the properties are not the same and
the mode is PropModePrepend or PropModeAppend.
BadValue Some numeric value falls outside the range of values
accepted by the request. Unless a specific range is
specified for an argument, the full range defined by the
argument's type is accepted. Any argument defined as a
set of alternatives can generate this error.
BadWindow The source or destination window does not exist, or the
requesting client does not own both destination and
source windows or have the dg_cap_xwindow_owner
capability.
SYNTAX
Status XsecureSetDisplayACL(display, entries, pacl)
Display *display;
long entries;
struct XsecureDisplayACL *pacl;
ARGUMENTS
display specifies the connection to the X server
entries number of entries in acl
pacl an array of XsecureDisplayACL structures
DESCRIPTION
XsecureSetDisplayACL sets the controlling ACL for the display; access
control is enabled upon receipt of this request. The array of acl
entries specifies which machines and users should be allowed or
denied access to the server. Local clients are clients which have
the same internet address as the X server, or in the case of xdm
controlled displays, clients which have the same internet address as
the xdm client. A value of zero for entries indicates a NULL acl and
limits server access to local clients with the dg_cap_xwindow_manager
capability. A value of -1 for the user field in an XsecureDisplayACL
structure indicates any user. A value of -1 for the family field
indicates any host. An array consisting of a single member with the
user field set to -1, the family field set to -1 and the access field
set to ACCESS_GRANTED indicates that the server may be accessed by
any user from any host, disabling access control. This routine can
only be accessed by local clients having the dg_cap_xwindow_manager
capability.
DIAGNOSTICS
BadAccess The client making the request was not a local client
having the dg_cap_xwindow_manager capability.
BadAlloc There was insufficient memory for the request to be sent
to the X server.
BadAccess The client making the request was not a local client.
BadValue The family field of the acl is something other than
FamilyInternet or the access field is something besides
ACCESS_DENIED or ACESS_GRANTED.
SYNTAX
Status XsecureFreeDisplayACL(pacl, nentries)
struct XsecureDisplayACL **pacl;
long nentries;
ARGUMENTS
pacl address of acl to be freed
nentries number of acl entries
DESCRIPTION
XsecureFreeDisplayACL frees the memory allocated in
XsecureGetDisplayACL. This includes the array of pointers, the
structures pointed to by this array and the addresses pointed to in
the address fields of the XsecureDisplayACL struct. If any of these
are to be retained after calling XsecureFreeDisplayACL, they should
be copied before making the call.
SYNTAX
Status XsecureFreeDisplayACL(pacl, nentries)
Display *display;
struct XsecureDisplayACL ***pacl;
long *pnentries;
long *penabled;
ARGUMENTS
display specifies the connection to the X server
pacl returned array of XsecureDisplayACL structures pointers
pnentries number of acl entries
penabled is access control enabled
DESCRIPTION
XsecureGetDisplayACL returns the ACL controlling the server display,
the number of entries in the ACL, and whether or not access control
is enabled. The value returned in pacl is an array of pointers to
XsecureDisplayACL structures. This space should be freed using
XsecureFreeDisplayACL when it is no longer needed. If the server
display ACL contains no entries, the value returned in pnentries is 0
and the value returned in pacl is NULL. This is also true if the
server access control is disabled.
DIAGNOSTICS
BadAlloc Insufficient memory to contain the structures received
from the X server.
SYNTAX
Status XsecureSetResourceLabel(display, resource, rtype, ltype,
length, plabel)
Display *display;
XID resource;
Atom rtype;
Atom ltype;
long length;
unsigned char *plabel;
ARGUMENTS
display specifies the connection to the X server
resource X resource for which the label is to be changed
rtype type of the X resource
ltype type of label (XA_SENSITIVITY_LABEL)
length length of label
plabel label (X server format)
DESCRIPTION
XsecureSetResourceLabel sets the appropriate label on the given
resource. The possible label type is currently only
XA_SENSITIVITY_LABEL. The plabel argument is a pointer to a server-
style label. Currently, the only supported resource type is
XA_WINDOW. The mac label of the requesting client must dominate that
of the specified resource, or the requesting client must have the
dg_cap_xserver_mac_override capability when modifying the sensitivity
label.
DIAGNOSTICS
BadAlloc Server had insufficient memory to allocate the label
value.
BadMatch Rtype is something other than XA_WINDOW.
BadValue The argument for ltype is not XA_SENSITIVITY_LABEL.
BadWindow The client had insufficient privilege or mac label to
complete the request.
SYNTAX
Status XsecureSetResourceLabel(display, resource, rtype, ltype,
length, plabel)
Display *display;
Window window;
ARGUMENTS
display specifies the connection to the X server
window target window
DESCRIPTION
XsecureClearResetWindow resets the information label of the specified
window and generates a ClearResetNotify event for that window. This
event is delivered to all clients that have selected for the event
using the ClearResetNotifyMask on the target window.
DIAGNISTICS
BadAccess The requesting client does not have the
dg_cap_xwindow_manager capability.
BadWindow The specified window does not exist.
STRUCTURES
The following are structures used in some of the above extensions.
The XsecureDisplayACL Structure
The XsecureDisplayACL structure is defined in Xsecure.h as follows:
struct XDisplayACL {
int family; /* protocol family, now: FamilyInternet (or -1) */
int length; /* length of address in bytes */
void *address; /* internet address */
int user; /* login id (or -1) */
int access; /* ACCESS_GRANTED or ACCESS_DENIED */
};
The family entry can currently only be FamilyInternet. The length
field is the length of the address which is pointed to by the
address field. This address is in the FamilyInternet format. There
may be additional address formats supported in the future. The user
field contains the user id. The access field contains either
ACCESS_DENIED or ACCESS_GRANTED. If the family field is -1, it
is interpreted as matching any host name value. If the user field
is -1, it is interpreted as matching any user.
Xsecure Notify event structure
There are two new events, SecureClearResetNotify and
SecureInactivityNotify. They both have identical event structures,
also defined in Xsecure.h:
typedef struct {
int type; /* type of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if event is from a SendEvent request */
Display *display; /* Display from which the event was read */
Window window; /* Window receiving the event */
} XsecureNotifyEvent;
The SecureInactivityNotify event occurs when the inactivity timeout
expires. The window field always has a value of 0. The
SecureClearResetNotify event is sent whenever a successful call to
XsecureClearResetWindow occurs. The window field is the window
passed to the call to XsecureClearResetWindow. These events are
requested using the SecureInactivityNotifyMask and the
SecureClearResetNotifyMask.
NOTES
This extension is supported only on Tektronix X terminals.
The DG/UX system does not support information labels; they are,
however, supported by the Tektronix X terminal.
Licensed material--property of copyright holder(s)