zip

Documentation

Overview

Package zip is a drop-in replacement for archive/zip which security focus.

To prevent security implications (e.g. directory traversal) of attacker controlled crafted zip archives, this library sanitizes - file names (bugos filename entries like ../something are fixed on the fly) - the file mode (removing special bits like setuid) It also: - skips symbolic link entries - skips special file types silently (fifos, device nodes, char devices, etc.)

All these features are enabled by default and can be turned off one-by-one via the SetSecurityMode method of the Reader/ReadCloser.

Features turned on by default: - SanitizeFilenames - PreventSymlinkTraversal These two features are compatible with all known legitimate use-cases.

You may enable the other features individually like this: tr := zip.OpenReader("some.zip") tr.SetSecurityMode(tr.GetSecurityMode() | zip.SanitizeFileMode | zip.SkipSpecialFiles) or tr.SetSecurityMode(zip.MaximumSecurityMode)

You may opt out from a certain feature like this: tr.SetSecurityMode(tr.GetSecurityMode() &^ zip.SanitizeFileMode)

Index

• Constants
• Variables
• func RegisterCompressor(method uint16, comp Compressor)
• func RegisterDecompressor(method uint16, dcomp Decompressor)
• type Compressor
• type Decompressor
• type File
• type FileHeader
  • func FileInfoHeader(fi fs.FileInfo) (*FileHeader, error)
• type ReadCloser
  • func OpenReader(name string) (*ReadCloser, error)
  • func (r *ReadCloser) Close() error
  • func (r *ReadCloser) GetSecurityMode() SecurityMode
  • func (r *ReadCloser) SetSecurityMode(sm SecurityMode)
• type Reader
  • func NewReader(r io.ReaderAt, size int64) (*Reader, error)
  • func (r *Reader) GetSecurityMode() SecurityMode
  • func (r *Reader) SetSecurityMode(sm SecurityMode)
• type SecurityMode
• type Writer
  • func NewWriter(w io.Writer) *Writer

Constants

const (
	// Store no compression
	Store uint16 = zip.Store
	// Deflate DEFLATE compressed
	Deflate uint16 = zip.Deflate
)

const DefaultSecurityMode = SanitizeFilenames | PreventSymlinkTraversal

DefaultSecurityMode enables path traversal security measures. This mode should be safe for all existing integrations.

const MaximumSecurityMode = SanitizeFilenames | PreventSymlinkTraversal | SanitizeFileMode | SkipSpecialFiles | PreventCaseInsensitiveSymlinkTraversal | SkipWindowsShortFilenames

MaximumSecurityMode enables all security features. Apps that care about file contents only and nothing unix specific (e.g. file modes or special devices) should use this mode.

Variables

var (
	// ErrFormat not a valid zip file
	ErrFormat = zip.ErrFormat
	// ErrAlgorithm unsupported compression algorithm
	ErrAlgorithm = zip.ErrAlgorithm
	// ErrChecksum checksum error
	ErrChecksum = zip.ErrChecksum
)

Functions

func RegisterCompressor

func RegisterCompressor(method uint16, comp Compressor)

RegisterCompressor registers custom compressors for a specified method ID. The common methods Store and Deflate are built in.

func RegisterDecompressor

func RegisterDecompressor(method uint16, dcomp Decompressor)

RegisterDecompressor allows custom decompressors for a specified method ID. The common methods Store and Deflate are built in.

Types

type Compressor

type Compressor = zip.Compressor

A Compressor returns a new compressing writer, writing to w. The WriteCloser's Close method must be used to flush pending data to w. The Compressor itself must be safe to invoke from multiple goroutines simultaneously, but each returned writer will be used only by one goroutine at a time.

type Decompressor

type Decompressor = zip.Decompressor

A Decompressor returns a new decompressing reader, reading from r. The ReadCloser's Close method must be used to release associated resources. The Decompressor itself must be safe to invoke from multiple goroutines simultaneously, but each returned reader will be used only by one goroutine at a time.

type File

type File = zip.File

A File is a single file in a ZIP archive. The file information is in the embedded FileHeader. The file content can be accessed by calling Open.

type FileHeader

type FileHeader = zip.FileHeader

FileHeader describes a file within a zip file. See the zip spec for details.

func FileInfoHeader

func FileInfoHeader(fi fs.FileInfo) (*FileHeader, error)

FileInfoHeader creates a partially-populated FileHeader from an fs.FileInfo. Because fs.FileInfo's Name method returns only the base name of the file it describes, it may be necessary to modify the Name field of the returned header to provide the full path name of the file. If compression is desired, callers should set the FileHeader.Method field; it is unset by default.

type ReadCloser

type ReadCloser struct {
	Reader
	// contains filtered or unexported fields
}

A ReadCloser is a Reader that must be closed when no longer needed.

func OpenReader

func OpenReader(name string) (*ReadCloser, error)

OpenReader will open the Zip file specified by name and return a ReadCloser.

func (*ReadCloser) Close

func (r *ReadCloser) Close() error

Close closes the Zip file, rendering it unusable for I/O.

func (*ReadCloser) GetSecurityMode

func (r *ReadCloser) GetSecurityMode() SecurityMode

GetSecurityMode returns the currently enabled security rules

func (*ReadCloser) SetSecurityMode

func (r *ReadCloser) SetSecurityMode(sm SecurityMode)

SetSecurityMode applies the security rules on the set of files in the archive

type Reader

type Reader struct {
	*zip.Reader
	// contains filtered or unexported fields
}

A Reader serves content from a ZIP archive.

func NewReader

func NewReader(r io.ReaderAt, size int64) (*Reader, error)

NewReader returns a new Reader reading from r, which is assumed to have the given size in bytes.

func (*Reader) GetSecurityMode

func (r *Reader) GetSecurityMode() SecurityMode

GetSecurityMode returns the currently enabled security rules

func (*Reader) SetSecurityMode

func (r *Reader) SetSecurityMode(sm SecurityMode)

SetSecurityMode applies the security rules on the set of files in the archive

type SecurityMode

type SecurityMode int

SecurityMode controls security features to enforce

const (
	// PreventSymlinkTraversal security mode detects symlink
	// This feature is enabled by default.
	PreventSymlinkTraversal SecurityMode = 1
	// SkipSpecialFiles security mode skips special files (e.g. block devices or fifos), links are allowed still
	// This feature is not enabled by default.
	SkipSpecialFiles SecurityMode = 2
	// SanitizeFileMode will drop special file modes (e.g. setuid and tmp bit)
	// This feature is not enabled by default.
	SanitizeFileMode SecurityMode = 4
	// SanitizeFilenames will sanitize filenames (dropping .. path components and turning entries into relative)
	// This feature is enabled by default.
	SanitizeFilenames SecurityMode = 8
	// PreventCaseInsensitiveSymlinkTraversal activates case insensitive symlink traversal detection.
	// This feature requires PreventSymlinkTraversal to be enabled as well.
	// By default, this is activated only on MacOS and Windows builds. If you are extracting to a
	// case insensitive filesystem on a Unix platform, you should activate this feature explicitly.
	PreventCaseInsensitiveSymlinkTraversal SecurityMode = 16
	// SkipWindowsShortFilenames drops archive entries that have a path component that look like a
	// Windows short filename (e.g. GIT~1).
	// By default, this is activated only on Windows builds. If you are extracting to a Windows
	// filesystem on a non-Windows platform, you should activate this feature explicitly.
	SkipWindowsShortFilenames SecurityMode = 32
)

type Writer

type Writer = zip.Writer

Writer implements a zip file writer.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter returns a new Writer writing a zip file to w.