Merge pull request #138 from thaJeztah/fix_symlink_docs

symlink: touch-up documentation

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

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)
 }

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 (