...
▽

Package oprf

import "github.com/cloudflare/circl/oprf"
Overview
Index
Examples

Overview ▾

Package oprf provides Verifiable, Oblivious Pseudo-Random Functions.

An Oblivious Pseudorandom Function (OPRFs) is a two-party protocol for computing the output of a PRF. One party (the server) holds the PRF secret key, and the other (the client) holds the PRF input.

This package is compatible with the OPRF specification at draft-irtf-cfrg-voprf [1].

Protocol Overview

This diagram shows the steps of the protocol that are common for all operation modes. 

Client(info*)                               Server(sk, pk, info*)
=================================================================
finData, evalReq = Blind(input)

                            evalReq
                          ---------->

                            evaluation = Evaluate(evalReq, info*)

                           evaluation
                          <----------

output = Finalize(finData, evaluation, info*)

Operation Modes

Each operation mode provides different properties to the PRF.

Base Mode: Provides obliviousness to the PRF evaluation, i.e., it ensures that the server does not learn anything about the client's input and output during the Evaluation step.

Verifiable Mode: Extends the Base mode allowing the client to verify that Server used the private key that corresponds to the public key.

Partial Oblivious Mode: Extends the Verifiable mode by including shared public information to the PRF input.

All three modes can perform batches of PRF evaluations, so passing an array of inputs will produce an array of outputs.

References

[1] draft-irtf-cfrg-voprf: https://datatracker.ietf.org/doc/draft-irtf-cfrg-voprf

▾ Example (Oprf)

Code:

suite := SuiteP256
//                                  Server(sk, pk, info*)
private, _ := GenerateKey(suite, rand.Reader)
server := NewServer(suite, private)
//   Client(info*)
client := NewClient(suite)
//   =================================================================
//   finData, evalReq = Blind(input)
inputs := [][]byte{[]byte("first input"), []byte("second input")}
finData, evalReq, _ := client.Blind(inputs)
//
//                               evalReq
//                             ---------->
//
//                               evaluation = Evaluate(evalReq, info*)
evaluation, _ := server.Evaluate(evalReq)
//
//                              evaluation
//                             <----------
//
//   output = Finalize(finData, evaluation, info*)
outputs, err := client.Finalize(finData, evaluation)
fmt.Print(err == nil && len(inputs) == len(outputs))

Output:

true

Index ▾

Variables
type Blind
type Blinded
type Client
    func NewClient(s Suite) Client
    func (c Client) Blind(inputs [][]byte) (*FinalizeData, *EvaluationRequest, error)
    func (c Client) DeterministicBlind(inputs [][]byte, blinds []Blind) (*FinalizeData, *EvaluationRequest, error)
    func (c Client) Finalize(f *FinalizeData, e *Evaluation) (outputs [][]byte, err error)
type Evaluated
type Evaluation
type EvaluationRequest
type FinalizeData
    func (f FinalizeData) CopyBlinds() []Blind
type Mode
type PartialObliviousClient
    func NewPartialObliviousClient(s Suite, server *PublicKey) PartialObliviousClient
    func (c PartialObliviousClient) Blind(inputs [][]byte) (*FinalizeData, *EvaluationRequest, error)
    func (c PartialObliviousClient) DeterministicBlind(inputs [][]byte, blinds []Blind) (*FinalizeData, *EvaluationRequest, error)
    func (c PartialObliviousClient) Finalize(f *FinalizeData, e *Evaluation, info []byte) (outputs [][]byte, err error)
type PartialObliviousServer
    func NewPartialObliviousServer(s Suite, key *PrivateKey) PartialObliviousServer
    func (s PartialObliviousServer) Evaluate(req *EvaluationRequest, info []byte) (*Evaluation, error)
    func (s PartialObliviousServer) FullEvaluate(input, info []byte) (output []byte, err error)
    func (s PartialObliviousServer) PublicKey() *PublicKey
    func (s PartialObliviousServer) VerifyFinalize(input, info, expectedOutput []byte) bool
type PrivateKey
    func DeriveKey(s Suite, mode Mode, seed, info []byte) (*PrivateKey, error)
    func GenerateKey(s Suite, rnd io.Reader) (*PrivateKey, error)
    func (k *PrivateKey) MarshalBinary() ([]byte, error)
    func (k *PrivateKey) Public() *PublicKey
    func (k *PrivateKey) UnmarshalBinary(s Suite, data []byte) error
