smb

Documentation

Overview

Package smb provides an embeddable SMB2/SMB3 server that serves a facetfs.FileSystem on caller-supplied net.Listener or net.Conn values. The caller owns the transport, the credential store, and the share policy.

Experimental: the protocol and race suites pass, but the Windows, macOS, and Linux acceptance profile has not yet been completed. Test the clients you intend to support before deploying it.

The package serves dialects 2.1 and 3.1.1 over direct TCP. It answers the SMB1 multi-protocol negotiate that Windows Explorer and the macOS Finder open a connection with, by stepping the client up to SMB2; it implements nothing else of SMB1. It signs messages but does not encrypt them, so the transport is not confidential: serve it on a trusted network. It grants no oplock and no lease, and its byte-range locks are advisory, so they coordinate cooperating SMB clients but do not prevent access through another protocol.

The server exports one disk share. It implements session setup, tree and handle lifetime, create/read/write/flush/close, share modes, byte-range locks, directory enumeration, metadata queries and changes, and negotiate validation. Oplocks, leases, durable handles, alternate data streams, named pipes, ACL storage, and encryption are intentionally unsupported.

Authentication is NTLMv2. SMB derives the key that signs every message from that exchange, so the package runs it and the application supplies the secret through an Authenticator. The application therefore keeps its credential store, and the package keeps the protocol.

Index

• func NTHash(password string) []byte
• type Authenticator
• type Server
  • func (s *Server) Serve(ctx context.Context, l net.Listener) error
  • func (s *Server) ServeConn(ctx context.Context, c net.Conn) error

Functions

func NTHash

func NTHash(password string) []byte

NTHash derives the password-equivalent value expected by Authenticator. Callers should protect the result as carefully as the password itself.

Types

type Authenticator

type Authenticator interface {
	NTHash(ctx context.Context, domain, user string) ([]byte, error)
}

Authenticator supplies the secret for one user.

SMB derives the key that signs every message from the authentication exchange, so the package must run that exchange itself. The split is therefore drawn one level lower than in the other packages: the application owns the credential store and answers one question, and the package owns the protocol.

NTHash returns MD4(UTF-16LE(password)) for the named user. An unknown user must return an error. The value is password-equivalent: store it as carefully as a password, and use it for nothing else.

type Server

type Server struct {
	// FileSystem is the served filesystem. Required.
	FileSystem facetfs.FileSystem
	// Authenticator supplies the secret for a user. Required: this server
	// grants no anonymous access.
	Authenticator Authenticator
	// ShareName is the single share this Server exports. Zero means "share".
	ShareName string
	// ServerName is reported during authentication. Zero means "FACETFS".
	ServerName string
	// MaxReadBytes, MaxWriteBytes, and MaxTransactBytes cap one operation and
	// are advertised during negotiation. Zero means 1 MiB.
	MaxReadBytes     uint32
	MaxWriteBytes    uint32
	MaxTransactBytes uint32
	// MaxDirectoryEntries caps one directory listing. Zero means 100 000.
	MaxDirectoryEntries int
	// RequireSigning refuses a session that will not sign. The server signs
	// whenever the client asks for it either way.
	RequireSigning bool
	// Logger, if set, receives per-connection faults from Serve.
	Logger func(error)
	// contains filtered or unexported fields
}

Server serves SMB2 and SMB3 from a FileSystem. The zero value of every optional field is usable.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, l net.Listener) error

Serve accepts connections until ctx is canceled or the listener fails.

func (*Server) ServeConn

func (s *Server) ServeConn(ctx context.Context, c net.Conn) error

ServeConn serves one connection until the client disconnects or ctx is canceled. It returns nil on a clean client disconnect.