ssh

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: BSD-3-Clause Imports: 28 Imported by: 0

README

SSH Server SDK for Go

This Go package wraps the crypto/ssh package with a higher-level API for building SSH servers. The goal of the API was to make it as simple as using net/http, so the API is very similar:

 package main

 import (
     "io"
     "log"

     "github.com/engity-com/ssh-server-go"
 )

 func main() {
     ssh.Handle(func(s ssh.Session) {
         io.WriteString(s, "Hello world\n")
     })

     log.Fatal(ssh.ListenAndServe("127.0.0.1:2222", nil))
 }

[!NOTE] The minimal example uses anonymous authentication and an automatically generated, process-local host key. These defaults are intended for local development only. Production servers should configure PasswordHandler, PublicKeyHandler, or a custom authentication policy, add a persistent host key, set RequireHostSigners: true and RequireClientAuth: true, and expose only explicitly intended interfaces and forwarding destinations. Agent forwarding is denied unless AgentForwardingCallback explicitly allows it.

The module requires Go 1.27 or newer. The core package is portable across the platforms supported by Go and its dependencies; some examples require Unix facilities or programs.

Getting into this SDK

Acknowledgements

This project was originally forked from gliderlabs/ssh. Special thanks to its maintainers and contributors for laying the foundation for this work.

Documentation

Overview

Package ssh wraps the crypto/ssh package with a higher-level API for building SSH servers. The goal of the API was to make it as simple as using net/http, so the API is very similar.

You should be able to build any SSH server using only this package, which wraps relevant types and some functions from crypto/ssh. However, you still need to use crypto/ssh for building SSH clients.

ListenAndServe starts an SSH server with a given address, handler, and options. The handler is usually nil, which means to use DefaultHandler. Handle sets DefaultHandler: 

ssh.Handle(func(s ssh.Session) {
    io.WriteString(s, "Hello world\n")
})

log.Fatal(ssh.ListenAndServe(":2222", nil))

If you don't specify a host key, it will generate one every time. This development convenience does not provide a stable server identity. Production servers should configure a persistent signer and set Server.RequireHostSigners. It's a better idea to generate or point to an existing key on your system: 

log.Fatal(ssh.ListenAndServe(":2222", nil, ssh.HostKeyFile("/Users/progrium/.ssh/id_rsa")))

Although all options have functional option helpers, another way to control the server's behavior is by creating a custom Server: 

s := &ssh.Server{
    Addr:             ":2222",
    Handler:          sessionHandler,
    PublicKeyHandler: authHandler,
}
s.AddHostKey(hostKeySigner)

log.Fatal(s.ListenAndServe())

This package handles basic SSH requests such as environment variables, PTYs, window changes, signals, and breaks. Relevant state and delivery hooks are exposed through Session.

The module requires the Go version declared in go.mod. The core package supports the operating systems supported by its dependencies; examples that launch Unix programs or use Unix sockets have additional platform requirements.

Index

Examples

Constants

View Source 
const (
	DefaultHandshakeTimeout                = 2 * time.Minute
	DefaultIdleTimeout                     = time.Duration(0)
	DefaultMaxTimeout                      = time.Duration(0)
	DefaultMaxStartupsStart                = 10
	DefaultMaxStartupsRate                 = 30
	DefaultMaxStartupsFull                 = 100
	DefaultMaxSessionsPerConnection        = 10
	DefaultMaxChannelsPerConnection        = 64
	DefaultMaxReverseForwardsPerConnection = 16
	DefaultMaxConnections                  = 256
	DefaultMaxChannels                     = 1024
)

Variables

