purbs

Documentation

Index

• Constants
• func Decode(blob []byte, recipient *Recipient, ...) (bool, []byte, error)
• func KDF(purpose string, seed []byte) []byte
• func SimulMeasureEncodingTime(nRepeat int, recipients []int, suites []int) string
• func SimulMeasureHeaderCompactness(nRepeat int, recipients []int, suites []int) string
• func SimulMeasureHeaderSize(nRepeat int, numRecipients []int) string
• func SimulMeasureWorstDecodingTime(nRepeat int, recipients []int, suites []int) string
• type Cornerstone
• type EntryPoint
• type GrowableBuffer
• type Header
  • func (h *Header) Length() int
• type Monitor
• type Purb
  • func Encode(data []byte, recipients []Recipient, stream cipher.Stream, ...) (*Purb, error)
  • func (purb *Purb) CreateHeader()
  • func (purb *Purb) ToBytes() []byte
  • func (purb *Purb) VisualRepresentation(withBoundaries bool) string
• type PurbPublicFixedParameters
  • func NewPublicFixedParameters(infoMap SuiteInfoMap, simplifiedEntryPointTable bool) *PurbPublicFixedParameters
• type Recipient
• type Region
  • func (r *Region) ComputeOverlap(otherRegion *Region) *Region
  • func (r *Region) DoesOverlapWith(otherRegion *Region) bool
  • func (r *Region) ToString() string
• type RegionReservationStruct
  • func NewRegionReservationStruct() *RegionReservationStruct
  • func (r *RegionReservationStruct) Clone() *RegionReservationStruct
  • func (r *RegionReservationStruct) IsFree(startPos int, endPos int) bool
  • func (r *RegionReservationStruct) Reserve(startPos int, endPos int, requireFree bool, label string) bool
  • func (r *RegionReservationStruct) Reset()
  • func (r *RegionReservationStruct) ScanFreeRegions(f func(int, int), maxByteOffset int)
  • func (r *RegionReservationStruct) ToString() string
• type ResultRow
  • func (r ResultRow) String() string
• type Results
  • func (results Results) String() string
• type Suite
• type SuiteInfo
  • func (si SuiteInfo) String() string
• type SuiteInfoMap

Constants

const END_OFFSET_LEN = START_OFFSET_LEN

Length (in bytes) of the pointer to the end of the payload

const ENTRYPOINT_LENGTH = 16 + 4 + 4 + 16

Fixed for the simulation: 16-byte symmetric key + 4-byte offset start position + 4-byte offset end position + 16-byte authentication tag

const MAC_AUTHENTICATION_TAG_LENGTH = 32

Length (in bytes) of the MAC tag in the entry point (only used with entrypoints are encrypted with AEAD)

const NONCE_LENGTH = 12

Length (in bytes) of the Nonce used at the beginning of the PURB

const START_OFFSET_LEN = 4

Length (in bytes) of the pointer to the start of the payload

const SYMMETRIC_KEY_LENGTH = 16

Length (in bytes) of the symmetric key used to encrypt the payload

Functions

func Decode

func Decode(blob []byte, recipient *Recipient, publicFixedParameters *PurbPublicFixedParameters, verbose bool) (bool, []byte, error)

Decode takes a PURB blob and a recipient info (suite+KeyPair) and extracts the payload

func KDF

func KDF(purpose string, seed []byte) []byte

KDF derives a key from a purpose string and seed bytes

func SimulMeasureEncodingTime

func SimulMeasureEncodingTime(nRepeat int, recipients []int, suites []int) string

SimulMeasureEncodingTime

func SimulMeasureHeaderCompactness

func SimulMeasureHeaderCompactness(nRepeat int, recipients []int, suites []int) string

SimulMeasureHeaderCompactness

func SimulMeasureHeaderSize

func SimulMeasureHeaderSize(nRepeat int, numRecipients []int) string

SimulMeasureHeaderSize

func SimulMeasureWorstDecodingTime

func SimulMeasureWorstDecodingTime(nRepeat int, recipients []int, suites []int) string

SimulMeasureNumRecipients

Types

type Cornerstone

type Cornerstone struct {
	SuiteName string
	KeyPair   *key.Pair
	Offset    int    // Starting byte position in the header
	EndPos    int    // Ending byte position in the header
	Bytes     []byte // singleton. Since calling marshalling the KeyPair is non-deterministic, at least we do it only once so prints are consistents
	SuiteInfo *SuiteInfo
}

Ephemeral Diffie-Hellman keys for all SessionKey-holders using this suite. Should have a uniform representation, e.g., an Elligator point.

type EntryPoint

type EntryPoint struct {
	Recipient    Recipient // Recipient whom this entrypoint is for
	SharedSecret []byte    // Ephemeral secret derived using DH
	Offset       int       // Starting byte position in the header
	Length       int
}

EntryPoint holds the info required to create an entrypoint for each recipient.

type GrowableBuffer

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

A simple []byte slice with helpful wrapper

type Header

type Header struct {
	EntryPoints  map[string][]*EntryPoint // map of suiteName -> []entrypoints
	Cornerstones map[string]*Cornerstone  // Holds sender's ephemeral private/public keys for each suite in the header
	Layout       *RegionReservationStruct // An array of byte slices where each of the bytes slice represents a hash table entry
}

Structure defining the actual header of a purb

func (*Header) Length

func (h *Header) Length() int

Compute the length of the header when transformed to []byte

type Monitor

type Monitor struct {
	CPUtime float64
}

Helpers for measurement of CPU cost of operations

type Purb

