ukey2

README

Ukey2

This is an implementation of ukey2 protocol in Go. The java implementation of the same can be found at google/ukey2

Protocol

sequenceDiagram
    Client->>Server: UKEY2 ClientInit
    Server->>Client: UKEY2 ServerInit
    Client->>Server: UKEY2 ClientFinish
    Note over Server, Client: Client and Server now derive auth key

    Client->Server: Out of band verification of auth key

    Note over Server, Client: Client and Server now derive next protocol secret
    Note over Server, Client: All following packets are encrypted

Usage

Client

client := ukey2.ForInitiator(ukey2.P256_SHA512)
clientInit, err := client.GetNextHandshakeMessage()
if err != nil {
	// handle error
}
sendMessageToServer(clientInit)
serverInit := receiveMessageFromServer()
_, _, err = client.ParseHandshakeMessage(serverInit)
if err != nil {
	// handle error
}
clientFinish, err := client.GetNextHandshakeMessage()
if err != nil {
	// handle error
}
sendMessageToServer(clientFinish)
verificationString := client.getVerificationString()

// show string to user and verify the key with server key and get confirmation from user
showStringToUser(verificationString)
// call VerifyHandshake once user confirmation received
client.VerifyHandshake()

cc, err := client.ToConnectionContext()
if err != nil {
	// handle error
}
ccv1 := cc.(*d2d.D2DConnectionContextV1)
helloFromClient := ccv1.EncodeMessageToPeer(ccv1, []byte("hello from client"))
// send encrypted message to server
sendMessageToServer(helloFromClient)

serverResponse := receiveMessageFromServer()

helloFromServer, err := ccv1.DecodeMessageFromPeer(ccv1, serverResponse)

if err != nil {
	// handle error
}

Server

server := ukey2.ForResponder(ukey2.P256_SHA512)

clientInit := receiveMessageFromClient()
ok, _, err := server.ParseHandshakeMessage(clientInit)
if ok != true || err != nil {
	// handle error
}
serverInit, err := server.GetNextHandshakeMessage()
if err != nil {
	// handle error
}

sendMessageToClient(serverInit)

clientFinish := receiveMessageFromClient()

_, _, err = server.ParseHandshakeMessage(clientFinish)
if err != nil {
	// handle error
}
verificationString := client.getVerificationString()

// show string to user and verify the key with client key and get confirmation from user
showStringToUser(verificationString)
// call VerifyHandshake once user confirmation received
cc, err := server.ToConnectionContext()
if err != nil {
	// handle error
}
ccv1 := cc.(*d2d.D2DConnectionContextV1)

clientMessage := receiveMessageFromClient() //receive encrypted message from client
helloFromClient, _ := ccv1.DecodeMessageFromPeer(ccv1, clientMessage) // decrypt clientMessage
helloFromServer := ccv1.EncodeMessageToPeer(ccv1, []byte("hello from server")) // encrypt a server message
sendMessageToClient(helloFromServer) // send encrypted message to client

Documentation

Index

• Constants
• type HandShakeCipher
• type State
• type UKey2Handshake
  • func ForInitiator(cipher HandShakeCipher) *UKey2Handshake
  • func ForResponder(cipher HandShakeCipher) *UKey2Handshake
  • func (u *UKey2Handshake) GetHandshakeState() (State, error)
  • func (u *UKey2Handshake) GetNextHandshakeMessage() ([]byte, error)
  • func (u *UKey2Handshake) GetVerificationString(byteLength int) ([]byte, error)
  • func (u *UKey2Handshake) ParseHandshakeMessage(message []byte) (bool, []byte, error)
  • func (u *UKey2Handshake) ToConnectionContext() (d2d.D2DConnectionContext, error)
  • func (u *UKey2Handshake) VerifyHandshake() error

Constants

const (
	CLIENT_START handshakeState = iota
	CLIENT_WAITING_FOR_SERVER_INIT
	CLIENT_AFTER_SERVER_INIT

	// Responder/server state
	SERVER_START
	SERVER_AFTER_CLIENT_INIT
	SERVER_WAITING_FOR_CLIENT_FINISHED

	// Common completion state
	HANDSHAKE_VERIFICATION_NEEDED
	HANDSHAKE_VERIFICATION_IN_PROGRESS
	HANDSHAKE_FINISHED
	HANDSHAKE_ALREADY_USED
	HANDSHAKE_ERROR
)

const (
	CLIENT handshakeRole = iota
	SERVER
)

Types

type HandShakeCipher

type HandShakeCipher int32

const (
	P256_SHA512 HandShakeCipher = 100
)

type State

type State int

const (
	IN_PROGRESS State = iota
	VERIFICATION_NEEDED
	VERIFICATION_IN_PROGRESS
	FINISHED
	ALREADY_USED
	ERROR
	UNKNOWN = -1
)

type UKey2Handshake

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

func ForInitiator

func ForInitiator(cipher HandShakeCipher) *UKey2Handshake

func ForResponder

func ForResponder(cipher HandShakeCipher) *UKey2Handshake

func (*UKey2Handshake) GetHandshakeState

func (u *UKey2Handshake) GetHandshakeState() (State, error)

func (*UKey2Handshake) GetNextHandshakeMessage

func (u *UKey2Handshake) GetNextHandshakeMessage() ([]byte, error)

func (*UKey2Handshake) GetVerificationString

func (u *UKey2Handshake) GetVerificationString(byteLength int) ([]byte, error)

func (*UKey2Handshake) ParseHandshakeMessage

func (u *UKey2Handshake) ParseHandshakeMessage(message []byte) (bool, []byte, error)

func (*UKey2Handshake) ToConnectionContext

func (u *UKey2Handshake) ToConnectionContext() (d2d.D2DConnectionContext, error)

func (*UKey2Handshake) VerifyHandshake

func (u *UKey2Handshake) VerifyHandshake() error