View Source 
var (

	// ContextKeyUser is a context key for use with Contexts in this package.
	// The associated value will be of type string.
	ContextKeyUser = &contextKey{"user"}

	// ContextKeySessionID is a context key for use with Contexts in this package.
	// The associated value will be of type string.
	ContextKeySessionID = &contextKey{"session-id"}

	// ContextKeyPermissions is a context key for use with Contexts in this package.
	// The associated value will be of type *Permissions.
	ContextKeyPermissions = &contextKey{"permissions"}

	// ContextKeyClientVersion is a context key for use with Contexts in this package.
	// The associated value will be of type string.
	ContextKeyClientVersion = &contextKey{"client-version"}

	// ContextKeyServerVersion is a context key for use with Contexts in this package.
	// The associated value will be of type string.
	ContextKeyServerVersion = &contextKey{"server-version"}

	// ContextKeyLocalAddr is a context key for use with Contexts in this package.
	// The associated value will be of type net.Addr.
	ContextKeyLocalAddr = &contextKey{"local-addr"}

	// ContextKeyRemoteAddr is a context key for use with Contexts in this package.
	// The associated value will be of type net.Addr.
	ContextKeyRemoteAddr = &contextKey{"remote-addr"}

	// ContextKeyServer is a context key for use with Contexts in this package.
	// The associated value will be of type *Server.
	ContextKeyServer = &contextKey{"ssh-server"}

	// ContextKeyConn is a context key for use with Contexts in this package.
	// The associated value will be of type *gossh.ServerConn after the SSH
	// handshake has completed.
	ContextKeyConn = &contextKey{"ssh-conn"}

	// ContextKeyPublicKey is a context key for use with Contexts in this package.
	// The associated value will be of type PublicKey.
	ContextKeyPublicKey = &contextKey{"public-key"}
)
View Source 
var (
	// ErrServerClosed is returned by [Server.Serve] and [Server.ListenAndServe]
	// after a call to [Server.Shutdown] or [Server.Close].
	ErrServerClosed = errors.New("ssh: Server closed")

	ErrServerPermissionDenied     = errors.New("permission denied")
	ErrServerHostSignerRequired   = errors.New("ssh: at least one persistent host signer is required")
	ErrServerRunning              = errors.New("ssh: server configuration cannot be changed while running")
	ErrServerClientAuthRequired   = errors.New("ssh: at least one client authentication method is required")
	ErrServerAuthCallbackConflict = errors.New("ssh: conflicting authentication callbacks")
)
View Source 
var DefaultChannelHandlers = map[string]ChannelHandler{
	"session": DefaultSessionHandler,
}
View Source 
var (
	DefaultCiphers = Ciphers{
		CipherAes256Gcm,
		CipherAes256Ctr,
		CipherAes192Ctr,
	}
)
View Source 
var (
	DefaultKeyExchanges = KeyExchanges{
		KeyExchangeCurve25519Sha256LibSsh,
		KeyExchangeCurve25519Sha256,
		KeyExchangeDh16Sha512,
		KeyExchangeMlkem768x25519xSha256,
	}
)
View Source 
var (
	DefaultMessageAuthentications = MessageAuthentications{
		MessageAuthenticationHmacSha2B512Etm,
		MessageAuthenticationHmacSha2B256Etm,
	}
)
View Source 
var DefaultRequestHandlers = map[string]RequestHandler{}
View Source 
var DefaultSubsystemHandlers = map[string]SubsystemHandler{}

Functions

func AgentRequested 

func AgentRequested(sess Session) bool

AgentRequested returns true if the client requested agent forwarding.

func DefaultSessionHandler 

func DefaultSessionHandler(srv *Server, conn *gossh.ServerConn, newChan gossh.NewChannel, ctx Context)

func DirectTCPIPHandler 

func DirectTCPIPHandler(srv *Server, sshConn *gossh.ServerConn, newChan gossh.NewChannel, ctx Context)

DirectTCPIPHandler can be enabled by adding it to the server's ChannelHandlers under direct-tcpip.

func ForwardAgentConnections 

func ForwardAgentConnections(ln net.Listener, logger log.Logger, sess Session)

ForwardAgentConnections takes connections from a listener to proxy into the session on the OpenSSH channel for agent connections. It blocks and services connections until the listener stop accepting.

func FullDuplexCopy 

func FullDuplexCopy(ctx context.Context, left io.ReadWriteCloser, right io.ReadWriteCloser, opts *FullDuplexCopyOpts) (rErr error)

FullDuplexCopy copies data in both directions until both streams finish. It half-closes completed streams and closes both sides on cancellation or error. To guarantee cancellation, Close on each side must unblock concurrent Read and Write calls; implementations that do not honor that contract can prevent this function from returning. A nil context is treated as context.Background.

func Handle 

func Handle(handler Handler)

Handle registers the handler as the DefaultHandler.

func KeysEqual 

func KeysEqual(ak, bk PublicKey) bool

KeysEqual is constant time compare of the keys to avoid timing attacks.

func ListenAndServe 

