opaque

package module
Version: v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Aug 17, 2021 License: MIT Imports: 13 Imported by: 0

README

OPAQUE

OPAQUE Go Reference codecov FOSSA Status

This package implements the asymmetric password-authenticated key exchange protocol as in the latest Internet Draft.

OPAQUE enables a client to authenticate to a server without ever revealing its password, with strong security guarantees. The server and client share a nice session secret on successful authentication.

Installation

  go get github.com/bytemare/opaque@v0.6.0

Usage

You can find the documentation and usage examples in the project wiki and the package doc.

Versioning

SemVer is used for versioning. For the versions available, see the tags on the repository.

Minor v0.x versions match the corresponding CFRG draft version, the master branch implements the latest changes of the draft development.

Contributing

Please read CONTRIBUTING.md for details on the code of conduct, and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package opaque implements the OPAQUE asymmetric password-authenticated key exchange protocol.

OPAQUE is an asymmetric Password Authenticated Key Exchange (PAKE).

This package implements the official OPAQUE definition. For protocol details, please refer to the IETF protocol document at https://datatracker.ietf.org/doc/draft-irtf-cfrg-opaque.

Index

Constants

View Source
const (
	// RistrettoSha512 identifies the Ristretto255 group and SHA-512.
	RistrettoSha512 = Group(oprf.RistrettoSha512)

	// P256Sha256 identifies the NIST P-256 group and SHA-256.
	P256Sha256 = Group(oprf.P256Sha256)

	// P384Sha512 identifies the NIST P-384 group and SHA-512.
	P384Sha512 = Group(oprf.P384Sha512)

	// P521Sha512 identifies the NIST P-512 group and SHA-512.
	P521Sha512 = Group(oprf.P521Sha512)
)

Variables

View Source
var (
	// ErrAkeInvalidClientMac indicates that the MAC contained in the KE3 message is not valid in the given session.
	ErrAkeInvalidClientMac = errors.New("failed to authenticate client: invalid client mac")

	// ErrInvalidState indicates that the given state is not valid due to a wrong length.
	ErrInvalidState = errors.New("invalid state length")
)

Functions

func GetFakeEnvelope

func GetFakeEnvelope(c *Configuration) []byte

GetFakeEnvelope returns a byte array filled with 0s the length of a legitimate envelope size in the configuration's mode. This fake envelope byte array is used in the client enumeration mitigation scheme.

Types

type Client

type Client struct {
	Core *envelope.Core
	Ake  *ake.Client
	Ke1  *message.KE1
	*internal.Parameters
	// contains filtered or unexported fields
}

Client represents an OPAQUE Client, exposing its functions and holding its state.

func NewClient

func NewClient(p *Configuration) *Client

NewClient returns a new Client instantiation given the application Configuration.

func (*Client) DeserializeKE1

func (c *Client) DeserializeKE1(ke1 []byte) (*message.KE1, error)

DeserializeKE1 takes a serialized KE1 message and returns a deserialized KE1 structure.

func (*Client) DeserializeKE2

func (c *Client) DeserializeKE2(ke2 []byte) (*message.KE2, error)

DeserializeKE2 takes a serialized KE2 message and returns a deserialized KE2 structure.

func (*Client) DeserializeKE3

func (c *Client) DeserializeKE3(ke3 []byte) (*message.KE3, error)

DeserializeKE3 takes a serialized KE3 message and returns a deserialized KE3 structure.

func (*Client) Finish

func (c *Client) Finish(idc, ids []byte, ke2 *message.KE2) (ke3 *message.KE3, exportKey []byte, err error)

Finish returns a KE3 message given the server's KE2 response message and the identities. If the idc or ids parameters are nil, the client and server's public keys are taken as identities for both.

func (*Client) Init

func (c *Client) Init(password []byte) *message.KE1

Init initiates the authentication process, returning a KE1 message blinding the given password. clientInfo is optional client information sent in clear, and only authenticated in KE3.

func (*Client) KeyGen

func (c *Client) KeyGen() (secretKey, publicKey []byte)

