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_v10/client"

Index

Constants

Default NativeOS / NativeLanMan strings sent in SESSION_SETUP_ANDX when the caller leaves Client.NativeOS / Client.NativeLanMan empty. They must be non-empty: strict servers (e.g. Windows Server 2016) reject a session setup with empty values. The exact strings are informational only.

const (
    DefaultNativeOS     = "Unix"
    DefaultNativeLanMan = "Samba"
)

TRANS2 information level codes (MS-CIFS 2.2.2.3). QUERY file levels are used with QueryPathInformation/QueryFileInformation; SET file levels with SetPathInformation/SetFileInformation; FS levels with QueryFsInformation.

const (
    InfoLevelQueryFileBasic       uint16 = 0x0101
    InfoLevelQueryFileStandard    uint16 = 0x0102
    InfoLevelQueryFileEA          uint16 = 0x0103
    InfoLevelQueryFileName        uint16 = 0x0104
    InfoLevelQueryFileAll         uint16 = 0x0107
    InfoLevelQueryFileAltName     uint16 = 0x0108
    InfoLevelQueryFileStream      uint16 = 0x0109
    InfoLevelQueryFileCompression uint16 = 0x010B

    InfoLevelSetFileBasic       uint16 = 0x0101
    InfoLevelSetFileDisposition uint16 = 0x0102
    InfoLevelSetFileAllocation  uint16 = 0x0103
    InfoLevelSetFileEndOfFile   uint16 = 0x0104

    InfoLevelQueryFsVolume    uint16 = 0x0102
    InfoLevelQueryFsSize      uint16 = 0x0103
    InfoLevelQueryFsDevice    uint16 = 0x0104
    InfoLevelQueryFsAttribute uint16 = 0x0105
)

Seek mode values for Seek (MS-CIFS 2.2.4.43.1).

const (
    SeekModeStart   uint16 = 0 // offset is relative to the start of the file
    SeekModeCurrent uint16 = 1 // offset is relative to the current file pointer
    SeekModeEnd     uint16 = 2 // offset is relative to the end of the file
)

Server signing policy states, recorded in Server.SigningState after negotiation.

const (
    SigningStateDisabled = "disabled"
    SigningStateEnabled  = "enabled"
    SigningStateRequired = "required"
)

Variables

FileIODebug, when true, dumps the raw bytes of file-I/O requests and responses to stdout. It is a coarse diagnostic aid until a structured logger is wired in.

var FileIODebug bool

type Client

Client represents an SMB v1.0 client

type Client struct {
    // Transport is the transport layer for the client
    Transport transport.Transport

    // Session is the session for the client
    Session *Session

    // Connection is the connection for the client
    Connection *Connection

    // NativeOS is the native operating system of the client
    NativeOS string

    // NativeLanMan is the native LAN Manager of the client
    NativeLanMan string

    // Workstation is the workstation name of the client
    Workstation string
}

func NewClientUsingNBTTransport

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

NewClientUsingNBTTransport creates a new SMB v1.0 client using NBT transport

Returns:

  • A pointer to the initialized SMB client
  • An error if the client initialization fails

func NewClientUsingTCPTransport

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

NewClientUsingTCPTransport creates a new SMB v1.0 client using TCP transport

Returns:

  • A pointer to the initialized SMB client
  • An error if the client initialization fails

func NewFromTransport

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

NewFromTransport builds an SMB v1.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 together with the SMB_COM_NEGOTIATE response it received, applied via ApplyNegotiateResponse.

func (*Client) ApplyNegotiateResponse

func (c *Client) ApplyNegotiateResponse(negotiateResponse *commands.NegotiateResponse, offered dialects.Dialects) error

ApplyNegotiateResponse records the negotiated connection state — selected dialect, server capabilities, session key, timestamps, buffer sizes, identity, security mode, and derived signing policy — from an SMB_COM_NEGOTIATE response. offered is the dialect list that was sent, needed to resolve the server’s selected dialect from its index.

It is shared by Negotiate, which exchanges the response on the transport, and by the generic SMB client (network/smb/client), which hands over the response it received during a multi-protocol negotiate (SMB1 cannot renegotiate on an already-established connection).

func (*Client) CheckDirectory

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

CheckDirectory tests whether a path on the current tree is a valid directory. path uses backslash separators relative to the share root (e.g. “\subdir”). Returns nil if the path is a directory, or an error otherwise.

Wire: SMB_COM_CHECK_DIRECTORY request / response.

func (*Client) CloseFile

func (c *Client) CloseFile(fid FID) error

CloseFile releases an open FID on the server.

Wire: CloseRequest / CloseResponse.

func (*Client) Connect

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

Connect establishes a connection to an SMB server

Returns:

func (*Client) CreateDirectory

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

CreateDirectory creates a directory on the current tree. path uses backslash separators relative to the share root (e.g. “\newdir”).