func ListenAndServe(addr string, handler Handler, options ...Option) error

ListenAndServe listens on the TCP network address addr and then calls Serve with handler to handle sessions on incoming connections. Handler is typically nil, in which case the DefaultHandler is used.

Example 
package main

import (
	"io"
	"log"

	"github.com/engity-com/ssh-server-go"
)

func main() {
	log.Fatal(ssh.ListenAndServe(":2222", func(s ssh.Session) {
		_, _ = io.WriteString(s, "Hello world\n")
	}))
}

func NewAgentListener 

func NewAgentListener() (net.Listener, error)

NewAgentListener sets up a temporary Unix socket that can be communicated to the session environment and used for forwarding connections.

func Serve 

func Serve(l net.Listener, handler Handler, options ...Option) error

Serve accepts incoming SSH connections on the listener l, creating a new connection goroutine for each. The connection goroutines read requests and then calls handler to handle sessions. Handler is typically nil, in which case the DefaultHandler is used.

func SetAgentRequested 

func SetAgentRequested(ctx Context)

SetAgentRequested sets up the session context so that AgentRequested returns true.

Types

type AgentForwardingCallback 

type AgentForwardingCallback func(ctx Context) bool

AgentForwardingCallback is a hook for allowing agent forwarding per session. A nil callback denies agent forwarding.

type BannerHandler 

type BannerHandler func(ctx Context) string

BannerHandler is a callback for displaying the server banner.

type ChannelHandler 

type ChannelHandler func(srv *Server, conn *gossh.ServerConn, newChan gossh.NewChannel, ctx Context)

ChannelHandler handles one channel synchronously. It should not return until ownership of the channel and its associated resources has ended.

type Cipher 

type Cipher uint8
const (
	CipherAes128Cbc Cipher = iota
	Cipher3desCbc
	CipherArcfour
	CipherArcfour128
	CipherArcfour256
	CipherChacha20Poly1305
	CipherAes128Ctr
	CipherAes192Ctr
	CipherAes256Ctr
	CipherAes128Gcm
	CipherAes256Gcm
)

func (Cipher) IsEqualTo 

func (c Cipher) IsEqualTo(other any) bool

func (Cipher) IsZero 

func (c Cipher) IsZero() bool

func (Cipher) MarshalText 

func (c Cipher) MarshalText() (text []byte, err error)

func (*Cipher) Set 

func (c *Cipher) Set(text string) error

func (Cipher) String 

func (c Cipher) String() string

func (*Cipher) UnmarshalText 

func (c *Cipher) UnmarshalText(text []byte) error

func (Cipher) Validate 

func (c Cipher) Validate() error

type Ciphers 

type Ciphers []Cipher

func (Ciphers) Contains 

func (c Ciphers) Contains(v Cipher) bool

func (Ciphers) IsCumulative 

func (c Ciphers) IsCumulative() bool

func (Ciphers) IsEmpty 

func (c Ciphers) IsEmpty() bool

func (Ciphers) IsEqualTo 

func (c Ciphers) IsEqualTo(other any) bool

func (Ciphers) IsZero 

func (c Ciphers) IsZero() bool

func (Ciphers) MarshalText 

func (c Ciphers) MarshalText() (text []byte, err error)

func (Ciphers) MarshalTexts 

func (c Ciphers) MarshalTexts() (texts [][]byte, err error)

func (*Ciphers) Set 

func (c *Ciphers) Set(text string) error

func (Ciphers) String 

func (c Ciphers) String() string

func (*Ciphers) UnmarshalText 

func (c *Ciphers) UnmarshalText(text []byte) error

func (Ciphers) Validate 

func (c Ciphers) Validate() error

type ConnCallback 

type ConnCallback func(ctx Context, conn net.Conn) net.Conn

ConnCallback is a hook for new connections before handling. It allows wrapping for timeouts and limiting by returning the net.Conn that will be used as the underlying connection. Implementations must return promptly and honor Context cancellation; network deadlines cannot forcibly stop callback code that blocks without doing I/O.

type ConnectionFailedCallback 

type ConnectionFailedCallback func(conn net.Conn, err error)

ConnectionFailedCallback is a hook for reporting failed connections Please note: the net.Conn is likely to be closed at this point

type Context 

