winio

package module
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 9, 2024 License: MIT Imports: 3 Imported by: 606

README

go-winio Build Status

This repository contains utilities for efficiently performing Win32 IO operations in Go. Currently, this is focused on accessing named pipes and other file handles, and for using named pipes as a net transport.

This code relies on IO completion ports to avoid blocking IO on system threads, allowing Go to reuse the thread to schedule another goroutine. This limits support to Windows Vista and newer operating systems. This is similar to the implementation of network sockets in Go's net package.

Please see the LICENSE file for licensing information.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Microsoft CLA.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Additionally, the pull request pipeline requires the following steps to be performed before mergining.

Code Sign-Off

We require that contributors sign their commits using git commit --signoff to certify they either authored the work themselves or otherwise have permission to use it in this project.

A range of commits can be signed off using git rebase --signoff.

Please see the developer certificate for more info, as well as to make sure that you can attest to the rules listed. Our CI uses the DCO Github app to ensure that all commits in a given PR are signed-off.

Linting

Code must pass a linting stage, which uses golangci-lint. The linting settings are stored in .golangci.yaml, and can be run automatically with VSCode by adding the following to your workspace or folder settings:

    "go.lintTool": "golangci-lint",
    "go.lintOnSave": "package",

Additional editor integrations options are also available.

Alternatively, golangci-lint can be installed locally and run from the repo root:

# use . or specify a path to only lint a package
# to show all lint errors, use flags "--max-issues-per-linter=0 --max-same-issues=0"
> golangci-lint run ./...
Go Generate

The pipeline checks that auto-generated code, via go generate, are up to date.

This can be done for the entire repo:

> go generate ./...

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Special Thanks

Thanks to natefinch for the inspiration for this library. See npipe for another named pipe implementation.

Documentation

Overview

This package provides utilities for efficiently performing Win32 IO operations in Go. Currently, this package is provides support for genreal IO and management of

This code is similar to Go's net package, and uses IO completion ports to avoid blocking IO on system threads, allowing Go to reuse the thread to schedule other goroutines.

This limits support to Windows Vista and newer operating systems.

Additionally, this package provides support for:

  • creating and managing GUIDs
  • writing to ETW
  • opening and manageing VHDs
  • parsing Windows Image files
  • auto-generating Win32 API code

Index

Constants

View Source 
const (
	BackupData = uint32(iota + 1)
	BackupEaData
	BackupSecurity
	BackupAlternateData
	BackupLink
	BackupPropertyData
	BackupObjectId //revive:disable-line:var-naming ID, not Id
	BackupReparseData
	BackupSparseBlock
	BackupTxfsData
)
View Source 
const (
	WRITE_DAC              = windows.WRITE_DAC
	WRITE_OWNER            = windows.WRITE_OWNER
	ACCESS_SYSTEM_SECURITY = windows.ACCESS_SYSTEM_SECURITY
)
View Source 
const (
	PipeImpLevelAnonymous      = PipeImpLevel(fs.SECURITY_ANONYMOUS)
	PipeImpLevelIdentification = PipeImpLevel(fs.SECURITY_IDENTIFICATION)
	PipeImpLevelImpersonation  = PipeImpLevel(fs.SECURITY_IMPERSONATION)
	PipeImpLevelDelegation     = PipeImpLevel(fs.SECURITY_DELEGATION)
)
View Source 
const (
	//revive:disable-next-line:var-naming ALL_CAPS
	SE_PRIVILEGE_ENABLED = windows.SE_PRIVILEGE_ENABLED

	//revive:disable-next-line:var-naming ALL_CAPS
	ERROR_NOT_ALL_ASSIGNED windows.Errno = windows.ERROR_NOT_ALL_ASSIGNED

	SeBackupPrivilege   = "SeBackupPrivilege"
	SeRestorePrivilege  = "SeRestorePrivilege"
	SeSecurityPrivilege = "SeSecurityPrivilege"
)
View Source 
const (
	StreamSparseAttributes = uint32(8)
)

