opaque

package module
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.

Source Files

View all Source files

Directories

Path Synopsis
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.
Package message provides message structures for the OPAQUE protocol.
 Package message provides message structures for the OPAQUE protocol.

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.