1// Copyright (C) 2014-2015 Docker Inc & Go Authors. All rights reserved.
 2// Copyright (C) 2017-2024 SUSE LLC. All rights reserved.
 3// Use of this source code is governed by a BSD-style
 4// license that can be found in the LICENSE file.
 5
 6// Package securejoin implements a set of helpers to make it easier to write Go
 7// code that is safe against symlink-related escape attacks. The primary idea
 8// is to let you resolve a path within a rootfs directory as if the rootfs was
 9// a chroot.
10//
11// securejoin has two APIs, a "legacy" API and a "modern" API.
12//
13// The legacy API is [SecureJoin] and [SecureJoinVFS]. These methods are
14// **not** safe against race conditions where an attacker changes the
15// filesystem after (or during) the [SecureJoin] operation.
16//
17// The new API is made up of [OpenInRoot] and [MkdirAll] (and derived
18// functions). These are safe against racing attackers and have several other
19// protections that are not provided by the legacy API. There are many more
20// operations that most programs expect to be able to do safely, but we do not
21// provide explicit support for them because we want to encourage users to
22// switch to [libpathrs](https://github.com/openSUSE/libpathrs) which is a
23// cross-language next-generation library that is entirely designed around
24// operating on paths safely.
25//
26// securejoin has been used by several container runtimes (Docker, runc,
27// Kubernetes, etc) for quite a few years as a de-facto standard for operating
28// on container filesystem paths "safely". However, most users still use the
29// legacy API which is unsafe against various attacks (there is a fairly long
30// history of CVEs in dependent as a result). Users should switch to the modern
31// API as soon as possible (or even better, switch to libpathrs).
32//
33// This project was initially intended to be included in the Go standard
34// library, but [it was rejected](https://go.dev/issue/20126). There is now a
35// [new Go proposal](https://go.dev/issue/67002) for a safe path resolution API
36// that shares some of the goals of filepath-securejoin. However, that design
37// is intended to work like `openat2(RESOLVE_BENEATH)` which does not fit the
38// usecase of container runtimes and most system tools.
39package securejoin