|
|
1
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
2
|
+<protocol name="ext_session_lock_v1">
|
|
|
3
|
+ <copyright>
|
|
|
4
|
+ Copyright 2021 Isaac Freund
|
|
|
5
|
+
|
|
|
6
|
+ Permission to use, copy, modify, and/or distribute this software for any
|
|
|
7
|
+ purpose with or without fee is hereby granted, provided that the above
|
|
|
8
|
+ copyright notice and this permission notice appear in all copies.
|
|
|
9
|
+
|
|
|
10
|
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
11
|
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
12
|
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
13
|
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
14
|
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
15
|
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
16
|
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
17
|
+ </copyright>
|
|
|
18
|
+
|
|
|
19
|
+ <description summary="secure session locking with arbitrary graphics">
|
|
|
20
|
+ This protocol allows for a privileged Wayland client to lock the session
|
|
|
21
|
+ and display arbitrary graphics while the session is locked.
|
|
|
22
|
+
|
|
|
23
|
+ The compositor may choose to restrict this protocol to a special client
|
|
|
24
|
+ launched by the compositor itself or expose it to all privileged clients,
|
|
|
25
|
+ this is compositor policy.
|
|
|
26
|
+
|
|
|
27
|
+ The client is responsible for performing authentication and informing the
|
|
|
28
|
+ compositor when the session should be unlocked. If the client dies while
|
|
|
29
|
+ the session is locked the session remains locked, possibly permanently
|
|
|
30
|
+ depending on compositor policy.
|
|
|
31
|
+
|
|
|
32
|
+ Warning! The protocol described in this file is currently in the
|
|
|
33
|
+ testing phase. Backward compatible changes may be added together with
|
|
|
34
|
+ the corresponding interface version bump. Backward incompatible changes
|
|
|
35
|
+ can only be done by creating a new major version of the extension.
|
|
|
36
|
+ </description>
|
|
|
37
|
+
|
|
|
38
|
+ <interface name="ext_session_lock_manager_v1" version="1">
|
|
|
39
|
+ <description summary="used to lock the session">
|
|
|
40
|
+ This interface is used to request that the session be locked.
|
|
|
41
|
+ </description>
|
|
|
42
|
+
|
|
|
43
|
+ <request name="destroy" type="destructor">
|
|
|
44
|
+ <description summary="destroy the session lock manager object">
|
|
|
45
|
+ This informs the compositor that the session lock manager object will
|
|
|
46
|
+ no longer be used. Existing objects created through this interface
|
|
|
47
|
+ remain valid.
|
|
|
48
|
+ </description>
|
|
|
49
|
+ </request>
|
|
|
50
|
+
|
|
|
51
|
+ <request name="lock">
|
|
|
52
|
+ <description summary="attempt to lock the session">
|
|
|
53
|
+ This request creates a session lock and asks the compositor to lock the
|
|
|
54
|
+ session. The compositor will send either the ext_session_lock_v1.locked
|
|
|
55
|
+ or ext_session_lock_v1.finished event on the created object in
|
|
|
56
|
+ response to this request.
|
|
|
57
|
+ </description>
|
|
|
58
|
+ <arg name="id" type="new_id" interface="ext_session_lock_v1"/>
|
|
|
59
|
+ </request>
|
|
|
60
|
+ </interface>
|
|
|
61
|
+
|
|
|
62
|
+ <interface name="ext_session_lock_v1" version="1">
|
|
|
63
|
+ <description summary="manage lock state and create lock surfaces">
|
|
|
64
|
+ On creation of this object either the locked or finished event will
|
|
|
65
|
+ immediately be sent.
|
|
|
66
|
+
|
|
|
67
|
+ The locked event indicates that the session is locked. This means that
|
|
|
68
|
+ the compositor should stop rendering and providing input to normal
|
|
|
69
|
+ clients. Instead the compositor should blank all outputs with an opaque
|
|
|
70
|
+ color such that their normal content is fully hidden.
|
|
|
71
|
+
|
|
|
72
|
+ The only surfaces that should be rendered while the session is locked
|
|
|
73
|
+ are the lock surfaces created through this interface and optionally,
|
|
|
74
|
+ at the compositor's discretion, special privileged surfaces such as
|
|
|
75
|
+ input methods or portions of desktop shell UIs.
|
|
|
76
|
+
|
|
|
77
|
+ If the client dies while the session is locked, the compositor should not
|
|
|
78
|
+ unlock the session in response. It is acceptable for the session to be
|
|
|
79
|
+ permanently locked if this happens. The compositor may choose to continue
|
|
|
80
|
+ to display the lock surfaces the client had mapped before it died or
|
|
|
81
|
+ alternatively fall back to a solid color, this is compositor policy.
|
|
|
82
|
+
|
|
|
83
|
+ Compositors may also allow a secure way to recover the session, the
|
|
|
84
|
+ details of this are compositor policy. Compositors may allow a new
|
|
|
85
|
+ client to create a ext_session_lock_v1 object and take responsibility
|
|
|
86
|
+ for unlocking the session, they may even start a new lock client
|
|
|
87
|
+ instance automatically.
|
|
|
88
|
+ </description>
|
|
|
89
|
+
|
|
|
90
|
+ <enum name="error">
|
|
|
91
|
+ <entry name="invalid_destroy" value="0"
|
|
|
92
|
+ summary="attempted to destroy session lock while locked"/>
|
|
|
93
|
+ <entry name="invalid_unlock" value="1"
|
|
|
94
|
+ summary="unlock requested but locked event was never sent"/>
|
|
|
95
|
+ <entry name="role" value="2"
|
|
|
96
|
+ summary="given wl_surface already has a role"/>
|
|
|
97
|
+ <entry name="duplicate_output" value="3"
|
|
|
98
|
+ summary="given output already has a lock surface"/>
|
|
|
99
|
+ <entry name="already_constructed" value="4"
|
|
|
100
|
+ summary="given wl_surface has a buffer attached or committed"/>
|
|
|
101
|
+ </enum>
|
|
|
102
|
+
|
|
|
103
|
+ <request name="destroy" type="destructor">
|
|
|
104
|
+ <description summary="destroy the session lock">
|
|
|
105
|
+ This informs the compositor that the lock object will no longer be
|
|
|
106
|
+ used. Existing objects created through this interface remain valid.
|
|
|
107
|
+
|
|
|
108
|
+ After this request is made, lock surfaces created through this object
|
|
|
109
|
+ should be destroyed by the client as they will no longer be used by
|
|
|
110
|
+ the compositor.
|
|
|
111
|
+
|
|
|
112
|
+ It is a protocol error to make this request if the locked event was
|
|
|
113
|
+ sent, the unlock_and_destroy request must be used instead.
|
|
|
114
|
+ </description>
|
|
|
115
|
+ </request>
|
|
|
116
|
+
|
|
|
117
|
+ <event name="locked">
|
|
|
118
|
+ <description summary="session successfully locked">
|
|
|
119
|
+ This client is now responsible for displaying graphics while the
|
|
|
120
|
+ session is locked and deciding when to unlock the session.
|
|
|
121
|
+
|
|
|
122
|
+ Either this event or the finished event will be sent immediately on
|
|
|
123
|
+ creation of this object.
|
|
|
124
|
+
|
|
|
125
|
+ If this event is sent, making the destroy request is a protocol error,
|
|
|
126
|
+ the lock object may only be destroyed using the unlock_and_destroy
|
|
|
127
|
+ request.
|
|
|
128
|
+ </description>
|
|
|
129
|
+ </event>
|
|
|
130
|
+
|
|
|
131
|
+ <event name="finished">
|
|
|
132
|
+ <description summary="the session lock object should be destroyed">
|
|
|
133
|
+ The compositor has decided that the session lock should be
|
|
|
134
|
+ destroyed. Exactly when this event is sent is compositor policy, but
|
|
|
135
|
+ it will never be sent more than once for a given session lock object.
|
|
|
136
|
+
|
|
|
137
|
+ This might be sent because there is already another ext_session_lock_v1
|
|
|
138
|
+ object held by a client, or the compositor has decided to deny the
|
|
|
139
|
+ request to lock the session for some other reason. This might also
|
|
|
140
|
+ be sent because the compositor implements some alternative, secure
|
|
|
141
|
+ way to authenticate and unlock the session.
|
|
|
142
|
+
|
|
|
143
|
+ Either this event or the locked event will be sent exactly once on
|
|
|
144
|
+ creation of this object. If the locked event is sent on creation of
|
|
|
145
|
+ this object, the finished event may still be sent at some later time
|
|
|
146
|
+ in this object's lifetime, this is compositor policy.
|
|
|
147
|
+
|
|
|
148
|
+ Upon receiving this event, the client should make either the destroy
|
|
|
149
|
+ request or the unlock_and_destroy request, depending on whether or
|
|
|
150
|
+ not the locked event was received on this object.
|
|
|
151
|
+ </description>
|
|
|
152
|
+ </event>
|
|
|
153
|
+
|
|
|
154
|
+ <request name="get_lock_surface">
|
|
|
155
|
+ <description summary="create a lock surface for a given output">
|
|
|
156
|
+ The client is expected to create lock surfaces for all outputs
|
|
|
157
|
+ currently present and any new outputs as they are advertised. These
|
|
|
158
|
+ won't be displayed by the compositor unless the lock is successful
|
|
|
159
|
+ and the locked event is sent.
|
|
|
160
|
+
|
|
|
161
|
+ Providing a wl_surface which already has a role or already has a buffer
|
|
|
162
|
+ attached or committed is a protocol error, as is attaching/committing
|
|
|
163
|
+ a buffer before the first ext_session_lock_surface_v1.configure event.
|
|
|
164
|
+
|
|
|
165
|
+ Attempting to create more than one lock surface for a given output
|
|
|
166
|
+ is a duplicate_output protocol error.
|
|
|
167
|
+ </description>
|
|
|
168
|
+ <arg name="id" type="new_id" interface="ext_session_lock_surface_v1"/>
|
|
|
169
|
+ <arg name="surface" type="object" interface="wl_surface"/>
|
|
|
170
|
+ <arg name="output" type="object" interface="wl_output"/>
|
|
|
171
|
+ </request>
|
|
|
172
|
+
|
|
|
173
|
+ <request name="unlock_and_destroy" type="destructor">
|
|
|
174
|
+ <description summary="unlock the session, destroying the object">
|
|
|
175
|
+ This request indicates that the session should be unlocked, for
|
|
|
176
|
+ example because the user has entered their password and it has been
|
|
|
177
|
+ verified by the client.
|
|
|
178
|
+
|
|
|
179
|
+ This request also informs the compositor that the lock object will
|
|
|
180
|
+ no longer be used and may be safely destroyed. Existing objects
|
|
|
181
|
+ created through this interface remain valid.
|
|
|
182
|
+
|
|
|
183
|
+ After this request is made, lock surfaces created through this object
|
|
|
184
|
+ should be destroyed by the client as they will no longer be used by
|
|
|
185
|
+ the compositor.
|
|
|
186
|
+
|
|
|
187
|
+ It is a protocol error to make this request if the locked event has
|
|
|
188
|
+ not been sent. In that case, the lock object may only be destroyed
|
|
|
189
|
+ using the destroy request.
|
|
|
190
|
+ </description>
|
|
|
191
|
+ </request>
|
|
|
192
|
+ </interface>
|
|
|
193
|
+
|
|
|
194
|
+ <interface name="ext_session_lock_surface_v1" version="1">
|
|
|
195
|
+ <description summary="a surface displayed while the session is locked">
|
|
|
196
|
+ The client may use lock surfaces to display a screensaver, render a
|
|
|
197
|
+ dialog to enter a password and unlock the session, or however else it
|
|
|
198
|
+ sees fit.
|
|
|
199
|
+
|
|
|
200
|
+ On binding this interface the compositor will immediately send the
|
|
|
201
|
+ first configure event. After making the ack_configure request in
|
|
|
202
|
+ response to this event the client may attach and commit the first
|
|
|
203
|
+ buffer. Committing the surface before acking the first configure is a
|
|
|
204
|
+ protocol error. Committing the surface with a null buffer at any time
|
|
|
205
|
+ is a protocol error.
|
|
|
206
|
+
|
|
|
207
|
+ The compositor is free to handle keyboard/pointer focus for lock
|
|
|
208
|
+ surfaces however it chooses. A reasonable way to do this would be to
|
|
|
209
|
+ give the first lock surface created keyboard focus and change keyboard
|
|
|
210
|
+ focus if the user clicks on other surfaces.
|
|
|
211
|
+ </description>
|
|
|
212
|
+
|
|
|
213
|
+ <enum name="error">
|
|
|
214
|
+ <entry name="commit_before_first_ack" value="0"
|
|
|
215
|
+ summary="surface committed before first ack_configure request"/>
|
|
|
216
|
+ <entry name="null_buffer" value="1"
|
|
|
217
|
+ summary="surface committed with a null buffer"/>
|
|
|
218
|
+ <entry name="dimensions_mismatch" value="2"
|
|
|
219
|
+ summary="failed to match ack'd width/height"/>
|
|
|
220
|
+ <entry name="invalid_serial" value="3"
|
|
|
221
|
+ summary="serial provided in ack_configure is invalid"/>
|
|
|
222
|
+ </enum>
|
|
|
223
|
+
|
|
|
224
|
+ <request name="destroy" type="destructor">
|
|
|
225
|
+ <description summary="destroy the lock surface object">
|
|
|
226
|
+ This informs the compositor that the lock surface object will no
|
|
|
227
|
+ longer be used.
|
|
|
228
|
+
|
|
|
229
|
+ It is recommended for a lock client to destroy lock surfaces if
|
|
|
230
|
+ their corresponding wl_output global is removed.
|
|
|
231
|
+
|
|
|
232
|
+ If a lock surface on an active output is destroyed before the
|
|
|
233
|
+ ext_session_lock_v1.unlock_and_destroy event is sent, the compositor
|
|
|
234
|
+ must fall back to rendering a solid color.
|
|
|
235
|
+ </description>
|
|
|
236
|
+ </request>
|
|
|
237
|
+
|
|
|
238
|
+ <request name="ack_configure">
|
|
|
239
|
+ <description summary="ack a configure event">
|
|
|
240
|
+ When a configure event is received, if a client commits the surface
|
|
|
241
|
+ in response to the configure event, then the client must make an
|
|
|
242
|
+ ack_configure request sometime before the commit request, passing
|
|
|
243
|
+ along the serial of the configure event.
|
|
|
244
|
+
|
|
|
245
|
+ If the client receives multiple configure events before it can
|
|
|
246
|
+ respond to one, it only has to ack the last configure event.
|
|
|
247
|
+
|
|
|
248
|
+ A client is not required to commit immediately after sending an
|
|
|
249
|
+ ack_configure request - it may even ack_configure several times
|
|
|
250
|
+ before its next surface commit.
|
|
|
251
|
+
|
|
|
252
|
+ A client may send multiple ack_configure requests before committing,
|
|
|
253
|
+ but only the last request sent before a commit indicates which
|
|
|
254
|
+ configure event the client really is responding to.
|
|
|
255
|
+
|
|
|
256
|
+ Sending an ack_configure request consumes the configure event
|
|
|
257
|
+ referenced by the given serial, as well as all older configure events
|
|
|
258
|
+ sent on this object.
|
|
|
259
|
+
|
|
|
260
|
+ It is a protocol error to issue multiple ack_configure requests
|
|
|
261
|
+ referencing the same configure event or to issue an ack_configure
|
|
|
262
|
+ request referencing a configure event older than the last configure
|
|
|
263
|
+ event acked for a given lock surface.
|
|
|
264
|
+ </description>
|
|
|
265
|
+ <arg name="serial" type="uint" summary="serial from the configure event"/>
|
|
|
266
|
+ </request>
|
|
|
267
|
+
|
|
|
268
|
+ <event name="configure">
|
|
|
269
|
+ <description summary="the client should resize its surface">
|
|
|
270
|
+ This event is sent once on binding the interface and may be sent again
|
|
|
271
|
+ at the compositor's discretion, for example if output geometry changes.
|
|
|
272
|
+
|
|
|
273
|
+ The width and height are in surface-local coordinates and are exact
|
|
|
274
|
+ requirements. Failing to match these surface dimensions in the next
|
|
|
275
|
+ commit after acking a configure is a protocol error.
|
|
|
276
|
+ </description>
|
|
|
277
|
+ <arg name="serial" type="uint" summary="serial for use in ack_configure"/>
|
|
|
278
|
+ <arg name="width" type="uint"/>
|
|
|
279
|
+ <arg name="height" type="uint"/>
|
|
|
280
|
+ </event>
|
|
|
281
|
+ </interface>
|
|
|
282
|
+</protocol>
|