1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="weston_content_protection"> 3 4 <copyright> 5 Copyright 2016 The Chromium Authors. 6 Copyright 2018-2019 Collabora, Ltd. 7 Copyright © 2018-2019 Intel Corporation. 8 9 Permission is hereby granted, free of charge, to any person obtaining a 10 copy of this software and associated documentation files (the "Software"), 11 to deal in the Software without restriction, including without limitation 12 the rights to use, copy, modify, merge, publish, distribute, sublicense, 13 and/or sell copies of the Software, and to permit persons to whom the 14 Software is furnished to do so, subject to the following conditions: 15 16 The above copyright notice and this permission notice (including the next 17 paragraph) shall be included in all copies or substantial portions of the 18 Software. 19 20 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 21 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 22 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 23 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 24 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 25 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 26 DEALINGS IN THE SOFTWARE. 27 </copyright> 28 29 <description summary="Protocol for providing secure output"> 30 This protocol specifies a set of interfaces used to provide 31 content-protection for e.g. HDCP, and protect surface contents on the 32 secured outputs and prevent from appearing in screenshots or from being 33 visible on non-secure outputs. 34 35 A secure-output is defined as an output that is secured by some 36 content-protection mechanism e.g. HDCP, and meets at least the minimum 37 required content-protection level requested by a client. 38 39 The term content-protection is defined in terms of HDCP type 0 and 40 HDCP type 1, but this may be extended in future. 41 42 This protocol is not intended for implementing Digital Rights Management on 43 general (e.g. Desktop) systems, and would only be useful for closed systems. 44 As the server is the one responsible for implementing 45 the content-protection, the client can only trust the content-protection as 46 much they can trust the server. 47 48 In order to protect the content and prevent surface contents from appearing 49 in screenshots or from being visible on non-secure outputs, a client must 50 first bind the global interface "weston_content_protection" which, if a 51 compositor supports secure output, is exposed by the registry. 52 Using the bound global object, the client uses the "get_protection" request 53 to instantiate an interface extension for a wl_surface object. 54 This extended interface will then allow surfaces to request for 55 content-protection, and also to censor the visibility of the surface on 56 non-secure outputs. Client applications should not wait for the protection 57 to change, as it might never change in case the content-protection cannot be 58 achieved. Alternatively, clients can use a timeout and start showing the 59 content in lower quality. 60 61 Censored visibility is defined as the compositor censoring the protected 62 content on non-secure outputs. Censoring may include artificially reducing 63 image quality or replacing the protected content completely with 64 placeholder graphics. 65 66 Censored visibility is controlled by protection mode, set by the client. 67 In "relax" mode, the compositor may show protected content on non-secure 68 outputs. It will be up to the client to adapt to secure and non-secure 69 presentation. In "enforce" mode, the compositor will censor the parts of 70 protected content that would otherwise show on non-secure outputs. 71 </description> 72 73 <interface name="weston_content_protection" version="1"> 74 <description summary="content protection global interface"> 75 The global interface weston_content_protection is used for exposing the 76 content protection capabilities to a client. It provides a way for clients 77 to request their wl_surface contents to not be displayed on an output 78 below their required level of content-protection. 79 Using this interface clients can request for a weston_protected_surface 80 which is an extension to the wl_surface to provide content-protection, and 81 set the censored-visibility on the non-secured-outputs. 82 </description> 83 84 <request name="destroy" type="destructor"> 85 <description summary="unbind from the content protection interface"> 86 Informs the server that the client will not be using this 87 protocol object anymore. This does not affect any other objects, 88 protected_surface objects included. 89 </description> 90 </request> 91 92 <enum name="error"> 93 <entry name="surface_exists" value="0" 94 summary="the surface already has a protected surface associated"/> 95 </enum> 96 97 <request name="get_protection"> 98 <description summary="extend surface interface for protection"> 99 Instantiate an interface extension for the given wl_surface to 100 provide surface protection. If the given wl_surface already has 101 a weston_protected_surface associated, the surface_exists protocol 102 error is raised. 103 </description> 104 <arg name="id" type="new_id" interface="weston_protected_surface" 105 summary="new object id for protected surface"/> 106 <arg name="surface" type="object" interface="wl_surface" 107 summary="the surface"/> 108 </request> 109 </interface> 110 111 <interface name="weston_protected_surface" version="1"> 112 <description summary="content protection interface to a wl_surface"> 113 An additional interface to a wl_surface object, which allows a client to 114 request the minimum level of content-protection, request to change the 115 visibility of their contents, and receive notifications about changes in 116 content-protection. 117 118 A protected surface has a 'status' associated with it, that indicates 119 what type of protection it is currently providing, specified by 120 content-type. Updates to this status are sent to the client 121 via the 'status' event. Before the first status event is sent, the client 122 should assume that the status is 'unprotected'. 123 124 A client can request a content protection level to be the minimum for an 125 output to be considered secure, using the 'set_type' request. 126 It is responsibility of the client to monitor the actual 127 content-protection level achieved via the 'status' event, and make 128 decisions as to what content to show based on this. 129 130 The server should make its best effort to achieve the desired 131 content-protection level on all of the outputs the client's contents are 132 being displayed on. Any changes to the content protection status should be 133 reported to the client, even if they are below the requested 134 content-protection level. If the client's contents are being displayed on 135 multiple outputs, the lowest content protection level achieved should be 136 reported. 137 138 A client can also request that its content only be displayed on outputs 139 that are considered secure. The 'enforce/relax' requests can achieve this. 140 In enforce mode, the content is censored for non-secure outputs. 141 The implementation of censored-visibility is compositor-defined. 142 In relax mode there are no such limitation. On an attempt to show the 143 client on unsecured output, compositor would keep on showing the content 144 and send the 'status' event to the client. Client can take a call to 145 downgrade the content. 146 147 If the wl_surface associated with the protected_surface is destroyed, 148 the protected_surface becomes inert. 149 </description> 150 151 <enum name="error"> 152 <entry name="invalid_type" value="0" 153 summary="provided type was not valid"/> 154 </enum> 155 156 <enum name="type"> 157 <description summary="content types"> 158 Description of a particular type of content protection. 159 160 A server may not necessarily support all of these types. 161 162 Note that there is no ordering between enum members unless specified. 163 Over time, different types of content protection may be added, which 164 may be considered less secure than what is already here. 165 </description> 166 <entry name="unprotected" value="0" summary="no protection required"/> 167 <entry name="hdcp_0" value="1" summary="HDCP type 0"/> 168 <entry name="hdcp_1" value="2" 169 summary="HDCP type 1. This is a more secure than HDCP type 0."/> 170 </enum> 171 172 <request name="destroy" type="destructor"> 173 <description summary="remove security from the surface"> 174 If the protected_surface is destroyed, the wl_surface desired protection 175 level returns to unprotected, as if set_type request was sent with type 176 as 'unprotected'. 177 </description> 178 </request> 179 180 <request name="set_type"> 181 <description summary="set the acceptable level of content protection"> 182 Informs the server about the type of content. The level of 183 content-protection depends upon the content-type set by the client 184 through this request. Initially, this is set to 'unprotected'. 185 186 If the requested value is not a valid content_type enum value, the 187 'invalid_type' protocol error is raised. It is not an error to request 188 a valid protection type the compositor does not implement or cannot 189 achieve. 190 191 The requested content protection is double-buffered, see 192 wl_surface.commit. 193 </description> 194 <arg name="type" type="uint" enum="type" 195 summary="the desired type of content protection"/> 196 </request> 197 198 <request name="enforce"> 199 <description summary="enforce censored-visibility constrain"> 200 Censor the visibility of the wl_surface contents on non-secure outputs. 201 See weston_protected_surface for the description. 202 203 The force constrain mode is double-buffered, see wl_surface.commit 204 </description> 205 </request> 206 207 <request name="relax"> 208 <description summary="relax the censored-visibility constrain"> 209 Do not enforce censored-visibility of the wl_surface contents on 210 non-secure-outputs. See weston_protected_surface for the description. 211 212 The relax mode is selected by default, if no explicit request is made 213 for enforcing the censored-visibility. 214 215 The relax mode is double-buffered, see wl_surface.commit 216 </description> 217 </request> 218 219 <event name="status"> 220 <description summary="security status changed"> 221 This event is sent to the client to inform about the actual protection 222 level for its surface in the relax mode. 223 224 The 'type' argument indicates what that current level of content 225 protection that the server has currently established. 226 227 The 'status' event is first sent, when a weston_protected_surface is 228 created. 229 230 Until this event is sent for the first time, the client should assume 231 that its contents are not secure, and the type is 'unprotected'. 232 233 Possible reasons the content protection status can change is due to 234 change in censored-visibility mode from enforced to relaxed, a new 235 connector being added, movement of window to another output, or, 236 the client attaching a buffer too large for what the server may secure. 237 However, it is not limited to these reasons. 238 239 A client may want to listen to this event and lower the resolution of 240 their content until it can successfully be shown securely. 241 242 In case of "enforce" mode, the client will not get any status event. 243 If the mode is then changed to "relax", the client will receive the 244 status event. 245 </description> 246 <arg name="type" type="uint" enum="type" 247 summary="the current content protection level"/> 248 </event> 249 </interface> 250 251</protocol> 252