The Manticore Project
GitHub Discord Get Started
Generated from Manticore v1.1.5 • 201 packages. View on pkg.go.dev

client

import "github.com/TheManticoreProject/Manticore/network/smb/smb_v20/client"

Index

func IsChangeNotifyCancelled

func IsChangeNotifyCancelled(err error) bool

IsChangeNotifyCancelled reports whether err is the error ChangeNotify returns when it was interrupted by Cancel.

type Client

Client represents an SMB 2.0 client. It mirrors the SMB 1.0 client (network/smb/smb_v10/client) but drives the SMB2 wire layer.

type Client struct {
    // Transport is the byte-stream transport (TCP / NBT) to the server.
    Transport transport.Transport

    // Connection holds per-connection negotiated state.
    Connection *Connection

    // Session is the authenticated session, once established.
    Session *Session

    // ClientGuid is a per-client GUID sent in SMB2 NEGOTIATE.
    ClientGuid [16]byte

    // Workstation is the client workstation name used during NTLM authentication.
    Workstation string
    // contains filtered or unexported fields
}

func NewClientUsingNBTTransport

func NewClientUsingNBTTransport(host net.IP, port int) *Client

NewClientUsingNBTTransport creates a new SMB 2.0 client using NetBIOS transport.

func NewClientUsingTCPTransport

func NewClientUsingTCPTransport(host net.IP, port int) *Client

NewClientUsingTCPTransport creates a new SMB 2.0 client using direct TCP transport.

func NewFromTransport

func NewFromTransport(t transport.Transport, host net.IP, port int) *Client

NewFromTransport builds an SMB 2.0 client over an already-connected transport, without connecting or negotiating. It is the handoff entry point used by the generic SMB client (network/smb/client), which performs a multi-protocol negotiate and then hands the live transport to this engine. The caller drives negotiation either via Negotiate (a native SMB2 NEGOTIATE over t) or by applying an already-exchanged response with ApplyNegotiateResponse.

func (*Client) AcknowledgeOplockBreak

func (c *Client) AcknowledgeOplockBreak(fileId types.SMB2_FILEID, oplockLevel uint8) error

AcknowledgeOplockBreak replies to an OPLOCK_BREAK notification, accepting the reduced oplock level on the given open, and waits for the server’s response. Wire: SMB2 OPLOCK_BREAK Acknowledgment.

func (*Client) ApplyNegotiateResponse

func (c *Client) ApplyNegotiateResponse(negotiateResponse *commands.NegotiateResponse)

ApplyNegotiateResponse records the negotiated connection state — selected dialect, server security mode, capabilities, maximum transfer sizes, GUID, timestamps, and GSS security buffer — from an SMB2 NEGOTIATE response.

It is shared by Negotiate, which exchanges the response on the transport, and by the generic SMB client (network/smb/client), which may hand over a response already exchanged as part of a multi-protocol negotiate. Because NEGOTIATE occupies MessageId 0, the next request on the connection uses MessageId 1; this is set here for the handoff path (in the Negotiate path the MessageId has already advanced past 0).

func (*Client) Cancel

func (c *Client) Cancel() error

Cancel requests cancellation of the operation currently awaiting an async (STATUS_PENDING) completion on this connection — for example a blocked ChangeNotify. It sends an SMB2 CANCEL carrying that request’s MessageId and AsyncId. CANCEL itself has no response; the cancelled operation instead completes with STATUS_CANCELLED, which its blocked caller observes.

Cancel is intended to be called from a different goroutine than the one blocked in the operation. It returns an error if no operation is currently pending. Wire: SMB2 CANCEL.

func (*Client) ChangeNotify

func (c *Client) ChangeNotify(fileId types.SMB2_FILEID, completionFilter uint32, watchTree bool) ([]filesystem.FileNotifyInformation, error)

