Documentation
¶
Overview ¶
Package privatefile creates and maintains local files and directories that only the current user can read.
The SDK keeps data on the local disk on its own behalf: cached file contents, scratch files a mounted file system stores outside Files.com, working copies of files being uploaded, and downloads that are still being written. None of that is meant for other users of the same computer, so it is created private and kept private until it is deleted or, for a download, deliberately published.
"Private" means the process owner on POSIX systems (mode 0700 for directories and 0600 for files), and on Windows an access control list that grants access only to the owning account, SYSTEM and Administrators. On Windows the mode bits Go accepts do not restrict anything, so the Windows implementation sets discretionary access control lists instead.
Index ¶
- func CheckContainer(dir string) error
- func CheckEntry(path string, info fs.FileInfo) error
- func EnsureDir(path string) error
- func EnsureEntryPrivate(path string, info fs.FileInfo) error
- func Mkdir(path string) error
- func MkdirTemp(dir string, pattern string) (string, error)
- func OpenFile(root *os.Root, name string, flag int, perm fs.FileMode) (*os.File, error)
- type Publication
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckContainer ¶
CheckContainer reports whether private storage can safely be created inside dir, a directory the caller selected. Private storage is only as private as the directories above it: a user who can rename or delete entries in dir or in any directory above it can replace the private storage with a tree they control. So dir and every directory above it must be owned by the current user or the system, and must not let other users modify their entries. World-writable directories with the sticky bit, such as the system temporary directory, are accepted: there only the owner of an entry can remove it.
Every name on the way is examined as it is given and as it resolves: a directory component must itself be safe, and a link component must be owned by the current user or the system, must sit in a safe directory, and must lead, through any further links, only through safe directories. Otherwise a user who can replace the link, or a directory the link passes through, could redirect the path.
A configuration that fails this check is refused with a descriptive error rather than used, because there is no way to make storage inside it private.
func CheckEntry ¶
CheckEntry reports whether one entry inside a directory this package is about to make private may be made private along with it. info must be the Lstat of path. Only entries this package could have created qualify: a regular file or directory owned by the current user with a single name. A symbolic link is refused because chmod would follow it to whatever it points at; a file with several names is refused because its mode is shared with a name somewhere this process does not control; an entry owned by someone else is refused because it is not this process's data and could not be made private anyway. Nothing is modified.
func EnsureDir ¶
EnsureDir makes path a private directory this process owns: it creates a missing one, and removes group and other access from an existing one.
An existing path must be a real directory (not a symbolic link) owned by the current user. Anything else is refused rather than used, because chmod on a link or a directory another user prepared could change unrelated data or hand this process's data to that user.
func EnsureEntryPrivate ¶
EnsureEntryPrivate removes group and other access from one entry inside a directory that EnsureDir made private, after CheckEntry accepts it. info must be the Lstat of path.
func Mkdir ¶
Mkdir creates a directory only the current user can access. It fails if path already exists.
func MkdirTemp ¶
MkdirTemp creates a new private directory with a unique name inside dir and returns its path. The name is pattern with the final "*" replaced by a random string, like os.MkdirTemp, but the directory is private on every platform, including Windows where os.MkdirTemp inherits the parent's access.
func OpenFile ¶
OpenFile opens name inside root as a file only the current user can read. perm is the mode for a file this call creates; it must not grant group or other access. A file that already existed is made private before OpenFile returns, by removing its group and other bits, so no data written through the returned file is ever exposed.
Types ¶
type Publication ¶
type Publication struct {
// contains filtered or unexported fields
}
Publication is the access a privately staged file receives when it is published at its final path: what a freshly created file would get there, never more than an existing file at that path already had, and never more than the caller prepared for the staged file.
The staged file keeps its private access through every rename or copy that moves it into place. Only once it is at its final path does it receive the published access, through a handle whose identity is checked, so bytes are never readable by others while publication can still fail, and access is never applied to a file that took the staged file's place.
func PublicationFor ¶
func PublicationFor(root *os.Root, name string, probeName string, limit fs.FileMode) (Publication, error)
PublicationFor determines the access a file published as name inside root receives. probeName is a name inside the directory of name that nothing else uses; on POSIX systems an empty file is created and removed under that name to observe the process umask without the process-global umask call. limit is the most access the published file may have on account of the staged file itself: fs.ModePerm when the stage was created by the caller's own code and carries no wishes of its own, or the mode a caller-prepared stage had before it was made private.
func (Publication) ApplyToPublished ¶
ApplyToPublished gives the file now at name inside root the published access. published identifies the file that was moved there; a different file at that name is left alone and reported.
Source Files