datachannel

package
v0.0.0-...-96383a8 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2022 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrBufferFull = errors.New("buffer full")

Functions

func NewMessageBuffer 

func NewMessageBuffer(size int) *messageBuffer

Types

type ActionStatus 

type ActionStatus int

ActionStatus is use to communicate the result of an ActionType. 

const (
	Success     ActionStatus = 1
	Failed      ActionStatus = 2
	Unsupported ActionStatus = 3
)

type ActionType 

type ActionType string

ActionType is used in Handshake to determine action requested by the agent. 

const (
	KMSEncryption ActionType = "KMSEncryption"
	SessionType   ActionType = "SessionType"
)

type AgentMessage 

type AgentMessage struct {
	MessageType MessageType // this is a 32 byte space-padded string on the wire

	SequenceNumber int64
	Flags          AgentMessageFlag // REF: https://github.com/aws/amazon-ssm-agent/blob/master/agent/session/contracts/agentmessage.go

	PayloadType PayloadType // REF: https://github.com/aws/amazon-ssm-agent/blob/master/agent/session/contracts/model.go

	Payload []byte
	// contains filtered or unexported fields
}

AgentMessage is the structural representation of the binary format of an SSM agent message use for communication between local clients (like this), and remote agents installed on EC2 instances. This is the order the fields must appear as on the wire REF: https://github.com/aws/amazon-ssm-agent/blob/master/agent/session/contracts/agentmessage.go.

func NewAgentMessage 

func NewAgentMessage() *AgentMessage

NewAgentMessage creates an AgentMessage ready to load with payload.

func (*AgentMessage) MarshalBinary 

func (m *AgentMessage) MarshalBinary() ([]byte, error)

MarshalBinary converts the fields in the method receiver to the expected wire format used by the websocket protocol with the SSM messaging service. Satisfies the encoding.BinaryMarshaler interface.

func (*AgentMessage) String 

func (m *AgentMessage) String() string

func (*AgentMessage) UnmarshalBinary 

