migp

package
v0.0.0-...-c364ba8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2021 License: BSD-3-Clause Imports: 14 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	// DefaultMIGPVersion gives the version of the MIGP library and
	// parameter set.  Compatibility across versions is not guaranteed.
	DefaultMIGPVersion = 1

	// DefaultBucketIDBitSize is the number of high-order bits of the
	// bucket hash to use for the bucket identifier. The max size of this
	// field is 32 to allow the bucket identifier to be stored as a uint32.
	DefaultBucketIDBitSize = 20

	// Default cryptographic parameters for this version of MIGP
	DefaultBucketHasher    = BucketHasherSHA256
	DefaultSlowHasher      = SlowHasherScrypt
	DefaultBucketEncryptor = BucketEncryptorHKDFSHA256
	DefaultOPRFSuite       = uint16(oprf.OPRFP256)

	// CtxtKeyCheckSize is the size of key check string in bytes. We use this
	// to check if a given bucket entry header matches the derived key.
	CtxtKeyCheckSize = 20

	// HeaderSize is the size of a MIGP entry header in bytes. The header
	// consists of the key check bytes, 1-byte flag, and 4-byte body
	// length.
	HeaderSize = CtxtKeyCheckSize + 5
)
View Source 
const (
	BucketHasherSHA256 uint16 = 0x0001

	BucketHashSalt = "MIGP bucket"
)
View Source 
const (
	SlowHasherNull   uint16 = 0x0000
	SlowHasherScrypt uint16 = 0x0001
)
View Source 
const (
	SlowHashSalt = "MIGP slow hash"
	SlowHashLen  = 32    // scrypt number of bytes of output to request
	ScryptN      = 16384 // scrypt N
	Scryptr      = 8     // scrypt r
	Scryptp      = 1     // scrypt p
)
View Source 
const (
	BucketEncryptorHKDFSHA256 uint16 = 0x0001
)

Variables

View Source 
var (
	DerivePadHeaderSalt = []byte("MIGP derive pad header")
	DerivePadBodySalt   = []byte("MIGP derive pad body")
)
View Source 
var (
	OprfInfo = []byte("MIGP oprf info")
)

Functions

func BucketIDToHex 

func BucketIDToHex(bucketID uint32) string

BucketIDToHex encodes a uint32 bucket ID to a hex string

func NewHKDFSHA256BucketEncryptor 

func NewHKDFSHA256BucketEncryptor() hkdfSHA256BucketEncryptor

NewHKDFSHA256BucketEncryptor returns a new key-commiting AEAD based on HKDF-SHA256 key derivation and XOR-based encryption

func NewNullSlowHasher 

func NewNullSlowHasher() nullSlowHasher

NewNullSlowHasher returns a no-op implementation of the SlowHasher interface

func NewSHA256BucketHasher 

func NewSHA256BucketHasher() sha256BucketHasher

NewSHA256BucketHasher returns a BucketHasher that uses SHA256 with a fixed salt for computing a hash of a bucket.

func NewScryptSlowHasher 

func NewScryptSlowHasher() scryptSlowHasher

NewScryptSlowHasher returns a SlowHasher instance using Scrypt with the following parameters from Google's mundane: - N: 16384 - r: 8 - p: 1 See: https://github.com/google/mundane/blob/master/src/password.rs#L68

Types

type BreachStatus 

type BreachStatus uint8

BreachStatus indicates the status of (username, password) tuple with respect to known breaches, e.g., whether or not the pair exists in a known breach, a similar password exists in a known breach, or it's not in a breach at all. 

const (
	// NotInBreach indicates the target tuple was not in a known breach.
	NotInBreach BreachStatus = iota
	// InBreach indicates the target tuple was in a known breach.
	InBreach
	// SimilarInBreach indicates that a pair with a similar password to
	// the target tuple was in a known breach.
	SimilarInBreach
	// UsernameInBreach indicates the target username has at least one
	// associated password in a known breach.
	UsernameInBreach
)

func Query 

func Query(cfg Config, targetURL string, username, password []byte) (BreachStatus, []byte, error)

Query submits a MIGP query to the target MIGP server.

func (BreachStatus) String 

func (bs BreachStatus) String() string

String returns a string representation of a breach status

type BucketEncryptor 

type BucketEncryptor interface {
	ID() uint16
	Encrypt(secret []byte, metadataFlag MetadataType, metadata []byte) (ciphertext []byte, err error)
	DecryptHeader(secret []byte, ciphertext []byte) (keyCheck bool, flag MetadataType, bodyLength int, err error)
	DecryptBody(secret []byte, ciphertext []byte) (body []byte, err error)
}

BucketEncryptor is a generic interface for a bucket encryption algorithm.

func NewBucketEncryptor 

func NewBucketEncryptor(id uint16) (BucketEncryptor, error)

NewBucketEncryptor returns a bucket encryptor given its ID

type BucketHasher 

type BucketHasher interface {
	ID() uint16
	Hash([]byte) []byte
}

BucketHasher is a generic interface for a cryptographic hash algorithm that computes a bucket identifier

func NewBucketHasher 

func NewBucketHasher(id uint16) (BucketHasher, error)

NewBucketHasher returns an hasher given its ID

type Client 

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

Client wraps the relevant context needed to generate MIGP requests.

func NewClient 

func NewClient(cfg Config) (*Client, error)

func (*Client) BucketID 

func (c *Client) BucketID(username []byte) uint32

BucketID returns the bucket ID for the given username

func (Client) Request 

func (c Client) Request(username, password []byte) (ClientRequest, ClientRequestContext, error)

