Documentation

Overview

Package crypto provides core cryptographic functionality for the Reunion protocol.

Index

Constants

View Source
const (
	// PayloadSize is the size of the Reunion protocol payload.
	PayloadSize = 1000

	// SymmetricKeySize is the size of the symmetric keys we use.
	SymmetricKeySize = 32

	// Type1MessageSize is the size in bytes of the Type 1 Message.
	Type1MessageSize = t1AlphaSize + t1BetaSize + t1GammaSize

	// Type2MessageSize is the size in bytes of the Type 2 Message.
	Type2MessageSize = SPRPMinimumBlockLength

	// Type3MessageSize is the size in bytes of the Type 3 Message.
	Type3MessageSize = SymmetricKeySize
)
View Source
const (
	// PublicKeyLength is the length of a Curve25519 public key.
	PublicKeyLength = 32

	// RepresentativeLength is the length of an Elligator representative.
	RepresentativeLength = 32

	// PrivateKeyLength is the length of a Curve25519 private key.
	PrivateKeyLength = 32

	// SharedSecretLength is the length of a Curve25519 shared secret.
	SharedSecretLength = 32

	// GroupElementLength is the length of a ECDH group element in bytes.
	GroupElementLength = PublicKeyLength
)
View Source
const (
	// SPRPMinimumBlockLength is the minimum block length of the SPRP.
	SPRPMinimumBlockLength = 32

	// SPRPKeyLength is the key size of the SPRP in bytes.
	SPRPKeyLength = 48

	// SPRPIVLength is the IV size of the SPRP in bytes.
	SPRPIVLength = 16
)
View Source
const (

	// SharedEpochKeySize is the length of the shared epoch key.
	SharedEpochKeySize = 32
)

Variables

View Source
var ErrInvalidMessageSize = errors.New("invalid message size")

ErrInvalidMessageSize is an error indicating an invalid message size.

View Source
var HashFunc = sha256.New

HashFunc implements the Hash interface as defined in https://godoc.org/hash#Hash We use it below in our HKDF construction.

Functions

func DecodeT1Message

func DecodeT1Message(message []byte) ([]byte, []byte, []byte, error)

DecodeT1Message upon success returns alpha, beta, gamma

func Exp

func Exp(dst, x, y *[GroupElementLength]byte)

Exp sets the group element dst to be the result of x^y, over the ECDH group.

func SPRPDecrypt

func SPRPDecrypt(key *[SPRPKeyLength]byte, iv *[SPRPIVLength]byte, msg []byte) []byte

SPRPDecrypt returns the plaintext of the message msg, decrypted via the Sphinx SPRP with the provided key and IV.

func SPRPEncrypt

func SPRPEncrypt(key *[SPRPKeyLength]byte, iv *[SPRPIVLength]byte, msg []byte) []byte

SPRPEncrypt returns the ciphertext of the message msg, encrypted via the Sphinx SPRP with the provided key and IV.

Types

type Keypair

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

Keypair is a Curve25519 keypair with an optional Elligator representative. As only certain Curve25519 keys can be obfuscated with Elligator, the representative must be generated along with the keypair.

func NewKeypair

func NewKeypair(elligator bool) (*Keypair, error)

NewKeypair generates a new Curve25519 keypair, and optionally also generates an Elligator representative of the public key.

func (*Keypair) Destroy

func (keypair *Keypair) Destroy()

Destroy causes the private key meterial to be destroyed.

func (*Keypair) HasElligator

func (keypair *Keypair) HasElligator() bool

HasElligator returns true if the Keypair has an Elligator representative.

func (*Keypair) MarshalBinary

func (keypair *Keypair) MarshalBinary() ([]byte, error)

MarshalBinary is an implementation of a method on the BinaryMarshaler interface defined in https://golang.org/pkg/encoding/

func (*Keypair) Private

func (keypair *Keypair) Private() *PrivateKey

Private returns the Curve25519 private key belonging to the Keypair.

func (*Keypair) Public

func (keypair *Keypair) Public() *PublicKey

Public returns the Curve25519 public key belonging to the Keypair.

