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 is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in
14 all copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 THE SOFTWARE.
23 </copyright>
24
25 <description summary="secure session locking with arbitrary graphics">
26 This protocol allows for a privileged Wayland client to lock the session
27 and display arbitrary graphics while the session is locked.
28
29 The compositor may choose to restrict this protocol to a special client
30 launched by the compositor itself or expose it to all privileged clients,
31 this is compositor policy.
32
33 The client is responsible for performing authentication and informing the
34 compositor when the session should be unlocked. If the client dies while
35 the session is locked the session remains locked, possibly permanently
36 depending on compositor policy.
37
38 The key words "must", "must not", "required", "shall", "shall not",
39 "should", "should not", "recommended", "may", and "optional" in this
40 document are to be interpreted as described in IETF RFC 2119.
41
42 Warning! The protocol described in this file is currently in the
43 testing phase. Backward compatible changes may be added together with
44 the corresponding interface version bump. Backward incompatible changes
45 can only be done by creating a new major version of the extension.
46 </description>
47
48 <interface name="ext_session_lock_manager_v1" version="1">
49 <description summary="used to lock the session">
50 This interface is used to request that the session be locked.
51 </description>
52
53 <request name="destroy" type="destructor">
54 <description summary="destroy the session lock manager object">
55 This informs the compositor that the session lock manager object will
56 no longer be used. Existing objects created through this interface
57 remain valid.
58 </description>
59 </request>
60
61 <request name="lock">
62 <description summary="attempt to lock the session">
63 This request creates a session lock and asks the compositor to lock the
64 session. The compositor will send either the ext_session_lock_v1.locked
65 or ext_session_lock_v1.finished event on the created object in
66 response to this request.
67 </description>
68 <arg name="id" type="new_id" interface="ext_session_lock_v1"/>
69 </request>
70 </interface>
71
72 <interface name="ext_session_lock_v1" version="1">
73 <description summary="manage lock state and create lock surfaces">
74 In response to the creation of this object the compositor must send
75 either the locked or finished event.
76
77 The locked event indicates that the session is locked. This means
78 that the compositor must stop rendering and providing input to normal
79 clients. Instead the compositor must blank all outputs with an opaque
80 color such that their normal content is fully hidden.
81
82 The only surfaces that should be rendered while the session is locked
83 are the lock surfaces created through this interface and optionally,
84 at the compositor's discretion, special privileged surfaces such as
85 input methods or portions of desktop shell UIs.
86
87 The locked event must not be sent until a new "locked" frame (either
88 from a session lock surface or the compositor blanking the output) has
89 been presented on all outputs and no security sensitive normal/unlocked
90 content is possibly visible.
91
92 The finished event should be sent immediately on creation of this
93 object if the compositor decides that the locked event will not be sent.
94
95 The compositor may wait for the client to create and render session lock
96 surfaces before sending the locked event to avoid displaying intermediate
97 blank frames. However, it must impose a reasonable time limit if
98 waiting and send the locked event as soon as the hard requirements
99 described above can be met if the time limit expires. Clients should
100 immediately create lock surfaces for all outputs on creation of this
101 object to make this possible.
102
103 This behavior of the locked event is required in order to prevent
104 possible race conditions with clients that wish to suspend the system
105 or similar after locking the session. Without these semantics, clients
106 triggering a suspend after receiving the locked event would race with
107 the first "locked" frame being presented and normal/unlocked frames
108 might be briefly visible as the system is resumed if the suspend
109 operation wins the race.
110
111 If the client dies while the session is locked, the compositor must not
112 unlock the session in response. It is acceptable for the session to be
113 permanently locked if this happens. The compositor may choose to continue
114 to display the lock surfaces the client had mapped before it died or
115 alternatively fall back to a solid color, this is compositor policy.
116
117 Compositors may also allow a secure way to recover the session, the
118 details of this are compositor policy. Compositors may allow a new
119 client to create a ext_session_lock_v1 object and take responsibility
120 for unlocking the session, they may even start a new lock client
121 instance automatically.
122 </description>
123
124 <enum name="error">
125 <entry name="invalid_destroy" value="0"
126 summary="attempted to destroy session lock while locked"/>
127 <entry name="invalid_unlock" value="1"
128 summary="unlock requested but locked event was never sent"/>
129 <entry name="role" value="2"
130 summary="given wl_surface already has a role"/>
131 <entry name="duplicate_output" value="3"
132 summary="given output already has a lock surface"/>
133 <entry name="already_constructed" value="4"
134 summary="given wl_surface has a buffer attached or committed"/>
135 </enum>
136
137 <request name="destroy" type="destructor">
138 <description summary="destroy the session lock">
139 This informs the compositor that the lock object will no longer be
140 used. Existing objects created through this interface remain valid.
141
142 After this request is made, lock surfaces created through this object
143 should be destroyed by the client as they will no longer be used by
144 the compositor.
145
146 It is a protocol error to make this request if the locked event was
147 sent, the unlock_and_destroy request must be used instead.
148 </description>
149 </request>
150
151 <event name="locked">
152 <description summary="session successfully locked">
153 This client is now responsible for displaying graphics while the
154 session is locked and deciding when to unlock the session.
155
156 The locked event must not be sent until a new "locked" frame has been
157 presented on all outputs and no security sensitive normal/unlocked
158 content is possibly visible.
159
160 If this event is sent, making the destroy request is a protocol error,
161 the lock object must be destroyed using the unlock_and_destroy request.
162 </description>
163 </event>
164
165 <event name="finished">
166 <description summary="the session lock object should be destroyed">
167 The compositor has decided that the session lock should be destroyed
168 as it will no longer be used by the compositor. Exactly when this
169 event is sent is compositor policy, but it must never be sent more
170 than once for a given session lock object.
171
172 This might be sent because there is already another ext_session_lock_v1
173 object held by a client, or the compositor has decided to deny the
174 request to lock the session for some other reason. This might also
175 be sent because the compositor implements some alternative, secure
176 way to authenticate and unlock the session.
177
178 The finished event should be sent immediately on creation of this
179 object if the compositor decides that the locked event will not
180 be sent.
181
182 If the locked event is sent on creation of this object the finished
183 event may still be sent at some later time in this object's
184 lifetime. This is compositor policy.
185
186 Upon receiving this event, the client should make either the destroy
187 request or the unlock_and_destroy request, depending on whether or
188 not the locked event was received on this object.
189 </description>
190 </event>
191
192 <request name="get_lock_surface">
193 <description summary="create a lock surface for a given output">
194 The client is expected to create lock surfaces for all outputs
195 currently present and any new outputs as they are advertised. These
196 won't be displayed by the compositor unless the lock is successful
197 and the locked event is sent.
198
199 Providing a wl_surface which already has a role or already has a buffer
200 attached or committed is a protocol error, as is attaching/committing
201 a buffer before the first ext_session_lock_surface_v1.configure event.
202
203 Attempting to create more than one lock surface for a given output
204 is a duplicate_output protocol error.
205 </description>
206 <arg name="id" type="new_id" interface="ext_session_lock_surface_v1"/>
207 <arg name="surface" type="object" interface="wl_surface"/>
208 <arg name="output" type="object" interface="wl_output"/>
209 </request>
210
211 <request name="unlock_and_destroy" type="destructor">
212 <description summary="unlock the session, destroying the object">
213 This request indicates that the session should be unlocked, for
214 example because the user has entered their password and it has been
215 verified by the client.
216
217 This request also informs the compositor that the lock object will
218 no longer be used and should be destroyed. Existing objects created
219 through this interface remain valid.
220
221 After this request is made, lock surfaces created through this object
222 should be destroyed by the client as they will no longer be used by
223 the compositor.
224
225 It is a protocol error to make this request if the locked event has
226 not been sent. In that case, the lock object must be destroyed using
227 the destroy request.
228
229 Note that a correct client that wishes to exit directly after unlocking
230 the session must use the wl_display.sync request to ensure the server
231 receives and processes the unlock_and_destroy request. Otherwise
232 there is no guarantee that the server has unlocked the session due
233 to the asynchronous nature of the Wayland protocol. For example,
234 the server might terminate the client with a protocol error before
235 it processes the unlock_and_destroy request.
236 </description>
237 </request>
238 </interface>
239
240 <interface name="ext_session_lock_surface_v1" version="1">
241 <description summary="a surface displayed while the session is locked">
242 The client may use lock surfaces to display a screensaver, render a
243 dialog to enter a password and unlock the session, or however else it
244 sees fit.
245
246 On binding this interface the compositor will immediately send the
247 first configure event. After making the ack_configure request in
248 response to this event the client should attach and commit the first
249 buffer. Committing the surface before acking the first configure is a
250 protocol error. Committing the surface with a null buffer at any time
251 is a protocol error.
252
253 The compositor is free to handle keyboard/pointer focus for lock
254 surfaces however it chooses. A reasonable way to do this would be to
255 give the first lock surface created keyboard focus and change keyboard
256 focus if the user clicks on other surfaces.
257 </description>
258
259 <enum name="error">
260 <entry name="commit_before_first_ack" value="0"
261 summary="surface committed before first ack_configure request"/>
262 <entry name="null_buffer" value="1"
263 summary="surface committed with a null buffer"/>
264 <entry name="dimensions_mismatch" value="2"
265 summary="failed to match ack'd width/height"/>
266 <entry name="invalid_serial" value="3"
267 summary="serial provided in ack_configure is invalid"/>
268 </enum>
269
270 <request name="destroy" type="destructor">
271 <description summary="destroy the lock surface object">
272 This informs the compositor that the lock surface object will no
273 longer be used.
274
275 It is recommended for a lock client to destroy lock surfaces if
276 their corresponding wl_output global is removed.
277
278 If a lock surface on an active output is destroyed before the
279 ext_session_lock_v1.unlock_and_destroy event is sent, the compositor
280 must fall back to rendering a solid color.
281 </description>
282 </request>
283
284 <request name="ack_configure">
285 <description summary="ack a configure event">
286 When a configure event is received, if a client commits the surface
287 in response to the configure event, then the client must make an
288 ack_configure request sometime before the commit request, passing
289 along the serial of the configure event.
290
291 If the client receives multiple configure events before it can
292 respond to one, it only has to ack the last configure event.
293
294 A client is not required to commit immediately after sending an
295 ack_configure request - it may even ack_configure several times
296 before its next surface commit.
297
298 A client may send multiple ack_configure requests before committing,
299 but only the last request sent before a commit indicates which
300 configure event the client really is responding to.
301
302 Sending an ack_configure request consumes the configure event
303 referenced by the given serial, as well as all older configure events
304 sent on this object.
305
306 It is a protocol error to issue multiple ack_configure requests
307 referencing the same configure event or to issue an ack_configure
308 request referencing a configure event older than the last configure
309 event acked for a given lock surface.
310 </description>
311 <arg name="serial" type="uint" summary="serial from the configure event"/>
312 </request>
313
314 <event name="configure">
315 <description summary="the client should resize its surface">
316 This event is sent once on binding the interface and may be sent again
317 at the compositor's discretion, for example if output geometry changes.
318
319 The width and height are in surface-local coordinates and are exact
320 requirements. Failing to match these surface dimensions in the next
321 commit after acking a configure is a protocol error.
322 </description>
323 <arg name="serial" type="uint" summary="serial for use in ack_configure"/>
324 <arg name="width" type="uint"/>
325 <arg name="height" type="uint"/>
326 </event>
327 </interface>
328</protocol>