From 6fffd3696eaf5fe86cb6ec7d132898a47b0c1bbf Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Wed, 14 Jul 2021 10:33:30 +0100 Subject: [PATCH] Clarify PATHPATTERN wildcards are glob-like The common interpretation of PATHPATTERN's use shell-style wildcards is that they match the behaviour of a UNIX glob: https://man7.org/linux/man-pages/man7/glob.7.html However, the reference implementation currently ( https://github.com/theupdateframework/tuf/blob/04bbc03b9f16e49ee114ed9b5eae69fdea266b93/tuf/client/updater.py#L2868 ) implements PATHPATTERN wildcard matching using fnmatch ( https://docs.python.org/3/library/fnmatch.html#module-fnmatch) where, unlike a glob, wildcards in PATHPATTERN will match path separators in the PATHPATTERN. The existing recommendation in the spec to treat `/` as a directory separator implies that, like a glob, a '/' in a pathname SHOULD not be matched by a wildcard in a PATHPATTERN. Edit the description of PATHPATTERN to be explicit that this is glob-like behaviour AND we do not expect a wildcard to match a path separator. Make this even more explicit by including an examples demonstrating how a path separator would not match. Signed-off-by: Joshua Lock --- tuf-spec.md | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index d9c24fb..f8030c5 100644 --- a/tuf-spec.md +++ b/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 Note: We strive to make the specification easy to implement, so if you come @@ -1019,8 +1019,8 @@ as is described for the root.json file. ignored. In order to discuss target paths, a role MUST specify only one of the -"path_hash_prefixes" or "paths" attributes, each of which we -discuss next. +"path_hash_prefixes" or "paths" attributes, +each of which we discuss next. : "path_hash_prefixes" :: @@ -1036,21 +1036,30 @@ discuss next. : "paths" :: - 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. PATHPATTERN - 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 PATHPATTERN 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. + + PATHPATTERN 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 PATHPATTERN, - it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as - directory separator and does not start with a directory separator, akin to - TARGETPATH. + it is RECOMMENDED that PATHPATTERN uses the forward slash (`/`) as + directory separator and does not start with a directory separator, as is + also recommended for TARGETPATH. A path separator in a path SHOULD + NOT be matched by a wildcard in the PATHPATTERN. + + Some example PATHPATTERNs and expected matches: + * a PATHPATTERN of `"targets/*.tgz"` would match file paths + `"targets/foo.tgz"` and `"targets/bar.tgz"`, but not `"targets/foo.txt"`. + * a PATHPATTERN of `"foo-version-?.tgz"` matches + `"foo-version-2.tgz"` and `"foo-version-a.tgz"`, but not + `"foo-version-alpha.tgz"`. + * a PATHPATTERN of `"*.tgz"` would match `"foo.tgz"` and `"bar.tgz"`, + but not `"targets/foo.tgz"` + * a PATHPATTERN of `"foo.tgz"` would match only `"foo.tgz"` Prioritized delegations allow clients to resolve conflicts between delegated