func (*Keypair) Representative

func (keypair *Keypair) Representative() *Representative

Representative returns the Elligator representative of the public key belonging to the Keypair.

func (*Keypair) UnmarshalBinary

func (keypair *Keypair) UnmarshalBinary(data []byte) error

UnmarshalBinary is an implementation of a method on the BinaryUnmarshaler interface defined in https://golang.org/pkg/encoding/

type KeypairSerializable

type KeypairSerializable struct {
	Public         *PublicKey
	Private        *PrivateKey
	Representative *Representative
}

KeypairSerializable is used to help serialize Keypair.

type PrivateKey

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

PrivateKey is a Curve25519 private key in little-endian byte order.

func NewEmptyPrivateKey

func NewEmptyPrivateKey() *PrivateKey

NewEmptyPrivateKey creates a new PrivateKey with the lockedBuffer initialized to the correct size but not yet initialized to random bytes.

func NewRandomPrivateKey

func NewRandomPrivateKey() *PrivateKey

NewRandomPrivateKey creates a new PrivateKey with the lockedBuffer initialized to PrivateKeyLength random bytes.

func (*PrivateKey) ByteArray32

func (k *PrivateKey) ByteArray32() *[32]byte

ByteArray32 returns a pointer to the raw Curve25519 private key.

func (*PrivateKey) Bytes

func (k *PrivateKey) Bytes() []byte

Bytes returns a pointer to the raw Curve25519 private key.

func (*PrivateKey) Destroy

func (k *PrivateKey) Destroy()

Destroy destroys the private key material and frees up the memory.

func (*PrivateKey) Exp

func (k *PrivateKey) Exp(sharedSecret *[GroupElementLength]byte, publicKey *PublicKey)

Exp calculates the shared secret with the provided public key.

func (*PrivateKey) FromBytes

func (k *PrivateKey) FromBytes(b []byte) error

FromBytes deserializes the byte slice b into the PrivateKey.

func (*PrivateKey) Hex

func (k *PrivateKey) Hex() string

Hex returns the hexdecimal representation of the Curve25519 private key.

func (*PrivateKey) MarshalBinary

func (k *PrivateKey) MarshalBinary() ([]byte, error)

MarshalBinary is an implementation of a method on the BinaryMarshaler interface defined in https://golang.org/pkg/encoding/

func (*PrivateKey) UnmarshalBinary

func (k *PrivateKey) UnmarshalBinary(data []byte) error

UnmarshalBinary is an implementation of a method on the BinaryUnmarshaler interface defined in https://golang.org/pkg/encoding/

type PrivateKeyLengthError

type PrivateKeyLengthError int

PrivateKeyLengthError is the error returned when the private key being imported is an invalid length.

func (PrivateKeyLengthError) Error

func (e PrivateKeyLengthError) Error() string

type PublicKey

type PublicKey [PublicKeyLength]byte

PublicKey is a Curve25519 public key in little-endian byte order.

func DecryptT1Beta

func DecryptT1Beta(candidateKey []byte, t1Beta []byte) (*PublicKey, error)

DecryptT1Beta decrypts the Beta portion of a T1 message.

func NewPublicKey

func NewPublicKey(raw []byte) (*PublicKey, error)

NewPublicKey creates a PublicKey from the raw bytes.

func PublicKeyFromHex

func PublicKeyFromHex(encoded string) (*PublicKey, error)

PublicKeyFromHex returns a PublicKey from the hexdecimal representation.

func (*PublicKey) Bytes

func (k *PublicKey) Bytes() *[PublicKeyLength]byte

Bytes returns a pointer to the raw Curve25519 public key.

func (*PublicKey) FromBytes

func (k *PublicKey) FromBytes(b []byte) error

FromBytes deserializes the byte slice b into the PublicKey.

func (*PublicKey) Hex

func (k *PublicKey) Hex() string

Hex returns the hexdecimal representation of the Curve25519 public key.

func (*PublicKey) MarshalBinary

func (k *PublicKey) MarshalBinary() ([]byte, error)

