secureio

type DebugOutputEntry struct {
	// Format has the same meaning as the first argument to `fmt.Printf`
	Format string

	// Args has the same meaning as the rest arguments (except the first one)
	// to `fmt.Printf`
	Args []interface{}
}

type ErrAlreadyClosed struct{}

type ErrAnswersModeMismatch struct {
	AnswersModeLocal  KeyExchangeAnswersMode
	AnswersModeRemote KeyExchangeAnswersMode
}

type ErrCanceled struct{}

type ErrCannotDecrypt struct{}

type ErrCannotLoadKeys struct {
	OriginalError error
}

type ErrCannotPauseOrUnpauseFromThisState struct{}

type ErrCannotSetReadDeadline struct {
	Backend io.ReadWriter
}

type ErrInvalidChecksum struct {
	ExpectedChecksum [poly1305.TagSize]byte
	RealChecksum     [poly1305.TagSize]byte
}

type ErrInvalidSignature struct{}

type ErrKeyExchangeTimeout struct{}

type ErrPartialWrite struct{}

type ErrPayloadTooBig struct {
	MaxSize  uint
	RealSize uint
}

type ErrTooShort struct {
	ExpectedLength uint
	RealLength     uint
}

type ErrWrongKeyLength struct {
	ExpectedLength uint
	RealLength     uint
}

type EventHandler interface {
	// OnConnect is called right after the first successful key exchange
	// with the remote side.
	OnConnect(*Session)

	// Error is called when there's an error occurred which is nowhere
	// else to return to.
	Error(*Session, error) bool
}

type Handler interface {
	// Handler is the function called each time to Handler an incoming message
	Handle([]byte) error
}

type Identity struct {
	Keys Keys
	// contains filtered or unexported fields
}

type KeyExchangeAnswersMode uint8

type KeyExchangerOptions struct {
	// KeyUpdateInterval defines delay between generating a new cipher key.
	//
	// Generating a key is an expensive operation. Moreover
	// secureio remembers only the current key and the previous one. So
	// if you generate keys with interval less than required for stable
	// round-trip between peers, then the session will be very unstable.
	//
	// If a zero-value then DefaultKeyExchangeInterval is used.
	KeyUpdateInterval time.Duration

	// RetryInterval defines the maximal delay between sending a key exchange
	// packet and success key exchange before resending the key exchange
	// packet.
	//
	// If a zero-value then DefaultKeyExchangeRetryInterval is used instead.
	RetryInterval time.Duration

	// Timeout defines how long it can wait after sending a request
	// to exchange keys and before the successful key exchange. If
	// it waits more than the timeout then an error is returned.
	//
	// If a zero-value then DefaultKeyExchangeTimeout is used.
	Timeout time.Duration

	// PSK is a Pre-Shared Key. If it is set then it is used as
	// an additional source for ephemeral key ("cipher key") generation.
	// So if it is set then to initiate a working session it's required to
	// satisfy both conditions: valid (and expected) identities and the same PSK.
	PSK []byte

	// AnswersMode set the behavior of key-exchange message acknowledgments.
	//
	// When the local side receives a packet from the remote side it _may_
	// send a key exchange packet even if it was already sent before. This
	// packet is called "answer". An answer packet is marked with a special
	// flag to prevent answers on answers (to prevent loops).
	//
	// If two parties has different AnswersModes then an error will be
	// reported.
	//
	// See KeyExchangeAnswersMode values.
	AnswersMode KeyExchangeAnswersMode
	// contains filtered or unexported fields
}

type Keys struct {
	Public  ed25519.PublicKey
	Private ed25519.PrivateKey
}

type MessageType uint32

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

type NegotiatorEnable uint8

type NegotiatorOptions struct {
	// Enable controls if negotiations should be enabled.
	Enable NegotiatorEnable

	// ReadTimeout defines how long the negotiator is allowed to wait
	// without any incoming message before consider the connection
	// unreliable and return an error.
	//
	// The default value is DefaultNegotiatorReadTimeout
	//
	// Use a negative value to disable this behavior.
	ReadTimeout time.Duration

	// TotalTimeout defines how long the negotiator is allowed to wait
	// in total before give up and just try to use the best-yet-found
	// settings. And if the timeout was reached and there was no
	// pong-responses at all (there is no of any found settings) then
	// return an error
	//
	// The default value is DefaultNegotiatorTotalTimeout
	//
	// Use a negative value to disable this behavior.
	TotalTimeout time.Duration

	// MaxIterations define how many iterations of probing for packet
	// size is permitted. The more this value the more time will
	// be required to negotiate, but the value of the optimal packet
	// size will be more precise
	//
	// The default value is DefaultNegotiatorMaxIterations
	MaxIterations uint32
}

type SendInfo struct {
	// Err contains the resulting error
	Err error

	// N contains the number of bytes were written to send the merged
	// messaged through the backend.
	N int
	// contains filtered or unexported fields
}

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