ChangeNotify monitors the directory open identified by fileId and blocks until a change matching completionFilter (a combination of filesystem.FILE_NOTIFY_CHANGE_* bits) occurs, then returns the changes. When watchTree is set the whole subtree is monitored.

The call blocks: the server registers the watch (replying STATUS_PENDING) and sends the result only when a change happens. A concurrent Cancel interrupts the wait, in which case ChangeNotify returns an error for which IsChangeNotifyCancelled reports true. A STATUS_NOTIFY_ENUM_DIR result (too many changes to report) returns no entries and no error; the caller should re-enumerate. Wire: SMB2 CHANGE_NOTIFY.

func (*Client) CloseFile

func (c *Client) CloseFile(fileId types.SMB2_FILEID) error

CloseFile closes an open identified by FileId. Wire: SMB2 CLOSE.

func (*Client) Connect

func (c *Client) Connect(ipaddr net.IP, port int) error

Connect establishes the transport connection and performs SMB2 negotiation.

func (*Client) CreateDirectory

func (c *Client) CreateDirectory(path string) error

CreateDirectory creates a directory on the current tree.

func (*Client) CreateFile

func (c *Client) CreateFile(path string, desiredAccess, shareAccess, createDisposition, createOptions uint32) (types.SMB2_FILEID, error)

CreateFile opens or creates a file (or pipe) on the currently connected tree and returns the server-assigned FileId. It requests no oplock.

The path is relative to the share root; a leading backslash is stripped (an SMB2 CREATE name is share-relative). Wire: SMB2 CREATE.

func (*Client) CreateFileWithOplock

func (c *Client) CreateFileWithOplock(path string, desiredAccess, shareAccess, createDisposition, createOptions uint32, requestedOplock uint8) (types.SMB2_FILEID, uint8, error)

CreateFileWithOplock opens or creates a file like CreateFile but also requests an oplock (one of commands.SMB2_OPLOCK_LEVEL_*) and returns the oplock level the server granted. When the server later needs to break that oplock — because another client opens the same file — it sends an OPLOCK_BREAK notification; the caller observes it with WaitOplockBreak and replies with AcknowledgeOplockBreak.

func (*Client) CreateQueryInfoClose

func (c *Client) CreateQueryInfoClose(path string, desiredAccess, shareAccess, createDisposition, createOptions uint32, infoType, fileInfoClass uint8, additionalInformation uint32) ([]byte, error)

CreateQueryInfoClose opens path, queries the given information class on the resulting handle, and closes it — all in a single compounded request (SMB2_FLAGS_RELATED_OPERATIONS), so the three operations cost one network round trip instead of three. It returns the QUERY_INFO output buffer.

infoType is one of commands.SMB2_0_INFO_* and fileInfoClass the class within it; additionalInformation carries the security-info bits for a security query and is 0 otherwise. Wire: SMB2 CREATE + QUERY_INFO + CLOSE compounded with related operations, where the QUERY_INFO and CLOSE inherit the CREATE’s handle via the reserved related FileId.

func (*Client) DeleteDirectory

func (c *Client) DeleteDirectory(path string) error

DeleteDirectory removes an (empty) directory on the current tree.

func (*Client) DeleteFile

func (c *Client) DeleteFile(path string) error

DeleteFile removes a file on the current tree. It opens the file with DELETE access and FILE_DELETE_ON_CLOSE, so the file is removed when the handle closes.

func (*Client) Disconnect

func (c *Client) Disconnect() error

Disconnect closes the underlying transport connection. It does not send any SMB2 commands; call TreeDisconnect and Logoff first for a clean teardown.

func (*Client) Echo

func (c *Client) Echo() error

Echo sends an SMB2 ECHO and waits for the reply. ECHO carries no data; it is a keepalive that confirms the connection (and, if established, the session) is still alive. Wire: SMB2 ECHO.

func (*Client) Flush

func (c *Client) Flush(fileId types.SMB2_FILEID) error

