safeopen

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

Functions

func CreateAt

func CreateAt(directory, file string) (*os.File, error)

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

func CreateBeneath(directory, file string) (*os.File, error)

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

func OpenAt(directory, file string) (*os.File, error)

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

func OpenBeneath(directory, file string) (*os.File, error)

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

func OpenFileAt(directory, file string, flag int, perm os.FileMode) (*os.File, error)

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

func OpenFileBeneath(directory, file string, flag int, perm os.FileMode) (*os.File, error)

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

func ReadFileAt(directory, file string) ([]byte, error)

ReadFileAt is a replacement of os.ReadFile that leverages safeopen.OpenAt.

func ReadFileBeneath

func ReadFileBeneath(directory, file string) ([]byte, error)

ReadFileBeneath is a replacement of os.ReadFile that leverages safeopen.OpenBeneath.

func WriteFileAt

func WriteFileAt(directory, file string, data []byte, perm os.FileMode) error

WriteFileAt is a replacement of os.WriteFile that leverages safeopen.CreateAt.

func WriteFileBeneath

func WriteFileBeneath(directory, file string, data []byte, perm os.FileMode) error

WriteFileBeneath is a replacement of os.WriteFile that leverages safeopen.CreateBeneath.