From 41a565e45b6806e089ef1644b37e36c09355508c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 3 Jul 2024 13:09:28 +0200 Subject: [PATCH] symlink: touch-up documentation - Fix references to EvalSymlinksInScope, which is non-exported - Add relevant links to original implementation / introduction of the code to allow comparing the fork with the original upstream code. - Move GoDoc from the non-exported evalSymlinksInScope function to the exported FollowSymlinkInScope. - Remove the README.md, instead using doc.go to provide the package description. Signed-off-by: Sebastiaan van Stijn --- symlink/README.md | 6 ---- symlink/doc.go | 13 ++++++-- symlink/fs.go | 71 ++++++++++++++++++++++++++++--------------- symlink/fs_windows.go | 12 ++++++++ 4 files changed, 68 insertions(+), 34 deletions(-) delete mode 100644 symlink/README.md diff --git a/symlink/README.md b/symlink/README.md deleted file mode 100644 index 8dba54fd..00000000 --- a/symlink/README.md +++ /dev/null @@ -1,6 +0,0 @@ -Package symlink implements EvalSymlinksInScope which is an extension of filepath.EvalSymlinks, -as well as a Windows long-path aware version of filepath.EvalSymlinks -from the [Go standard library](https://golang.org/pkg/path/filepath). - -The code from filepath.EvalSymlinks has been adapted in fs.go. -Please read the LICENSE.BSD file that governs fs.go and LICENSE.APACHE for fs_test.go. diff --git a/symlink/doc.go b/symlink/doc.go index d2de7ecd..7c22ca27 100644 --- a/symlink/doc.go +++ b/symlink/doc.go @@ -1,4 +1,11 @@ -// Package symlink implements EvalSymlinksInScope which is an extension of -// filepath.EvalSymlinks, as well as a Windows long-path aware version of -// filepath.EvalSymlinks from the Go standard library (https://golang.org/pkg/path/filepath). +// Package symlink implements [FollowSymlinkInScope] which is an extension +// of [path/filepath.EvalSymlinks], as well as a Windows long-path aware +// version of [path/filepath.EvalSymlinks] from the Go standard library. +// +// The code from [path/filepath.EvalSymlinks] has been adapted in fs.go. +// Read the [LICENSE.BSD] file that governs fs.go and [LICENSE.APACHE] for +// fs_unix_test.go. +// +// [LICENSE.APACHE]: https://github.com/moby/sys/blob/symlink/v0.2.0/symlink/LICENSE.APACHE +// [LICENSE.BSD]: https://github.com/moby/sys/blob/symlink/v0.2.0/symlink/LICENSE.APACHE package symlink diff --git a/symlink/fs.go b/symlink/fs.go index ac26ca11..6b826613 100644 --- a/symlink/fs.go +++ b/symlink/fs.go @@ -2,7 +2,13 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE.BSD file. -// This code is a modified version of path/filepath/symlink.go from the Go standard library. +// This code is a modified version of path/filepath/symlink.go from the Go +// standard library in [docker@fa3ec89], which was based on [go1.3.3], +// with Windows implementatinos being added in [docker@9b648df]. +// +// [docker@fa3ec89]: https://github.com/moby/moby/commit/fa3ec89515431ce425f924c8a9a804d5cb18382f +// [go1.3.3]: https://github.com/golang/go/blob/go1.3.3/src/pkg/path/filepath/symlink.go +// [docker@9b648df]: https://github.com/moby/moby/commit/9b648dfac6453de5944ee4bb749115d85a253a05 package symlink @@ -14,8 +20,34 @@ import ( "strings" ) -// FollowSymlinkInScope is a wrapper around evalSymlinksInScope that returns an -// absolute path. This function handles paths in a platform-agnostic manner. +// FollowSymlinkInScope evaluates symbolic links in "path" within a scope "root" +// and returns a result guaranteed to be contained within the scope "root" at +// the time of the call. It returns an error of either "path" or "root" cannot +// be converted to an absolute path. +// +// Symbolic links in "root" are not evaluated and left as-is. Errors encountered +// while attempting to evaluate symlinks in path are returned, but non-existing +// paths are valid and do not constitute an error. "path" must contain "root" +// as a prefix, or else an error is returned. Trying to break out from "root" +// does not constitute an error, instead resolves the path within "root". +// +// Example: +// +// // If "/foo/bar" is a symbolic link to "/outside": +// FollowSymlinkInScope("/foo/bar", "/foo") // Returns "/foo/outside" instead of "/outside" +// +// IMPORTANT: It is the caller's responsibility to call FollowSymlinkInScope +// after relevant symbolic links are created to avoid Time-of-check Time-of-use +// (TOCTOU) race conditions ([CWE-367]). No additional symbolic links must be +// created after evaluating, as those could potentially make a previously-safe +// path unsafe. +// +// For example, if "/foo/bar" does not exist, FollowSymlinkInScope("/foo/bar", "/foo") +// evaluates the path to "/foo/bar". If one makes "/foo/bar" a symbolic link to +// "/baz" subsequently, then "/foo/bar" should no longer be considered safely +// contained in "/foo". +// +// [CWE-367]: https://cwe.mitre.org/data/definitions/367.html func FollowSymlinkInScope(path, root string) (string, error) { path, err := filepath.Abs(filepath.FromSlash(path)) if err != nil { @@ -28,24 +60,9 @@ func FollowSymlinkInScope(path, root string) (string, error) { return evalSymlinksInScope(path, root) } -// evalSymlinksInScope will evaluate symlinks in `path` within a scope `root` and return -// a result guaranteed to be contained within the scope `root`, at the time of the call. -// Symlinks in `root` are not evaluated and left as-is. -// Errors encountered while attempting to evaluate symlinks in path will be returned. -// Non-existing paths are valid and do not constitute an error. -// `path` has to contain `root` as a prefix, or else an error will be returned. -// Trying to break out from `root` does not constitute an error. -// -// Example: -// -// If /foo/bar -> /outside, -// FollowSymlinkInScope("/foo/bar", "/foo") == "/foo/outside" instead of "/outside" -// -// IMPORTANT: it is the caller's responsibility to call evalSymlinksInScope *after* relevant symlinks -// are created and not to create subsequently, additional symlinks that could potentially make a -// previously-safe path, unsafe. Example: if /foo/bar does not exist, evalSymlinksInScope("/foo/bar", "/foo") -// would return "/foo/bar". If one makes /foo/bar a symlink to /baz subsequently, then "/foo/bar" should -// no longer be considered safely contained in "/foo". +// evalSymlinksInScope evaluates symbolic links in "path" within a scope "root" +// and returns a result guaranteed to be contained within the scope "root" at +// the time of the call. Refer to [FollowSymlinkInScope] for details. func evalSymlinksInScope(path, root string) (string, error) { root = filepath.Clean(root) if path == root { @@ -133,11 +150,15 @@ func evalSymlinksInScope(path, root string) (string, error) { return filepath.Clean(root + filepath.Clean(string(filepath.Separator)+b.String())), nil } +// EvalSymlinks is a modified version of [path/filepath.EvalSymlinks] from +// the Go standard library with support for Windows long paths (paths prepended +// with "\\?\"). On non-Windows platforms, it's an alias for [path/filepath.EvalSymlinks]. +// // EvalSymlinks returns the path name after the evaluation of any symbolic -// links. -// If path is relative the result will be relative to the current directory, -// unless one of the components is an absolute symbolic link. -// This version has been updated to support long paths prepended with `\\?\`. +// links. If path is relative, the result will be relative to the current +// directory, unless one of the components is an absolute symbolic link. +// +// EvalSymlinks calls [path/filepath.Clean] on the result. func EvalSymlinks(path string) (string, error) { return evalSymlinks(path) } diff --git a/symlink/fs_windows.go b/symlink/fs_windows.go index 87fd1b88..819b7289 100644 --- a/symlink/fs_windows.go +++ b/symlink/fs_windows.go @@ -1,3 +1,15 @@ +// Copyright 2012 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE.BSD file. + +// This code is a modified version of [path/filepath/symlink_windows.go] +// and [path/filepath/symlink.go] from the Go 1.4.2 standard library, and +// added in [docker@9b648df]. +// +// [path/filepath/symlink_windows.go]: https://github.com/golang/go/blob/go1.4.2/src/path/filepath/symlink_windows.go +// [path/filepath/symlink.go]: https://github.com/golang/go/blob/go1.4.2/src/path/filepath/symlink.go +// [docker@9b648df]: https://github.com/moby/moby/commit/9b648dfac6453de5944ee4bb749115d85a253a05 + package symlink import (