bots

README

CONIKS Registration Proxy for Twitter account verification in Golang

Usage

⇒  go install github.com/coniks-sys/coniks-go/bots/coniksbot
⇒  coniksbot -h

Usage:
  coniksbot [command]

Available Commands:
  init        Create a configuration file
  run         Run a CONIKS bot instance

Flags:
  -h, --help          help for coniksbot

Use "coniksbot [command] --help" for more information about a command.

Configure the bot

• Generate the configuration file:

⇒  mkdir coniksbot; cd coniksbot
⇒  coniksbot init # create the configuration file in the current directory

• Create a Twitter account for your bot.
• Obtain OAuth tokens to authorize the bot for the new Twitter account:
  • Visit https://apps.twitter.com
  • Click "Create New App" and enter the required information.
  • In the "Permissions" tab, change the app permissions to allow direct messages.
  • In the "Keys and Access Tokens" tab, create access tokens by clicking "Create my access token".
  • Replace the Consumer Key, Consumer Secret, AccessToken, and AccessSecret in the config file with the corresponding values in the "Keys and Access Tokens" tab.
  • Replace the Handle in the config file with the handle of your bot's Twitter account.

Run the bot

⇒  coniksbot run  # run the CONIKS bot

Disclaimer

Please keep in mind that this CONIKS account verification bot implementation is under active development. The repository may contain experimental features that aren't fully tested. We recommend using a tagged release.

Documentation

Overview

Package bots implements the CONIKS account verification protocol for first-party identity providers.

Many communication services provide user identifiers for their users (e.g. Twitter, XMPP servers), but do not provide end-to-end encryption by default. Users wishing to communicate securely often opt to use a third-party end-to-end encrypted communication service, which allows them to connect their first-party account.

bots provides such third-party secure communication services that use CONIKS for key management with a mechanism for ensuring that the first-party usernames registered with the CONIKS key directory belong to a legitimate first-party account. More specifically, bots provides registration proxies which verify that each first-party username belongs to a corresponding first-party account before forwarding the new registration to the third-party CONIKS server.

Bots

This module provides an account verification bot interface that can be used to implement a CONIKS registration proxy for any first-party identity provider.

Twitter Bot

This module provides a registration proxy for Twitter accounts that implements the CONIKS account verification Bot interface.

CONIKS Bot

This subpackage provides an executable reference implementation for a CONIKS registration proxy for Twitter accounts.

Index

• func SendRequestToCONIKS(addr string, msg []byte) ([]byte, error)
• type Bot
  • func NewTwitterBot(path string) (Bot, error)
• type TwitterBot
  • func (bot *TwitterBot) HandleRegistration(username string, msg []byte) string
  • func (bot *TwitterBot) Run()
  • func (bot *TwitterBot) SendDM(screenname, msg string) error
  • func (bot *TwitterBot) Stop()
• type TwitterConfig
• type TwitterOAuth

Functions

func SendRequestToCONIKS

func SendRequestToCONIKS(addr string, msg []byte) ([]byte, error)

SendRequestToCONIKS forwards a given msg to the CONIKS server listening at the named Unix socket addr. SendRequestToCONIKS, therefore, assumes that the registration proxy runs on the same host OS as the CONIKS server.

Types

type Bot

type Bot interface {
	HandleRegistration(string, []byte) string
	Run()
	Stop()
}

A Bot is a CONIKS registration proxy that verifies the authenticity of a user account with an identity provider (i.e. communication service that hands out service-specific user identifiers).

func NewTwitterBot

func NewTwitterBot(path string) (Bot, error)

NewTwitterBot constructs a new account verification bot for Twitter accounts that implements the Bot interface.

NewTwitterBot loads the TwitterConfig for this bot from the corresponding config file, checks that the CONIKS key server is live, and authenticates the bot's Twitter client via OAuth. If any of these steps fail, NewTwitterBot returns a (nil, error) tuple. Otherwise, it returns a TwitterBot struct with the appropriate values obtained during the setup.

type TwitterBot

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

A TwitterBot is an account verification bot for CONIKS clients registering Twitter usernames with a CONIKS key server.

A TwitterBot maintains information about a twitter client and stream, the address of its corresponding CONIKS server, and its reserved Twitter handle.

func (*TwitterBot) HandleRegistration

func (bot *TwitterBot) HandleRegistration(username string, msg []byte) string

HandleRegistration verifies the authenticity of a CONIKS registration request msg for a Twitter user, and forwards this request to the bot's corresponding CONIKS key server if the Twitter account for username is valid.

HandleRegistration() validates a registration request sent by a CONIKS client on behalf of the Twitter user via Twitter DM. It does so by comparing the username indicated in the request with the Twitter handle which sent the DM. HandleRegistration() forwards the registration request to the CONIKS server via SendRequestToCONIKS() if username matches request.Username, and returns the server's response as a string. See https://godoc.org/github.com/coniks-sys/coniks-go/protocol/#ConiksDirectory.Register for details on the possible server responses.

func (*TwitterBot) Run

func (bot *TwitterBot) Run()

Run implements the main functionality of a Twitter registration proxy. It listens for a Twitter direct message (DM) sent to the bot's reserved handle and calls HandleRegistration() upon receiving a valid DM sent by a CONIKS client connected to a Twitter account. The result of HandleRegistration() is returned to the CONIKS client via DM.

func (*TwitterBot) SendDM

func (bot *TwitterBot) SendDM(screenname, msg string) error

SendDM sends a Twitter direct message msg to the given Twitter screenname. The sender screenname should be set to the bot's reserved Twitter handle.

func (*TwitterBot) Stop

func (bot *TwitterBot) Stop()

Stop closes the bot's open stream through which it communicates with Twitter.

type TwitterConfig

type TwitterConfig struct {
	CONIKSAddress string `toml:"coniks_address"`
	TwitterOAuth  `toml:"twitter_oauth"`
	Handle        string `toml:"twitter_bot_handle"`
}

A TwitterConfig contains the address of the named UNIX socket through which the bot and the CONIKS server communicate, the OAuth information needed to authenticate the bot with Twitter, and the bot's reserved Twitter handle. These values are specified in a configuration file, which is read at initialization time.

type TwitterOAuth

type TwitterOAuth struct {
	ConsumerKey    string
	ConsumerSecret string
	AccessToken    string
	AccessSecret   string
}

A TwitterOAuth contains the four secret values needed to authenticate the bot with Twitter. These values are unique to each application that uses the Twitter API to access an account's feed and direct messages, and must be generated via Twitter's developer portal.