type Context interface {
	context.Context
	sync.Locker

	// User returns the current username, or "" before metadata is available.
	User() string

	// SessionID returns the hex-encoded session hash, or "" before it is available.
	SessionID() string

	// ClientVersion returns the version reported by the client, or "" before it is available.
	ClientVersion() string

	// ServerVersion returns the version reported by the server, or "" before it is available.
	ServerVersion() string

	// RemoteAddr returns the remote address, or nil before metadata is available.
	RemoteAddr() net.Addr

	// LocalAddr returns the local address, or nil before metadata is available.
	LocalAddr() net.Addr

	// Permissions returns the current authentication permissions. Server-created
	// contexts initialize an empty value before authentication starts.
	Permissions() *Permissions

	// SetValue allows you to easily write new values into the underlying context.
	SetValue(key, value any)
}

Context is a package-specific context interface. It exposes connection metadata and allows new values to be written to it. Metadata getters return zero values until metadata is available during the SSH handshake. Context is used in authentication handlers and callbacks and exposed by Session.Context. A connection-scoped lock is embedded for coordinating application state.

type ForwardedTCPHandler 

type ForwardedTCPHandler struct {
	Logger log.Logger

	sync.Mutex
	// contains filtered or unexported fields
}

ForwardedTCPHandler can be enabled by creating a ForwardedTCPHandler and adding the HandleSSHRequest callback to the server's RequestHandlers under tcpip-forward and cancel-tcpip-forward.

func (*ForwardedTCPHandler) HandleSSHRequest 

func (h *ForwardedTCPHandler) HandleSSHRequest(ctx Context, srv *Server, req *gossh.Request) (bool, []byte)

type FullDuplexCopyOpts 

type FullDuplexCopyOpts struct {
	OnStart       func()
	OnEnd         func(l2r, r2l int64, duration time.Duration, err error, wasInL2r *bool)
	OnStreamStart func(isL2r bool)
	OnStreamEnd   func(isL2r bool, err error)
}

FullDuplexCopyOpts defines optional callbacks for observing a bidirectional copy. Callbacks are invoked asynchronously in event order on one observer goroutine and cannot delay FullDuplexCopy. They must still return promptly to avoid retaining that observer goroutine.

type Handler 

type Handler func(Session)

Handler is a callback for handling established SSH sessions. 

var DefaultHandler Handler

DefaultHandler is the default Handler used by Serve.

type KeyExchange 

type KeyExchange uint8
const (
	KeyExchangeDh1Sha1 KeyExchange = iota
	KeyExchangeDh14Sha1
	KeyExchangeDh14Sha256
	KeyExchangeDh16Sha512
	KeyExchangeEcdh256
	KeyExchangeEcdh384
	KeyExchangeEcdh521
	KeyExchangeCurve25519Sha256LibSsh
	KeyExchangeCurve25519Sha256
	KeyExchangeDhgexSha1
	KeyExchangeDhgexSha256
	KeyExchangeMlkem768x25519xSha256
)

func (KeyExchange) IsEqualTo 

func (ke KeyExchange) IsEqualTo(other any) bool

func (KeyExchange) IsZero 

func (ke KeyExchange) IsZero() bool

func (KeyExchange) MarshalText 

func (ke KeyExchange) MarshalText() (text []byte, err error)

func (*KeyExchange) Set 

func (ke *KeyExchange) Set(text string) error

func (KeyExchange) String 

func (ke KeyExchange) String() string

func (*KeyExchange) UnmarshalText 

func (ke *KeyExchange) UnmarshalText(text []byte) error

func (KeyExchange) Validate 

func (ke KeyExchange) Validate() error

type KeyExchanges 

type KeyExchanges []KeyExchange

func (KeyExchanges) Contains 

func (ke KeyExchanges) Contains(v KeyExchange) bool

func (KeyExchanges) IsCumulative 

func (ke KeyExchanges) IsCumulative() bool

func (KeyExchanges) IsEmpty 

func (ke KeyExchanges) IsEmpty() bool

func (KeyExchanges) IsEqualTo 

func (ke KeyExchanges) IsEqualTo(other any) bool

func (KeyExchanges) IsZero 

func (ke KeyExchanges) IsZero() bool

func (KeyExchanges) MarshalText 

func (ke KeyExchanges) MarshalText() (text []byte, err error)

func (KeyExchanges) MarshalTexts 