type PublicKey
    func (k *PublicKey) MarshalBinary() ([]byte, error)
    func (k *PublicKey) UnmarshalBinary(s Suite, data []byte) error
type Server
    func NewServer(s Suite, key *PrivateKey) Server
    func (s Server) Evaluate(req *EvaluationRequest) (*Evaluation, error)
    func (s Server) FullEvaluate(input []byte) (output []byte, err error)
    func (s Server) PublicKey() *PublicKey
    func (s Server) VerifyFinalize(input, expectedOutput []byte) bool
type Suite
    func GetSuite(identifier string) (Suite, error)
type VerifiableClient
    func NewVerifiableClient(s Suite, server *PublicKey) VerifiableClient
    func (c VerifiableClient) Blind(inputs [][]byte) (*FinalizeData, *EvaluationRequest, error)
    func (c VerifiableClient) DeterministicBlind(inputs [][]byte, blinds []Blind) (*FinalizeData, *EvaluationRequest, error)
    func (c VerifiableClient) Finalize(f *FinalizeData, e *Evaluation) (outputs [][]byte, err error)
type VerifiableServer
    func NewVerifiableServer(s Suite, key *PrivateKey) VerifiableServer
    func (s VerifiableServer) Evaluate(req *EvaluationRequest) (*Evaluation, error)
    func (s VerifiableServer) FullEvaluate(input []byte) (output []byte, err error)
    func (s VerifiableServer) PublicKey() *PublicKey
    func (s VerifiableServer) VerifyFinalize(input, expectedOutput []byte) bool

Examples

Package (Oprf)

Package files

client.go keys.go oprf.go server.go

Variables

var (
    ErrInvalidSuite       = errors.New("invalid suite")
    ErrInvalidMode        = errors.New("invalid mode")
    ErrDeriveKeyPairError = errors.New("key pair derivation failed")
    ErrInvalidInput       = errors.New("invalid input")
    ErrInvalidInfo        = errors.New("invalid info")
    ErrInvalidProof       = errors.New("proof verification failed")
    ErrInverseZero        = errors.New("inverting a zero value")
    ErrNoKey              = errors.New("must provide a key")
)

type Blind 

type Blind = group.Scalar

type Blinded 

type Blinded = group.Element

type Client 

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

func NewClient 

func NewClient(s Suite) Client

func (Client) Blind 

func (c Client) Blind(inputs [][]byte) (*FinalizeData, *EvaluationRequest, error)

func (Client) DeterministicBlind 

func (c Client) DeterministicBlind(inputs [][]byte, blinds []Blind) (*FinalizeData, *EvaluationRequest, error)

func (Client) Finalize 

func (c Client) Finalize(f *FinalizeData, e *Evaluation) (outputs [][]byte, err error)

type Evaluated 

type Evaluated = group.Element

type Evaluation

Evaluation contains a list of elements produced during server's evaluation, and for verifiable modes it also includes a proof. 

type Evaluation struct {
    Elements []Evaluated
    Proof    *dleq.Proof
}

type EvaluationRequest

EvaluationRequest contains the blinded elements to be evaluated by the Server. 

type EvaluationRequest struct {
    Elements []Blinded
}

type FinalizeData

FinalizeData encapsulates data needed for Finalize step. 

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

func (FinalizeData) CopyBlinds 

func (f FinalizeData) CopyBlinds() []Blind

CopyBlinds copies the serialized blinds to use when deterministically invoking DeterministicBlind.

type Mode 

type Mode = uint8
const (
    BaseMode             Mode = 0x00
    VerifiableMode       Mode = 0x01
    PartialObliviousMode Mode = 0x02
)

type PartialObliviousClient 

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

func NewPartialObliviousClient 

func NewPartialObliviousClient(s Suite, server *PublicKey) PartialObliviousClient

func (PartialObliviousClient) Blind 

func (c PartialObliviousClient) Blind(inputs [][]byte) (*FinalizeData, *EvaluationRequest, error)

func (PartialObliviousClient) DeterministicBlind 

func (c PartialObliviousClient) DeterministicBlind(inputs [][]byte, blinds []Blind) (*FinalizeData, *EvaluationRequest, error)

