Add helpers for Windows Extended Attributes

This commit is contained in:
aneesh-n 2024-05-17 14:15:03 -06:00
parent 7ed560a201
commit d6708505b9
No known key found for this signature in database
GPG key ID: 6F5A52831C046F44
2 changed files with 543 additions and 0 deletions

284
internal/fs/ea_windows.go Normal file
View file

@ -0,0 +1,284 @@
//go:build windows
// +build windows
package fs
import (
"bytes"
"encoding/binary"
"errors"
"fmt"
"syscall"
"unsafe"
"golang.org/x/sys/windows"
)
// The code below was adapted from https://github.com/microsoft/go-winio under MIT license.
// The MIT License (MIT)
// Copyright (c) 2015 Microsoft
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
// The code below was copied over from https://github.com/microsoft/go-winio/blob/main/ea.go under MIT license.
type fileFullEaInformation struct {
NextEntryOffset uint32
Flags uint8
NameLength uint8
ValueLength uint16
}
var (
fileFullEaInformationSize = binary.Size(&fileFullEaInformation{})
errInvalidEaBuffer = errors.New("invalid extended attribute buffer")
errEaNameTooLarge = errors.New("extended attribute name too large")
errEaValueTooLarge = errors.New("extended attribute value too large")
)
// ExtendedAttribute represents a single Windows EA.
type ExtendedAttribute struct {
Name string
Value []byte
Flags uint8
}
func parseEa(b []byte) (ea ExtendedAttribute, nb []byte, err error) {
var info fileFullEaInformation
err = binary.Read(bytes.NewReader(b), binary.LittleEndian, &info)
if err != nil {
err = errInvalidEaBuffer
return ea, nb, err
}
nameOffset := fileFullEaInformationSize
nameLen := int(info.NameLength)
valueOffset := nameOffset + int(info.NameLength) + 1
valueLen := int(info.ValueLength)
nextOffset := int(info.NextEntryOffset)
if valueLen+valueOffset > len(b) || nextOffset < 0 || nextOffset > len(b) {
err = errInvalidEaBuffer
return ea, nb, err
}
ea.Name = string(b[nameOffset : nameOffset+nameLen])
ea.Value = b[valueOffset : valueOffset+valueLen]
ea.Flags = info.Flags
if info.NextEntryOffset != 0 {
nb = b[info.NextEntryOffset:]
}
return ea, nb, err
}
// DecodeExtendedAttributes decodes a list of EAs from a FILE_FULL_EA_INFORMATION
// buffer retrieved from BackupRead, ZwQueryEaFile, etc.
func DecodeExtendedAttributes(b []byte) (eas []ExtendedAttribute, err error) {
for len(b) != 0 {
ea, nb, err := parseEa(b)
if err != nil {
return nil, err
}
eas = append(eas, ea)
b = nb
}
return eas, err
}
func writeEa(buf *bytes.Buffer, ea *ExtendedAttribute, last bool) error {
if int(uint8(len(ea.Name))) != len(ea.Name) {
return errEaNameTooLarge
}
if int(uint16(len(ea.Value))) != len(ea.Value) {
return errEaValueTooLarge
}
entrySize := uint32(fileFullEaInformationSize + len(ea.Name) + 1 + len(ea.Value))
withPadding := (entrySize + 3) &^ 3
nextOffset := uint32(0)
if !last {
nextOffset = withPadding
}
info := fileFullEaInformation{
NextEntryOffset: nextOffset,
Flags: ea.Flags,
NameLength: uint8(len(ea.Name)),
ValueLength: uint16(len(ea.Value)),
}
err := binary.Write(buf, binary.LittleEndian, &info)
if err != nil {
return err
}
_, err = buf.Write([]byte(ea.Name))
if err != nil {
return err
}
err = buf.WriteByte(0)
if err != nil {
return err
}
_, err = buf.Write(ea.Value)
if err != nil {
return err
}
_, err = buf.Write([]byte{0, 0, 0}[0 : withPadding-entrySize])
if err != nil {
return err
}
return nil
}
// EncodeExtendedAttributes encodes a list of EAs into a FILE_FULL_EA_INFORMATION
// buffer for use with BackupWrite, ZwSetEaFile, etc.
func EncodeExtendedAttributes(eas []ExtendedAttribute) ([]byte, error) {
var buf bytes.Buffer
for i := range eas {
last := false
if i == len(eas)-1 {
last = true
}
err := writeEa(&buf, &eas[i], last)
if err != nil {
return nil, err
}
}
return buf.Bytes(), nil
}
// The code below was copied over from https://github.com/microsoft/go-winio/blob/main/pipe.go under MIT license.
type ntStatus int32
func (status ntStatus) Err() error {
if status >= 0 {
return nil
}
return rtlNtStatusToDosError(status)
}
// The code below was copied over from https://github.com/microsoft/go-winio/blob/main/zsyscall_windows.go under MIT license.
// ioStatusBlock represents the IO_STATUS_BLOCK struct defined here:
// https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/ns-wdm-_io_status_block
type ioStatusBlock struct {
Status, Information uintptr
}
var (
modntdll = windows.NewLazySystemDLL("ntdll.dll")
procRtlNtStatusToDosErrorNoTeb = modntdll.NewProc("RtlNtStatusToDosErrorNoTeb")
)
func rtlNtStatusToDosError(status ntStatus) (winerr error) {
r0, _, _ := syscall.SyscallN(procRtlNtStatusToDosErrorNoTeb.Addr(), uintptr(status))
if r0 != 0 {
winerr = syscall.Errno(r0)
}
return
}
// The code below was adapted from https://github.com/ambarve/go-winio/blob/a7564fd482feb903f9562a135f1317fd3b480739/ea.go
// under MIT license.
var (
procNtQueryEaFile = modntdll.NewProc("NtQueryEaFile")
procNtSetEaFile = modntdll.NewProc("NtSetEaFile")
)
const (
// noExtendedAttribsStatus is a constant value which indicates no extended attributes were found
noExtendedAttribsStatus = -1073741742
)
// GetFileEA retrieves the extended attributes for the file represented by `handle`. The
// `handle` must have been opened with file access flag FILE_READ_EA (0x8).
// The extended file attribute names in windows are case-insensitive and when fetching
// the attributes the names are generally returned in UPPER case.
func GetFileEA(handle windows.Handle) ([]ExtendedAttribute, error) {
// default buffer size to start with
bufLen := 1024
buf := make([]byte, bufLen)
var iosb ioStatusBlock
// keep increasing the buffer size until it is large enough
for {
status := getFileEA(handle, &iosb, &buf[0], uint32(bufLen), false, 0, 0, nil, true)
if status == noExtendedAttribsStatus {
//If status is -1073741742, no extended attributes were found
return nil, nil
}
err := status.Err()
if err != nil {
// convert ntstatus code to windows error
if err == windows.ERROR_INSUFFICIENT_BUFFER || err == windows.ERROR_MORE_DATA {
bufLen *= 2
buf = make([]byte, bufLen)
continue
}
return nil, fmt.Errorf("get file EA failed with: %w", err)
}
break
}
return DecodeExtendedAttributes(buf)
}
// SetFileEA sets the extended attributes for the file represented by `handle`. The
// handle must have been opened with the file access flag FILE_WRITE_EA(0x10).
func SetFileEA(handle windows.Handle, attrs []ExtendedAttribute) error {
encodedEA, err := EncodeExtendedAttributes(attrs)
if err != nil {
return fmt.Errorf("failed to encoded extended attributes: %w", err)
}
var iosb ioStatusBlock
return setFileEA(handle, &iosb, &encodedEA[0], uint32(len(encodedEA))).Err()
}
// The code below was adapted from https://github.com/ambarve/go-winio/blob/a7564fd482feb903f9562a135f1317fd3b480739/zsyscall_windows.go
// under MIT license.
func getFileEA(handle windows.Handle, iosb *ioStatusBlock, buf *uint8, bufLen uint32, returnSingleEntry bool, eaList uintptr, eaListLen uint32, eaIndex *uint32, restartScan bool) (status ntStatus) {
var _p0 uint32
if returnSingleEntry {
_p0 = 1
}
var _p1 uint32
if restartScan {
_p1 = 1
}
r0, _, _ := syscall.SyscallN(procNtQueryEaFile.Addr(), uintptr(handle), uintptr(unsafe.Pointer(iosb)), uintptr(unsafe.Pointer(buf)), uintptr(bufLen), uintptr(_p0), uintptr(eaList), uintptr(eaListLen), uintptr(unsafe.Pointer(eaIndex)), uintptr(_p1))
status = ntStatus(r0)
return
}
func setFileEA(handle windows.Handle, iosb *ioStatusBlock, buf *uint8, bufLen uint32) (status ntStatus) {
r0, _, _ := syscall.SyscallN(procNtSetEaFile.Addr(), uintptr(handle), uintptr(unsafe.Pointer(iosb)), uintptr(unsafe.Pointer(buf)), uintptr(bufLen))
status = ntStatus(r0)
return
}