type Purb struct {
	PublicParameters *PurbPublicFixedParameters

	Nonce      []byte // Nonce used in both AEAD of entrypoints and payload. The same for different entrypoints as the keys are different. It is stored in the very beginning of the purb
	Header     *Header
	Payload    []byte        // Payload contains already encrypted and padded plaintext
	SessionKey []byte        // SessionKey is encapsulated and used to derive PayloadKey and MacKey
	Recipients []Recipient   // tuple with (Suite, PublicKey, PrivateKey)
	Stream     cipher.Stream // used to get randomness

	EncryptedDataLen int    // used to record the end of encrypted data in the entry points
	OriginalData     []byte // kept to compare between "Payload" and this
	IsVerbose        bool   // if true, the various operations on the data structure will print what is happening
	// contains filtered or unexported fields
}

Structure to define the whole PURB

func Encode

func Encode(data []byte, recipients []Recipient, stream cipher.Stream, params *PurbPublicFixedParameters, verbose bool) (*Purb, error)

Creates a PURB from some data and Recipients information

func (*Purb) CreateHeader

func (purb *Purb) CreateHeader()

Construct header computes and finds an appropriate placements for the Entrypoints and the Cornerstones

func (*Purb) ToBytes

func (purb *Purb) ToBytes() []byte

ToBytes get the []byte representation of the PURB

func (*Purb) VisualRepresentation

func (purb *Purb) VisualRepresentation(withBoundaries bool) string

Simply returns a string with the internal details of the PURB

type PurbPublicFixedParameters

type PurbPublicFixedParameters struct {
	SuiteInfoMap                   SuiteInfoMap // public suite information (Allowed Positions, etc)
	SimplifiedEntrypointsPlacement bool         // If true, does not use hash tables for entrypoints

	HashTableCollisionLinearResolutionAttempts int // Number of attempts to shift entrypoint position in a hash table by +1 if the computed position is already occupied
}

This struct's contents are *not* parameters to the PURBs. Here they vary for the simulations and the plots, but they should be fixed for all purbs

func NewPublicFixedParameters

func NewPublicFixedParameters(infoMap SuiteInfoMap, simplifiedEntryPointTable bool) *PurbPublicFixedParameters

Creates a struct with parameters that are *fixed* across all PURBs. Should be constants, but here it is a variable for simulating various parameters

type Recipient

type Recipient struct {
	SuiteName string
	Suite
	PublicKey  kyber.Point
	PrivateKey kyber.Scalar
}

Recipient holds information needed to be able to encrypt anything for it PrivateKey is nil for encoder

type Region

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

tuple (startPos, endPos, label)

func (*Region) ComputeOverlap

func (r *Region) ComputeOverlap(otherRegion *Region) *Region

returns true iff the two regions overlap

func (*Region) DoesOverlapWith

func (r *Region) DoesOverlapWith(otherRegion *Region) bool

returns true iff the two regions overlap

func (*Region) ToString

func (r *Region) ToString() string

ToString // thank you golang for forcing me to comment on "ToString()"

type RegionReservationStruct

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

RangeReservationLayout is used to represent a []byte array with (potentially overlapping) range=byteRangeForAllowedPositionIndex reservations Expose "Reset()", "Reserve(range)", and "ScanFree"

func NewRegionReservationStruct

func NewRegionReservationStruct() *RegionReservationStruct

NewSkipLayout creates a new RangeReservationLayout

func (*RegionReservationStruct) Clone

func (r *RegionReservationStruct) Clone() *RegionReservationStruct

Deep-clone structure

func (*RegionReservationStruct) IsFree

func (r *RegionReservationStruct) IsFree(startPos int, endPos int) bool

Returns true iff the requested byteRangeForAllowedPositionIndex is free

func (*RegionReservationStruct) Reserve

func (r *RegionReservationStruct) Reserve(startPos int, endPos int, requireFree bool, label string) bool

Attempt to reserve a specific extent in the layout. Region work as [startPos, endPos[ If requireFree is true, attempt to reserve it exclusively (return true) or fails (return false) If requireFree is false, reserve byteRangeForAllowedPositionIndex even if some or all of it already reserved. (always returns true) Returns true if requested byteRangeForAllowedPositionIndex was reserved, false if not.

func (*RegionReservationStruct) Reset

func (r *RegionReservationStruct) Reset()

Reset marks all regions as free

func (*RegionReservationStruct) ScanFreeRegions

func (r *RegionReservationStruct) ScanFreeRegions(f func(int, int), maxByteOffset int)

Call the supplied function on every free byteRangeForAllowedPositionIndex in the layout, up to a given maximum byte offset.

func (*RegionReservationStruct) ToString

func (r *RegionReservationStruct) ToString() string

ToString // thank you golang for forcing me to comment on "ToString()"

type ResultRow

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

ResultRow contains data about one sample of one experiment

func (ResultRow) String

func (r ResultRow) String() string

type Results

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

Results is a collection of ResultRow's

func (Results) String

func (results Results) String() string

type Suite

type Suite interface {
	kyber.Encoding
	kyber.Group
	kyber.HashFactory
	kyber.XOFFactory
	kyber.Random
}

Suite defines the required functionalities for each suite from kyber

type SuiteInfo

type SuiteInfo struct {
	AllowedPositions  []int // alternative SessionKey/point position in purb header
	CornerstoneLength int   // length of each SessionKey/point in bytes
	EntryPointLength  int   // Length of each encrypted entry point
}

SuiteInfo holds possible positions whose cornerstones might take in a header and a SessionKey length for this suite

func (SuiteInfo) String

func (si SuiteInfo) String() string

type SuiteInfoMap

type SuiteInfoMap map[string]*SuiteInfo

A map of suite->info, info being the length of a marshalled public key, and the Allowed Positions in the purb header