From: Marc-André Lureau <marcandre.lureau@xxxxxxxxxx> A recent discussion about Spice URI scheme on the QEMU mailing list with Gerd prompted me to make an effort to standardize the Spice URIs usage. So far, it is mostly used and desribed in spice-gtk (see URI in man/spice-client.pod). But it would be more appropriate as part of spice-protocol. Based on the "vnc" URI Scheme RFC (https://tools.ietf.org/html/rfc7869), I sketeched a Spice URI Scheme document, that should cover current URI usage in spice-gtk, and should open up possibilities for future discussions and proposals. At some point, it would also be worthwhile to follow the "vnc" scheme, and turn this into a IETF RFC and register with IANA etc. Signed-off-by: Marc-André Lureau <marcandre.lureau@xxxxxxxxxx> --- spice-uri-scheme.txt | 142 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 spice-uri-scheme.txt diff --git a/spice-uri-scheme.txt b/spice-uri-scheme.txt new file mode 100644 index 0000000..389a33c --- /dev/null +++ b/spice-uri-scheme.txt @@ -0,0 +1,142 @@ +Spice URI scheme +================ + +This document is inspired by 'The "vnc" URI Scheme' (rfc7869) and +attempts to document a standard Spice URI scheme. + +The normative syntax of the Spice URI is defined in the <spice-uri> +rule in the following syntax specification. This specification +uses the Augmented Backus-Naur Form (ABNF) as described in +[RFC5234]. The Spice URI conforms to the generic URI syntax +specified in [RFC3986]. The <userinfo>, <host>, <port>, +<unreserved>, and <pct-encoded> rules are defined in [RFC3986]. + +spice-uri = spice-scheme "://" [ userinfo "@" ] [ host [ ":" port ] ] + [ "?" [ spice-params ] ] + +spice-scheme = "spice" / "spice+unix" / "spice+tls" + +spice-params = param "=" value *("&" param "=" value) ["&"] + +param = 1*( param-char ) + +value = *( param-char ) + +param-char = unreserved / pct-encoded / unreserved-symbols + +unreserved-symbols = ":" / "/" / "@" / "!" / "$" / "'" + / "(" / ")" / "*" / "," / ";" + +The "?", "=", and "&" characters are used to delimit Spice parameters +and must be percent-encoded when representing a data octet as +specified in [RFC3986]. Within the <spice-params> portion of a Spice +URI, the <unreserved-symbols> do not have special meaning and need not +be percent-encoded when representing a data octet. + +A Spice URI has the general form: + + spice-scheme://host:port?param1=value1¶m2=value2... + +The host information and each parameter value specify information +used in establishing or operating the remote desktop session as +specified in Section "URI Parameters". + +URI Parameters +-------------- + +A description of host information and URI parameters is provided in +this section. Information on the constraints of various data types is +provided in Section "Data Types". All parameters are considered optional; +however, a client will not be able to connect without sufficient +information. + +A parameter without a specified default value indicates that no +default value is implied by this URI scheme; however, Spice clients +can apply implementation-dependent default behaviors otherwise +consistent with this document. + +The <userinfo> value is deprecated and processed only in an +implementation-specific manner. The <userinfo> component MUST NOT be +generated in an environment where a client supporting an updated URI +format is expected to be available. When processing a URI value from +an untrusted source, Spice clients SHOULD alert the user in order to +mitigate the risk that the URI is constructed to obscure the identity +of the remote host unless the URI can be validated or backwards- +compatibility considerations make an alert impractical. + +The <host> and <port> values in the "spice://" and "spice+tls://" URIs +specify the address of the Spice server on the remote host: + ++------------+------------+---------------------------------+----------+ +| Name | Type | Description | Default | ++------------+------------+---------------------------------+----------+ +| host | string | Spice server hostname or IP | none | ++------------+------------+---------------------------------+----------+ +| port | ushort | Spice server port | none | ++------------+------------+---------------------------------+----------+ + +The <host> value in the "spice+unix://" URI specify the UNIX domain +socket path of the Spice server on the local host. + ++------------+------------+---------------------------------+----------+ +| Name | Type | Description | Default | ++------------+------------+---------------------------------+----------+ +| host | string | UNIX domain socket path | none | ++------------+------------+---------------------------------+----------+ + +The Spice URI parameter values specify remote desktop connection or +session properties, including aspects of client operation, usability, +and security as specified in the table below: + ++------------+------------+---------------------------------+----------+ +| Name | Type | Description | Default | ++------------+------------+---------------------------------+----------+ +| port | ushort | Spice server port (legacy) | none | ++------------+------------+---------------------------------+----------+ +| tls-port | ushort | Spice server TLS port (legacy) | none | ++------------+------------+---------------------------------+----------+ +| password | string | Spice server password (legacy) | none | ++------------+------------+---------------------------------+----------+ +| ... | | | | ++------------+------------+---------------------------------+----------+ + +Parameter names SHOULD be provided in the case specified in this +document; however, for compatibility, clients SHOULD accept +parameters in a case-insensitive manner. Values SHALL be interpreted +in a case-sensitive manner, unless otherwise noted. + +Additional parameters likely to be useful with multiple Spice clients +can be added to the "URI Parameters" registry (at the moment, +discussed and approved on the Spice mailing list). Individual clients +MAY support parameters specific to that client. Spice clients +supporting application-specific parameters SHOULD include a +distinguishing prefix within the parameter name, such as the name of +the application package specified in source code except when precluded +by compatibility constraints. For example: + + spice://?com.redhat.spiceclient.MonitorMapping=2& + +It can also be expected that clients will maintain backward +compatibility with legacy URI formats and parameters. + +Legacy software applications respond to "spice" URIs in different ways +and may fail to behave as expected. It is advisable to test "spice" +URIs with specific applications or consult application-specific +documentation. + +Data Types +---------- + +Spice URIs can be percent-encoded as specified in [RFC3986] and MUST +be decoded. After decoding, the following type constraints and +semantics apply: + +o string + +Values of "string" type are UTF-encoded strings as specified in +[RFC3629]. + +o ushort + +The "ushort" values represent unsigned 16-bit integers expressed +in decimal digits with value between 0-65535 inclusive. -- 2.20.0 _______________________________________________ Spice-devel mailing list Spice-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/spice-devel