weston/protocol/weston-content-protection.xml

252 lines
12 KiB
XML
Raw Normal View History

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="weston_content_protection">
<copyright>
Copyright 2016 The Chromium Authors.
Copyright 2018-2019 Collabora, Ltd.
Copyright © 2018-2019 Intel Corporation.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="Protocol for providing secure output">
This protocol specifies a set of interfaces used to provide
content-protection for e.g. HDCP, and protect surface contents on the
secured outputs and prevent from appearing in screenshots or from being
visible on non-secure outputs.
A secure-output is defined as an output that is secured by some
content-protection mechanism e.g. HDCP, and meets at least the minimum
required content-protection level requested by a client.
The term content-protection is defined in terms of HDCP type 0 and
HDCP type 1, but this may be extended in future.
This protocol is not intended for implementing Digital Rights Management on
general (e.g. Desktop) systems, and would only be useful for closed systems.
As the server is the one responsible for implementing
the content-protection, the client can only trust the content-protection as
much they can trust the server.
In order to protect the content and prevent surface contents from appearing
in screenshots or from being visible on non-secure outputs, a client must
first bind the global interface "weston_content_protection" which, if a
compositor supports secure output, is exposed by the registry.
Using the bound global object, the client uses the "get_protection" request
to instantiate an interface extension for a wl_surface object.
This extended interface will then allow surfaces to request for
content-protection, and also to censor the visibility of the surface on
non-secure outputs. Client applications should not wait for the protection
to change, as it might never change in case the content-protection cannot be
achieved. Alternatively, clients can use a timeout and start showing the
content in lower quality.
Censored visibility is defined as the compositor censoring the protected
content on non-secure outputs. Censoring may include artificially reducing
image quality or replacing the protected content completely with
placeholder graphics.
Censored visibility is controlled by protection mode, set by the client.
In "relax" mode, the compositor may show protected content on non-secure
outputs. It will be up to the client to adapt to secure and non-secure
presentation. In "enforce" mode, the compositor will censor the parts of
protected content that would otherwise show on non-secure outputs.
</description>
<interface name="weston_content_protection" version="1">
<description summary="content protection global interface">
The global interface weston_content_protection is used for exposing the
content protection capabilities to a client. It provides a way for clients
to request their wl_surface contents to not be displayed on an output
below their required level of content-protection.
Using this interface clients can request for a weston_protected_surface
which is an extension to the wl_surface to provide content-protection, and
set the censored-visibility on the non-secured-outputs.
</description>
<request name="destroy" type="destructor">
<description summary="unbind from the content protection interface">
Informs the server that the client will not be using this
protocol object anymore. This does not affect any other objects,
protected_surface objects included.
</description>
</request>
<enum name="error">
<entry name="surface_exists" value="0"
summary="the surface already has a protected surface associated"/>
</enum>
<request name="get_protection">
<description summary="extend surface interface for protection">
Instantiate an interface extension for the given wl_surface to
provide surface protection. If the given wl_surface already has
a weston_protected_surface associated, the surface_exists protocol
error is raised.
</description>
<arg name="id" type="new_id" interface="weston_protected_surface"
summary="new object id for protected surface"/>
<arg name="surface" type="object" interface="wl_surface"
summary="the surface"/>
</request>
</interface>
<interface name="weston_protected_surface" version="1">
<description summary="content protection interface to a wl_surface">
An additional interface to a wl_surface object, which allows a client to
request the minimum level of content-protection, request to change the
visibility of their contents, and receive notifications about changes in
content-protection.
A protected surface has a 'status' associated with it, that indicates
what type of protection it is currently providing, specified by
content-type. Updates to this status are sent to the client
via the 'status' event. Before the first status event is sent, the client
should assume that the status is 'unprotected'.
A client can request a content protection level to be the minimum for an
output to be considered secure, using the 'set_type' request.
It is responsibility of the client to monitor the actual
content-protection level achieved via the 'status' event, and make
decisions as to what content to show based on this.
The server should make its best effort to achieve the desired
content-protection level on all of the outputs the client's contents are
being displayed on. Any changes to the content protection status should be
reported to the client, even if they are below the requested
content-protection level. If the client's contents are being displayed on
multiple outputs, the lowest content protection level achieved should be
reported.
A client can also request that its content only be displayed on outputs
that are considered secure. The 'enforce/relax' requests can achieve this.
In enforce mode, the content is censored for non-secure outputs.
The implementation of censored-visibility is compositor-defined.
In relax mode there are no such limitation. On an attempt to show the
client on unsecured output, compositor would keep on showing the content
and send the 'status' event to the client. Client can take a call to
downgrade the content.
If the wl_surface associated with the protected_surface is destroyed,
the protected_surface becomes inert.
</description>
<enum name="error">
<entry name="invalid_type" value="0"
summary="provided type was not valid"/>
</enum>
<enum name="type">
<description summary="content types">
Description of a particular type of content protection.
A server may not necessarily support all of these types.
Note that there is no ordering between enum members unless specified.
Over time, different types of content protection may be added, which
may be considered less secure than what is already here.
</description>
<entry name="unprotected" value="0" summary="no protection required"/>
<entry name="hdcp_0" value="1" summary="HDCP type 0"/>
<entry name="hdcp_1" value="2"
summary="HDCP type 1. This is a more secure than HDCP type 0."/>
</enum>
<request name="destroy" type="destructor">
<description summary="remove security from the surface">
If the protected_surface is destroyed, the wl_surface desired protection
level returns to unprotected, as if set_type request was sent with type
as 'unprotected'.
</description>
</request>
<request name="set_type">
<description summary="set the acceptable level of content protection">
Informs the server about the type of content. The level of
content-protection depends upon the content-type set by the client
through this request. Initially, this is set to 'unprotected'.
If the requested value is not a valid content_type enum value, the
'invalid_type' protocol error is raised. It is not an error to request
a valid protection type the compositor does not implement or cannot
achieve.
The requested content protection is double-buffered, see
wl_surface.commit.
</description>
<arg name="type" type="uint" enum="type"
summary="the desired type of content protection"/>
</request>
<request name="enforce">
<description summary="enforce censored-visibility constrain">
Censor the visibility of the wl_surface contents on non-secure outputs.
See weston_protected_surface for the description.
The force constrain mode is double-buffered, see wl_surface.commit
</description>
</request>
<request name="relax">
<description summary="relax the censored-visibility constrain">
Do not enforce censored-visibility of the wl_surface contents on
non-secure-outputs. See weston_protected_surface for the description.
The relax mode is selected by default, if no explicit request is made
for enforcing the censored-visibility.
The relax mode is double-buffered, see wl_surface.commit
</description>
</request>
<event name="status">
<description summary="security status changed">
This event is sent to the client to inform about the actual protection
level for its surface in the relax mode.
The 'type' argument indicates what that current level of content
protection that the server has currently established.
The 'status' event is first sent, when a weston_protected_surface is
created.
Until this event is sent for the first time, the client should assume
that its contents are not secure, and the type is 'unprotected'.
Possible reasons the content protection status can change is due to
change in censored-visibility mode from enforced to relaxed, a new
connector being added, movement of window to another output, or,
the client attaching a buffer too large for what the server may secure.
However, it is not limited to these reasons.
A client may want to listen to this event and lower the resolution of
their content until it can successfully be shown securely.
In case of "enforce" mode, the client will not get any status event.
If the mode is then changed to "relax", the client will receive the
status event.
</description>
<arg name="type" type="uint" enum="type"
summary="the current content protection level"/>
</event>
</interface>
</protocol>