func (ke KeyExchanges) MarshalTexts() (texts [][]byte, err error)

func (*KeyExchanges) Set 

func (ke *KeyExchanges) Set(text string) error

func (KeyExchanges) String 

func (ke KeyExchanges) String() string

func (*KeyExchanges) UnmarshalText 

func (ke *KeyExchanges) UnmarshalText(text []byte) error

func (KeyExchanges) Validate 

func (ke KeyExchanges) Validate() error

type KeyboardInteractiveHandler 

type KeyboardInteractiveHandler func(ctx Context, challenger gossh.KeyboardInteractiveChallenge) bool

KeyboardInteractiveHandler is a callback for performing keyboard-interactive authentication.

type LocalPortForwardingCallback 

type LocalPortForwardingCallback func(ctx Context, destinationHost string, destinationPort uint32) bool

LocalPortForwardingCallback is a hook for allowing port forwarding

type MaxStartupsConfig 

type MaxStartupsConfig struct {
	Start int // number of unauthenticated connections before random early drop begins
	Rate  int // initial drop probability in percent, clamped to 0..100
	Full  int // hard limit for unauthenticated connections; nonpositive disables the limit
}

MaxStartupsConfig limits concurrent unauthenticated connections using the OpenSSH start:rate:full random early-drop model.

type MessageAuthentication 

type MessageAuthentication uint8
const (
	MessageAuthenticationHmacSha1 MessageAuthentication = iota
	MessageAuthenticationHmacSha1B96
	MessageAuthenticationHmacSha2B256
	MessageAuthenticationHmacSha2B512
	MessageAuthenticationHmacSha2B256Etm
	MessageAuthenticationHmacSha2B512Etm
)

func (MessageAuthentication) IsEqualTo 

func (ma MessageAuthentication) IsEqualTo(other any) bool

func (MessageAuthentication) IsZero 

func (ma MessageAuthentication) IsZero() bool

func (MessageAuthentication) MarshalText 

func (ma MessageAuthentication) MarshalText() (text []byte, err error)

func (*MessageAuthentication) Set 

func (ma *MessageAuthentication) Set(text string) error

func (MessageAuthentication) String 

func (ma MessageAuthentication) String() string

func (*MessageAuthentication) UnmarshalText 

func (ma *MessageAuthentication) UnmarshalText(text []byte) error

func (MessageAuthentication) Validate 

func (ma MessageAuthentication) Validate() error

type MessageAuthentications 

type MessageAuthentications []MessageAuthentication

func (MessageAuthentications) Contains 

func (me MessageAuthentications) Contains(v MessageAuthentication) bool

func (MessageAuthentications) IsCumulative 

func (me MessageAuthentications) IsCumulative() bool

func (MessageAuthentications) IsEmpty 

func (me MessageAuthentications) IsEmpty() bool

func (MessageAuthentications) IsEqualTo 

func (me MessageAuthentications) IsEqualTo(other any) bool

func (MessageAuthentications) IsZero 

func (me MessageAuthentications) IsZero() bool

func (MessageAuthentications) MarshalText 

func (me MessageAuthentications) MarshalText() (text []byte, err error)

func (MessageAuthentications) MarshalTexts 

func (me MessageAuthentications) MarshalTexts() (texts [][]byte, err error)

func (*MessageAuthentications) Set 

func (me *MessageAuthentications) Set(text string) error

func (MessageAuthentications) String 

func (me MessageAuthentications) String() string

func (*MessageAuthentications) UnmarshalText 

func (me *MessageAuthentications) UnmarshalText(text []byte) error

func (MessageAuthentications) Validate 

func (me MessageAuthentications) Validate() error

type Option 

type Option func(*Server) error

Option is a functional option handler for Server.

func HostKeyFile 

func HostKeyFile(filepath string) Option

HostKeyFile returns a functional option that adds HostSigners to the server from a PEM file at filepath.

Example 
package main

import (
	"log"

	"github.com/engity-com/ssh-server-go"
)

func main() {
	log.Fatal(ssh.ListenAndServe(":2222", nil, ssh.HostKeyFile("/path/to/host/key")))
}

func HostKeyPEM 

func HostKeyPEM(bytes []byte) Option

HostKeyPEM returns a functional option that adds HostSigners to the server from a PEM file as bytes.

func KeyboardInteractiveAuth 

