otr

Documentation

Overview

Package otr implements the Off The Record protocol as specified in http://www.cypherpunks.ca/otr/Protocol-v2-3.1.0.html

The version of OTR implemented by this package has been deprecated (https://bugs.otr.im/lib/libotr/issues/140). An implementation of OTRv3 is available at https://github.com/coyim/otr3.

Index

• Variables
• type Conversation
  • func (c *Conversation) Authenticate(question string, mutualSecret []byte) (toSend [][]byte, err error)
  • func (c *Conversation) End() (toSend [][]byte)
  • func (c *Conversation) IsEncrypted() bool
  • func (c *Conversation) Receive(in []byte) (out []byte, encrypted bool, change SecurityChange, toSend [][]byte, err error)
  • func (c *Conversation) SMPQuestion() string
  • func (c *Conversation) Send(msg []byte) ([][]byte, error)
• type PrivateKey
  • func (priv *PrivateKey) Generate(rand io.Reader)
  • func (priv *PrivateKey) Import(in []byte) bool
  • func (priv *PrivateKey) Parse(in []byte) ([]byte, bool)
  • func (priv *PrivateKey) Serialize(in []byte) []byte
  • func (priv *PrivateKey) Sign(rand io.Reader, hashed []byte) []byte
• type PublicKey
  • func (pk *PublicKey) Fingerprint() []byte
  • func (pk *PublicKey) Parse(in []byte) ([]byte, bool)
  • func (pk *PublicKey) Serialize(in []byte) []byte
  • func (pk *PublicKey) Verify(hashed, sig []byte) ([]byte, bool)
• type SecurityChange

Variables

var ErrorPrefix = "?OTR Error:"

ErrorPrefix can be used to make an OTR error by appending an error message to it.

var QueryMessage = "?OTRv2?"

QueryMessage can be sent to a peer to start an OTR conversation.

Types

type Conversation

type Conversation struct {
	// PrivateKey contains the private key to use to sign key exchanges.
	PrivateKey *PrivateKey

	// Rand can be set to override the entropy source. Otherwise,
	// crypto/rand will be used.
	Rand io.Reader
	// If FragmentSize is set, all messages produced by Receive and Send
	// will be fragmented into messages of, at most, this number of bytes.
	FragmentSize int

	// Once Receive has returned NewKeys once, the following fields are
	// valid.
	SSID           [8]byte
	TheirPublicKey PublicKey
	// contains filtered or unexported fields
}

Conversation represents a relation with a peer. The zero value is a valid Conversation, although PrivateKey must be set.

When communicating with a peer, all inbound messages should be passed to Conversation.Receive and all outbound messages to Conversation.Send. The Conversation will take care of maintaining the encryption state and negotiating encryption as needed.

func (*Conversation) Authenticate

func (c *Conversation) Authenticate(question string, mutualSecret []byte) (toSend [][]byte, err error)

Authenticate begins an authentication with the peer. Authentication involves an optional challenge message and a shared secret. The authentication proceeds until either Receive returns SMPComplete, SMPSecretNeeded (which indicates that a new authentication is happening and thus this one was aborted) or SMPFailed.

func (*Conversation) End

func (c *Conversation) End() (toSend [][]byte)

End ends a secure conversation by generating a termination message for the peer and switches to unencrypted communication.

func (*Conversation) IsEncrypted

func (c *Conversation) IsEncrypted() bool

IsEncrypted returns true if a message passed to Send would be encrypted before transmission. This result remains valid until the next call to Receive or End, which may change the state of the Conversation.

func (*Conversation) Receive

func (c *Conversation) Receive(in []byte) (out []byte, encrypted bool, change SecurityChange, toSend [][]byte, err error)

Receive handles a message from a peer. It returns a human readable message, an indicator of whether that message was encrypted, a hint about the encryption state and zero or more messages to send back to the peer. These messages do not need to be passed to Send before transmission.

func (*Conversation) SMPQuestion

func (c *Conversation) SMPQuestion() string

SMPQuestion returns the human readable challenge question from the peer. It's only valid after Receive has returned SMPSecretNeeded.

func (*Conversation) Send

func (c *Conversation) Send(msg []byte) ([][]byte, error)

Send takes a human readable message from the local user, possibly encrypts it and returns zero one or more messages to send to the peer.

type PrivateKey

type PrivateKey struct {
	PublicKey
	dsa.PrivateKey
}

func (*PrivateKey) Generate

func (priv *PrivateKey) Generate(rand io.Reader)

func (*PrivateKey) Import

func (priv *PrivateKey) Import(in []byte) bool

Import parses the contents of a libotr private key file.

func (*PrivateKey) Parse

func (priv *PrivateKey) Parse(in []byte) ([]byte, bool)

func (*PrivateKey) Serialize

func (priv *PrivateKey) Serialize(in []byte) []byte

func (*PrivateKey) Sign

func (priv *PrivateKey) Sign(rand io.Reader, hashed []byte) []byte

type PublicKey

type PublicKey struct {
	dsa.PublicKey
}

func (*PublicKey) Fingerprint

func (pk *PublicKey) Fingerprint() []byte

Fingerprint returns the 20-byte, binary fingerprint of the PublicKey.

func (*PublicKey) Parse

func (pk *PublicKey) Parse(in []byte) ([]byte, bool)

func (*PublicKey) Serialize

func (pk *PublicKey) Serialize(in []byte) []byte

func (*PublicKey) Verify

func (pk *PublicKey) Verify(hashed, sig []byte) ([]byte, bool)

type SecurityChange

type SecurityChange int

SecurityChange describes a change in the security state of a Conversation.

const (
	NoChange SecurityChange = iota
	// NewKeys indicates that a key exchange has completed. This occurs
	// when a conversation first becomes encrypted, and when the keys are
	// renegotiated within an encrypted conversation.
	NewKeys
	// SMPSecretNeeded indicates that the peer has started an
	// authentication and that we need to supply a secret. Call SMPQuestion
	// to get the optional, human readable challenge and then Authenticate
	// to supply the matching secret.
	SMPSecretNeeded
	// SMPComplete indicates that an authentication completed. The identity
	// of the peer has now been confirmed.
	SMPComplete
	// SMPFailed indicates that an authentication failed.
	SMPFailed
	// ConversationEnded indicates that the peer ended the secure
	// conversation.
	ConversationEnded
)