func (m *AgentMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary reads the wire format data and updates the fields in the method receiver. Satisfies the encoding.BinaryUnmarshaler interface.

func (*AgentMessage) ValidateMessage 

func (m *AgentMessage) ValidateMessage() error

ValidateMessage performs checks on the values of the AgentMessage to ensure they are sane.

type AgentMessageFlag 

type AgentMessageFlag uint64

AgentMessageFlag is the value set in the AgentMessage.Flags field to indicate where in the stream this message belongs. 

const (
	Data AgentMessageFlag = iota
	Syn  AgentMessageFlag = iota
	Fin  AgentMessageFlag = iota
	Ack  AgentMessageFlag = iota
)

type ChannelClosedPayload 

type ChannelClosedPayload struct {
	MessageType   string
	MessageID     string
	DestinationID string
	SessionID     string
	SchemaVersion int
	CreatedDate   string
	Output        string
}

ChannelClosedPayload is the payload in a ChannelClosed message send from the agent.

type DataChannel 

type DataChannel interface {
	Open(aws.Config, *ssm.StartSessionInput) error
	HandleMsg(data []byte) ([]byte, error)
	SetTerminalSize(rows, cols uint32) error
	TerminateSession() error
	DisconnectPort() error
	WriteMsg(*AgentMessage) (int, error)
	io.ReadWriteCloser
	io.ReaderFrom
	io.WriterTo
}

DataChannel is the interface definition for handling communication with the AWS SSM messaging service.

type HandshakeCompletePayload 

type HandshakeCompletePayload struct {
	HandshakeTimeToComplete time.Duration
	CustomerMessage         string
}

HandshakeCompletePayload is the message returned from the agent when the handshake negotiation is successful.

type HandshakeRequestPayload 

type HandshakeRequestPayload struct {
	AgentVersion           string
	RequestedClientActions []RequestedClientAction
}

HandshakeRequestPayload is the data format sent from the agent to initiate a session handshake.

type HandshakeResponsePayload 

type HandshakeResponsePayload struct {
	ClientVersion          string
	ProcessedClientActions []ProcessedClientAction
	Errors                 []string
}

HandshakeResponsePayload is the local client response to the offered handshake request. The ProcessedClientActions field should have an entry for each RequestedClientActions in the handshake request.

type MessageBuffer 

type MessageBuffer interface {
	Len() int
	Add(msg *AgentMessage) error
	Remove(seqNum int64)
	Get(seqNum int64) *AgentMessage
	Next() *AgentMessage
}

type MessageType 

type MessageType string

MessageType is the label used in the AgentMessage.MessageType field REF: https://github.com/aws/amazon-ssm-agent/blob/master/agent/session/contracts/model.go. 

const (
	InteractiveShell MessageType = "interactive_shell"
	TaskReply        MessageType = "agent_task_reply"
	TaskComplete     MessageType = "agent_task_complete"
	Acknowledge      MessageType = "acknowledge"
	AgentSession     MessageType = "agent_session_state"
	ChannelClosed    MessageType = "channel_closed"
	OutputStreamData MessageType = "output_stream_data"
	InputStreamData  MessageType = "input_stream_data"
	PausePublication MessageType = "pause_publication"
	StartPublication MessageType = "start_publication"
)

type PayloadType 

type PayloadType uint32

PayloadType is the value set in the AgentMessage.PayloadType field to indicate the data format of the Payload field. 

const (
	Undefined            PayloadType = iota
	Output               PayloadType = iota
	Error                PayloadType = iota
	Size                 PayloadType = iota
	Parameter            PayloadType = iota
	HandshakeRequest     PayloadType = iota
	HandshakeResponse    PayloadType = iota
	HandshakeComplete    PayloadType = iota
	EncChallengeRequest  PayloadType = iota
	EncChallengeResponse PayloadType = iota
	Flag                 PayloadType = iota
)

type PayloadTypeFlag 

type PayloadTypeFlag uint32

PayloadTypeFlag is the value set in the Payload of certain messages to indicate certain control operations. 

const (
	DisconnectToPort   PayloadTypeFlag = 1
	TerminateSession   PayloadTypeFlag = 2
	ConnectToPortError PayloadTypeFlag = 3
)

type ProcessedClientAction 

type ProcessedClientAction struct {
	ActionType   ActionType
	ActionStatus ActionStatus
	ActionResult json.RawMessage
	Error        string
}

ProcessedClientAction is the result of a particular client action to send back to the remote agent.

type RequestedClientAction 

type RequestedClientAction struct {
	ActionType       ActionType
	ActionParameters interface{}
}

RequestedClientAction is the type of actions requested as part of the handshake negotiation.

type SessionTypeRequest 

type SessionTypeRequest struct {
	SessionType string
	Properties  interface{}
}

SessionTypeRequest is part of the handshake process.

type SsmDataChannel 

type SsmDataChannel struct {
	// contains filtered or unexported fields
}

SsmDataChannel represents the data channel of the websocket connection used to communicate with the AWS SSM service. A new(SsmDataChannel) is ready for use, and should immediately call the Open() method.

func (*SsmDataChannel) Close 

func (c *SsmDataChannel) Close() error

Close shuts down the web socket connection with the AWS service. Type-specific actions (like sending TerminateSession for port forwarding should be handled before calling Close().

func (*SsmDataChannel) DisconnectPort 

func (c *SsmDataChannel) DisconnectPort() error

DisconnectPort sends the DisconnectToPort message to the AWS service to indicate that a non-muxing stream is shutting down and any connection used to communicate with the EC2 instance agent can be cleaned up. Unlike the TerminateSession action, the websocket connection is still capable of initiating a new port forwarding stream to the agent without needing to restart the program.

func (*SsmDataChannel) HandleMsg 

func (c *SsmDataChannel) HandleMsg(data []byte) ([]byte, error)

HandleMsg takes the unprocessed message bytes from the websocket connection (a la Read()), unmarshals the data and takes the appropriate action based on the message type. Messages which have an actionable payload (output payload types, and channel closed payloads) will have that data returned. Errors will be returned for unknown/ unhandled message or payload types. A ChannelClosed message type will return an io.EOF error to indicate that this SSM data channel is shutting down and should no longer be used.

func (*SsmDataChannel) Open 

func (c *SsmDataChannel) Open(cfg aws.Config, in *ssm.StartSessionInput) error

Open creates the web socket connection with the AWS service and opens the data channel.

func (*SsmDataChannel) Read 

func (c *SsmDataChannel) Read(data []byte) (int, error)

Read will get a single message from the websocket connection. The unprocessed message is copied to the requested []byte (which should be sized to handle at least 1536 bytes).

func (*SsmDataChannel) ReadFrom 

func (c *SsmDataChannel) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom uses the data channel as an io.Copy write destination, reading data from the provided reader.

func (*SsmDataChannel) SetTerminalSize 

func (c *SsmDataChannel) SetTerminalSize(rows, cols uint32) error

SetTerminalSize sends a message to the SSM service which indicates the size to use for the remote terminal when using a shell session client.

func (*SsmDataChannel) StartSessionFromDataChannelURL 

func (c *SsmDataChannel) StartSessionFromDataChannelURL(url string, token string) error

func (*SsmDataChannel) TerminateSession 

func (c *SsmDataChannel) TerminateSession() error

TerminateSession sends the TerminateSession message to the AWS service to indicate that the port forwarding session is ending, so it can clean up any connections used to communicate with the EC2 instance agent.

func (*SsmDataChannel) WaitForHandshakeComplete 

func (c *SsmDataChannel) WaitForHandshakeComplete() error

WaitForHandshakeComplete blocks further processing until the required SSM handshake sequence used for port-based clients (including ssh) completes.

func (*SsmDataChannel) Write 

func (c *SsmDataChannel) Write(payload []byte) (int, error)

Write sends an input stream data message type with the provided payload bytes as the message payload.

func (*SsmDataChannel) WriteMsg 

func (c *SsmDataChannel) WriteMsg(msg *AgentMessage) (int, error)

WriteMsg is the underlying method which marshals AgentMessage types and sends them to the AWS service. This is provided as a convenience so that messages types not already handled can be sent. If the message SequenceNumber field is less than 0, it will be automatically incremented using the internal counter.

func (*SsmDataChannel) WriteTo 

func (c *SsmDataChannel) WriteTo(w io.Writer) (n int64, err error)

WriteTo uses the data channel as an io.Copy read source, writing output to the provided writer.

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.