func KeyboardInteractiveAuth(fn KeyboardInteractiveHandler) Option

func NoPty 

func NoPty() Option

NoPty returns a functional option that sets PtyCallback to return false, denying PTY requests.

Example 
package main

import (
	"log"

	"github.com/engity-com/ssh-server-go"
)

func main() {
	log.Fatal(ssh.ListenAndServe(":2222", nil, ssh.NoPty()))
}

func PasswordAuth 

func PasswordAuth(fn PasswordHandler) Option

PasswordAuth returns a functional option that sets PasswordHandler on the server.

Example 
package main

import (
	"log"

	"github.com/engity-com/ssh-server-go"
)

func main() {
	log.Fatal(ssh.ListenAndServe(":2222", nil,
		ssh.PasswordAuth(func(ctx ssh.Context, pass string) bool {
			return pass == "secret"
		}),
	))
}

func PublicKeyAuth 

func PublicKeyAuth(fn PublicKeyHandler) Option

PublicKeyAuth returns a functional option that sets PublicKeyHandler on the server.

Example 
package main

import (
	"log"
	"os"

	"github.com/engity-com/ssh-server-go"
)

func main() {
	log.Fatal(ssh.ListenAndServe(":2222", nil,
		ssh.PublicKeyAuth(func(ctx ssh.Context, key ssh.PublicKey) bool {
			data, _ := os.ReadFile("/path/to/allowed/key.pub")
			allowed, _, _, _, _ := ssh.ParseAuthorizedKey(data)
			return ssh.KeysEqual(key, allowed)
		}),
	))
}

func WrapConn 

func WrapConn(fn ConnCallback) Option

WrapConn returns a functional option that sets ConnCallback on the server.

type PasswordHandler 

type PasswordHandler func(ctx Context, password string) bool

PasswordHandler is a callback for performing password authentication.

type Permissions 

type Permissions struct {
	*gossh.Permissions
}

The Permissions type holds fine-grained permissions that are specific to a user or a specific authentication method for a user. Permissions, except for "source-address", must be enforced in the server application layer, after successful authentication.

type Pty 

type Pty struct {
	Term   string
	Window Window
}

Pty represents a PTY request and configuration.

type PtyCallback 

type PtyCallback func(ctx Context, pty Pty) bool

PtyCallback is a hook for allowing PTY sessions.

type PublicKey 

type PublicKey interface {
	gossh.PublicKey
}

PublicKey is an abstraction of different types of public keys.

func ParseAuthorizedKey 

func ParseAuthorizedKey(in []byte) (out PublicKey, comment string, options []string, rest []byte, err error)

ParseAuthorizedKey parses a public key from an authorized_keys file used in OpenSSH according to the sshd(8) manual page.

func ParsePublicKey 

func ParsePublicKey(in []byte) (out PublicKey, err error)

ParsePublicKey parses an SSH public key formatted for use in the SSH wire protocol according to RFC 4253, section 6.6.

type PublicKeyHandler 

type PublicKeyHandler func(ctx Context, key PublicKey) bool

PublicKeyHandler is a callback for performing public key authentication.

type RequestHandler 

type RequestHandler func(ctx Context, srv *Server, req *gossh.Request) (ok bool, payload []byte)

type ReversePortForwardingCallback 

type ReversePortForwardingCallback func(ctx Context, bindHost string, bindPort uint32) bool

ReversePortForwardingCallback is a hook for allowing reverse port forwarding

type Server 