Variables

View Source 
var (
	ErrFileClosed = errors.New("file has already been closed")
	ErrTimeout    = &timeoutError{}
)
View Source 
var (
	// ErrPipeListenerClosed is returned for pipe operations on listeners that have been closed.
	ErrPipeListenerClosed = net.ErrClosed
)

Functions

func DialPipe 

func DialPipe(path string, timeout *time.Duration) (net.Conn, error)

DialPipe connects to a named pipe by path, timing out if the connection takes longer than the specified duration. If timeout is nil, then we use a default timeout of 2 seconds. (We do not use WaitNamedPipe.)

func DialPipeAccess added in v0.4.15 

func DialPipeAccess(ctx context.Context, path string, access uint32) (net.Conn, error)

DialPipeAccess attempts to connect to a named pipe by `path` with `access` until `ctx` cancellation or timeout.

func DialPipeAccessImpLevel added in v0.6.2 

func DialPipeAccessImpLevel(ctx context.Context, path string, access uint32, impLevel PipeImpLevel) (net.Conn, error)

DialPipeAccessImpLevel attempts to connect to a named pipe by `path` with `access` at `impLevel` until `ctx` cancellation or timeout. The other DialPipe* implementations use PipeImpLevelAnonymous.

func DialPipeContext added in v0.4.13 

func DialPipeContext(ctx context.Context, path string) (net.Conn, error)

DialPipeContext attempts to connect to a named pipe by `path` until `ctx` cancellation or timeout.

func DisableProcessPrivileges added in v0.3.6 

func DisableProcessPrivileges(names []string) error

DisableProcessPrivileges disables privileges globally for the process.

func EnableProcessPrivileges added in v0.3.4 

func EnableProcessPrivileges(names []string) error

EnableProcessPrivileges enables privileges globally for the process.

func EncodeExtendedAttributes added in v0.4.5 

func EncodeExtendedAttributes(eas []ExtendedAttribute) ([]byte, error)

EncodeExtendedAttributes encodes a list of EAs into a FILE_FULL_EA_INFORMATION buffer for use with BackupWrite, ZwSetEaFile, etc.

func EncodeReparsePoint 

func EncodeReparsePoint(rp *ReparsePoint) []byte

EncodeReparsePoint encodes a Win32 REPARSE_DATA_BUFFER structure describing a symlink or mount point.

func HvsockGUIDBroadcast added in v0.6.0 

func HvsockGUIDBroadcast() guid.GUID

HvsockGUIDBroadcast is the wildcard VmId for broadcasting sends to all partitions.

func HvsockGUIDChildren added in v0.6.0 

func HvsockGUIDChildren() guid.GUID

HvsockGUIDChildren is the wildcard VmId for accepting connections from the connector's child partitions.

func HvsockGUIDLoopback added in v0.6.0 

func HvsockGUIDLoopback() guid.GUID

HvsockGUIDLoopback is the Loopback VmId for accepting connections to the same partition as the connector.

func HvsockGUIDParent added in v0.6.0 

func HvsockGUIDParent() guid.GUID

HvsockGUIDParent is the wildcard VmId for accepting connections from the connector's parent partition. Listening on this VmId accepts connection from:

  • Inside silos: silo host partition.
  • Inside hosted silo: host of the VM.
  • Inside VM: VM host.
  • Physical host: Not supported.

func HvsockGUIDSiloHost added in v0.6.0 

func HvsockGUIDSiloHost() guid.GUID

HvsockGUIDSiloHost is the address of a silo's host partition:

  • The silo host of a hosted silo is the utility VM.
  • The silo host of a silo on a physical host is the physical host.

func HvsockGUIDWildcard added in v0.6.0 

func HvsockGUIDWildcard() guid.GUID

HvsockGUIDWildcard is the wildcard VmId for accepting connections from all partitions.

