main
1//go:build windows
2// +build windows
3
4package winio
5
6import (
7 "encoding/binary"
8 "errors"
9 "fmt"
10 "io"
11 "os"
12 "runtime"
13 "unicode/utf16"
14
15 "github.com/Microsoft/go-winio/internal/fs"
16 "golang.org/x/sys/windows"
17)
18
19//sys backupRead(h windows.Handle, b []byte, bytesRead *uint32, abort bool, processSecurity bool, context *uintptr) (err error) = BackupRead
20//sys backupWrite(h windows.Handle, b []byte, bytesWritten *uint32, abort bool, processSecurity bool, context *uintptr) (err error) = BackupWrite
21
22const (
23 BackupData = uint32(iota + 1)
24 BackupEaData
25 BackupSecurity
26 BackupAlternateData
27 BackupLink
28 BackupPropertyData
29 BackupObjectId //revive:disable-line:var-naming ID, not Id
30 BackupReparseData
31 BackupSparseBlock
32 BackupTxfsData
33)
34
35const (
36 StreamSparseAttributes = uint32(8)
37)
38
39//nolint:revive // var-naming: ALL_CAPS
40const (
41 WRITE_DAC = windows.WRITE_DAC
42 WRITE_OWNER = windows.WRITE_OWNER
43 ACCESS_SYSTEM_SECURITY = windows.ACCESS_SYSTEM_SECURITY
44)
45
46// BackupHeader represents a backup stream of a file.
47type BackupHeader struct {
48 //revive:disable-next-line:var-naming ID, not Id
49 Id uint32 // The backup stream ID
50 Attributes uint32 // Stream attributes
51 Size int64 // The size of the stream in bytes
52 Name string // The name of the stream (for BackupAlternateData only).
53 Offset int64 // The offset of the stream in the file (for BackupSparseBlock only).
54}
55
56type win32StreamID struct {
57 StreamID uint32
58 Attributes uint32
59 Size uint64
60 NameSize uint32
61}
62
63// BackupStreamReader reads from a stream produced by the BackupRead Win32 API and produces a series
64// of BackupHeader values.
65type BackupStreamReader struct {
66 r io.Reader
67 bytesLeft int64
68}
69
70// NewBackupStreamReader produces a BackupStreamReader from any io.Reader.
71func NewBackupStreamReader(r io.Reader) *BackupStreamReader {
72 return &BackupStreamReader{r, 0}
73}
74
75// Next returns the next backup stream and prepares for calls to Read(). It skips the remainder of the current stream if
76// it was not completely read.
77func (r *BackupStreamReader) Next() (*BackupHeader, error) {
78 if r.bytesLeft > 0 { //nolint:nestif // todo: flatten this
79 if s, ok := r.r.(io.Seeker); ok {
80 // Make sure Seek on io.SeekCurrent sometimes succeeds
81 // before trying the actual seek.
82 if _, err := s.Seek(0, io.SeekCurrent); err == nil {
83 if _, err = s.Seek(r.bytesLeft, io.SeekCurrent); err != nil {
84 return nil, err
85 }
86 r.bytesLeft = 0
87 }
88 }
89 if _, err := io.Copy(io.Discard, r); err != nil {
90 return nil, err
91 }
92 }
93 var wsi win32StreamID
94 if err := binary.Read(r.r, binary.LittleEndian, &wsi); err != nil {
95 return nil, err
96 }
97 hdr := &BackupHeader{
98 Id: wsi.StreamID,
99 Attributes: wsi.Attributes,
100 Size: int64(wsi.Size),
101 }
102 if wsi.NameSize != 0 {
103 name := make([]uint16, int(wsi.NameSize/2))
104 if err := binary.Read(r.r, binary.LittleEndian, name); err != nil {
105 return nil, err
106 }
107 hdr.Name = windows.UTF16ToString(name)
108 }
109 if wsi.StreamID == BackupSparseBlock {
110 if err := binary.Read(r.r, binary.LittleEndian, &hdr.Offset); err != nil {
111 return nil, err
112 }
113 hdr.Size -= 8
114 }
115 r.bytesLeft = hdr.Size
116 return hdr, nil
117}
118
119// Read reads from the current backup stream.
120func (r *BackupStreamReader) Read(b []byte) (int, error) {
121 if r.bytesLeft == 0 {
122 return 0, io.EOF
123 }
124 if int64(len(b)) > r.bytesLeft {
125 b = b[:r.bytesLeft]
126 }
127 n, err := r.r.Read(b)
128 r.bytesLeft -= int64(n)
129 if err == io.EOF {
130 err = io.ErrUnexpectedEOF
131 } else if r.bytesLeft == 0 && err == nil {
132 err = io.EOF
133 }
134 return n, err
135}
136
137// BackupStreamWriter writes a stream compatible with the BackupWrite Win32 API.
138type BackupStreamWriter struct {
139 w io.Writer
140 bytesLeft int64
141}
142
143// NewBackupStreamWriter produces a BackupStreamWriter on top of an io.Writer.
144func NewBackupStreamWriter(w io.Writer) *BackupStreamWriter {
145 return &BackupStreamWriter{w, 0}
146}
147
148// WriteHeader writes the next backup stream header and prepares for calls to Write().
149func (w *BackupStreamWriter) WriteHeader(hdr *BackupHeader) error {
150 if w.bytesLeft != 0 {
151 return fmt.Errorf("missing %d bytes", w.bytesLeft)
152 }
153 name := utf16.Encode([]rune(hdr.Name))
154 wsi := win32StreamID{
155 StreamID: hdr.Id,
156 Attributes: hdr.Attributes,
157 Size: uint64(hdr.Size),
158 NameSize: uint32(len(name) * 2),
159 }
160 if hdr.Id == BackupSparseBlock {
161 // Include space for the int64 block offset
162 wsi.Size += 8
163 }
164 if err := binary.Write(w.w, binary.LittleEndian, &wsi); err != nil {
165 return err
166 }
167 if len(name) != 0 {
168 if err := binary.Write(w.w, binary.LittleEndian, name); err != nil {
169 return err
170 }
171 }
172 if hdr.Id == BackupSparseBlock {
173 if err := binary.Write(w.w, binary.LittleEndian, hdr.Offset); err != nil {
174 return err
175 }
176 }
177 w.bytesLeft = hdr.Size
178 return nil
179}
180
181// Write writes to the current backup stream.
182func (w *BackupStreamWriter) Write(b []byte) (int, error) {
183 if w.bytesLeft < int64(len(b)) {
184 return 0, fmt.Errorf("too many bytes by %d", int64(len(b))-w.bytesLeft)
185 }
186 n, err := w.w.Write(b)
187 w.bytesLeft -= int64(n)
188 return n, err
189}
190
191// BackupFileReader provides an io.ReadCloser interface on top of the BackupRead Win32 API.
192type BackupFileReader struct {
193 f *os.File
194 includeSecurity bool
195 ctx uintptr
196}
197
198// NewBackupFileReader returns a new BackupFileReader from a file handle. If includeSecurity is true,
199// Read will attempt to read the security descriptor of the file.
200func NewBackupFileReader(f *os.File, includeSecurity bool) *BackupFileReader {
201 r := &BackupFileReader{f, includeSecurity, 0}
202 return r
203}
204
205// Read reads a backup stream from the file by calling the Win32 API BackupRead().
206func (r *BackupFileReader) Read(b []byte) (int, error) {
207 var bytesRead uint32
208 err := backupRead(windows.Handle(r.f.Fd()), b, &bytesRead, false, r.includeSecurity, &r.ctx)
209 if err != nil {
210 return 0, &os.PathError{Op: "BackupRead", Path: r.f.Name(), Err: err}
211 }
212 runtime.KeepAlive(r.f)
213 if bytesRead == 0 {
214 return 0, io.EOF
215 }
216 return int(bytesRead), nil
217}
218
219// Close frees Win32 resources associated with the BackupFileReader. It does not close
220// the underlying file.
221func (r *BackupFileReader) Close() error {
222 if r.ctx != 0 {
223 _ = backupRead(windows.Handle(r.f.Fd()), nil, nil, true, false, &r.ctx)
224 runtime.KeepAlive(r.f)
225 r.ctx = 0
226 }
227 return nil
228}
229
230// BackupFileWriter provides an io.WriteCloser interface on top of the BackupWrite Win32 API.
231type BackupFileWriter struct {
232 f *os.File
233 includeSecurity bool
234 ctx uintptr
235}
236
237// NewBackupFileWriter returns a new BackupFileWriter from a file handle. If includeSecurity is true,
238// Write() will attempt to restore the security descriptor from the stream.
239func NewBackupFileWriter(f *os.File, includeSecurity bool) *BackupFileWriter {
240 w := &BackupFileWriter{f, includeSecurity, 0}
241 return w
242}
243
244// Write restores a portion of the file using the provided backup stream.
245func (w *BackupFileWriter) Write(b []byte) (int, error) {
246 var bytesWritten uint32
247 err := backupWrite(windows.Handle(w.f.Fd()), b, &bytesWritten, false, w.includeSecurity, &w.ctx)
248 if err != nil {
249 return 0, &os.PathError{Op: "BackupWrite", Path: w.f.Name(), Err: err}
250 }
251 runtime.KeepAlive(w.f)
252 if int(bytesWritten) != len(b) {
253 return int(bytesWritten), errors.New("not all bytes could be written")
254 }
255 return len(b), nil
256}
257
258// Close frees Win32 resources associated with the BackupFileWriter. It does not
259// close the underlying file.
260func (w *BackupFileWriter) Close() error {
261 if w.ctx != 0 {
262 _ = backupWrite(windows.Handle(w.f.Fd()), nil, nil, true, false, &w.ctx)
263 runtime.KeepAlive(w.f)
264 w.ctx = 0
265 }
266 return nil
267}
268
269// OpenForBackup opens a file or directory, potentially skipping access checks if the backup
270// or restore privileges have been acquired.
271//
272// If the file opened was a directory, it cannot be used with Readdir().
273func OpenForBackup(path string, access uint32, share uint32, createmode uint32) (*os.File, error) {
274 h, err := fs.CreateFile(path,
275 fs.AccessMask(access),
276 fs.FileShareMode(share),
277 nil,
278 fs.FileCreationDisposition(createmode),
279 fs.FILE_FLAG_BACKUP_SEMANTICS|fs.FILE_FLAG_OPEN_REPARSE_POINT,
280 0,
281 )
282 if err != nil {
283 err = &os.PathError{Op: "open", Path: path, Err: err}
284 return nil, err
285 }
286 return os.NewFile(uintptr(h), path), nil
287}