Wire: SMB_COM_CREATE_DIRECTORY request / response.

func (c *Client) CreateHardLink(existingPath, linkPath string) error

CreateHardLink creates a hard link at linkPath that refers to the existing file existingPath, using SMB_COM_NT_RENAME (SMB_NT_RENAME_SET_LINK_INFO).

func (*Client) DeleteDirectory

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

DeleteDirectory removes an empty directory on the current tree. path uses backslash separators relative to the share root (e.g. “\olddir”).

Wire: SMB_COM_DELETE_DIRECTORY request / response.

func (*Client) DeleteFile

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

DeleteFile deletes one or more files matching pattern on the current tree. pattern uses backslash separators relative to the share root (e.g. “\subdir\file.txt”). Wildcards are permitted in the filename component.

Wire: SMB_COM_DELETE request / response.

func (*Client) Disconnect

func (c *Client) Disconnect() error

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

func (*Client) Echo

func (c *Client) Echo(data []byte) ([]byte, error)

Echo sends an SMB_COM_ECHO request carrying data and returns the data echoed back by the server. It is a round-trip/keepalive check on the connection.

Wire: SMB_COM_ECHO request / response (EchoCount 1).

func (*Client) Flush

func (c *Client) Flush(fid FID) error

Flush requests that the server flush all buffered data for the open file referenced by fid to stable storage. Passing FID 0xFFFF flushes every file the client has open on the connection.

Wire: SMB_COM_FLUSH request / response.

func (*Client) GetFileBasicInfo

func (c *Client) GetFileBasicInfo(path string) (*informationlevels.SMB_QUERY_FILE_BASIC_INFO, error)

GetFileBasicInfo queries the 64-bit timestamps and extended attributes of a share-relative path.

func (*Client) GetFileStandardInfo

func (c *Client) GetFileStandardInfo(path string) (*informationlevels.SMB_QUERY_FILE_STANDARD_INFO, error)

GetFileStandardInfo queries the size, link count, delete-pending and directory flags of a share-relative path.

func (*Client) GetFsAttributeInfo

func (c *Client) GetFsAttributeInfo() (*informationlevels.SMB_QUERY_FS_ATTRIBUTE_INFO, error)

GetFsAttributeInfo queries the filesystem attribute flags and name.

func (*Client) GetFsSizeInfo

func (c *Client) GetFsSizeInfo() (*informationlevels.SMB_QUERY_FS_SIZE_INFO, error)

GetFsSizeInfo queries the volume’s total/free allocation units and sector sizes.

func (*Client) GetHost

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

GetHost returns the current host IP address of the SMB client

func (*Client) GetPort

func (c *Client) GetPort() int

GetPort returns the current port number of the SMB client

func (*Client) GetRemoteServerTime

func (c *Client) GetRemoteServerTime() (time.Time, error)

GetRemoteServerTime returns the server’s system clock as reported in the SMB_COM_NEGOTIATE response.

SMBv1 has no dedicated query-time command; the server’s time is delivered in the NEGOTIATE response and captured by Negotiate as Connection.Server.SystemTime (a FILETIME, i.e. 100ns ticks since 1601-01-01 UTC). The returned time therefore reflects the server’s clock at the moment of negotiation, in UTC.

Returns:

  • The server time in UTC.
  • An error if no connection exists or negotiation has not populated the time.

func (*Client) ListDirectory

func (c *Client) ListDirectory(path string) ([]Entry, error)

ListDirectory lists all entries (files and directories) in the given directory on the current tree. path is a directory path using backslash separators relative to the share root (e.g. “\”, “\subdir”, “\subdir\nested”). An empty path defaults to the share root.

Wire: TRANS2_FIND_FIRST2 / FIND_NEXT2 with “\path\*” pattern.

func (*Client) ListEntries

func (c *Client) ListEntries(pattern string) ([]Entry, error)

ListEntries enumerates entries matching pattern in the current tree, using TRANS2_FIND_FIRST2 followed by as many TRANS2_FIND_NEXT2 calls as needed, and always closing the search with FindClose2.

pattern uses SMB wildcards and backslash separators relative to the share root (e.g. “\*.txt”, “\docs\report-*.pdf”). An empty pattern defaults to “\*”.

func (*Client) LockFile

func (c *Client) LockFile(fid FID, offset, length uint64, exclusive bool) error

LockFile locks a byte range [offset, offset+length) on the open file referenced by fid. When exclusive is false the lock is a shared (read-only) lock. The request fails immediately (no wait) if the range cannot be locked.

Wire: SMB_COM_LOCKING_ANDX with a single 64-bit lock range.

func (*Client) Logoff

func (c *Client) Logoff() error

Logoff releases the current session (UID) on the server.

Wire: SMB_COM_LOGOFF_ANDX request / response.

