README
¶
safeopen
This is not an officially supported Google product.
Safe-by-construction library with file open/create primitives for Golang that are not vulnerable to path traversal attacks. The library supports Unix and Windows systems. OS native safe primitives are leveraged where available (e.g. openat2 + RESOLVE_BENEATH). Symbolic links are followed only if there is a safe way to prevent traversal (e.g. on platforms where OS level safe primitives are available), otherwise an error is returned.
Usage
All these library functions expect a base directory as their first parameter. There are two families of API functions, they have the suffix:
- #1 At: The file to be opened must be directly in the base directory
- #2 Beneath: The file to be opened must be somewhere underneath the base directory
Example:
fd, err := safeopen.OpenBeneath("/workdir", filenameFromUserInput)
if err != nil {
return fmt.Errorf("unable to open file %v: %v", filenameFromUserInput, err)
}
// now do the same what you would with the return value of `os.Open`
...
The library also supports replacement functions of os.ReadFile and
os.WriteFile. Example:
data, err := safeopen.ReadFileBeneath("/workdir", filenameFromUserInput)
if err != nil {
return fmt.Errorf("unable to open file %v: %v", filenameFromUserInput, err)
}
// now you can process data safely
...
Documentation
¶
Overview ¶
Package safeopen provides replacement APIs for Open that do not permit path traversal. The library supports Unix and Windows systems. OS native safe primitives are leveraged where available (e.g. openat2 + RESOLVE_BENEATH). Symbolic links are followed only if there is a safe way to prevent traversal (e.g. on platforms where OS level safe primitives are available), otherwise an error is returned.
Index ¶
- func CreateAt(directory, file string) (*os.File, error)
- func CreateBeneath(directory, file string) (*os.File, error)
- func OpenAt(directory, file string) (*os.File, error)
- func OpenBeneath(directory, file string) (*os.File, error)
- func OpenFileAt(directory, file string, flag int, perm os.FileMode) (*os.File, error)
- func OpenFileBeneath(directory, file string, flag int, perm os.FileMode) (*os.File, error)
- func ReadFileAt(directory, file string) ([]byte, error)
- func ReadFileBeneath(directory, file string) ([]byte, error)
- func WriteFileAt(directory, file string, data []byte, perm os.FileMode) error
- func WriteFileBeneath(directory, file string, data []byte, perm os.FileMode) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateAt ¶
CreateAt creates or truncates the named file in the named directory. file may not contain path separators.
If the file already exists, it is truncated. If the file does not exist, it is created with mode 0666 (before umask). If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. If there is an error, it will be of type *PathError.
func CreateBeneath ¶
CreateBeneath creates or truncates the named file in the named directory. file may not contain .. path traversal entries.
If the file already exists, it is truncated. If the file does not exist, it is created with mode 0666 (before umask). If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. If there is an error, it will be of type *PathError.
func OpenAt ¶
OpenAt opens the named file in the named directory for reading. file may not contain path separators.
If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY. If there is an error, it will be of type *PathError.
func OpenBeneath ¶
OpenBeneath opens the named file in the named directory, or a subdirectory, for reading. file may not contain .. path traversal entries.
If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY. If there is an error, it will be of type *PathError.
func OpenFileAt ¶
OpenFileAt is the generalized OpenAt call; most users will use OpenAt or CreateAt instead.
It opens the named file in the named directory with specified flag (O_RDONLY etc.). File may not contain path separators. If the file does not exist, and the O_CREATE flag is passed, it is created with mode perm (before umask). The perm parameter is ignored on Windows. If successful, methods on the returned File can be used for I/O. If there is an error, it will be of type *PathError.
func OpenFileBeneath ¶
OpenFileBeneath is the generalized OpenBeneath call; most users will use OpenBeneath or CreateBeneath instead.
It opens the named file in the named directory with specified flag (O_RDONLY etc.). File may not contain .. path traversal entries. If the file does not exist, and the O_CREATE flag is passed, it is created with mode perm (before umask). The perm parameter is ignored on Windows. If successful, methods on the returned File can be used for I/O. If there is an error, it will be of type *PathError.
func ReadFileAt ¶
ReadFileAt is a replacement of os.ReadFile that leverages safeopen.OpenAt.
func ReadFileBeneath ¶
ReadFileBeneath is a replacement of os.ReadFile that leverages safeopen.OpenBeneath.
func WriteFileAt ¶
WriteFileAt is a replacement of os.WriteFile that leverages safeopen.CreateAt.
Types ¶
This section is empty.
Source Files