KeyGen returns a key pair in the AKE group. It can then be used for the external mode.

func (*Client) RegistrationFinalize

func (c *Client) RegistrationFinalize(clientSecretKey []byte, creds *Credentials,
	resp *message.RegistrationResponse) (upload *message.RegistrationRecord, exportKey []byte, err error)

RegistrationFinalize returns a RegistrationRecord message given the server's RegistrationResponse and credentials. If the envelope mode is internal, then clientSecretKey is ignored and can be set to nil. For the external mode, clientSecretKey must be the client's private key for the AKE.

func (*Client) RegistrationInit

func (c *Client) RegistrationInit(password []byte) *message.RegistrationRequest

RegistrationInit returns a RegistrationRequest message blinding the given password.

func (*Client) SessionKey

func (c *Client) SessionKey() []byte

SessionKey returns the session key if the previous call to Finish() was successful.

type ClientRecord

type ClientRecord struct {
	CredentialIdentifier []byte
	ClientIdentity       []byte
	*message.RegistrationRecord

	// testing
	TestMaskNonce []byte
}

ClientRecord is a server-side structure enabling the storage of user relevant information.

type Configuration

type Configuration struct {
	// Context is optional shared information to include in the AKE transcript.
	Context []byte

	// KDF identifies the hash function to be used for key derivation (e.g. HKDF).
	KDF crypto.Hash `json:"kdf"`

	// MAC identifies the hash function to be used for message authentication (e.g. HMAC).
	MAC crypto.Hash `json:"mac"`

	// Hash identifies the hash function to be used for hashing, as defined in github.com/bytemare/crypto/hash.
	Hash crypto.Hash `json:"hash"`

	// OPRF identifies the ciphersuite to use for the OPRF.
	OPRF Group `json:"oprf"`

	// MHF identifies the memory-hard function for expensive key derivation on the client,
	// defined in github.com/bytemare/crypto/mhf.
	MHF mhf.Identifier `json:"mhf"`

	// Mode identifies the envelope mode to be used.
	Mode Mode `json:"mode"`

	// AKE identifies the group to use for the AKE.
	AKE Group `json:"group"`
}

Configuration represents an OPAQUE configuration. Note that OprfGroup and AKEGroup are recommended to be the same, as well as KDF, MAC, Hash should be the same.

func DefaultConfiguration

func DefaultConfiguration() *Configuration

DefaultConfiguration returns a default configuration with strong parameters.

func DeserializeConfiguration

func DeserializeConfiguration(encoded []byte) (*Configuration, error)

DeserializeConfiguration decodes the input and returns a Parameter structure. This assumes that the encoded parameters are valid, and will not be checked.

func (*Configuration) Client

func (c *Configuration) Client() *Client

Client returns a newly instantiated Client from the Configuration.

func (*Configuration) Serialize

func (c *Configuration) Serialize() []byte

Serialize returns the byte encoding of the Configuration structure.

func (*Configuration) Server

func (c *Configuration) Server() *Server

Server returns a newly instantiated Server from the Configuration.

type Credentials

type Credentials struct {
	Client, Server              []byte
	TestEnvNonce, TestMaskNonce []byte
}

