Skip to main content

2.2.8. Query Parameters

2.2.8. Query Parameters​

If the query portion of a request target URI uses HTML form parameters in the format defined in Section 5 ("application/ x-www-form-urlencoded") of [HTMLURL], the @query-param derived component allows addressing of these individual query parameters. The query parameters MUST be parsed according to Section 5.1 ("application/x-www-form-urlencoded parsing") of [HTMLURL], resulting in a list of (nameString, valueString) tuples. The REQUIRED name parameter of each component identifier contains the encoded nameString of a single query parameter as a String value. The component value of a single named parameter is the encoded valueString of that single query parameter. Several different named query parameters MAY be included in the covered components. Single named parameters MAY occur in any order in the covered components, regardless of the order they occur in the query string.

The value of the name parameter and the component value of a single named parameter are calculated via the following process:

  1. Parse the nameString or valueString of the named query parameter defined by Section 5.1 ("application/x-www-form-urlencoded parsing") of [HTMLURL]; this is the value after percent-encoded octets are decoded.

  2. Encode the nameString or valueString using the "percent-encode after encoding" process defined by Section 5.2 ("application/ x-www-form-urlencoded serializing") of [HTMLURL]; this results in an ASCII string [ASCII].

  3. Output the ASCII string.

Note that the component value does not include any leading question mark (?) characters, equals sign (=) characters, or separating ampersand (&) characters. Named query parameters with an empty valueString have an empty string as the component value. Note that due to inconsistencies in implementations, some query parameter parsing libraries drop such empty values.

If a query parameter is named as a covered component but it does not occur in the query parameters, this MUST cause an error in the signature base generation.

For example, for the following request:

GET /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 Host: www.example.com

Indicating the baz, qux, and param named query parameters would result in the following @query-param component values:

baz: batman

qux: an empty string

param: value

and the following signature base lines, with (SP) indicating a single trailing space character before the empty component value:

"@query-param";name="baz": batman "@query-param";name="qux":(SP) "@query-param";name="param": value

This derived component has some limitations. Specifically, the algorithms provided in Section 5 ("application/ x-www-form-urlencoded") of [HTMLURL] only support query parameters using percent-escaped UTF-8 encoding. Other encodings are not supported. Additionally, multiple instances of a named parameter are not reliably supported in the wild. If a parameter name occurs multiple times in a request, the named query parameter MUST NOT be included. If multiple parameters are common within an application, it is RECOMMENDED to sign the entire query string using the @query component identifier defined in Section 2.2.7.

The encoding process allows query parameters that include newlines or other problematic characters in their values, or with alternative encodings such as using the plus (+) character to represent spaces. For the query parameters in this message:

NOTE: '' line wrapping per RFC 8792

GET /parameters?var=this%20is%20a%20big%0Amultiline%20value&
bar=with+plus+whitespace&fa%C3%A7ade%22%3A%20=something HTTP/1.1 Host: www.example.com Date: Tue, 20 Apr 2021 02:07:56 GMT

The resulting values are encoded as follows:

"@query-param";name="var": this%20is%20a%20big%0Amultiline%20value "@query-param";name="bar": with%20plus%20whitespace "@query-param";name="fa%C3%A7ade%22%3A%20": something

If the encoding were not applied, the resultant values would be:

"@query-param";name="var": this is a big multiline value "@query-param";name="bar": with plus whitespace "@query-param";name="façade": ": something

This base string contains characters that violate the constraints on component names and values and is therefore invalid.

Last updated on