Merge pull request #174 from joshuagl/joshuagl/pathpattern

Clarify PATHPATTERN wildcards are glob-like

Author: joshuagl

tuf-spec.md

@@ -3,7 +3,7 @@ Title: The Update Framework Specification
 Shortname: TUF
 Status: LS
 Abstract: A framework for securing software update systems.
-Date: 2021-05-27
+Date: 2021-07-13
 Editor: Justin Cappos, NYU
 Editor: Trishank Karthik Kuppusamy, Datadog
 Editor: Joshua Lock, VMware
@@ -16,7 +16,7 @@ Boilerplate: copyright no, conformance no
 Local Boilerplate: header yes
 Markup Shorthands: css no, markdown yes
 Metadata Include: This version off, Abstract off
-Text Macro: VERSION 1.0.19
+Text Macro: VERSION 1.0.20
 </pre>
 
 Note: We strive to make the specification easy to implement, so if you come
@@ -1019,8 +1019,8 @@ as is described for the <a>root.json</a> file.
     ignored.
 
 In order to discuss target paths, a role MUST specify only one of the
-<a>"path_hash_prefixes"</a> or <a for="delegation-role">"paths"</a> attributes, each of which we
-discuss next.
+<a>"path_hash_prefixes"</a> or <a for="delegation-role">"paths"</a> attributes,
+each of which we discuss next.
 
   : <dfn>"path_hash_prefixes"</dfn>
   ::
@@ -1036,21 +1036,30 @@ discuss next.
 
   : <dfn for="delegation-role">"paths"</dfn>
   ::
-    A list of strings, where each string describes a path that the role is
-    trusted to provide.  Clients MUST check that a target is in one of the
-    trusted paths of all roles in a delegation chain, not just in a trusted
-    path of the role that describes the target file.  <dfn>PATHPATTERN</dfn>
-    can include shell-style wildcards and supports the Unix filename pattern
-    matching convention.  Its format may either indicate a path to a single
-    file, or to multiple paths with the use of shell-style wildcards.  For
-    example, the path pattern "targets/*.tgz" would match file paths
-    "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
-    Likewise, path pattern "foo-version-?.tgz" matches "foo-version-2.tgz" and
-    "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+    A list of strings, where each string is a <a>PATHPATTERN</a> describing a
+    path that the delegated role is trusted to provide.  Clients MUST check that
+    a target is in one of the trusted paths of all roles in a delegation chain,
+    not just in a trusted path of the role that describes the target file.
+
+    <dfn>PATHPATTERN</dfn> supports the Unix shell pattern matching convention
+    for paths ([glob](https://man7.org/linux/man-pages/man7/glob.7.html)bing
+    pathnames). Its format may either indicate a path to a single file, or to
+    multiple files with the use of shell-style wildcards (`*` or `?`).
     To avoid surprising behavior when matching targets with <a>PATHPATTERN</a>,
-    it is RECOMMENDED that <a>PATHPATTERN</a> uses the forward slash (/) as
-    directory separator and does not start with a directory separator, akin to
-    <a>TARGETPATH</a>.
+    it is RECOMMENDED that <a>PATHPATTERN</a> uses the forward slash (`/`) as
+    directory separator and does not start with a directory separator, as is
+    also recommended for <a>TARGETPATH</a>. A path separator in a path SHOULD
+    NOT be matched by a wildcard in the <a>PATHPATTERN</a>.
+
+    Some example <a>PATHPATTERN</a>s and expected matches:
+    * a <a>PATHPATTERN</a> of `"targets/*.tgz"` would match file paths
+      `"targets/foo.tgz"` and `"targets/bar.tgz"`, but not `"targets/foo.txt"`.
+    * a <a>PATHPATTERN</a> of `"foo-version-?.tgz"` matches
+      `"foo-version-2.tgz"` and `"foo-version-a.tgz"`, but not
+      `"foo-version-alpha.tgz"`.
+    * a <a>PATHPATTERN</a> of `"*.tgz"` would match `"foo.tgz"` and `"bar.tgz"`,
+      but not `"targets/foo.tgz"`
+    * a <a>PATHPATTERN</a> of `"foo.tgz"` would match only `"foo.tgz"`
 
 
 Prioritized delegations allow clients to resolve conflicts between delegated