x11

Documentation

Overview

Copyright 2022 Gravitational, Inc

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package X11 contains contains the ssh client/server helper functions for performing X11 forwarding.

Index

• Constants
• func CheckXAuthPath() error
• func Forward(ctx context.Context, client, server XServerConn) error
• func OpenNewXServerListener(displayOffset int, maxDisplay int, screen uint32) (XServerListener, Display, error)
• func ReadAndRewriteXAuthPacket(xreq io.Reader, spoofedXAuthEntry, realXAuthEntry *XAuthEntry) ([]byte, error)
• func RequestForwarding(sess *ssh.Session, xauthEntry *XAuthEntry) error
• func ServeChannelRequests(ctx context.Context, clt *ssh.Client, handler x11ChannelHandler) error
• type ChannelRequestPayload
• type Display
  • func GetXDisplay() (Display, error)
  • func ParseDisplay(displayString string) (Display, error)
  • func (d *Display) Dial() (XServerConn, error)
  • func (d *Display) Listen() (XServerListener, error)
  • func (d *Display) String() string
• type ForwardRequestPayload
• type ServerConfig
• type XAuthCommand
  • func NewXAuthCommand(ctx context.Context, xauthFile string) *XAuthCommand
  • func (x *XAuthCommand) AddEntry(entry XAuthEntry) error
  • func (x *XAuthCommand) GenerateUntrustedCookie(display Display, timeout time.Duration) error
  • func (x *XAuthCommand) ReadEntry(display Display) (*XAuthEntry, error)
  • func (x *XAuthCommand) RemoveEntries(display Display) error
• type XAuthEntry
  • func NewFakeXAuthEntry(display Display) (*XAuthEntry, error)
  • func (e *XAuthEntry) SpoofXAuthEntry() (*XAuthEntry, error)
• type XServerConn
• type XServerListener

Constants

const (
	// DefaultDisplayOffset is the default display offset when
	// searching for an open XServer unix socket.
	DefaultDisplayOffset = 10
	// DefaultMaxDisplays is the default maximum number of displays
	// supported when searching for an open XServer unix socket.
	DefaultMaxDisplays = 1000
	// MaxDisplay is the theoretical max display value which
	// X Clients and serverwill be able to parse into a unix socket.
	MaxDisplayNumber = math.MaxInt32
	// DisplayEnv is an environment variable used to determine what
	// local display should be connected to during X11 forwarding.
	DisplayEnv = "DISPLAY"
)

Functions

func CheckXAuthPath

func CheckXAuthPath() error

CheckXAuthPath checks if xauth is runnable in the current environment.

func Forward

func Forward(ctx context.Context, client, server XServerConn) error

forwardIO forwards io between two XServer connections until one of the connections is closed. If the ctx is closed early, the function will return, but forwarding will continue until the XServer connnections are closed.

func OpenNewXServerListener

func OpenNewXServerListener(displayOffset int, maxDisplay int, screen uint32) (XServerListener, Display, error)

OpenNewXServerListener opens an XServerListener for the first available Display. displayOffset will determine what display number to start from when searching for an open display unix socket, and maxDisplays in optional limit for the number of display sockets which can be opened at once.

func ReadAndRewriteXAuthPacket

func ReadAndRewriteXAuthPacket(xreq io.Reader, spoofedXAuthEntry, realXAuthEntry *XAuthEntry) ([]byte, error)

ReadAndRewriteXAuthPacket reads the initial xauth packet from an XServer request. The xauth packet has 2 parts:

1. fixed size buffer (12 bytes) - holds byteOrder bit, and the sizes of the protocol string and auth data
2. variable size xauth packet - holds xauth protocol and data used to connect to the remote XServer.

Then it compares the received auth packet with the auth proto and fake cookie sent to the server with the original "x11-req". If the data matches, the auth packet is returned with the fake cookie replaced by the real cookie to provide access to the client's X display.

func RequestForwarding

func RequestForwarding(sess *ssh.Session, xauthEntry *XAuthEntry) error

RequestForwarding sends an "x11-req" to the server to set up X11 forwarding for the given session. authProto and authCookie are required to set up authentication with the Server. screenNumber is used by the server to determine which screen should be connected to for X11 forwarding. singleConnection is an optional argument to request X11 forwarding for a single connection.

func ServeChannelRequests

func ServeChannelRequests(ctx context.Context, clt *ssh.Client, handler x11ChannelHandler) error

ServeChannelRequests opens an X11 channel handler and starts a goroutine to serve any channels received with the handler provided.

Types

type ChannelRequestPayload

type ChannelRequestPayload struct {
	// OriginatorAddress is the address of the server requesting an X11 channel
	OriginatorAddress string
	// OriginatorPort is the port of the server requesting an X11 channel
	OriginatorPort uint32
}

ChannelRequestPayload according to http://www.ietf.org/rfc/rfc4254.txt

type Display

type Display struct {
	// HostName is the the display's hostname. For tcp display sockets, this will be
	// an ip address. For unix display sockets, this will be empty or "unix".
	HostName string `json:"hostname"`
	// DisplayNumber is a number representing an x display.
	DisplayNumber int `json:"display_number"`
	// ScreenNumber is a specific screen number of an x display.
	ScreenNumber int `json:"screen_number"`
}