func ListenPipe 

func ListenPipe(path string, c *PipeConfig) (net.Listener, error)

ListenPipe creates a listener on a Windows named pipe path, e.g. \\.\pipe\mypipe. The pipe must not already exist.

func LookupNameBySid added in v0.6.0 

func LookupNameBySid(sid string) (name string, err error)

LookupNameBySid looks up the name of an account by SID

func LookupSidByName 

func LookupSidByName(name string) (sid string, err error)

LookupSidByName looks up the SID of an account by name

func MakeOpenFile deprecated 

func MakeOpenFile(h syscall.Handle) (io.ReadWriteCloser, error)

Deprecated: use NewOpenFile instead.

func NewOpenFile added in v0.6.2 

func NewOpenFile(h windows.Handle) (io.ReadWriteCloser, error)

func OpenForBackup added in v0.2.0 

func OpenForBackup(path string, access uint32, share uint32, createmode uint32) (*os.File, error)

OpenForBackup opens a file or directory, potentially skipping access checks if the backup or restore privileges have been acquired.

If the file opened was a directory, it cannot be used with Readdir().

func RunWithPrivilege 

func RunWithPrivilege(name string, fn func() error) error

RunWithPrivilege enables a single privilege for a function call.

func RunWithPrivileges 

func RunWithPrivileges(names []string, fn func() error) error

RunWithPrivileges enables privileges for a function call.

func SddlToSecurityDescriptor 

func SddlToSecurityDescriptor(sddl string) ([]byte, error)

func SecurityDescriptorToSddl 

func SecurityDescriptorToSddl(sd []byte) (string, error)

func SetFileBasicInfo 

func SetFileBasicInfo(f *os.File, bi *FileBasicInfo) error

SetFileBasicInfo sets times and attributes for a file.

func VsockServiceID added in v0.4.13 

func VsockServiceID(port uint32) guid.GUID

VsockServiceID returns an hvsock service ID corresponding to the specified AF_VSOCK port.

Types

type AccountLookupError 

type AccountLookupError struct {
	Name string
	Err  error
}

func (*AccountLookupError) Error 

func (e *AccountLookupError) Error() string

func (*AccountLookupError) Unwrap added in v0.6.0 

func (e *AccountLookupError) Unwrap() error

type BackupFileReader 

type BackupFileReader struct {
	// contains filtered or unexported fields
}

BackupFileReader provides an io.ReadCloser interface on top of the BackupRead Win32 API.

func NewBackupFileReader 

func NewBackupFileReader(f *os.File, includeSecurity bool) *BackupFileReader

NewBackupFileReader returns a new BackupFileReader from a file handle. If includeSecurity is true, Read will attempt to read the security descriptor of the file.

func (*BackupFileReader) Close 

func (r *BackupFileReader) Close() error

Close frees Win32 resources associated with the BackupFileReader. It does not close the underlying file.

func (*BackupFileReader) Read 

func (r *BackupFileReader) Read(b []byte) (int, error)

Read reads a backup stream from the file by calling the Win32 API BackupRead().

type BackupFileWriter 

type BackupFileWriter struct {
	// contains filtered or unexported fields
}

BackupFileWriter provides an io.WriteCloser interface on top of the BackupWrite Win32 API.

func NewBackupFileWriter 

func NewBackupFileWriter(f *os.File, includeSecurity bool) *BackupFileWriter

NewBackupFileWriter returns a new BackupFileWriter from a file handle. If includeSecurity is true, Write() will attempt to restore the security descriptor from the stream.

func (*BackupFileWriter) Close 

func (w *BackupFileWriter) Close() error

Close frees Win32 resources associated with the BackupFileWriter. It does not close the underlying file.

func (*BackupFileWriter) Write 

func (w *BackupFileWriter) Write(b []byte) (int, error)

Write restores a portion of the file using the provided backup stream.

type BackupHeader 

