README
¶
======================================
sphinx mixnet packet crypto for golang
======================================
.. image:: https://travis-ci.org/david415/go-sphinxmixcrypto.png?branch=master
:target: https://www.travis-ci.org/david415/go-sphinxmixcrypto
:alt: travis for go-sphinxmixcrypto
.. image:: https://coveralls.io/repos/github/david415/go-sphinxmixcrypto/badge.svg?branch=master
:target: https://coveralls.io/github/david415/go-sphinxmixcrypto
:alt: coveralls for go-sphinxmixcrypto
.. image:: https://godoc.org/github.com/david415/go-sphinxmixcrypto?status.svg
:target: https://godoc.org/github.com/david415/go-sphinxmixcrypto
:alt: golang api docs for go-sphinxmixcrypto
what sphinx?
------------
Sphinx is a mixnet packet format.
Read the Sphinx paper:
**Sphinx: A Compact and Provably Secure Mix Format**
by George Danezis and Ian Goldberg
- http://www0.cs.ucl.ac.uk/staff/G.Danezis/papers/sphinx-eprint.pdf
status
------
This package is binary compatible with the python library:
- https://github.com/david415/sphinxmixcrypto
Although the two libraries are binary compatible and share test vectors to prove it,
go-sphinxmixcrypto is still a work-in-progress and does not yet have full feature
parity. In particular the client's use and creation of SURBs has not yet been written,
nor has the Nymserver's cryptographic components.
dependencies
------------
You can see a list of dependencies on godocs:
- https://godoc.org/github.com/david415/go-sphinxmixcrypto?imports
Currently this library depends on my own LIONESS wide block cipher implementation:
- https://github.com/david415/go-lioness
The other external dependencies include:
- https://git.schwanenlied.me/yawning/chacha20
- https://github.com/minio/blake2b-simd
- https://golang.org/x/crypto/curve25519
=======
license
=======
go-sphinxmixcrypto is free software made available via the MIT License.
License details located in the LICENSE file.
Some code was inspired or copied from Lightning-Onion's partial Sphinx
implementation located here:
- https://github.com/lightningnetwork/lightning-onion/blob/master/sphinx.go
- https://github.com/lightningnetwork/lightning-onion/blob/master/sphinx_test.go
Included in this repo is Lightning-Onion's MIT License file:
LICENSE-lightening-onion
=======
contact
=======
* email dstainton415@gmail.com
* gpg key ID 0x836501BE9F27A723
* gpg fingerprint F473 51BD 87AB 7FCF 6F88 80C9 8365 01BE 9F27 A723
Documentation
¶
Overview ¶
Package sphinxmixcrypto provides cryptographic encoding/decoding using the Sphinx mix network packet format as described in the paper
"Sphinx: A Compact and Provably Secure Mix Format" written by Ian Goldberg and George Danezis
If you're looking to dive right into code, see the unit tests for examples.
Index ¶
- Constants
- Variables
- func AddPadding(src []byte, blockSize int) ([]byte, error)
- func EncodeDestination(destination []byte) []byte
- func RemovePadding(src []byte) ([]byte, error)
- type GroupCurve25519
- type MixHeader
- type OnionPacket
- type Params
- func (s *Params) CreateBlockCipherKey(secret [32]byte) ([lioness.KeyLen]byte, error)
- func (s *Params) DecryptBlock(key [lioness.KeyLen]byte, data []byte) ([]byte, error)
- func (s *Params) EncryptBlock(key [lioness.KeyLen]byte, data []byte) ([]byte, error)
- func (s *Params) GenerateCipherStream(key [chachaKeyLen]byte, numBytes uint) ([]byte, error)
- func (s *Params) GenerateHMACKey(secret [32]byte) [16]byte
- func (s *Params) GenerateStreamCipherKey(secret [32]byte) [32]byte
- func (s *Params) HMAC(key [16]byte, data []byte) [16]byte
- func (s *Params) Hash(data []byte) [32]byte
- func (s *Params) HashBlindingFactor(alpha []byte, secret [32]byte) [32]byte
- func (s *Params) HashSeen(secret [32]byte) [32]byte
- type SphinxNode
- type SphinxNodeOptions
- type SphinxNymServer
- type SphinxPKI
- type UnwrappedMessage
Constants ¶
const ( // NumMaxHops is the maximum path length. NumMaxHops = 5 // HopPayloadSize is the per-hop payload size in the header HopPayloadSize = 32 // PayloadSize is the packet payload size PayloadSize = 1024 )
const ( // ExitNode indicates an exit hop ExitNode = 0 // MoreHops indicates another mix hop MoreHops = 255 // ClientHop indicates a client hop ClientHop = 128 // Failure indicates a prefix-free decoding failure Failure )
Variables ¶
var ( // ErrInvalidBlockSize indicates block size <= 0 ErrInvalidBlockSize = errors.New("invalid block size") // ErrInvalidData indicates zero size data ErrInvalidData = errors.New("invalid data, empty") // ErrInvalidPadding indicates an invalid padded input ErrInvalidPadding = errors.New("invalid padding on input") // ErrInvalidPadOffset indicates a bad padding offset ErrInvalidPadOffset = errors.New("invalid padding offset") // ErrInputTooBig indicates the input data is too big ErrInputTooBig = errors.New("input too big") )
var ( // ErrReplayedPacket indicates a replay attack ErrReplayedPacket = fmt.Errorf("sphinx packet replay attempted") )
Functions ¶
func AddPadding ¶
AddPadding returns src with padding appended
func EncodeDestination ¶
EncodeDestination encodes a destination using our prefix-free encoding
func RemovePadding ¶
RemovePadding returns src with padding removed
Types ¶
type GroupCurve25519 ¶
type GroupCurve25519 struct {
// contains filtered or unexported fields
}
GroupCurve25519 performs group operations on the curve
func NewGroupCurve25519 ¶
func NewGroupCurve25519() *GroupCurve25519
NewGroupCurve25519 creates a new GroupCurve25519
func (*GroupCurve25519) ExpOn ¶
func (g *GroupCurve25519) ExpOn(base, exp [32]byte) [32]byte
ExpOn does scalar multiplication on the curve
func (*GroupCurve25519) GenerateSecret ¶
func (g *GroupCurve25519) GenerateSecret(rand io.Reader) ([32]byte, error)
GenerateSecret generats a new key
func (*GroupCurve25519) MakeExp ¶
func (g *GroupCurve25519) MakeExp(data [32]byte) [32]byte
MakeExp flips some bits
func (*GroupCurve25519) MultiExpOn ¶
func (g *GroupCurve25519) MultiExpOn(base [32]byte, exps [][32]byte) [32]byte
MultiExpOn does multiple scalar multiplication operations and returns the accumulator
type MixHeader ¶
type MixHeader struct {
Version byte
EphemeralKey [32]byte // alpha
RoutingInfo [routingInfoSize]byte // beta
HeaderMAC [securityParameter]byte // gamma
}
MixHeader contains the sphinx header but not the payload. A version number is also included; TODO: make the version number do something useful.
func NewMixHeader ¶
func NewMixHeader(params *Params, route [][16]byte, nodeMap map[[16]byte][32]byte, destinationType byte, destinationID [16]byte, secret []byte, padding []byte) (*MixHeader, [][32]byte, error)
NewMixHeader generates the a mix header containing the neccessary onion routing information required to propagate the message through the mixnet.
type OnionPacket ¶
type OnionPacket struct {
Header *MixHeader
Payload [PayloadSize]byte // delta
}
OnionPacket represents a forwarding message containing onion wrapped hop-to-hop routing information along with an onion encrypted payload message addressed to the final destination.
func NewOnionPacket ¶
func NewOnionPacket(params *Params, route [][16]byte, nodeMap map[[16]byte][32]byte, destination [16]byte, payload []byte, secret []byte, padding []byte) (*OnionPacket, error)
NewOnionPacket creates a mixnet packet
func (*OnionPacket) Decode ¶
func (f *OnionPacket) Decode(r io.Reader) error
Decode fully populates the target ForwardingMessage from the raw bytes encoded within the io.Reader. In the case of any decoding errors, an error will be returned. If the method successs, then the new OnionPacket is ready to be processed by an instance of SphinxNode.
type Params ¶
type Params struct {
// contains filtered or unexported fields
}
Params handles the cryptographic operations
func NewParams ¶
func NewParams() *Params
NewParams creates a new Params struct with max mixnet nodes per route set to r
func (*Params) CreateBlockCipherKey ¶
CreateBlockCipherKey returns the LIONESS block cipher key
func (*Params) DecryptBlock ¶
DecryptBlock decrypts a block
func (*Params) EncryptBlock ¶
EncryptBlock encrypts a block
func (*Params) GenerateCipherStream ¶
GenerateCipherStream xor's the input data with a cipher stream
func (*Params) GenerateHMACKey ¶
GenerateHMACKey make a new key that can be used with our HMAC
func (*Params) GenerateStreamCipherKey ¶
GenerateStreamCipherKey generates a stream cipher key
func (*Params) HashBlindingFactor ¶
HashBlindingFactor compute a hash of alpha and secret to use as a blinding factor
type SphinxNode ¶
SphinxNode is used to keep track of a mix node's state
func NewSphinxNode ¶
func NewSphinxNode(params *Params, options *SphinxNodeOptions) (*SphinxNode, error)
NewSphinxNode creates a new SphinxNode
func (*SphinxNode) PrefixFreeDecode ¶
func (n *SphinxNode) PrefixFreeDecode(s []byte) (int, []byte, []byte)
PrefixFreeDecode decodes the prefix-free encoding. Return the type, value, and the remainder of the input string
func (*SphinxNode) Unwrap ¶
func (n *SphinxNode) Unwrap(packet *OnionPacket) (*UnwrappedMessage, error)
Unwrap unwraps a layer of encryption from a sphinx packet and upon success returns an UnwrappedMessage, otherwise an error.
type SphinxNodeOptions ¶
type SphinxNodeOptions struct {
// contains filtered or unexported fields
}
SphinxNodeOptions are node state options such as pub/priv key and an ID
type SphinxNymServer ¶
type SphinxNymServer interface {
}
SphinxNymServer interface XXX add more description here XXX
Source Files