Request generates a client request byte string and a ClientRequest struct, given a username and password

type ClientRequest 

type ClientRequest struct {
	Version      uint32 `json:"version"`
	BucketID     string `json:"bucketID"`
	BlindElement []byte `json:"blindElement"`
}

ClientRequest carries the information the server needs to perform an evaluation

type ClientRequestContext 

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

ClientRequestContext wraps the context needed to process MIGP responses to produce the request (username, password) breach status and associated metadata (if available). Not all breach entries will have metadata.

func (ClientRequestContext) Finalize 

func (ctx ClientRequestContext) Finalize(response ServerResponse) (BreachStatus, []byte, error)

Finalize parses a response message from server, completes the computation of the OPRF value, determines if it is in the received bucket, and decrypts the associated ciphertext

type Config 

type Config struct {
	Version           uint16       `json:"version"`
	BucketIDBitSize   int          `json:"bucketIDBitSize"`
	BucketHasherID    uint16       `json:"bucketHasher"`
	SlowHasherID      uint16       `json:"slowHasher"`
	BucketEncryptorID uint16       `json:"bucketEncryptor"`
	OPRFSuite         oprf.SuiteID `json:"oprfSuite"`
}

Config contains MIGP configuration used both clients and servers.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a new default configuration

type Getter 

type Getter interface {
	Get(id string) ([]byte, error)
}

Getter defines the interface needed for fetching bucket items to insert into a response. The caller should define an implementation of this interface appropriate for their deployment.

type MetadataType 

type MetadataType uint8

Flag represents the type of metadata for a breach item. 

const (
	// Dummy means the metadata was dummy data (used for length-hiding purposes)
	MetadataDummy MetadataType = iota
	// MetadataBreachedPassword means the (username, password) tuple corresponds to a breached password
	MetadataBreachedPassword
	// MetadataSimilarPassword means the (username, password) tuple is similar to a breached password
	MetadataSimilarPassword
	// MetadataBreachedUsername means the username has at least one breached password
	MetadataBreachedUsername
)

func (MetadataType) String 

func (mt MetadataType) String() string

String returns a string representation of a metadata type

func (MetadataType) ToBreachStatus 

func (mt MetadataType) ToBreachStatus() BreachStatus

ToBreachStatus converts a metadata type to a breach status

func (MetadataType) Valid 

func (mt MetadataType) Valid() bool

Valid checks if the metadata type is recognized by the library

type Server 

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

Server implements the server-side functionality of MIGP, with two primary functionalities: FullEvaluate, to evaluate a (username, password) tuple and store it in the backing database, and HandleRequest, to process a Client request and return the corresponding bucket data.

func NewServer 

func NewServer(cfg ServerConfig) (*Server, error)

NewServer initializes and returns a new MIGP server from the given configuration

func (*Server) BucketID 

func (s *Server) BucketID(username []byte) uint32

BucketID returns the bucket ID for the given username

func (*Server) Config 

func (s *Server) Config() *ServerConfig

Config returns an inspectable ServerConfig associated with the given server.

func (*Server) EncryptBucketEntry 

func (s *Server) EncryptBucketEntry(username, password []byte, metadataFlag MetadataType, metadata []byte) ([]byte, error)

EncryptBucketEntry performs the full OPRF and encryption of metadata, without any blinding steps. This is useful for precomputing the buckets of encrypted items. The return value is the bucket ID (2 byte hash of username) as well as the ciphertext, both encoded as byte slices.

func (*Server) HandleRequest 

func (s *Server) HandleRequest(request ClientRequest, kv Getter) (ServerResponse, error)

HandleRequest takes as input a client request buffer and kv that implements the Getter interface. The request is a JSON encoding of a bucket identifier and oprf.IntValue (a blinded group element) Should return a new IntValue (input group element multiplied by server's secret key) plus the bucket contents associated to the bucket identifier Returns a byte string that is a protobuf encoding of an oprf.IntValue (the Eval'd blinded value) plus the associated bucket

type ServerConfig 

type ServerConfig struct {
	Config
	PrivateKey *oprf.PrivateKey
}

ServerConfig stores all version information associated with a given server. ServerConfig implements the json.Marshal and json.Unmarshal interfaces.

func DefaultServerConfig 

func DefaultServerConfig() ServerConfig

DefaultServerConfig generates a new default server state with a freshly keyed OPRF instance.

func (*ServerConfig) MarshalJSON 

func (c *ServerConfig) MarshalJSON() ([]byte, error)

MarshalJSON serializes a server configuration to JSON

func (*ServerConfig) UnmarshalJSON 

func (c *ServerConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes a server configuration from JSON

type ServerResponse 

type ServerResponse struct {
	Version          uint32 `json:"version"`
	EvaluatedElement []byte `json:"evaluatedElement"`
	BucketContents   []byte `json:"bucketContents"`
}

ServerResponse wraps up the server's response state.

func (*ServerResponse) MarshalBinary 

func (r *ServerResponse) MarshalBinary() ([]byte, error)

MarshalBinary marshals the server response in the following binary format: <32-bit version>|<evaluated-element>|<bucket-contents>

func (*ServerResponse) UnmarshalBinary 

func (r *ServerResponse) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals the server response from the following binary format: <32-bit version>|<evaluated-element>|<bucket-contents>

type SlowHasher 

type SlowHasher interface {
	ID() uint16
	Hash([]byte) []byte
}

SlowHasher is a generic interface for a slow (memory hard) hash algorithm

func NewSlowHasher 

func NewSlowHasher(id uint16) (SlowHasher, error)

NewHasher returns an slow hasher given its ID

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.