type SessionID struct {
	CreatedAt uint64
	Random    uint64
}

type SessionOptions struct {
	// EnableDebug enables the DEBUG messages to be passed through
	// `(*Session).DebugOutputChan()`. It causes performance penalty.
	//
	// This option will work only if the application was built
	// with tag "secureiodebug" (and/or "testlogging").
	EnableDebug bool

	// EnableInfo enables the INFO messages to be passed through
	// `(*Session).InfoOutputChan()`. It causes performance penalty.
	EnableInfo bool

	// SendDelay is the aggregation delay.
	// It is used to merge small messages into one while sending it
	// through the backend to reduce overheads.
	//
	// If it is set to a nil-value then DefaultSendDelay is used instead.
	//
	// If it is set to zero (`&[]time.Duration{0}[0]`) then no delay
	// will be performed and all messages will be sent right away.
	//
	// If you disable this option then you probably also would like
	// to disable the negotiator,
	// see `SessionOptions.NegotiatorOptions.Disable`.
	SendDelay *time.Duration

	// DetachOnMessagesCount is an amount of incoming messages after which
	// a Session will detach from the backend and close itself.
	// To use this feature the backend Reader should have
	// method SetReadDeadline or SetDeadline.
	//
	// If it is set to a zero-value then "never".
	DetachOnMessagesCount uint64

	// DetachOnSequentialDecryptFailsCount is an amount of sequential incoming
	// messages failed to be decrypted after which a Session will detach from
	// the backend and close itself.
	// To use this feature the backend Reader should have
	// method SetReadDeadline or SetDeadline.
	//
	// If it is set to a zero-value then "never".
	DetachOnSequentialDecryptFailsCount uint64

	// ErrorOnSequentialDecryptFailsCount is an amount of sequential incoming
	// messages failed to be decrypted after which a Session will report
	// and error.
	//
	// If it is set to a nil-value then
	// DefaultErrorOnSequentialDecryptFailsCount will be used instead.
	ErrorOnSequentialDecryptFailsCount *uint64

	// KeyExchangerOptions is the structure with options related only
	// to the key exchanging.
	//
	// See the description of fields of KeyExchangerOptions.
	KeyExchangerOptions KeyExchangerOptions

	// PayloadSizeLimit defines the maximal size of a messages passed
	// through the Session. The more this value is the more memory is consumed
	// and the larger payloads will be send through the underlying io.Writer.
	//
	// A whole packet (to be sent through the underlying io.Writer) will
	// be bigger (on size messagesContainerHeadersSize + messageHeadersSize).
	//
	// See also NegotiatorOptions.Disable.
	PayloadSizeLimit uint32

	// NegotiatorOptions is the structure with options related only
	// to the negotiation process. The negotiation process follows
	// after key-exchanging and called upon to find optimal settings
	// to communicate through given underlying io.ReadWriteCloser.
	NegotiatorOptions NegotiatorOptions

	// PacketIDStorageSize defines how many PacketID values could be
	// remembered to be able to check if packet was duplicated or
	// reordered.
	//
	// By default we try to eliminate possibility of duplicated packets
	// because it could be used by malefactors. So we remember
	// few (PacketIDStorageSize) highest values of received PacketID
	// values and:
	// * Drop if a packet has an ID we already remembered
	// * Drop if a packet has an ID lower than any remembered.
	//
	// If it's required to disable the mechanism of dropping packets
	// with invalid PacketID then set a negative value.
	//
	// Value "1" is a special value which enables the behaviour
	// where PacketID is allowed to grow only (no misordering is allowed).
	//
	// The default value (which is forced on a zero value) is
	// DefaultPacketIDStorageSize.
	PacketIDStorageSize int

	// EnableFragmentation allows to fragment messages. By default
	// a message larger than (*Session).GetEstablishedPayloadSize() are not
	// fragmented (and defragmented on the remote side), an error is returned
	// instead.
	EnableFragmentation bool

	// MaxChainIDDiff is the allowed maximum difference between the latest
	// chain ID and the oldest chain ID (stored in memory). The more this
	// value is the more memory will be consumed, but more-out-of-order
	// fragments still will be recognized.
	//
	// Each large message (which is larger than
	// (*Session).GetEstablishedPayloadSize()) is fragmented into smaller
	// packets (see also EnableFragmentation). These bunch of packets is
	// called "chain". And if there's a lot of chains and their packets are
	// received in a wrong order (for example due to properties of UDP) then
	// a lot of fragments are stored in memory. Moreover some packets
	// might be lost and we will store some fragments in memory forever.
	// And to do not consumer infinite amount of memory we limit how old
	// chains is permitted to keep.
	MaxChainIDDiff uint64

	// MaxFragmentedMessageSize is the maximum allows size of a message
	// (after assembling from all its fragments). The more this value is
	// the larder messages are allowed, but more memory is consumed.
	MaxFragmentedMessageSize uint64
}

type SessionState uint64