View file

@ -0,0 +1,259 @@
//go:build windows
// +build windows
package fs
import (
"crypto/rand"
"fmt"
"math/big"
"os"
"path/filepath"
"reflect"
"syscall"
"testing"
"unsafe"
"golang.org/x/sys/windows"
)
// The code below was adapted from github.com/Microsoft/go-winio under MIT license.
// The MIT License (MIT)
// Copyright (c) 2015 Microsoft
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
// The code below was adapted from https://github.com/ambarve/go-winio/blob/a7564fd482feb903f9562a135f1317fd3b480739/ea_test.go
// under MIT license.
var (
testEas = []ExtendedAttribute{
{Name: "foo", Value: []byte("bar")},
{Name: "fizz", Value: []byte("buzz")},
}
testEasEncoded = []byte{16, 0, 0, 0, 0, 3, 3, 0, 102, 111, 111, 0, 98, 97, 114, 0, 0,
0, 0, 0, 0, 4, 4, 0, 102, 105, 122, 122, 0, 98, 117, 122, 122, 0, 0, 0}
testEasNotPadded = testEasEncoded[0 : len(testEasEncoded)-3]
testEasTruncated = testEasEncoded[0:20]
)
func TestRoundTripEas(t *testing.T) {
b, err := EncodeExtendedAttributes(testEas)
if err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(testEasEncoded, b) {
t.Fatalf("Encoded mismatch %v %v", testEasEncoded, b)
}
eas, err := DecodeExtendedAttributes(b)
if err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(testEas, eas) {
t.Fatalf("mismatch %+v %+v", testEas, eas)
}
}
func TestEasDontNeedPaddingAtEnd(t *testing.T) {
eas, err := DecodeExtendedAttributes(testEasNotPadded)
if err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(testEas, eas) {
t.Fatalf("mismatch %+v %+v", testEas, eas)
}
}
func TestTruncatedEasFailCorrectly(t *testing.T) {
_, err := DecodeExtendedAttributes(testEasTruncated)
if err == nil {
t.Fatal("expected error")
}
}
func TestNilEasEncodeAndDecodeAsNil(t *testing.T) {
b, err := EncodeExtendedAttributes(nil)
if err != nil {
t.Fatal(err)
}
if len(b) != 0 {
t.Fatal("expected empty")
}
eas, err := DecodeExtendedAttributes(nil)
if err != nil {
t.Fatal(err)
}
if len(eas) != 0 {
t.Fatal("expected empty")
}
}
// TestSetFileEa makes sure that the test buffer is actually parsable by NtSetEaFile.
func TestSetFileEa(t *testing.T) {
f, err := os.CreateTemp("", "testea")
if err != nil {
t.Fatal(err)
}
defer func() {
err := os.Remove(f.Name())
if err != nil {
t.Logf("Error removing file %s: %v\n", f.Name(), err)
}
err = f.Close()
if err != nil {
t.Logf("Error closing file %s: %v\n", f.Name(), err)
}
}()
ntdll := syscall.MustLoadDLL("ntdll.dll")
ntSetEaFile := ntdll.MustFindProc("NtSetEaFile")
var iosb [2]uintptr
r, _, _ := ntSetEaFile.Call(f.Fd(),
uintptr(unsafe.Pointer(&iosb[0])),
uintptr(unsafe.Pointer(&testEasEncoded[0])),
uintptr(len(testEasEncoded)))
if r != 0 {
t.Fatalf("NtSetEaFile failed with %08x", r)
}
}
func TestSetGetFileEA(t *testing.T) {
tempDir := t.TempDir()
testfilePath := filepath.Join(tempDir, "testfile.txt")
// create temp file
testfile, err := os.Create(testfilePath)
if err != nil {
t.Fatalf("failed to create temporary file: %s", err)
}
defer func() {
err := testfile.Close()
if err != nil {
t.Logf("Error closing file %s: %v\n", testfile.Name(), err)
}
}()
nAttrs := 3
testEAs := make([]ExtendedAttribute, 3)
// generate random extended attributes for test
for i := 0; i < nAttrs; i++ {
// EA name is automatically converted to upper case before storing, so
// when reading it back it returns the upper case name. To avoid test
// failures because of that keep the name upper cased.
testEAs[i].Name = fmt.Sprintf("TESTEA%d", i+1)
testEAs[i].Value = make([]byte, getRandomInt())
_, err := rand.Read(testEAs[i].Value)
if err != nil {
t.Logf("Error reading rand for file %s: %v\n", testfilePath, err)
}
}
utf16Path := windows.StringToUTF16Ptr(testfilePath)
fileAccessRightReadWriteEA := (0x8 | 0x10)
fileHandle, err := windows.CreateFile(utf16Path, uint32(fileAccessRightReadWriteEA), 0, nil, windows.OPEN_EXISTING, windows.FILE_ATTRIBUTE_NORMAL, 0)
if err != nil {
t.Fatalf("open file failed with: %s", err)
}
defer func() {
err := windows.Close(fileHandle)
if err != nil {
t.Logf("Error closing file handle %s: %v\n", testfilePath, err)
}
}()
if err := SetFileEA(fileHandle, testEAs); err != nil {
t.Fatalf("set EA for file failed: %s", err)
}
var readEAs []ExtendedAttribute
if readEAs, err = GetFileEA(fileHandle); err != nil {
t.Fatalf("get EA for file failed: %s", err)
}
if !reflect.DeepEqual(readEAs, testEAs) {
t.Logf("expected: %+v, found: %+v\n", testEAs, readEAs)
t.Fatalf("EAs read from testfile don't match")
}
}
func TestSetGetFolderEA(t *testing.T) {
tempDir := t.TempDir()
testfolderPath := filepath.Join(tempDir, "testfolder")
// create temp folder
err := os.Mkdir(testfolderPath, os.ModeDir)
if err != nil {
t.Fatalf("failed to create temporary file: %s", err)
}
nAttrs := 3
testEAs := make([]ExtendedAttribute, 3)
// generate random extended attributes for test
for i := 0; i < nAttrs; i++ {
// EA name is automatically converted to upper case before storing, so
// when reading it back it returns the upper case name. To avoid test
// failures because of that keep the name upper cased.
testEAs[i].Name = fmt.Sprintf("TESTEA%d", i+1)
testEAs[i].Value = make([]byte, getRandomInt())
_, err := rand.Read(testEAs[i].Value)
if err != nil {
t.Logf("Error reading rand for file %s: %v\n", testfolderPath, err)
}
}
utf16Path := windows.StringToUTF16Ptr(testfolderPath)
fileAccessRightReadWriteEA := (0x8 | 0x10)
fileHandle, err := windows.CreateFile(utf16Path, uint32(fileAccessRightReadWriteEA), 0, nil, windows.OPEN_EXISTING, windows.FILE_ATTRIBUTE_NORMAL|windows.FILE_FLAG_BACKUP_SEMANTICS, 0)
if err != nil {
t.Fatalf("open folder failed with: %s", err)
}
defer func() {
err := windows.Close(fileHandle)
if err != nil {
t.Logf("Error closing file handle %s: %v\n", testfolderPath, err)
}
}()
if err := SetFileEA(fileHandle, testEAs); err != nil {
t.Fatalf("set EA for folder failed: %s", err)
}
var readEAs []ExtendedAttribute
if readEAs, err = GetFileEA(fileHandle); err != nil {
t.Fatalf("get EA for folder failed: %s", err)
}
if !reflect.DeepEqual(readEAs, testEAs) {
t.Logf("expected: %+v, found: %+v\n", testEAs, readEAs)
t.Fatalf("EAs read from test folder don't match")
}
}
func getRandomInt() int64 {
nBig, err := rand.Int(rand.Reader, big.NewInt(27))
if err != nil {
panic(err)
}
n := nBig.Int64()
if n == 0 {
n = getRandomInt()
}
return n
}