Flush issues an SMB2 FLUSH, asking the server to commit any buffered data for the open file to stable storage before returning. Wire: SMB2 FLUSH.

func (*Client) GetHost

func (c *Client) GetHost() net.IP

GetHost returns the target server IP address.

func (*Client) GetPort

func (c *Client) GetPort() int

GetPort returns the target server port.

func (*Client) GetVolumeSizeInfo

func (c *Client) GetVolumeSizeInfo() (*filesystem.FileFsSizeInformation, error)

GetVolumeSizeInfo returns the size information of the volume backing the current tree. It opens the share root and issues a filesystem QUERY_INFO.

func (*Client) Ioctl

func (c *Client) Ioctl(fileId types.SMB2_FILEID, ctlCode uint32, input []byte, isFsctl bool, maxOutputResponse uint32) ([]byte, error)

Ioctl issues an SMB2 IOCTL on the open identified by fileId and returns the output buffer. ctlCode is the control code; when isFsctl is true the SMB2_0_IOCTL_IS_FSCTL flag is set (the usual case for FSCTL_* codes). maxOutputResponse bounds the bytes the server may return.

STATUS_BUFFER_OVERFLOW is treated as success: it is a warning that the output did not fit, and the partial data that did fit is returned. Callers that need the remainder (e.g. a pipe transceive whose reply spans multiple reads) issue follow-up READs. Wire: SMB2 IOCTL.

func (*Client) Lock

func (c *Client) Lock(fileId types.SMB2_FILEID, offset, length uint64, exclusive, failImmediately bool) error

Lock acquires a byte-range lock on the open file: a shared (read) lock when exclusive is false, or an exclusive (write) lock when true. By default the server blocks until the range is available; when failImmediately is set, a conflicting range returns STATUS_LOCK_NOT_GRANTED instead of waiting. Wire: SMB2 LOCK.

func (*Client) Logoff

func (c *Client) Logoff() error

Logoff releases the current session (SessionId).

Wire: SMB2 LOGOFF request / response.

func (*Client) Negotiate

func (c *Client) Negotiate() error

Negotiate performs the SMB2 NEGOTIATE exchange, requesting the SMB 2.0.2 dialect and capturing the server’s security mode, capabilities, maximum transfer sizes, GUID, timestamps, and GSS security buffer.

NEGOTIATE uses MessageId 0 and SessionId 0, as required by the spec.

func (*Client) QueryDirectory

func (c *Client) QueryDirectory(fileId types.SMB2_FILEID, fileInformationClass uint8, searchPattern string, flags uint8) ([]byte, error)