MarshalBinary is an implementation of a method on the BinaryMarshaler interface defined in https://golang.org/pkg/encoding/

func (*PublicKey) UnmarshalBinary

func (k *PublicKey) UnmarshalBinary(data []byte) error

UnmarshalBinary is an implementation of a method on the BinaryUnmarshaler interface defined in https://golang.org/pkg/encoding/

type PublicKeyLengthError

type PublicKeyLengthError int

PublicKeyLengthError is the error returned when the public key being imported is an invalid length.

func (PublicKeyLengthError) Error

func (e PublicKeyLengthError) Error() string

type Representative

type Representative [RepresentativeLength]byte

Representative is an Elligator representative of a Curve25519 public key in little-endian byte order.

func (*Representative) Bytes

func (repr *Representative) Bytes() *[RepresentativeLength]byte

Bytes returns a pointer to the raw Elligator representative.

func (*Representative) FromBytes

func (repr *Representative) FromBytes(b []byte) error

FromBytes deserializes the byte slice b into the PublicKey.

func (*Representative) MarshalBinary

func (repr *Representative) MarshalBinary() ([]byte, error)

MarshalBinary is an implementation of a method on the BinaryMarshaler interface defined in https://golang.org/pkg/encoding/

func (*Representative) ToPublic

func (repr *Representative) ToPublic() *PublicKey

ToPublic converts a Elligator representative to a Curve25519 public key.

func (*Representative) UnmarshalBinary

func (repr *Representative) UnmarshalBinary(data []byte) error

UnmarshalBinary is an implementation of a method on the BinaryUnmarshaler interface defined in https://golang.org/pkg/encoding/

type RepresentativeKeyLengthError

type RepresentativeKeyLengthError int

RepresentativeKeyLengthError is the error returned when the public key being imported is an invalid length.

func (RepresentativeKeyLengthError) Error

type Session

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

Session encapsulates all the key material and provides a few methods for performing core cryptographic operations that form the Reunion protocol. Note that this so called Session does NOT keep any state. Therefore these client methods are supplemented with some helper functions defined in crypto.go

func NewSession

func NewSession(passphrase []byte, sharedRandomValue []byte, epoch uint64) (*Session, error)

NewSession creates a new client given a shared passphrase, shared random value and an epoch number.

func NewSessionFromKey

func NewSessionFromKey(sharedEpochKey *[SharedEpochKeySize]byte, sharedRandomValue []byte, epoch uint64) (*Session, error)

NewSessionFromKey creates a new client given a shared epoch key.

func (*Session) ComposeType3Message

func (c *Session) ComposeType3Message(beta2 *PublicKey) ([]byte, error)

ComposeType3Message composes a type three message.

func (*Session) Destroy

func (c *Session) Destroy()

Destroy destroys all the Session's key material and frees up the memory.

func (*Session) Epoch

func (c *Session) Epoch() uint64

Epoch returns the epoch.

func (*Session) GenerateType1Message

func (c *Session) GenerateType1Message(payload []byte) ([]byte, error)

GenerateType1Message generates a Type 1 message.

func (*Session) GetCandidateKey

func (c *Session) GetCandidateKey(t2 []byte, alpha *PublicKey) ([]byte, error)

GetCandidateKey extracts a candidate key from a type two message.

func (*Session) MarshalBinary

func (c *Session) MarshalBinary() ([]byte, error)

Marshal serializes the client key material.

func (*Session) ProcessType1MessageAlpha

func (c *Session) ProcessType1MessageAlpha(alpha []byte) ([]byte, *PublicKey, error)

ProcessType1MessageAlpha processes the alpha portion of a type one message.

func (*Session) ProcessType3Message

func (c *Session) ProcessType3Message(t3, gamma []byte, beta2 *PublicKey) ([]byte, error)

ProcessType3Message processes a type three message.

func (*Session) SharedRandom

func (c *Session) SharedRandom() []byte

SharedRandom returns the shared random value.

func (*Session) UnmarshalBinary

func (c *Session) UnmarshalBinary(data []byte) error

Unmarshal deserializes the client key material.