type Server struct {
	Logger log.Logger

	Addr                   string                 // TCP address to listen on, ":22" if empty
	Handler                Handler                // handler to invoke, ssh.DefaultHandler if nil
	HostSigners            []Signer               // private keys for the host key, must have at least one
	RequireHostSigners     bool                   // reject startup without an explicitly configured host signer
	RequireClientAuth      bool                   // reject connections without an effective, non-anonymous client authentication method
	Version                string                 // server version to be sent before the initial handshake
	Banner                 string                 // server banner
	Ciphers                Ciphers                // allowed ciphers, DefaultCiphers if empty
	KeyExchanges           KeyExchanges           // allowed key exchanges, DefaultKeyExchanges if empty
	MessageAuthentications MessageAuthentications // allowed MACs, DefaultMessageAuthentications if empty

	BannerHandler                 BannerHandler                 // server banner handler, overrides Banner
	KeyboardInteractiveHandler    KeyboardInteractiveHandler    // keyboard-interactive authentication handler
	PasswordHandler               PasswordHandler               // password authentication handler
	PublicKeyHandler              PublicKeyHandler              // public key authentication handler
	PtyCallback                   PtyCallback                   // callback for allowing PTY sessions, allows all if nil
	ConnCallback                  ConnCallback                  // optional callback for wrapping net.Conn before handling
	LocalPortForwardingCallback   LocalPortForwardingCallback   // callback for allowing local port forwarding, denies all if nil
	ReversePortForwardingCallback ReversePortForwardingCallback // callback for allowing reverse port forwarding, denies all if nil
	ServerConfigCallback          ServerConfigCallback          // callback for detailed SSH options; same-method auth conflicts are rejected
	SessionRequestCallback        SessionRequestCallback        // callback for allowing or denying SSH sessions
	AgentForwardingCallback       AgentForwardingCallback       // callback for allowing agent forwarding, denies all if nil

	ConnectionFailedCallback ConnectionFailedCallback // callback to report connection failures

	// Timeout fields use their Default* value when nil. A configured duration
	// less than or equal to zero disables that timeout.
	HandshakeTimeout *time.Duration // timeout until successful authentication, default 2 minutes
	IdleTimeout      *time.Duration // timeout when no activity, disabled by default
	MaxTimeout       *time.Duration // absolute connection timeout, disabled by default

	// Limit fields use their Default* value when nil. A configured value less
	// than or equal to zero disables that limit, meaning no limit is enforced.
	// MaxStartups is disabled when Full is less than or equal to zero.
	MaxStartups                     *MaxStartupsConfig
	MaxSessionsPerConnection        *int
	MaxChannelsPerConnection        *int
	MaxReverseForwardsPerConnection *int
	MaxConnections                  *int // authenticated connections across the server
	MaxChannels                     *int // active channels across all connections

	// ChannelHandlers allow overriding the built-in session handlers or provide
	// extensions to the protocol, such as tcpip forwarding. By default, only the
	// "session" handler is enabled.
	ChannelHandlers map[string]ChannelHandler

	// RequestHandlers allow overriding the server-level request handlers or
	// provide extensions to the protocol, such as tcpip forwarding. By default,
	// no handlers are enabled.
	RequestHandlers map[string]RequestHandler

	// SubsystemHandlers are handlers which are similar to the usual SSH command
	// handlers, but handle named subsystems.
	SubsystemHandlers map[string]SubsystemHandler
	// contains filtered or unexported fields
}

Server defines parameters for running an SSH server. The zero value for Server is a valid configuration. When both PasswordHandler and PublicKeyHandler are nil, no client authentication is performed. Public fields and pointed-to configuration values must not be mutated while the server is running; use synchronized methods for supported runtime updates.

func (*Server) AddHostKey 

func (srv *Server) AddHostKey(key Signer)

AddHostKey adds a private key as a host key. If an existing host key exists with the same algorithm, it is overwritten. Each server config must have at least one host key.

func (*Server) Close 

func (srv *Server) Close() error

Close immediately closes all active listeners and all active connections.

Close returns any error returned from closing the Server's underlying Listener(s).

func (*Server) Handle 

func (srv *Server) Handle(fn Handler)

Handle sets the Handler for the server.

func (*Server) HandleConn 

func (srv *Server) HandleConn(newConn net.Conn)

func (*Server) ListenAndServe 

func (srv *Server) ListenAndServe() error

ListenAndServe listens on the TCP network address srv.Addr and then calls Serve to handle incoming connections. If srv.Addr is blank, ":22" is used. ListenAndServe always returns a non-nil error.

func (*Server) Serve 

func (srv *Server) Serve(l net.Listener) error

Serve accepts incoming connections on the Listener l, creating a new connection goroutine for each. The connection goroutines read requests and then calls srv.Handler to handle sessions.

Serve always returns a non-nil error.

func (*Server) SetOption 

func (srv *Server) SetOption(option Option) error

SetOption runs a functional option against the server.

func (*Server) Shutdown 

