AWS mediapackage documentation change
Summary
Added detailed guidance on URL encoding reserved characters in query parameters, updated examples with encoded values, and restructured documentation sections for clarity.
Security assessment
The changes emphasize proper URL encoding of reserved characters (e.g., colon, semicolon) to ensure query parameters are parsed correctly. While improper encoding could lead to unintended manifest filtering results (potentially exposing unintended content), there is no explicit mention of a security vulnerability being addressed. The updates appear to be general documentation improvements to prevent user misconfiguration rather than patching a security flaw.
Diff
diff --git a/mediapackage/latest/userguide/manifest-filter-query-parameters.md b/mediapackage/latest/userguide/manifest-filter-query-parameters.md index cae28c304..0bc7183b7 100644 --- a//mediapackage/latest/userguide/manifest-filter-query-parameters.md +++ b//mediapackage/latest/userguide/manifest-filter-query-parameters.md @@ -5 +5 @@ -Query syntaxQuery value formatsQuery parameters +Query parameter formattingQuery syntaxQuery value formatsQuery parameters @@ -9 +9,3 @@ Query syntaxQuery value formatsQuery parameters -To use manifest filtering query parameters, append `aws.manifestfilter` to your playback request to MediaPackage. MediaPackage evaluates the query, and serves a client manifest based on those query parameters. Manifest queries are _not_ case-sensitive and can be up to 1024 characters long. If the query is malformed, or if it there aren't streams that match the query parameters, MediaPackage returns an incomplete or empty manifest. For query syntax, see the following section. +To use manifest filtering query parameters, append `aws.manifestfilter` to your playback request to MediaPackage. MediaPackage evaluates the query, and serves a client manifest based on those query parameters. + +The following sections describe how to configure manifest filtering query parameters. @@ -14,0 +17,24 @@ If you are using TS or CMAF origin endpoints, special conditions apply. For info +## Query parameter formatting + +Use the following guidelines when constructing query parameters: + + * Queries are not case sensitive. + + * Queries can be up to 1,024 characters. + + * Reserved characters in the queries must be URL encoded as indicated in the [URI: General Syntax](https://datatracker.ietf.org/doc/html/rfc3986) standard. + +At a minimum, if your query includes multiple parameters, the following characters in the query must be URL encoded. If they're not, MediaPackage processes just the first query parameter in the string. + +Character | Encoded value +---|--- +: (colon) | %3A +; (semicolon) | %3B +, (comma) | %2C +\+ (plus) | %2B + + + + +If the query is malformed, or if it there aren't streams that match the query parameters, MediaPackage returns an incomplete or empty manifest. For query syntax, see the following section. + @@ -19 +45,3 @@ The base query parameter is `aws.manifestfilter`, which is followed by optional -An Apple HLS filter query might look like this: +###### Example HLS filter query + +The following example query includes filters for audio sample rate, video bitrate, video codec, and audio language. Note that the reserved characters use URL-encoded values. @@ -21 +49 @@ An Apple HLS filter query might look like this: -`https://example-mediapackage-endpoint.mediapackage.us-west-2.amazonaws.com/out/v1/examplemediapackage/index.m3u8`?aws.manifestfilter=audio_sample_rate:0-44100;video_bitrate:0-2147483647;video_codec:h265;audio_language:fr,en-US,de`` +`https://example-mediapackage-endpoint.mediapackage.us-west-2.amazonaws.com/out/v1/examplemediapackage/index.m3u8`?aws.manifestfilter=audio_sample_rate%3A0-44100%3Bvideo_bitrate%3A0-2147483647%3Bvideo_codec%3Ah265%3Baudio_language%3Afr%2Cen-US%2Cde`` @@ -23 +51 @@ An Apple HLS filter query might look like this: -The query syntax is listed in the following table. +The query syntax is described in the following table. @@ -33,3 +61,3 @@ Query string component | Description -`:` | Used to associate the parameter name with a value. For example, ``parameter_name`:`value``. -`;` | Separates parameters in a query that contains multiple parameters. For example, ``parameter1_name:value`;`parameter2_name:minValue-maxValue``. When used in a list of parameters for the same query, implies an `AND` operation. -`,` | Separates a list of values. For example, `parameter_name:`value1`,`value2`,`value3``. Comma-separated values in a list imply an `OR` relationship. +`:` | Used to associate the parameter name with a value. For example, ``parameter_name`:`value``. When using multiple query parameters, this character must be URL encoded (%3A). +`;` | Separates parameters in a query that contains multiple parameters. For example, ``parameter1_name:value`;`parameter2_name:minValue-maxValue``. When used in a list of parameters for the same query, implies an `AND` operation.When using multiple query parameters, this character must be URL encoded (%3B). +`,` | Separates a list of values. For example, `parameter_name:`value1`,`value2`,`value3``. Comma-separated values in a list imply an `OR` relationship.When using multiple query parameters, this character must be URL encoded (%2C). @@ -104 +132 @@ Filter manifests by multiple single values or multiple ranges. -The following example filters for videos that are either 240p-360p OR 720p-1080p. +The following example filters for videos that are either 240p-360p OR 720p-1080p. It uses URL encoding for reserved characters. @@ -107 +135 @@ The following example filters for videos that are either 240p-360p OR 720p-1080p - stream.mpd?aws.manifestfilter=video_height:240-360,720-1080 + stream.mpd?aws.manifestfilter=video_height%3A240-360%2C720-1080 @@ -123 +151 @@ Filter manifests by a combination of ranges and values. -The following example filters for videos that are either 240p-360p, 720p-1080p, 1440p, OR 2160p. +The following example filters for videos that are either 240p-360p, 720p-1080p, 1440p, OR 2160p. It uses URL encoding for reserved characters. @@ -126 +154 @@ The following example filters for videos that are either 240p-360p, 720p-1080p, - stream.mpd?aws.manifestfilter=video_height:240-360,720-1080,1440,2160 + stream.mpd?aws.manifestfilter=video_height%3A240-360%2C720-1080%2C1440%2C2160