Documentation ¶
Index ¶
- Constants
- Variables
- func BucketIDToHex(bucketID uint32) string
- func NewHKDFSHA256BucketEncryptor() hkdfSHA256BucketEncryptor
- func NewNullSlowHasher() nullSlowHasher
- func NewSHA256BucketHasher() sha256BucketHasher
- func NewScryptSlowHasher() scryptSlowHasher
- type BreachStatus
- type BucketEncryptor
- type BucketHasher
- type Client
- type ClientRequest
- type ClientRequestContext
- type Config
- type Getter
- type MetadataType
- type Server
- func (s *Server) BucketID(username []byte) uint32
- func (s *Server) Config() *ServerConfig
- func (s *Server) EncryptBucketEntry(username, password []byte, metadataFlag MetadataType, metadata []byte) ([]byte, error)
- func (s *Server) HandleRequest(request ClientRequest, kv Getter) (ServerResponse, error)
- type ServerConfig
- type ServerResponse
- type SlowHasher
Constants ¶
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 )
const ( BucketHasherSHA256 uint16 = 0x0001 BucketHashSalt = "MIGP bucket" )
const ( SlowHasherNull uint16 = 0x0000 SlowHasherScrypt uint16 = 0x0001 )
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 )
const (
BucketEncryptorHKDFSHA256 uint16 = 0x0001
)
Variables ¶
var ( DerivePadHeaderSalt = []byte("MIGP derive pad header") DerivePadBodySalt = []byte("MIGP derive pad body") )
var (
OprfInfo = []byte("MIGP oprf info")
)
Functions ¶
func BucketIDToHex ¶
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 (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 ¶
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 (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.
type Getter ¶
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) 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 ¶
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