Credentials holds the client and server ids (will certainly disappear in next versions°.

type Group

type Group byte

Group identifies the prime-order group with hash-to-curve capability to use in OPRF and AKE.

type Mode

type Mode byte

Mode designates OPAQUE's envelope mode.

const (
	// Internal designates the internal mode.
	Internal Mode = iota + 1

	// External designates the external mode.
	External
)

type Server

type Server struct {
	*internal.Parameters
	Ake *ake.Server
}

Server represents an OPAQUE Server, exposing its functions and holding its state.

func NewServer

func NewServer(p *Configuration) *Server

NewServer returns a Server instantiation given the application Configuration.

func (*Server) DeserializeKE1

func (s *Server) DeserializeKE1(ke1 []byte) (*message.KE1, error)

DeserializeKE1 takes a serialized KE1 message and returns a deserialized KE1 structure.

func (*Server) DeserializeKE2

func (s *Server) DeserializeKE2(ke2 []byte) (*message.KE2, error)

DeserializeKE2 takes a serialized KE2 message and returns a deserialized KE2 structure.

func (*Server) DeserializeKE3

func (s *Server) DeserializeKE3(ke3 []byte) (*message.KE3, error)

DeserializeKE3 takes a serialized KE3 message and returns a deserialized KE3 structure.

func (*Server) DeserializeRegistrationRecord

func (s *Server) DeserializeRegistrationRecord(registrationUpload []byte) (*message.RegistrationRecord, error)

DeserializeRegistrationRecord takes a serialized RegistrationRecord message and returns a deserialized RegistrationRecord structure.

func (*Server) DeserializeRegistrationRequest

func (s *Server) DeserializeRegistrationRequest(registrationRequest []byte) (*message.RegistrationRequest, error)

DeserializeRegistrationRequest takes a serialized RegistrationRequest message and returns a deserialized RegistrationRequest structure.

func (*Server) DeserializeRegistrationResponse

func (s *Server) DeserializeRegistrationResponse(registrationResponse []byte) (*message.RegistrationResponse, error)

DeserializeRegistrationResponse takes a serialized RegistrationResponse message and returns a deserialized RegistrationResponse structure.

func (*Server) ExpectedMAC

func (s *Server) ExpectedMAC() []byte

ExpectedMAC returns the expected client MAC if the previous call to Init() was successful.

func (*Server) Finish

func (s *Server) Finish(ke3 *message.KE3) error

Finish returns an error if the KE3 received from the client holds an invalid mac, and nil if correct.

func (*Server) Init

func (s *Server) Init(ke1 *message.KE1, serverIdentity, serverSecretKey, serverPublicKey, oprfSeed []byte,
	record *ClientRecord) (*message.KE2, error)

Init responds to a KE1 message with a KE2 message given server credentials and client record.

func (*Server) KeyGen

func (s *Server) KeyGen() (secretKey, publicKey []byte)

KeyGen returns a key pair in the AKE group.

func (*Server) RegistrationResponse

func (s *Server) RegistrationResponse(req *message.RegistrationRequest,
	serverPublicKey, credentialIdentifier, oprfSeed []byte) (*message.RegistrationResponse, error)

RegistrationResponse returns a RegistrationResponse message to the input RegistrationRequest message and given identifiers.

func (*Server) SerializeState

func (s *Server) SerializeState() []byte

SerializeState returns the internal state of the AKE server serialized to bytes.

func (*Server) SessionKey

func (s *Server) SessionKey() []byte

SessionKey returns the session key if the previous call to Init() was successful.

func (*Server) SetAKEState

func (s *Server) SetAKEState(state []byte) error

SetAKEState sets the internal state of the AKE server from the given bytes.

Directories

Path Synopsis
Package message provides message structures for the OPAQUE protocol.
Package message provides message structures for the OPAQUE protocol.
Package internal provides structures and functions to operate OPAQUE that are not part of the public API.
Package internal provides structures and functions to operate OPAQUE that are not part of the public API.
ake
Package ake provides high-level functions for the 3DH AKE.
Package ake provides high-level functions for the 3DH AKE.
encoding
Package encoding provides encoding utilities.
Package encoding provides encoding utilities.
envelope
Package envelope provides utility functions and structures allowing credential management.
Package envelope provides utility functions and structures allowing credential management.
message
Package message provides the internal credential recovery messages.
Package message provides the internal credential recovery messages.
oprf
Package oprf implements the Elliptic Curve Oblivious Pseudorandom Function (EC-OPRF) from https://tools.ietf.org/html/draft-irtf-cfrg-voprf.
Package oprf implements the Elliptic Curve Oblivious Pseudorandom Function (EC-OPRF) from https://tools.ietf.org/html/draft-irtf-cfrg-voprf.
tag
Package tag provides the static tag strings to OPAQUE.
Package tag provides the static tag strings to OPAQUE.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL