Accessing protected X server interfaces
Note: This section is only relevant if your application requires access to protected X server interfaces, therefore it is not relevant to the majority of Harmattan developers.
In an upcoming MeeGo 1.2 Harmattan release, certain X server interfaces will be protected and the credentials to access them will be introduced. For a general introduction to this subject, see X Window System Wikipedia article.
By default, applications are not allowed to monitor input events, or synthesise input events for other applications. Reading the contents of windows and pixmaps that belong to other applications is also prohibited. Separate X clients (connections to X server) are considered to belong to the same application if a parent-child relationship exists between the processes that have created the X connections. Therefore applications are considered separate, if their X connections have been created from separate branches in the process tree.
Full access to services provided by the X server is provided with Aegis credentials. If an application tries to use protected interfaces without appropriate credentials, some events might be filtered, some responses may be partially censored and some requests may result in a BadAccess or BadRequest error. Note: The Aegis manifest file generation tool cannot detect the need for X server credentials. You must edit the Aegis manifest file manually.
Applications need access to protected X server interfaces only in special cases. Examples of such applications are:
- Screen shot application: see Reading window contents.
- Application that uses a virtual keyboard which is implemented in a different process than the application: see Synthesising input events.
- Application that replays input events, such as a test automation tool: see Listening to input events.
- (Legacy) applications that share images via X mechanisms (pixmaps or windows), for example, in a multi-process architecture: see Sharing window and pixmap contents.
- Window managers, especially compositing window managers: see Window management.
The following credentials and interfaces affect X server access:
- xserver-security-policy::record-input: Receive input events without restrictions.
- xserver-security-policy::playback-input: Send input events without restrictions.
- xserver-security-policy::capture-drawables: Read window contents without restrictions.
- XSERVER_SECURITY_POLICY_SHARE_DRAWABLE: Client message type for sharing individual drawables.
- All credentials simultaneously: Manage windows without restrictions.
Adding the required credential for X server access
To enable X server access for your application, you need to use credential matching mechanism, instead of the credential name. This is done by adding the line <credential match="<credential>" /> to the Aegis manifest file.
Example:
<credential match="xserver-security-policy::record-input" />
For instructions on editing the Aegis manifest file manually, see:
- Creating the Aegis manifest file manually with Qt SDK
- Creating the Aegis manifest file manually with Platform SDK
Listening to input events
By default, clients have no access to listen to input events of another application. To enable listening to input events, use the xserver-security-policy::record-input. However, some mechanisms have been modified in order to protect applications.
Affected interfaces:
- XRecord
- ChangeWindowAttributes
- XISelectEvents
- GrabPointer
- GrabButton
- GrabKeyboard
- GrabKey
- XIGrabDevice
- XIPassiveGrabDevice
- QueryKeymap
- QueryPointer
- GetMotionEvents
- XIQueryPointer
- XIQueryDevice
- GetDeviceMotionEvents
Synthesising input events
By default, clients are not allowed to send events such as key presses to other applications. To enable synthesising input events, you need to use the xserver-security-policy::playback-input.
Affected interfaces:
- XTest
- SendEvent
Reading window contents
By default, clients are not allowed to read the contents of windows or pixmaps that belong to other applications. There are some exceptions to this rule as applications sometimes need to access the drawable areas of components that have been designed to share content, such as status menu and theme daemon. In these cases, credentials are not needed.
To read the contents of windows or pixmaps of other applications in a way that compositing window manager would, the application must include the security credentials. In order to read contents of drawable areas that belong to other applications, you need to use the xserver-security-policy::capture-drawables credential.
Affected interfaces:
- CopyArea
- CopyPlane
- GetImage
- ShmGetImage
- CompositeNameWindowPixmap
- RenderCreatePicture
- RenderComposite
- RenderCompositeGlyphs
- DRI2GetBuffers
- DRI2GetBuffersWithFormat
Sharing window and pixmap contents
Some applications need to share their window and pixmap contents to other applications. In order to enable that, the application must send a properly formatted client message to the X server. A properly formatted client message contains an event of type ClientMessage that is sent with the SendEvent request as described below.
Constructing a proper client message type
Atom message = XInternAtom(d, "XSERVER_SECURITY_POLICY_SHARE_DRAWABLE", True);
If the returned atom is None, the X server security is not active and there is no point in executing the related SendEvent request.
For efficiency, use XInternAtoms if the application interns multiple atoms.
Constructing a proper client message
In the following example drawableToShare can be a window or a pixmap ID. The drawable can be shared or protected with the isDrawableShared boolean variable.
XClientMessageEvent event = { 0 };
event.type = ClientMessage;
event.window = drawableToShare;
event.message_type = message;
event.format = 8;
event.data.b[0] = isDrawableShared;
Null resource ID None can be also used in place of drawableToShare. This is intended for applications that want to share all of their drawables by default.
To share all (protect none) drawables by default regardless of the sharing status of individual drawables, use the following:
event.window = None; event.data.b[0] = False;
To not share any drawables by default and to check sharing status of each individual drawable, use the following:
event.window = None; event.data.b[0] = True;
Sending the message to server client (creator of root window)
Send the message with the following command:
XSendEvent(d, DefaultRootWindow(d), False, 0, (XEvent *)&event);
Note: The sent message has an effect only if the drawable is valid and owned by the application that issues the request.
Window management
Clients are not allowed to manage windows that are owned by other applications. In order to manage windows, all xserver-security-policy credentials are needed. This feature is relevant if you want to test your own window manager in Harmattan, or if you want to use certain X tools such as xkbwatch. Applications submitted to Nokia Store are not allowed to manage the windows of other applications.
Affected interfaces:
- CreateWindow
- ConfigureWindow
- All similar requests dealing with the window hierarchy.