cspp

README

CoinShuffle++

Overview

This module provides client and server implementations to execute the CoinShuffle++ mixing protocol. While intended to be used to create Decred CoinJoin transactions, the client and server packages are generic enough to anonymously mix and join elements of any group.

This implementation differs from the protocol described by the CoinShuffle++ paper in the following ways:

• DiceMix is replaced by DiceMix Light. This simplifies the computational cost by mixing smaller random numbers and sorting results to reserve anonymous slot assignments in a traditional XOR DC-net. It also enables scaling the protocol to mix very large messages without increasing the anonymization cost.

• Peer session keys are ephemeral. This is a tradeoff made to reduce participant correlation observed by the server between multiple mixes with the understanding that it makes peer reputation and authentication systems more difficult to design. These systems can still be built on top of ephemeral session keys, e.g. by signing a challenge with both the epheremal and a static identity key to demonstrate knowledge of both secret keys.

• A special server acts as the central communication point rather than all peers broadcasting all messages to every participant through a bulletin board or chat room. The server is the only party that advances the protocol into the next state when timeouts occur.

• TLS (or another secure, authenticated channel) is required. This simplifies the protocol by removing the need to use the session signing key to authenticate each individual message. It also improves efficiency by allowing authentication to be performed through a MAC.

• All non-anonymous portions of the final result (in a CoinJoin, all inputs and the change outputs) are shared with the server at the start of the protocol. The server is responsible for merging these messages, and the mixed messages from the DC-net, into a single message that clients confirm. With knowledge of how many inputs each peer is providing and their change output, a server can require each peer to pay their fair share of the transaction fee and check that inputs do not double spend.

Privacy guarantees and caveats

CoinShuffle++ provides creation of transactions with anonymized mixing of outputs with equally-sized amounts in a CoinJoin. It does not anonymize participation, transaction inputs, or change outputs. It is possible for a mix to be deanonymized in the future if participants reveal, maliciously or inadvertently, which mixed messages were theirs.

It is not possible to apply CoinShuffle++ to mix outputs with differing output amounts without aborting the protocol entirely upon run failure (rather than assigning blame, removing misbehaving peers, and starting another run). Doing so would deanonymize the final outputs by associating each peer with an output of the revealed amount. Therefore, only equally-sized outputs may be mixed anonymously.

Build requirements

All client packages and server software from this repo requires Go 1.13 or later.

In addition, the server software, found in the cmd/csppserver directory, depends on Flint2 to efficiently factor polynomials. This requires additional C libraries and headers to be installed for the server to compile and link against. On Ubuntu 18.04:

$ sudo apt-get install libflint-dev libmpfr-dev

License

cspp is released under a permissive ISC license.

Documentation

Overview

Package cspp implements a DiceMix Light and CoinShuffle++ client.

Index

• Constants
• type GenConfirmer
• type Logger
• type MissingMessage
• type Session
  • func NewSession(random io.Reader, log Logger, pairCommitment []byte, mixes int) (*Session, error)
  • func (s *Session) DiceMix(ctx context.Context, conn net.Conn, genConf GenConfirmer) error

Constants

const MessageSize = 20

MessageSize is the size of messages returned by Gen.

Types

type GenConfirmer

type GenConfirmer interface {
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
	Gen() ([][]byte, error)
	Confirm() error
}

GenConfirmer is a generator of fresh messages to mix in a DiceMix run and a signable message that can include the mixed messages. This will often be a transaction in wire encoding when CoinShuffle++ is used by applying DiceMix to create a CoinJoin transaction. Inputs spent by the CoinJoin must set the input amount. A single output for change is allowed, and if included, must pay the required share of fee.

The CoinShuffle++ server must combine inputs from all peers at the start of the protocol and share the combined message with each peer. Conforming implementations must return errors from Confirm if any of their inputs or anonymous outputs are missing after unmarshaling. See MissingMessage for documentation on how to return errors.

type Logger

type Logger interface {
	Print(args ...interface{})
	Printf(format string, args ...interface{})
}

Logger writes client logs.

type MissingMessage

type MissingMessage interface {
	error
	MissingMessage()
}

MissingMessage describes a UnmarshalBinary or Confirm error where an anonymized message is missing from the mix. It results in a failed run, revealing secrets, and assigning blame. If the mix is instead missing non-anonymized messages, this error should not be used, and any other error will cause the client to abort the protocol due to the server being malicious.

type Session

type Session struct {
	Pk ed25519.PublicKey  // Session pubkey
	Sk ed25519.PrivateKey // Session signing key
	// contains filtered or unexported fields
}

Session represents a DiceMix Light session (which consists of one or more runs to remove unresponsive or malicious peers).

func NewSession

func NewSession(random io.Reader, log Logger, pairCommitment []byte, mixes int) (*Session, error)

NewSession creates a new Session for a mix session described by pairCommitment, which will submit mixes number of mixed messages.

func (*Session) DiceMix

func (s *Session) DiceMix(ctx context.Context, conn net.Conn, genConf GenConfirmer) error

DiceMix performs the DiceMix Light client protocol with a server connected through conn.