type BackupHeader struct {
	//revive:disable-next-line:var-naming ID, not Id
	Id         uint32 // The backup stream ID
	Attributes uint32 // Stream attributes
	Size       int64  // The size of the stream in bytes
	Name       string // The name of the stream (for BackupAlternateData only).
	Offset     int64  // The offset of the stream in the file (for BackupSparseBlock only).
}

BackupHeader represents a backup stream of a file.

type BackupStreamReader 

type BackupStreamReader struct {
	// contains filtered or unexported fields
}

BackupStreamReader reads from a stream produced by the BackupRead Win32 API and produces a series of BackupHeader values.

func NewBackupStreamReader 

func NewBackupStreamReader(r io.Reader) *BackupStreamReader

NewBackupStreamReader produces a BackupStreamReader from any io.Reader.

func (*BackupStreamReader) Next 

func (r *BackupStreamReader) Next() (*BackupHeader, error)

Next returns the next backup stream and prepares for calls to Read(). It skips the remainder of the current stream if it was not completely read.

func (*BackupStreamReader) Read 

func (r *BackupStreamReader) Read(b []byte) (int, error)

Read reads from the current backup stream.

type BackupStreamWriter 

type BackupStreamWriter struct {
	// contains filtered or unexported fields
}

BackupStreamWriter writes a stream compatible with the BackupWrite Win32 API.

func NewBackupStreamWriter 

func NewBackupStreamWriter(w io.Writer) *BackupStreamWriter

NewBackupStreamWriter produces a BackupStreamWriter on top of an io.Writer.

func (*BackupStreamWriter) Write 

func (w *BackupStreamWriter) Write(b []byte) (int, error)

Write writes to the current backup stream.

func (*BackupStreamWriter) WriteHeader 

func (w *BackupStreamWriter) WriteHeader(hdr *BackupHeader) error

WriteHeader writes the next backup stream header and prepares for calls to Write().

type ExtendedAttribute added in v0.4.5 

type ExtendedAttribute struct {
	Name  string
	Value []byte
	Flags uint8
}

ExtendedAttribute represents a single Windows EA.

func DecodeExtendedAttributes added in v0.4.5 

func DecodeExtendedAttributes(b []byte) (eas []ExtendedAttribute, err error)

DecodeExtendedAttributes decodes a list of EAs from a FILE_FULL_EA_INFORMATION buffer retrieved from BackupRead, ZwQueryEaFile, etc.

type FileBasicInfo 

type FileBasicInfo struct {
	CreationTime, LastAccessTime, LastWriteTime, ChangeTime windows.Filetime
	FileAttributes                                          uint32
	// contains filtered or unexported fields
}

FileBasicInfo contains file access time and file attributes information.

func GetFileBasicInfo 

func GetFileBasicInfo(f *os.File) (*FileBasicInfo, error)

GetFileBasicInfo retrieves times and attributes for a file.

type FileIDInfo added in v0.2.0 

type FileIDInfo struct {
	VolumeSerialNumber uint64
	FileID             [16]byte
}

FileIDInfo contains the volume serial number and file ID for a file. This pair should be unique on a system.

func GetFileID added in v0.2.0 

func GetFileID(f *os.File) (*FileIDInfo, error)

GetFileID retrieves the unique (volume, file ID) pair for a file.

type FileStandardInfo added in v0.4.17 

type FileStandardInfo struct {
	AllocationSize, EndOfFile int64
	NumberOfLinks             uint32
	DeletePending, Directory  bool
}

FileStandardInfo contains extended information for the file. FILE_STANDARD_INFO in WinBase.h https://docs.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_standard_info

func GetFileStandardInfo added in v0.4.17 

func GetFileStandardInfo(f *os.File) (*FileStandardInfo, error)

GetFileStandardInfo retrieves ended information for the file.

type HvsockAddr added in v0.4.13 

type HvsockAddr struct {
	VMID      guid.GUID
	ServiceID guid.GUID
}