Display is an XServer display.

func GetXDisplay

func GetXDisplay() (Display, error)

GetXDisplay retrieves and validates the local XServer display set in the environment variable $DISPLAY.

func ParseDisplay

func ParseDisplay(displayString string) (Display, error)

ParseDisplay parses the given display value and returns the host, display number, and screen number, or a parsing error. display must be in one of the following formats - hostname:d[.s], unix:d[.s], :d[.s], ::d[.s].

func (*Display) Dial

func (d *Display) Dial() (XServerConn, error)

Dial opens an XServer connection to the display

func (*Display) Listen

func (d *Display) Listen() (XServerListener, error)

Listen opens an XServer listener. It will attempt to listen on the display address for both tcp and unix and return an aggregate error, unless one results in an addr in use error.

func (*Display) String

func (d *Display) String() string

String returns the string representation of the display.

type ForwardRequestPayload

type ForwardRequestPayload struct {
	// SingleConnection determines whether any connections will be forwarded
	// after the first connection, or after the session is closed. In OpenSSH
	// and Teleport SSH clients, SingleConnection is always set to false.
	SingleConnection bool
	// AuthProtocol is the name of the X11 authentication protocol being used.
	AuthProtocol string
	// AuthCookie is a hexadecimal encoded X11 authentication cookie. This should
	// be a fake, random cookie, which will be checked and replaced by the real
	// cookie once the connection request is received.
	AuthCookie string
	// ScreenNumber determines which screen will be.
	ScreenNumber uint32
}

ForwardRequestPayload according to http://www.ietf.org/rfc/rfc4254.txt

type ServerConfig

type ServerConfig struct {
	// Enabled controls whether X11 forwarding requests can be granted by the server.
	Enabled bool
	// DisplayOffset tells the server what X11 display number to start from when
	// searching for an open X11 unix socket for XServer proxies.
	DisplayOffset int
	// MaxDisplay tells the server what X11 display number to stop at when
	// searching for an open X11 unix socket for XServer proxies.
	MaxDisplay int
}

ServerConfig is a server configuration for X11 forwarding

type XAuthCommand

type XAuthCommand struct {
	*exec.Cmd
}

XAuthCommand is a os/exec.Cmd wrapper for running xauth commands.

func NewXAuthCommand

func NewXAuthCommand(ctx context.Context, xauthFile string) *XAuthCommand

NewXAuthCommand reate a new "xauth" command. xauthFile can be optionally provided to run the xauth command against a specific xauth file.

func (*XAuthCommand) AddEntry

func (x *XAuthCommand) AddEntry(entry XAuthEntry) error

AddEntry runs "xauth add" to add the given xauth entry.

func (*XAuthCommand) GenerateUntrustedCookie

func (x *XAuthCommand) GenerateUntrustedCookie(display Display, timeout time.Duration) error

GenerateUntrustedCookie runs "xauth generate untrusted" to create a new xauth entry with an untrusted MIT-MAGIC-COOKIE-1. A timeout can optionally be set for the xauth entry, after which the XServer will ignore this cookie.

func (*XAuthCommand) ReadEntry

func (x *XAuthCommand) ReadEntry(display Display) (*XAuthEntry, error)

ReadEntry runs "xauth list" to read the first xauth entry for the given display.

func (*XAuthCommand) RemoveEntries

func (x *XAuthCommand) RemoveEntries(display Display) error

RemoveEntries runs "xauth remove" to remove any xauth entries for the given display.

type XAuthEntry

type XAuthEntry struct {
	// Display is an X display in the format - [hostname]:[display_number].[screen_number]
	Display Display `json:"display"`
	// Proto is an XAuthority protocol, generally "MIT-MAGIC-COOKIE-1"
	Proto string `json:"proto"`
	// Cookie is a hex encoded XAuthority cookie
	Cookie string `json:"cookie"`
}

XAuthEntry is an entry in an XAuthority database which can be used to authenticate and authorize requests from an XServer to the associated X display.

func NewFakeXAuthEntry

func NewFakeXAuthEntry(display Display) (*XAuthEntry, error)

NewFakeXAuthEntry creates a fake xauth entry with a randomly generated MIT-MAGIC-COOKIE-1.

func (*XAuthEntry) SpoofXAuthEntry

func (e *XAuthEntry) SpoofXAuthEntry() (*XAuthEntry, error)

SpoofXAuthEntry creates a new xauth entry with a random cookie with the same length as the original entry's cookie. This is used to create a believable spoof of the client's xauth data to send to the server.

type XServerConn

type XServerConn interface {
	io.ReadWriteCloser
	// must implement CloseWrite to prevent read loop from halting pre-maturely
	CloseWrite() error
}

XServerConn is a connection to an XServer through a direct or forwarded connection. It can either be a tcp conn, unix conn, or an X11 channel.

type XServerListener

type XServerListener interface {
	// Accept waits for and returns the next connection to the listener.
	Accept() (XServerConn, error)

	// Close closes the listener.
	// Any blocked Accept operations will be unblocked and return errors.
	Close() error

	// Addr returns the listener's network address.
	Addr() net.Addr
}

XServerListener is a proxy XServer listener used to forward XServer requests. to an actual XServer. The underlying listener may be a unix or tcp listener.