func (*Client) Negotiate

func (c *Client) Negotiate() error

Negotiate initiates the SMB protocol negotiation with the server.

This function performs the SMB_COM_NEGOTIATE exchange, which is the first step in establishing an SMB session. It sends a list of dialects supported by the client and receives the server’s preferred dialect along with server capabilities.

The negotiation process: 1. Creates and sends an SMB_COM_NEGOTIATE_REQUEST message 2. Receives the SMB_COM_NEGOTIATE_RESPONSE from the server 3. Validates the response command type 4. Processes server capabilities and configuration

Returns:

  • nil if negotiation is successful
  • An error if any step in the negotiation process fails (connection issues, message creation/marshalling errors, transport errors, or unexpected responses)

func (*Client) NtRename

func (c *Client) NtRename(oldPath, newPath string) error

NtRename performs an in-place rename of oldPath to newPath using SMB_COM_NT_RENAME (SMB_NT_RENAME_RENAME_FILE). Unlike the legacy RenameFile, wildcards are not supported.

func (*Client) OpenFile

func (c *Client) OpenFile(path string, desiredAccess, shareAccess, createDisp, createOptions uint32) (FID, error)

OpenFile opens (or creates) a file on the currently connected tree and returns the server-assigned FID.

Wire: NtCreateAndxRequest / NtCreateAndxResponse.

func (*Client) QueryFileInformation

func (c *Client) QueryFileInformation(fid FID, infoLevel uint16) ([]byte, error)

QueryFileInformation issues TRANS2_QUERY_FILE_INFORMATION for an open FID at the given information level and returns the raw response data bytes.

func (*Client) QueryFsInformation

func (c *Client) QueryFsInformation(infoLevel uint16) ([]byte, error)

QueryFsInformation issues TRANS2_QUERY_FS_INFORMATION at the given information level and returns the raw response data bytes.

func (*Client) QueryPathInformation

func (c *Client) QueryPathInformation(path string, infoLevel uint16) ([]byte, error)

QueryPathInformation issues TRANS2_QUERY_PATH_INFORMATION for a share-relative path at the given information level and returns the raw response data bytes (the information-level structure).

func (*Client) ReadFile

func (c *Client) ReadFile(fid FID, offset uint64, maxLen uint32) ([]byte, error)

ReadFile reads up to maxLen bytes starting at offset from the file referenced by fid. It issues as many ReadAndx requests as required, stopping at maxLen or at the first short read (end of file).

Wire: ReadAndxRequest / ReadAndxResponse.

func (*Client) RenameFile

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

RenameFile renames (or moves) a file on the current tree. oldPath and newPath use backslash separators relative to the share root.

Wire: SMB_COM_RENAME request / response.

func (*Client) Seek

func (c *Client) Seek(fid FID, mode uint16, offset int32) (uint32, error)

Seek sets the file pointer of the open file referenced by fid and returns the resulting absolute file position (bytes from the start of the file). mode is one of SeekModeStart/SeekModeCurrent/SeekModeEnd and offset is a signed displacement.

Wire: SMB_COM_SEEK request / response.

func (*Client) SessionSetup

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

SessionSetup sets up a session with the SMB server

Returns:

  • An error if the session setup fails

func (*Client) SetFileDeleteOnClose

func (c *Client) SetFileDeleteOnClose(fid FID, deletePending bool) error

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

func (*Client) SetFileEndOfFile

func (c *Client) SetFileEndOfFile(fid FID, endOfFile uint64) error

SetFileEndOfFile sets the end-of-file position (logical size) of an open file.

func (*Client) SetFileInformation

func (c *Client) SetFileInformation(fid FID, infoLevel uint16, data []byte) error

SetFileInformation issues TRANS2_SET_FILE_INFORMATION for an open FID at the given information level, sending data as the information-level payload.

func (*Client) SetHost

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

SetHost sets the host IP address for the SMB client

func (*Client) SetPathInformation

func (c *Client) SetPathInformation(path string, infoLevel uint16, data []byte) error

SetPathInformation issues TRANS2_SET_PATH_INFORMATION for a share-relative path at the given information level, sending data as the information-level payload.

func (*Client) SetPort

func (c *Client) SetPort(port int)

SetPort sets the port number for the SMB client

func (*Client) TreeConnect

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

func (*Client) TreeDisconnect

func (c *Client) TreeDisconnect() error

TreeDisconnect releases the current tree connection (TID) on the server.

Wire: SMB_COM_TREE_DISCONNECT request / response.

func (*Client) UnlockFile

func (c *Client) UnlockFile(fid FID, offset, length uint64) error

UnlockFile releases a previously acquired byte-range lock [offset, offset+length) on the open file referenced by fid.

Wire: SMB_COM_LOCKING_ANDX with a single 64-bit unlock range.

func (*Client) WriteFile