An HvsockAddr is an address for a AF_HYPERV socket.

func (*HvsockAddr) Network added in v0.4.13 

func (*HvsockAddr) Network() string

Network returns the address's network name, "hvsock".

func (*HvsockAddr) String added in v0.4.13 

func (addr *HvsockAddr) String() string

type HvsockConn added in v0.4.13 

type HvsockConn struct {
	// contains filtered or unexported fields
}

HvsockConn is a connected socket of the AF_HYPERV address family.

func Dial added in v0.6.0 

func Dial(ctx context.Context, addr *HvsockAddr) (conn *HvsockConn, err error)

Dial the Hyper-V socket at addr.

See HvsockDialer.Dial for more information.

func (*HvsockConn) Close added in v0.4.13 

func (conn *HvsockConn) Close() error

Close closes the socket connection, failing any pending read or write calls.

func (*HvsockConn) CloseRead added in v0.4.13 

func (conn *HvsockConn) CloseRead() error

CloseRead shuts down the read end of the socket, preventing future read operations.

func (*HvsockConn) CloseWrite added in v0.4.13 

func (conn *HvsockConn) CloseWrite() error

CloseWrite shuts down the write end of the socket, preventing future write operations and notifying the other endpoint that no more data will be written.

func (*HvsockConn) IsClosed added in v0.5.2 

func (conn *HvsockConn) IsClosed() bool

func (*HvsockConn) LocalAddr added in v0.4.13 

func (conn *HvsockConn) LocalAddr() net.Addr

LocalAddr returns the local address of the connection.

func (*HvsockConn) Read added in v0.4.13 

func (conn *HvsockConn) Read(b []byte) (int, error)

func (*HvsockConn) RemoteAddr added in v0.4.13 

func (conn *HvsockConn) RemoteAddr() net.Addr

RemoteAddr returns the remote address of the connection.

func (*HvsockConn) SetDeadline added in v0.4.13 

func (conn *HvsockConn) SetDeadline(t time.Time) error

SetDeadline implements the net.Conn SetDeadline method.

func (*HvsockConn) SetReadDeadline added in v0.4.13 

func (conn *HvsockConn) SetReadDeadline(t time.Time) error

SetReadDeadline implements the net.Conn SetReadDeadline method.

func (*HvsockConn) SetWriteDeadline added in v0.4.13 

