package oprf

import "github.com/cloudflare/circl/oprf"

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 RFC-9497 [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] RFC-9497: https://www.rfc-editor.org/info/rfc9497

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
}

Output:

true

Index

Examples

Variables 

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

Types

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 

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

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

type EvaluationRequest 

type EvaluationRequest struct {
	Elements []Blinded
}

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

type FinalizeData 

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

FinalizeData encapsulates data needed for Finalize step.

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 32-byte seed and an 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

Source Files

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

Version
v1.6.1 (latest)
Published
Apr 9, 2025
Platform
linux/amd64
Imports
10 packages
Last checked
2 days ago –

Tools for package owners.