opaque

README

OPAQUE in Go

This repo contains a Go implementation of OPAQUE, a password authenticated key exchange protocol described in [1] and [2].

Important note: This code has been written for educational purposes only. No experts in cryptography or IT security have reviewed it. Do not use it for anything important.

Installation

go get -u github.com/frekui/opaque

Documentation

https://godoc.org/github.com/frekui/opaque

Testing

./run-tests.sh

Examples

The repo contains a sample client and server that authenticates each other using package opaque.

License

Copyright (c) 2018 Fredrik Kuivinen, frekui@gmail.com. Use of this source code is governed by the BSD-style license that can be found in the LICENSE file.

References

[1] https://tools.ietf.org/html/draft-krawczyk-cfrg-opaque-00

[2] Jarecki, S., Krawczyk, H., and J. Xu, "OPAQUE: An Asymmetric PAKE Protocol Secure Against Pre-Computation Attacks", Eurocrypt , 2018. (Full version available at https://eprint.iacr.org/2018/163)

Documentation

Overview

Package opaque contains an implementation of OPAQUE, a password authenticated key exchange protocol described. OPAQUE is described in [1] and [2].

OPAQUE can be split into two parts, a password registration protocol and a protocol for authentication once the user's password has been registered. It's assumed that the password registration protocol runs over an authentication connection (the authentication protocol does, of course, not have such an assumption). The client initiates the password registration protocol by calling PwRegInit. Similarly, the authentication protocol is initiated by the client calling AuthInit.

If the authentication protocol finishes successfully a newly generated random secret is shared between the client and server. The secret can be used to protect any future communication between the peers.

A number of structs with messages for the two protocols (AuthMsg1, AuthMsg2, AuthMsg3, PwRegMsg1, PwRegMsg2, PwRegMsg3) are defined in this package. It's up to the user of the package to serialize and deserialize these structs and send them from the client/server to the peer on the other end. In the example server and client (cmd/server and cmd/client) the messages are serialized using JSON, which is simple and works but isn't the most efficient option.

IMPORTANT NOTE: This code has been written for educational purposes only. No experts in cryptography or IT security have reviewed it. Do not use it for anything important.

[1] https://tools.ietf.org/html/draft-krawczyk-cfrg-opaque-00

[2] Jarecki, S., Krawczyk, H., and J. Xu, "OPAQUE: An Asymmetric PAKE Protocol Secure Against Pre-Computation Attacks", Eurocrypt , 2018. (Full version available at https://eprint.iacr.org/2018/163)

Index

• func Auth1(privS *rsa.PrivateKey, user *User, msg1 AuthMsg1) (*AuthServerSession, AuthMsg2, error)
• func Auth3(sess *AuthServerSession, msg3 AuthMsg3) (secret []byte, err error)
• func AuthInit(username, password string) (*AuthClientSession, AuthMsg1, error)
• func PwReg1(privS *rsa.PrivateKey, msg1 PwRegMsg1) (*PwRegServerSession, PwRegMsg2, error)
• func PwRegInit(username, password string, bits int) (*PwRegClientSession, PwRegMsg1, error)
• type AuthClientSession
• type AuthMsg1
• type AuthMsg2
• type AuthMsg3
  • func Auth2(sess *AuthClientSession, msg2 AuthMsg2) (secret []byte, msg3 AuthMsg3, err error)
• type AuthServerSession
• type PwRegClientSession
• type PwRegMsg1
• type PwRegMsg2
• type PwRegMsg3
  • func PwReg2(sess *PwRegClientSession, msg2 PwRegMsg2) (PwRegMsg3, error)
• type PwRegServerSession
• type User
  • func PwReg3(sess *PwRegServerSession, msg3 PwRegMsg3) *User

Functions

func Auth1

func Auth1(privS *rsa.PrivateKey, user *User, msg1 AuthMsg1) (*AuthServerSession, AuthMsg2, error)

Auth1 is the processing done by the server when it receives an AuthMsg1 struct. On success a nil error is returned together with a AuthServerSession and an AuthMsg2 struct. The AuthMsg2 struct should be sent to the client.

privS is the server's private RSA key. It can be the same for all users. The user argument needs to be created by the server (e.g., by looking it up based on msg1.Username).

A non-nil error is returned on failure.

See also AuthInit, Auth2, and Auth3.

func Auth3

func Auth3(sess *AuthServerSession, msg3 AuthMsg3) (secret []byte, err error)

Auth3 is the processing done by the server when it receives an AuthMsg3 struct. On success a nil error is returned together with a secret. On successful completion the secret returned by this function is equal to the secret returned by Auth2 invoked on the client. Auth3 is the final round in the authentication protocol.

If Auth3 returns a nil error the server has authenticated the client (i.e., the client has proved to the server that it posses information used when the password registration protocol ran for this user).

A non-nil error is returned on failure.

See also AuthInit, Auth1, and Auth2.

func AuthInit

func AuthInit(username, password string) (*AuthClientSession, AuthMsg1, error)

AuthInit initiates the authentication protocol. It's run on the client and, on success, returns a nil error, a client auth session, and an AuthMsg1 struct. The AuthMsg1 struct should be sent to the server.

A non-nil error is returned on failure.

See also Auth1, Auth2, and Auth3.

func PwReg1

func PwReg1(privS *rsa.PrivateKey, msg1 PwRegMsg1) (*PwRegServerSession, PwRegMsg2, error)

PwReg1 is the processing done by the server when it has received a PwRegMsg1 struct from a client.

privS is the server's private RSA key. It can be the same for all users.

A non-nil error is returned on failure.

See also PwRegInit, PwReg2, and PwReg3.

func PwRegInit

func PwRegInit(username, password string, bits int) (*PwRegClientSession, PwRegMsg1, error)

PwRegInit initiates the password registration protocol. It's invoked by the client. The bits argument specifies the number of bits that should be used in the client-specific RSA key.

On success a nil error is returned together with a client session and a PwRegMsg1 struct. The PwRegMsg1 struct should be sent to the server. A precondition of the password registration protocol is that it's running over an authenticated connection.

A non-nil error is returned on failure.

See also PwReg1, PwReg2, and PwReg3.

Types

type AuthClientSession

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

AuthClientSession keeps track of state needed on the client-side during a run of the authentication protocol.

type AuthMsg1

type AuthMsg1 struct {
	Username string

	// a=H'(x)*g^r
	A *big.Int

	// First message of D-H key-exchange (KE1): g^x
	DhPubClient *big.Int
}

AuthMsg1 is the first message in the authentication protocol. It is sent from the client to the server.

Users of package opaque does not need to read nor write to the A or DhPub field fields in this struct except to serialize and deserialize the struct when it's sent between the peers in the authentication protocol.

type AuthMsg2

type AuthMsg2 struct {

	// v=g^k
	V *big.Int

	// k below is the salt.
	// b=a^k
	B *big.Int

	// EnvU contains data encrypted by the client which is stored
	// server-side.
	EnvU []byte

	// Second message of D-H key-exchange (KE2): g^y, Sig(PrivS; g^x, g^y), Mac(Km1; IdS)
	// g^y
	DhPubServer *big.Int

	// Sig(PrivS; g^x, g^y)
	// RSASSA-PSS is used to compute dhSig.
	DhSig []byte

	// Mac(Km1; IdS)
	DhMac []byte
}

AuthMsg2 is the second message in the authentication protocol. It is sent from the server to the client.

Users of package opaque does not need to read nor write to any fields in this struct except to serialize and deserialize the struct when it's sent between the peers in the authentication protocol.

type AuthMsg3

type AuthMsg3 struct {

	// Third message of D-H key exchange (KE3): Sig(PrivU; g^y, g^x), Mac(Km2; IdU)
	// RSASSA-PSS is used to compute dhSig.
	DhSig []byte

	// Mac(Km2; IdU)
	DhMac []byte
}

AuthMsg3 is the third and final message in the authentication protocol. It is sent from the client to the server.

Users of package opaque does not need to read nor write to any fields in this struct except to serialize and deserialize the struct when it's sent between the peers in the authentication protocol.

func Auth2

func Auth2(sess *AuthClientSession, msg2 AuthMsg2) (secret []byte, msg3 AuthMsg3, err error)

Auth2 is the processing done by the client when it receives an AuthMsg2 struct. On success a nil error is returned together with a secret byte slice and an AuthMsg3 struct. The AuthMsg3 struct should be sent to the server. On a successful completion of the protocol the secret will be shared between the client and the server. Auth2 is the final round in the authentication protocol for the client.

If Auth2 returns a nil error the client has authenticated the server (i.e., the server has proved to the client that it posses information obtained from the password registration protocol for this user).

A non-nil error is returned on failure.

See also InitAuth, Auth1, and Auth3.

type AuthServerSession

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

AuthServerSession keeps track of state needed on the server-side during a run of the authentication protocol.

type PwRegClientSession

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

PwRegClientSession keeps track of state needed on the client-side during a run of the password registration protocol.

type PwRegMsg1

type PwRegMsg1 struct {
	Username string
	R        *big.Int
	A        *big.Int
}

PwRegMsg1 is the first message during password registration. It is sent from the client to the server.

Users of package opaque does not need to read nor write to any fields in this struct except to serialize and deserialize the struct when it's sent between the peers in the authentication protocol.

type PwRegMsg2

type PwRegMsg2 struct {
	V    *big.Int
	B    *big.Int
	PubS *rsa.PublicKey
}

PwRegMsg2 is the second message in password registration. Sent from server to client.

Users of package opaque does not need to read nor write to any fields in this struct except to serialize and deserialize the struct when it's sent between the peers in the authentication protocol.

type PwRegMsg3

type PwRegMsg3 struct {
	EnvU []byte
	PubU *rsa.PublicKey
}

PwRegMsg3 is the third and final message in password registration. Sent from client to server.

Users of package opaque does not need to read nor write to any fields in this struct except to serialize and deserialize the struct when it's sent between the peers in the authentication protocol.

func PwReg2

func PwReg2(sess *PwRegClientSession, msg2 PwRegMsg2) (PwRegMsg3, error)

PwReg2 is invoked on the client when it has received a PwRegMsg2 struct from the server.

A non-nil error is returned on failure.

See also PwRegInit, PwReg1, and PwReg3.

type PwRegServerSession

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

PwRegServerSession keeps track of state needed on the server-side during a run of the password registration protocol.

type User

type User struct {
	// Name of this user.
	Username string

	// OPRF key for this user. This is the salt.
	K *big.Int

	V *big.Int

	// EnvU and PubU are generated by the client during password
	// registration and stored at the server.
	EnvU []byte
	PubU *rsa.PublicKey
}

The User struct is the state that the server needs to store for each registered used. Values of this struct are created by PwReg3.

func PwReg3

func PwReg3(sess *PwRegServerSession, msg3 PwRegMsg3) *User

PwReg3 is invoked on the server after it has received a PwRegMsg3 struct from the client.

The returned User struct should be stored by the server and associated with the username.

See also PwRegInit, PwReg1, and PwReg2.