README
¶
This is a fork of the Go archive/zip package to add support
for reading/writing password protected .zip files.
Only supports Winzip's AES extension: http://www.winzip.com/aes_info.htm.
This package DOES NOT intend to implement the encryption methods
mentioned in the original PKWARE spec (sections 6.0 and 7.0):
https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
Status - Alpha. More tests and code clean up next.
Documentation -
https://godoc.org/github.com/alexmullins/zip
Roadmap
========
Reading - Done.
Writing - Done.
Testing - Needs more.
The process
============
1. hello.txt -> compressed -> encrypted -> .zip
2. .zip -> decrypted -> decompressed -> hello.txt
Example Encrypt zip
==========
```
package main
import (
"bytes"
"log"
"os"
"github.com/alexmullins/zip"
)
func main() {
contents := []byte("Hello World")
fzip, err := os.Create(`./test.zip`)
if err != nil {
log.Fatalln(err)
}
zipw := zip.NewWriter(fzip)
defer zipw.Close()
w, err := zipw.Encrypt(`test.txt`, `golang`)
if err != nil {
log.Fatal(err)
}
_, err = io.Copy(w, bytes.NewReader(contents))
if err != nil {
log.Fatal(err)
}
zipw.Flush()
}
```
WinZip AES specifies
=====================
1. Encryption-Decryption w/ AES-CTR (128, 192, or 256 bits)
2. Key generation with PBKDF2-HMAC-SHA1 (1000 iteration count) that
generates a master key broken into the following:
a. First m bytes is for the encryption key
b. Next n bytes is for the authentication key
c. Last 2 bytes is the password verification value.
3. Following salt lengths are used w/ password during keygen:
------------------------------
AES Key Size | Salt Size
------------------------------
128bit(16bytes) | 8 bytes
192bit(24bytes) | 12 bytes
256bit(32bytes) | 16 bytes
-------------------------------
4. Master key len = AESKeyLen + AuthKeyLen + PWVLen:
a. AES 128 = 16 + 16 + 2 = 34 bytes of key material
b. AES 192 = 24 + 24 + 2 = 50 bytes of key material
c. AES 256 = 32 + 32 + 2 = 66 bytes of key material
5. Authentication Key is same size as AES key.
6. Authentication with HMAC-SHA1-80 (truncated to 80bits).
7. A new master key is generated for every file.
8. The file header and directory header compression method will
be 99 (decimal) indicating Winzip AES encryption. The actual
compression method will be in the extra's payload at the end
of the headers.
9. A extra field will be added to the file header and directory
header identified by the ID 0x9901 and contains the following info:
a. Header ID (2 bytes)
b. Data Size (2 bytes)
c. Vendor Version (2 bytes)
d. Vendor ID (2 bytes)
e. AES Strength (1 byte)
f. Compression Method (2 bytes)
10. The Data Size is always 7.
11. The Vendor Version can be either 0x0001 (AE-1) or
0x0002 (AE-2).
12. Vendor ID is ASCII "AE"
13. AES Strength:
a. 0x01 - AES-128
b. 0x02 - AES-192
c. 0x03 - AES-256
14. Compression Method is the actual compression method
used that was replaced by the encryption process mentioned in #8.
15. AE-1 keeps the CRC and should be verified after decompression.
AE-2 removes the CRC and shouldn't be verified after decompression.
Refer to http://www.winzip.com/aes_info.htm#winzip11 for the reasoning.
16. Storage Format (file data payload totals CompressedSize64 bytes):
a. Salt - 8, 12, or 16 bytes depending on keysize
b. Password Verification Value - 2 bytes
c. Encrypted Data - compressed size - salt - pwv - auth code lengths
d. Authentication code - 10 bytes
Documentation
¶
Overview ¶
Package zip provides support for reading and writing password protected ZIP archives.
See: http://www.pkware.com/documents/casestudies/APPNOTE.TXT
This package does not support disk spanning.
A note about ZIP64:
To be backwards compatible the FileHeader has both 32 and 64 bit Size fields. The 64 bit fields will always contain the correct value and for normal archives both fields will be the same. For files requiring the ZIP64 format the 32 bit fields will be 0xffffffff and the 64 bit fields must be used instead.
Can read/write password protected files that use Winzip's AES encryption method. See: http://www.winzip.com/aes_info.htm
Index ¶
- Constants
- Variables
- func RegisterCompressor(method uint16, comp Compressor)
- func RegisterDecompressor(method uint16, d Decompressor)
- type Compressor
- type Decompressor
- type File
- type FileHeader
- func (h *FileHeader) FileInfo() os.FileInfo
- func (h *FileHeader) IsEncrypted() bool
- func (h *FileHeader) ModTime() time.Time
- func (h *FileHeader) Mode() (mode os.FileMode)
- func (h *FileHeader) SetModTime(t time.Time)
- func (h *FileHeader) SetMode(mode os.FileMode)
- func (h *FileHeader) SetPassword(password string)
- type ReadCloser
- type Reader
- type Writer
Examples ¶
Constants ¶
const ( Store uint16 = 0 Deflate uint16 = 8 )
Compression methods.
Variables ¶
var ( ErrDecryption = errors.New("zip: decryption error") ErrPassword = errors.New("zip: invalid password") ErrAuthentication = errors.New("zip: authentication failed") )
Encryption/Decryption Errors
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, d Decompressor)
RegisterDecompressor allows custom decompressors for a specified method ID.
Types ¶
type Compressor ¶
type Compressor func(io.Writer) (io.WriteCloser, error)
A Compressor returns a compressing writer, writing to the provided writer. On Close, any pending data should be flushed.
type Decompressor ¶
type Decompressor func(io.Reader) io.ReadCloser
Decompressor is a function that wraps a Reader with a decompressing Reader. The decompressed ReadCloser is returned to callers who open files from within the archive. These callers are responsible for closing this reader when they're finished reading.
type File ¶
type File struct {
FileHeader
// contains filtered or unexported fields
}
func (*File) DataOffset ¶
DataOffset returns the offset of the file's possibly-compressed data, relative to the beginning of the zip file.
Most callers should instead use Open, which transparently decompresses data and verifies checksums.
type FileHeader ¶
type FileHeader struct {
// Name is the name of the file.
// It must be a relative path: it must not start with a drive
// letter (e.g. C:) or leading slash, and only forward slashes
// are allowed.
Name string
CreatorVersion uint16
ReaderVersion uint16
Flags uint16
Method uint16
ModifiedTime uint16 // MS-DOS time
ModifiedDate uint16 // MS-DOS date
CRC32 uint32
CompressedSize uint32 // Deprecated: Use CompressedSize64 instead.
UncompressedSize uint32 // Deprecated: Use UncompressedSize64 instead.
CompressedSize64 uint64
UncompressedSize64 uint64
Extra []byte
ExternalAttrs uint32 // Meaning depends on CreatorVersion
Comment string
// DeferAuth being set to true will delay hmac auth/integrity
// checks when decrypting a file meaning the reader will be
// getting unauthenticated plaintext. It is recommended to leave
// this set to false. For more detail:
// https://www.imperialviolet.org/2014/06/27/streamingencryption.html
// https://www.imperialviolet.org/2015/05/16/aeads.html
DeferAuth bool
// contains filtered or unexported fields
}
FileHeader describes a file within a zip file. See the zip spec for details.
func FileInfoHeader ¶
func FileInfoHeader(fi os.FileInfo) (*FileHeader, error)
FileInfoHeader creates a partially-populated FileHeader from an os.FileInfo. Because os.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.
func (*FileHeader) FileInfo ¶
func (h *FileHeader) FileInfo() os.FileInfo
FileInfo returns an os.FileInfo for the FileHeader.
func (*FileHeader) IsEncrypted ¶
func (h *FileHeader) IsEncrypted() bool
IsEncrypted indicates whether this file's data is encrypted.
func (*FileHeader) ModTime ¶
func (h *FileHeader) ModTime() time.Time
ModTime returns the modification time in UTC. The resolution is 2s.
func (*FileHeader) Mode ¶
func (h *FileHeader) Mode() (mode os.FileMode)
Mode returns the permission and mode bits for the FileHeader.
func (*FileHeader) SetModTime ¶
func (h *FileHeader) SetModTime(t time.Time)
SetModTime sets the ModifiedTime and ModifiedDate fields to the given time in UTC. The resolution is 2s.
func (*FileHeader) SetMode ¶
func (h *FileHeader) SetMode(mode os.FileMode)
SetMode changes the permission and mode bits for the FileHeader.
func (*FileHeader) SetPassword ¶
func (h *FileHeader) SetPassword(password string)
SetPassword sets the password used for encryption/decryption.
type ReadCloser ¶
type ReadCloser struct {
Reader
// contains filtered or unexported fields
}
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 (rc *ReadCloser) Close() error
Close closes the Zip file, rendering it unusable for I/O.
type Reader ¶
Example ¶
package main
import (
"fmt"
"io"
"log"
"os"
"github.com/alexmullins/zip"
)
func main() {
// Open a zip archive for reading.
r, err := zip.OpenReader("testdata/readme.zip")
if err != nil {
log.Fatal(err)
}
defer r.Close()
// Iterate through the files in the archive,
// printing some of their contents.
for _, f := range r.File {
fmt.Printf("Contents of %s:\n", f.Name)
rc, err := f.Open()
if err != nil {
log.Fatal(err)
}
_, err = io.CopyN(os.Stdout, rc, 68)
if err != nil {
log.Fatal(err)
}
rc.Close()
fmt.Println()
}
}
Output: Contents of README: This is the source code repository for the Go programming language.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer implements a zip file writer.
Example ¶
package main
import (
"bytes"
"log"
"github.com/alexmullins/zip"
)
func main() {
// Create a buffer to write our archive to.
buf := new(bytes.Buffer)
// Create a new zip archive.
w := zip.NewWriter(buf)
// Add some files to the archive.
var files = []struct {
Name, Body string
}{
{"readme.txt", "This archive contains some text files."},
{"gopher.txt", "Gopher names:\nGeorge\nGeoffrey\nGonzo"},
{"todo.txt", "Get animal handling licence.\nWrite more examples."},
}
for _, file := range files {
f, err := w.Create(file.Name)
if err != nil {
log.Fatal(err)
}
_, err = f.Write([]byte(file.Body))
if err != nil {
log.Fatal(err)
}
}
// Make sure to check the error on Close.
err := w.Close()
if err != nil {
log.Fatal(err)
}
}
Output:
func (*Writer) Close ¶
Close finishes writing the zip file by writing the central directory. It does not (and can not) close the underlying writer.
func (*Writer) Create ¶
Create adds a file to the zip file using the provided name. It returns a Writer to which the file contents should be written. The name must be a relative path: it must not start with a drive letter (e.g. C:) or leading slash, and only forward slashes are allowed. The file's contents must be written to the io.Writer before the next call to Create, CreateHeader, or Close.
func (*Writer) CreateHeader ¶
func (w *Writer) CreateHeader(fh *FileHeader) (io.Writer, error)
CreateHeader adds a file to the zip file using the provided FileHeader for the file metadata. It returns a Writer to which the file contents should be written.
The file's contents must be written to the io.Writer before the next call to Create, CreateHeader, or Close. The provided FileHeader fh must not be modified after a call to CreateHeader.
func (*Writer) Encrypt ¶
Encrypt adds a file to the zip file using the provided name. It returns a Writer to which the file contents should be written. File contents will be encrypted with AES-256 using the given password. The file's contents must be written to the io.Writer before the next call to Create, CreateHeader, or Close.
Example ¶
package main
import (
"bytes"
"io"
"log"
"os"
"github.com/alexmullins/zip"
)
func main() {
contents := []byte("Hello World")
// write a password zip
raw := new(bytes.Buffer)
zipw := zip.NewWriter(raw)
w, err := zipw.Encrypt("hello.txt", "golang")
if err != nil {
log.Fatal(err)
}
_, err = io.Copy(w, bytes.NewReader(contents))
if err != nil {
log.Fatal(err)
}
zipw.Close()
// read the password zip
zipr, err := zip.NewReader(bytes.NewReader(raw.Bytes()), int64(raw.Len()))
if err != nil {
log.Fatal(err)
}
for _, z := range zipr.File {
z.SetPassword("golang")
rr, err := z.Open()
if err != nil {
log.Fatal(err)
}
_, err = io.Copy(os.Stdout, rr)
if err != nil {
log.Fatal(err)
}
rr.Close()
}
}
Output: Hello World
Source Files