func (c *Client) WriteFile(fid FID, offset uint64, data []byte) (int, error)

WriteFile writes data to the file referenced by fid starting at offset and returns the total number of bytes written. It issues as many WriteAndx requests as required, bounding each one so the request message stays within the negotiated MaxBufferSize.

Wire: WriteAndxRequest / WriteAndxResponse.

type Connection

Connection represents an established SMB connection between the client and server

type Connection struct {
    Server *Server

    // ClientNextSendSequenceNumber is the sequence number for the next signed request being sent
    ClientNextSendSequenceNumber uint32

    // ClientResponseSequenceNumber is the expected sequence numbers for responses of outstanding signed requests, indexed by PID and MID
    ClientResponseSequenceNumber map[uint32]uint32

    // ConnectionlessSessionID is the SMB Connection identifier for connectionless transport
    ConnectionlessSessionID uint32

    // IsSigningActive indicates whether message signing is active
    IsSigningActive bool

    // NegotiateSent indicates whether an SMB_COM_NEGOTIATE request has been sent
    NegotiateSent bool

    // NTLMChallenge is the cryptographic challenge received from the server during negotiation
    NTLMChallenge []byte

    // OpenTable is the list of Opens, allowing lookups based on FID
    OpenTable map[uint16]interface{}

    // PIDMIDList is the list of outstanding SMB commands
    PIDMIDList []interface{}

    // SearchOpenTable is the list of SearchOpens representing open file searches
    SearchOpenTable []interface{}

    // SelectedDialect is the SMB Protocol dialect selected for this connection
    SelectedDialect string

    // MaxMpxCount is the maximum number of commands permitted to be outstanding
    MaxMpxCount uint16

    // SessionTable is the list of authenticated sessions established on this connection
    SessionTable map[uint16]*Session

    // ShareLevelAccessControl indicates whether the server requires share passwords instead of user accounts
    ShareLevelAccessControl bool

    // SigningChallengeResponse is the challenge response used for signing
    SigningChallengeResponse []byte

    // SigningSessionKey is the session key used for signing packets
    SigningSessionKey []byte

    // TreeConnectTable is the list of tree connects over this SMB connection
    TreeConnectTable map[uint16]interface{}
}

type Entry

Entry is a high-level directory entry (file or directory) returned by ListDirectory and ListEntries.

type Entry struct {
    LongName    string
    ShortName   string
    Size        uint64
    Attributes  uint32
    CreatedAt   time.Time
    AccessedAt  time.Time
    ModifiedAt  time.Time
    ChangedAt   time.Time
    IsDirectory bool
}

type FID

FID is an opaque file handle returned by the server for an open file or directory.

type FID uint16

type Server

Server represents the server for the client

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

    // Port is the port number of the server
    Port int

    // Name is the name of the server
    Name string

    // SecurityMode is the security mode of the server
    SecurityMode securitymode.SecurityMode

    // SigningState is the signing policy of the server (Disabled, Enabled, or Required)
    SigningState string

    // Capabilities is the capabilities of the server
    Capabilities capabilities.Capabilities

    // MaxBufferSize is the negotiated maximum size for SMB messages sent to server
    MaxBufferSize uint32

    // ChallengeResponse indicates whether server supports challenge/response authentication
    ChallengeResponse bool

    // SessionKey is the session key value returned by the server in negotiate response
    SessionKey uint32

    // SystemTime is the system time of the server
    SystemTime types.SMB_TIME

    // TimeZone is the time zone of the server
    TimeZone int16

    // DomainName is the domain name of the server
    DomainName string

    // ServerGUID is the GUID of the server
    ServerGUID guid.GUID

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

    // OSName is the server's native operating-system string from the SESSION_SETUP
    // response (NativeOS). SMB1 only; populated by SessionSetup.
    OSName string

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

type Session

Session represents an established session between the client and server

type Session struct {
    // The SMB connection associated with this session
    Client *Client

    // The cryptographic session key associated with this session
    SessionKey []byte

    // The 2-byte UID for this session
    SessionUID uint16

    // TreeID is the TID of the tree connect currently selected for outbound
    // commands (file I/O, etc.). It is populated by Client.TreeConnect.
    TreeID uint16

    // The credentials for this session
    Credentials *credentials.Credentials
}

func (*Session) SessionSetup

func (s *Session) SessionSetup() error

type TreeConnect

TreeConnect represents an established tree connect between the client and share on the server

type TreeConnect struct {
    Connection *Connection // The SMB connection associated with this tree connect
    ShareName  string      // The share name corresponding to this tree connect
    TreeID     uint16      // The TreeID (TID) that identifies this tree connect
    Session    *Session    // A reference to the session on which this tree connect was established
    IsDfsShare bool        // A Boolean that, if set, indicates that the tree connect was established to a DFS share
}