func (srv *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server without interrupting any active connections. Shutdown works by first closing all open listeners, and then waiting indefinitely for connections to close. If the provided context expires before the shutdown is complete, then the context's error is returned.

type ServerConfigCallback 

type ServerConfigCallback func(ctx Context, config *gossh.ServerConfig)

ServerConfigCallback customizes a fresh per-connection server config. Public key multi-factor authentication must return PartialSuccessError from VerifiedPublicKeyCallback, after key ownership has been proven. Configuring a PasswordCallback, PublicKeyCallback, or KeyboardInteractiveCallback together with the corresponding high-level Server handler rejects that auth method with ErrServerAuthCallbackConflict rather than silently replacing either policy.

type Session 

type Session interface {
	gossh.Channel

	// User returns the username used when establishing the SSH connection.
	User() string

	// RemoteAddr returns the net.Addr of the client side of the connection.
	RemoteAddr() net.Addr

	// LocalAddr returns the net.Addr of the server side of the connection.
	LocalAddr() net.Addr

	// Environ returns a copy of strings representing the environment set by the
	// user for this session, in the form "key=value".
	Environ() []string

	// Exit sends an exit status and then closes the session.
	Exit(code int) error

	// Command returns a shell parsed slice of arguments that were provided by the
	// user. Shell parsing splits the command string according to POSIX shell rules,
	// which considers quoting not just whitespace.
	Command() []string

	// RawCommand returns the exact command that was provided by the user.
	RawCommand() string

	// Subsystem returns the subsystem requested by the user.
	Subsystem() string

	// PublicKey returns the PublicKey used to authenticate. If a public key was not
	// used it will return nil.
	PublicKey() PublicKey

	// Context returns the connection's context. The returned context is always
	// non-nil and holds the same data as the Context passed into auth
	// handlers and callbacks.
	//
	// The context is canceled when the client's connection closes or I/O
	// operation fails.
	Context() Context

	// Permissions returns a copy of the Permissions object that was available for
	// setup in the auth handlers via the Context. Its map containers are copied;
	// arbitrary values stored in ExtraData are not recursively cloned.
	Permissions() Permissions

	// Pty returns PTY information, a channel of window size changes, and a boolean
	// of whether a PTY was accepted for this session.
	Pty() (Pty, <-chan Window, bool)

	// Signals registers a channel to receive signals sent from the client. The
	// channel must handle signal sends promptly. Blocked sends are canceled when
	// the channel is unregistered, the session exits, or its context is canceled.
	// Registering nil will unregister the channel from signal sends. During the
	// time no channel is registered signals are buffered up to a reasonable amount.
	// If there are buffered signals when a channel is registered, they will be
	// sent in order on the channel immediately after registering. The receiver
	// must unregister the channel before closing it.
	Signals(c chan<- Signal)

	// Break registers a channel to receive notifications of break requests sent
	// from the client. The channel must handle break requests, or it will block
	// the request handling loop. Registering nil will unregister the channel.
	// During the time that no channel is registered, breaks are ignored.
	// The receiver must unregister the channel before closing it.
	Break(c chan<- bool)
}

Session provides access to information about an SSH session and methods to read and write to the SSH channel with an embedded Channel interface from crypto/ssh.

When Command() returns an empty slice, the user requested a shell. Otherwise the user is performing an exec with those command arguments.

type SessionRequestCallback 

type SessionRequestCallback func(sess Session, requestType string) bool

SessionRequestCallback is a callback for allowing or denying SSH sessions.

type Signal 

type Signal string
const (
	SIGABRT Signal = "ABRT"
	SIGALRM Signal = "ALRM"
	SIGFPE  Signal = "FPE"
	SIGHUP  Signal = "HUP"
	SIGILL  Signal = "ILL"
	SIGINT  Signal = "INT"
	SIGKILL Signal = "KILL"
	SIGPIPE Signal = "PIPE"
	SIGQUIT Signal = "QUIT"
	SIGSEGV Signal = "SEGV"
	SIGTERM Signal = "TERM"
	SIGUSR1 Signal = "USR1"
	SIGUSR2 Signal = "USR2"
)

POSIX signals as listed in RFC 4254 Section 6.10.

type Signer 

type Signer interface {
	gossh.Signer
}

A Signer can create signatures that verify against a public key.

type SubsystemHandler 

type SubsystemHandler func(s Session)

type Window 

type Window struct {
	Width  int
	Height int
}

Window represents the size of a PTY window.

Source Files

View all Source files

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.