func (PartialObliviousClient) Finalize 

func (c PartialObliviousClient) Finalize(f *FinalizeData, e *Evaluation, info []byte) (outputs [][]byte, err error)

type PartialObliviousServer 

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

func NewPartialObliviousServer 

func NewPartialObliviousServer(s Suite, key *PrivateKey) PartialObliviousServer

func (PartialObliviousServer) Evaluate 

func (s PartialObliviousServer) Evaluate(req *EvaluationRequest, info []byte) (*Evaluation, error)

func (PartialObliviousServer) FullEvaluate 

func (s PartialObliviousServer) FullEvaluate(input, info []byte) (output []byte, err error)

func (PartialObliviousServer) PublicKey 

func (s PartialObliviousServer) PublicKey() *PublicKey

func (PartialObliviousServer) VerifyFinalize 

func (s PartialObliviousServer) VerifyFinalize(input, info, expectedOutput []byte) bool

type PrivateKey 

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

func DeriveKey 

func DeriveKey(s Suite, mode Mode, seed, info []byte) (*PrivateKey, error)

DeriveKey generates a private key from a given seed and optional info string.

func GenerateKey 

func GenerateKey(s Suite, rnd io.Reader) (*PrivateKey, error)

GenerateKey generates a private key compatible with the suite.

func (*PrivateKey) MarshalBinary 

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

func (*PrivateKey) Public 

func (k *PrivateKey) Public() *PublicKey

func (*PrivateKey) UnmarshalBinary 

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

type PublicKey 

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

func (*PublicKey) MarshalBinary 

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

func (*PublicKey) UnmarshalBinary 

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

type Server 

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

func NewServer 

func NewServer(s Suite, key *PrivateKey) Server

func (Server) Evaluate 

func (s Server) Evaluate(req *EvaluationRequest) (*Evaluation, error)

func (Server) FullEvaluate 

func (s Server) FullEvaluate(input []byte) (output []byte, err error)

func (Server) PublicKey 

func (s Server) PublicKey() *PublicKey

func (Server) VerifyFinalize 

func (s Server) VerifyFinalize(input, expectedOutput []byte) bool

type Suite 

type Suite interface {
    Identifier() string
    Group() group.Group
    Hash() crypto.Hash
    // contains filtered or unexported methods
}
var (
    // SuiteRistretto255 represents the OPRF with Ristretto255 and SHA-512
    SuiteRistretto255 Suite = params{/* contains filtered or unexported fields */}
    // SuiteP256 represents the OPRF with P-256 and SHA-256.
    SuiteP256 Suite = params{/* contains filtered or unexported fields */}
    // SuiteP384 represents the OPRF with P-384 and SHA-384.
    SuiteP384 Suite = params{/* contains filtered or unexported fields */}
    // SuiteP521 represents the OPRF with P-521 and SHA-512.
    SuiteP521 Suite = params{/* contains filtered or unexported fields */}
)

func GetSuite 

func GetSuite(identifier string) (Suite, error)

type VerifiableClient 

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

func NewVerifiableClient 

func NewVerifiableClient(s Suite, server *PublicKey) VerifiableClient

func (VerifiableClient) Blind 

func (c VerifiableClient) Blind(inputs [][]byte) (*FinalizeData, *EvaluationRequest, error)

func (VerifiableClient) DeterministicBlind 

func (c VerifiableClient) DeterministicBlind(inputs [][]byte, blinds []Blind) (*FinalizeData, *EvaluationRequest, error)

func (VerifiableClient) Finalize 

func (c VerifiableClient) Finalize(f *FinalizeData, e *Evaluation) (outputs [][]byte, err error)

type VerifiableServer 

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

func NewVerifiableServer 

func NewVerifiableServer(s Suite, key *PrivateKey) VerifiableServer

func (VerifiableServer) Evaluate 

func (s VerifiableServer) Evaluate(req *EvaluationRequest) (*Evaluation, error)

func (VerifiableServer) FullEvaluate 

func (s VerifiableServer) FullEvaluate(input []byte) (output []byte, err error)

func (VerifiableServer) PublicKey 

func (s VerifiableServer) PublicKey() *PublicKey

func (VerifiableServer) VerifyFinalize 

func (s VerifiableServer) VerifyFinalize(input, expectedOutput []byte) bool