func (conn *HvsockConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements the net.Conn SetWriteDeadline method.

func (*HvsockConn) Write added in v0.4.13 

func (conn *HvsockConn) Write(b []byte) (int, error)

type HvsockDialer added in v0.6.0 

type HvsockDialer struct {
	// Deadline is the time the Dial operation must connect before erroring.
	Deadline time.Time

	// Retries is the number of additional connects to try if the connection times out, is refused,
	// or the host is unreachable
	Retries uint

	// RetryWait is the time to wait after a connection error to retry
	RetryWait time.Duration
	// contains filtered or unexported fields
}

HvsockDialer configures and dials a Hyper-V Socket (ie, HvsockConn).

func (*HvsockDialer) Dial added in v0.6.0 

func (d *HvsockDialer) Dial(ctx context.Context, addr *HvsockAddr) (conn *HvsockConn, err error)

Dial attempts to connect to the Hyper-V socket at addr, and returns a connection if successful. Will attempt (HvsockDialer).Retries if dialing fails, waiting (HvsockDialer).RetryWait between retries.

Dialing can be cancelled either by providing (HvsockDialer).Deadline, or cancelling ctx.

type HvsockListener added in v0.4.13 

type HvsockListener struct {
	// contains filtered or unexported fields
}

HvsockListener is a socket listener for the AF_HYPERV address family.

func ListenHvsock added in v0.4.13 

func ListenHvsock(addr *HvsockAddr) (_ *HvsockListener, err error)

ListenHvsock listens for connections on the specified hvsock address.

func (*HvsockListener) Accept added in v0.4.13 

func (l *HvsockListener) Accept() (_ net.Conn, err error)

Accept waits for the next connection and returns it.

func (*HvsockListener) Addr added in v0.4.13 

func (l *HvsockListener) Addr() net.Addr

Addr returns the listener's network address.

func (*HvsockListener) Close added in v0.4.13 

func (l *HvsockListener) Close() error

Close closes the listener, causing any pending Accept calls to fail.

type PipeConfig 

type PipeConfig struct {
	// SecurityDescriptor contains a Windows security descriptor in SDDL format.
	SecurityDescriptor string

	// MessageMode determines whether the pipe is in byte or message mode. In either
	// case the pipe is read in byte mode by default. The only practical difference in
	// this implementation is that CloseWrite() is only supported for message mode pipes;
	// CloseWrite() is implemented as a zero-byte write, but zero-byte writes are only
	// transferred to the reader (and returned as io.EOF in this implementation)
	// when the pipe is in message mode.
	MessageMode bool

	// InputBufferSize specifies the size of the input buffer, in bytes.
	InputBufferSize int32

	// OutputBufferSize specifies the size of the output buffer, in bytes.
	OutputBufferSize int32
}

PipeConfig contain configuration for the pipe listener.

type PipeConn added in v0.6.2 

type PipeConn interface {
	net.Conn
	Disconnect() error
	Flush() error
}

type PipeImpLevel added in v0.6.2 

type PipeImpLevel uint32

PipeImpLevel is an enumeration of impersonation levels that may be set when calling DialPipeAccessImpersonation.

type PrivilegeError 

type PrivilegeError struct {
	// contains filtered or unexported fields
}

PrivilegeError represents an error enabling privileges.

func (*PrivilegeError) Error 

func (e *PrivilegeError) Error() string

type ReparsePoint 

type ReparsePoint struct {
	Target       string
	IsMountPoint bool
}

ReparsePoint describes a Win32 symlink or mount point.

func DecodeReparsePoint 

func DecodeReparsePoint(b []byte) (*ReparsePoint, error)

DecodeReparsePoint decodes a Win32 REPARSE_DATA_BUFFER structure containing either a symlink or a mount point.

func DecodeReparsePointData added in v0.3.0 

func DecodeReparsePointData(tag uint32, b []byte) (*ReparsePoint, error)

type SddlConversionError 

type SddlConversionError struct {
	Sddl string
	Err  error
}

func (*SddlConversionError) Error 

func (e *SddlConversionError) Error() string

func (*SddlConversionError) Unwrap added in v0.6.0 

func (e *SddlConversionError) Unwrap() error

type UnsupportedReparsePointError 

type UnsupportedReparsePointError struct {
	Tag uint32
}

UnsupportedReparsePointError is returned when trying to decode a non-symlink or mount point reparse point.

func (*UnsupportedReparsePointError) Error 

func (e *UnsupportedReparsePointError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
internal
computestorage
fs
This package contains Win32 filesystem functionality.
 This package contains Win32 filesystem functionality.
interop
socket
stringbuffer
pkg
bindfilter
etw
Package etw provides support for TraceLogging-based ETW (Event Tracing for Windows).
 Package etw provides support for TraceLogging-based ETW (Event Tracing for Windows).
etw/sample
etwlogrus
fs
This package contains Win32 filesystem functionality.
 This package contains Win32 filesystem functionality.
guid
Package guid provides a GUID type.
 Package guid provides a GUID type.
process
security
tools
etw-provider-gen
mkwinsyscall
mkwinsyscall generates windows system call bodies
 mkwinsyscall generates windows system call bodies
wim
Package wim implements a WIM file parser.
 Package wim implements a WIM file parser.
lzx
Package lzx implements a decompressor for the the WIM variant of the LZX compression algorithm.
 Package lzx implements a decompressor for the the WIM variant of the LZX compression algorithm.
validate

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.