QueryDirectory enumerates the directory open identified by fileId using the given FILE_INFORMATION_CLASS and search pattern (empty means “*”), returning the raw output buffer of packed information entries. Decoding the entries into typed structures is the job of the MS-FSCC information-class package (#525).

A STATUS_NO_MORE_FILES result returns an empty buffer and no error, signalling the end of enumeration. Wire: SMB2 QUERY_DIRECTORY.

func (*Client) QueryFileAllInfo

func (c *Client) QueryFileAllInfo(fileId types.SMB2_FILEID) (*filesystem.FileAllInformation, error)

QueryFileAllInfo returns the FILE_ALL_INFORMATION (the aggregate basic, standard, internal, EA, access, position, mode, alignment, and name data) of an open file.

func (*Client) QueryFileBasicInfo

func (c *Client) QueryFileBasicInfo(fileId types.SMB2_FILEID) (*filesystem.FileBasicInformation, error)

QueryFileBasicInfo returns the FILE_BASIC_INFORMATION (timestamps, attributes) of an open file.

func (*Client) QueryFileNetworkOpenInfo

func (c *Client) QueryFileNetworkOpenInfo(fileId types.SMB2_FILEID) (*filesystem.FileNetworkOpenInformation, error)

QueryFileNetworkOpenInfo returns the FILE_NETWORK_OPEN_INFORMATION (timestamps, sizes, attributes) of an open file.

func (*Client) QueryFileStandardInfo

func (c *Client) QueryFileStandardInfo(fileId types.SMB2_FILEID) (*filesystem.FileStandardInformation, error)

QueryFileStandardInfo returns the FILE_STANDARD_INFORMATION (size, link count, delete/directory flags) of an open file.

func (*Client) QueryFsAttributeInfo

func (c *Client) QueryFsAttributeInfo(fileId types.SMB2_FILEID) (*filesystem.FileFsAttributeInformation, error)

QueryFsAttributeInfo returns the FILE_FS_ATTRIBUTE_INFORMATION (attribute flags, max component name length, file system name) of the volume backing fileId.

func (*Client) QueryFsDeviceInfo

func (c *Client) QueryFsDeviceInfo(fileId types.SMB2_FILEID) (*filesystem.FileFsDeviceInformation, error)

QueryFsDeviceInfo returns the FILE_FS_DEVICE_INFORMATION (device type and characteristics) of the volume backing fileId.

func (*Client) QueryFsFullSizeInfo

func (c *Client) QueryFsFullSizeInfo(fileId types.SMB2_FILEID) (*filesystem.FileFsFullSizeInformation, error)

QueryFsFullSizeInfo returns the FILE_FS_FULL_SIZE_INFORMATION (total and caller/actual available allocation units) of the volume backing fileId.

func (*Client) QueryFsSizeInfo

func (c *Client) QueryFsSizeInfo(fileId types.SMB2_FILEID) (*filesystem.FileFsSizeInformation, error)

QueryFsSizeInfo returns the FILE_FS_SIZE_INFORMATION of the volume backing the open identified by fileId (any open on the tree, e.g. the share root).

func (*Client) QueryFsVolumeInfo

func (c *Client) QueryFsVolumeInfo(fileId types.SMB2_FILEID) (*filesystem.FileFsVolumeInformation, error)

QueryFsVolumeInfo returns the FILE_FS_VOLUME_INFORMATION (creation time, serial number, label) of the volume backing the open identified by fileId.

func (*Client) QueryInfo

func (c *Client) QueryInfo(fileId types.SMB2_FILEID, infoType, fileInfoClass uint8, additionalInformation uint32) ([]byte, error)

QueryInfo issues an SMB2 QUERY_INFO on the open identified by fileId and returns the raw output buffer (an MS-FSCC structure, a security descriptor, …). infoType is one of commands.SMB2_0_INFO_* and fileInfoClass the class within it; additionalInformation carries the security-info bits for security queries and is 0 otherwise. Wire: SMB2 QUERY_INFO.

func (*Client) ReadFile

func (c *Client) ReadFile(fileId types.SMB2_FILEID, offset uint64, length uint32) ([]byte, error)

ReadFile reads up to length bytes from the open at the given offset. A read at or past end-of-file returns an empty slice and no error. Wire: SMB2 READ.

func (*Client) RenameByHandle

func (c *Client) RenameByHandle(fileId types.SMB2_FILEID, newName string, replaceIfExists bool) error

RenameByHandle renames the open file to newName (share-relative). The handle must have been opened with DELETE access.

func (*Client) RenameFile

func (c *Client) RenameFile(oldPath, newPath string, replaceIfExists bool) error

RenameFile renames (or moves) oldPath to newPath on the current tree. Both are share-relative. When replaceIfExists is false, the rename fails if newPath already exists.

func (*Client) SessionSetup

func (c *Client) SessionSetup(creds *credentials.Credentials) error

SessionSetup authenticates a session with the server using NTLM over SPNEGO, the SMB2 analog of the SMB 1.0 extended-security session setup. It performs the two-leg NEGOTIATE -> CHALLENGE -> AUTHENTICATE exchange, capturing the server-assigned SessionId from the first response and the derived session key.

The AUTHENTICATE request itself is not signed (the session is not yet established); once the server confirms the session, signing is activated so every subsequent request is signed. Live-validated against Windows Server 2016 with signing required.

func (*Client) SetDeleteOnClose

func (c *Client) SetDeleteOnClose(fileId types.SMB2_FILEID, deletePending bool) error

SetDeleteOnClose marks (or unmarks) an open file for deletion when its last handle is closed.

func (*Client) SetEndOfFile

func (c *Client) SetEndOfFile(fileId types.SMB2_FILEID, size int64) error

SetEndOfFile sets the logical size of an open file (truncate or extend).

func (*Client) SetHost

func (c *Client) SetHost(host net.IP)

SetHost sets the target server IP address.

func (*Client) SetInfo

func (c *Client) SetInfo(fileId types.SMB2_FILEID, infoType, fileInfoClass uint8, additionalInformation uint32, buffer []byte) error

SetInfo issues an SMB2 SET_INFO on fileId, sending buffer as the information to set. Wire: SMB2 SET_INFO.

func (*Client) SetPort

func (c *Client) SetPort(port int)

SetPort sets the target server port.

func (*Client) Stat

func (c *Client) Stat(path string) (*FileStat, error)

Stat opens path, queries its basic and standard information, and closes it.

func (*Client) TransactNamedPipe

func (c *Client) TransactNamedPipe(fileId types.SMB2_FILEID, input []byte, maxOutputResponse uint32) ([]byte, error)

TransactNamedPipe writes a message to the named pipe identified by fileId and returns the pipe’s reply in a single round-trip, via FSCTL_PIPE_TRANSCEIVE. It is the SMB2 basis for DCE/RPC over named pipes (ncacn_np). If the reply exceeds maxOutputResponse the returned data is the portion that fit; the caller reads the remainder with ReadFile.

func (*Client) TreeConnect

func (c *Client) TreeConnect(shareName string) error

TreeConnect connects to a share on the server and selects it for subsequent file operations. The server returns the assigned TreeId in the response header; it is recorded on the session and in the connection’s tree-connect table.

func (*Client) TreeDisconnect

func (c *Client) TreeDisconnect() error

TreeDisconnect releases the currently selected tree connect (TreeId).

Wire: SMB2 TREE_DISCONNECT request / response.

func (*Client) Unlock

func (c *Client) Unlock(fileId types.SMB2_FILEID, offset, length uint64) error

Unlock releases a byte-range lock previously acquired with Lock. The offset and length MUST exactly match a locked range. Wire: SMB2 LOCK (unlock flag).

func (*Client) WaitOplockBreak

func (c *Client) WaitOplockBreak() (*OplockBreak, error)

WaitOplockBreak reads the next unsolicited SMB2 OPLOCK_BREAK notification from the server. The server sends one when another client opens a file on which this client holds an oplock (granted via CreateFileWithOplock); the caller should reply with AcknowledgeOplockBreak. WaitOplockBreak blocks until a notification arrives and is therefore typically run on a dedicated goroutine; it must not run concurrently with another operation that reads the connection.

func (*Client) WriteFile

func (c *Client) WriteFile(fileId types.SMB2_FILEID, offset uint64, data []byte) (uint32, error)

WriteFile writes data to the open at the given offset and returns the number of bytes written. Wire: SMB2 WRITE.

type Connection

Connection represents an established SMB2 connection between client and server.

type Connection struct {
    // Server holds the negotiated properties of the peer.
    Server *Server

    // MessageId is the value to use for the next request's 64-bit MessageId. SMB2
    // requires each request on a connection to use a unique, monotonically
    // increasing MessageId.
    MessageId uint64

    // Credits is the number of credits the server has granted that the client may
    // still spend. SMB 2.0.2 uses a simple one-credit-per-request model.
    Credits uint16

    // Dialect is the SMB2 dialect selected during negotiation.
    Dialect dialects.Dialect

    // SessionTable holds authenticated sessions on this connection, keyed by the
    // server-assigned 64-bit SessionId.
    SessionTable map[uint64]*Session

    // TreeConnectTable holds tree connects on this connection, keyed by TreeId.
    TreeConnectTable map[uint32]*TreeConnect
}

type FileStat

FileStat is a convenience summary of a file’s metadata, combining FILE_BASIC_INFORMATION and FILE_STANDARD_INFORMATION. FILETIME fields are raw 100ns ticks since 1601-01-01 UTC.

type FileStat struct {
    Size           uint64
    AllocationSize uint64
    FileAttributes uint32
    IsDirectory    bool
    CreationTime   uint64
    LastAccessTime uint64
    LastWriteTime  uint64
    ChangeTime     uint64
}

type OplockBreak

OplockBreak is a server-initiated oplock break: the open whose oplock is being broken and the level the server is breaking it down to (one of commands.SMB2_OPLOCK_LEVEL_*).

type OplockBreak struct {
    FileId   types.SMB2_FILEID
    NewLevel uint8
}

type Server

Server holds the peer properties negotiated via SMB2 NEGOTIATE.

type Server struct {
    // Host is the server IP address.
    Host net.IP

    // Port is the server TCP port.
    Port int

    // SecurityMode is the server's signing policy.
    SecurityMode securitymode.SecurityMode

    // Capabilities is the server's capability set.
    Capabilities capabilities.Capabilities

    // MaxTransactSize / MaxReadSize / MaxWriteSize are the negotiated maxima.
    MaxTransactSize uint32
    MaxReadSize     uint32
    MaxWriteSize    uint32

    // ServerGuid is the server's GUID from the NEGOTIATE response.
    ServerGuid [16]byte

    // SystemTime / ServerStartTime are FILETIME values from the NEGOTIATE response.
    SystemTime      uint64
    ServerStartTime uint64

    // SecurityBuffer is the GSS (SPNEGO) token returned in the NEGOTIATE response,
    // used to seed authentication.
    SecurityBuffer []byte

    // Server identity advertised in the NTLM CHALLENGE during authentication: the
    // NetBIOS/DNS computer and domain names and the OS version. Populated by
    // SessionSetup; empty/zero before a successful authentication.
    NetBIOSComputerName string
    NetBIOSDomainName   string
    DNSComputerName     string
    DNSDomainName       string
    OSVersionMajor      uint8
    OSVersionMinor      uint8
    OSVersionBuild      uint16

    // SupportsNTLMv2 reports whether the server's NTLM CHALLENGE advertised
    // extended session security (NTLM2 / NTLMv2). Populated by SessionSetup.
    SupportsNTLMv2 bool
}

type Session

Session represents an authenticated SMB2 session.

type Session struct {
    // Client is the owning client.
    Client *Client

    // SessionId is the server-assigned 64-bit session identifier.
    SessionId uint64

    // TreeId is the 32-bit tree connect currently selected for file operations.
    TreeId uint32

    // SessionKey is the session key derived during authentication.
    SessionKey []byte

    // SigningKey is the key used to sign/verify messages on this session. For the
    // SMB 2.0.2 and 2.1 dialects it is the session key itself.
    SigningKey []byte

    // SigningActive indicates that requests on this session are signed and
    // responses are verified.
    SigningActive bool

    // Credentials are the credentials used to authenticate the session.
    Credentials *credentials.Credentials
}

type TreeConnect

TreeConnect represents a connection to a share on the server.

type TreeConnect struct {
    // Connection is the owning connection.
    Connection *Connection

    // Session is the session on which the tree connect was established.
    Session *Session

    // ShareName is the share this tree connect targets.
    ShareName string

    // TreeId is the server-assigned 32-bit tree identifier.
    TreeId uint32

    // ShareType is the type of share (disk/pipe/print) from the TREE_CONNECT response.
    ShareType uint8
}