Skip to content

ovip-0010.md

Latest commit

 

History

History
634 lines (411 loc) · 30.6 KB

ovip-0010.md

File metadata and controls

634 lines (411 loc) · 30.6 KB
OVIP: 10
Title: Whisper as Transport Layer
Author: David Riegelnig <david.riegelnig@bitcoinsuisse.com>
Discussions-To: https://community.openvasp.org/#narrow/stream/21-protocol-.2F.20ovip
Status: Accepted
Type: Standard
Created: 2020-06-02

Abstract

This OVIP specifies the transport layer implementation for the OpenVASP protocol using Ethereum Whisper. It is a revision of the initial specification proposed in the OpenVASP White Paper.

Specification

1. Ethereum Whisper

The Whisper messaging system has been developed as part of the Ethereum technology stack but can be used separately from the blockchain. It was designed to provide resilience and strong privacy in a peer-to-peer environment and targets message delivery below five seconds on a global scale.

The online documentation about the Whisper protocol can be found here: https://geth.ethereum.org/docs/whisper/whisper-overview.

2. Definitions

Node
System operating a Whisper node providing the transport layer service for the OpenVASP protocol.

Connection
Two Nodes sharing a common identifier representing a connection and an associated shared key, which can be used to exchange Envelopes containing an encrypted Message. Both Nodes have sent each other a Whisper topic to be used to send Envelopes related to this connection.

Active Node
Node inviting another node to establish a Connection.

Passive Node
Node responding to an invitation, either accepting or denying the Connection.

Initiator
VASP operating the Active Node.

Responder
VASP operating the Passive Node.

Sender
VASP sending an Envelope.

Receiver
VASP receiving an Envelope.

Envelope
Envelopes are the packets sent and received by Whisper nodes. They contain the encrypted Message and metadata for decryption.

Message
Message part of an Envelope, containing the message Payload, metadata and optional signature. Not to be confused with OpenVASP Messages, which are defined on the higher Session Layer.

Payload
Actual message payload within a Message transmitted by an Envelope.

3. Envelope Level

Whisper Envelopes are the packets sent and received by Whisper nodes. Once decoded, they have the following format:

[ Version, Expiry, TTL, Topic, AESNonce, Data, EnvNonce ]

The table below provides an overview about each of these elements and their usage as part of OpenVASP.

Element Description OpenVASP Usage See
Version Currently one byte containing zero As per Whisper default
Expiry UNIX time in seconds As per Whisper default
TTL Time-to-live in seconds As indicated in this document 5./6.
Topic Probabilistic hint about encryption key As indicated in this document 5./6.
AESNonce Salt (96-bit) for symmetric encryption Randomly set for each Envelope
Data Contains encrypted Whisper Message Defined Message structure 4.
EnvNonce Nonce used for Proof-of-Work calculation As per Whisper default

4. Message Level

Upon receipt of an Envelope, if the node detects a known topic, it tries to decrypt the Data element with the corresponding symmetric or asymmetric key. If decryption is successful, the Message is revealed with the following structure:

Element Description OpenVASP Usage See
flags Flags to specifiy Payload structure As per Whisper default
padding Random padding data, optional As per Whisper default
payload Message Payload OpenVASP Payload structure 4.1.
signature Signature, optional Not used

4.1. OpenVASP Payload

The table below shows the structure of the OpenVASP Payload. The last four elements are present depending on the value of the instruction element. The payload is encoded as a single big-endian, hex-encoded string with '0x' prefix.

Element Length Present Description See
version 1 byte Always OpenVASP Payload version, currently set to zero
instruction 3 bits Always Instructions to control a Connection 4.1.1
flags 5 bits Always Reserved for future use, must be set to zero
sender 6 bytes Always Sender's VASP Identity
connection 16 bytes Always Connection identifier
envelopeID 16 bytes Always Randomly set Envelope identifier
envelopeACK 16 bytes Reference to an Envelope identifier
returnTopic 4 bytes Return topic
ecdhPK 33 bytes Ephemeral compressed ECDH public key
ovMessage arbitrary size Session Message (JSON)

4.1.1. Instructions

The instruction element can have the following values:

Value Sent by Description
000 Active or Passive Node Acknowledge Envelope receipt (ACK)
001 Active Node Inviting for a Connection (INVITE)
010 Passive Node Accepting a Connection invitation (ACCEPT)
011 Passive Node Denying a Connection invitation (DENY)
100 Active or Passive Node Sending an Envelope over a Connection (UPDATE)
101 Active or Passive Node Closing a Connection (CLOSE)

4.1.2. Acknowledgment

Nodes must acknowledge the receipt of certain Envelopes by returning an OpenVASP Envelope of type ACK. The table below shows which Envelopes must be acknowledged.

To be acknowledged Envelopes with instruction value (see 4.1.1)
YES INVITE, ACCEPT, UPDATE, CLOSE
NO DENY, ACK

5. Connections

This sections explains how the Node is internally handling Connections without being normative about the actual implementation.

5.1. Connection Set

Each Node maintains the set of Connections established with other Nodes. Connections have no state, they are either present (and therefore in the set) or not.

5.2. Permanent vs. Transient Connections

Each VASP using the OpenVASP protocol must be contactable via its VASP Identifier. The VASP's Node must therefore always have this Connection in its set, which is called the Permanent Connection.

A Node serving several VASPs (or a VASP group operating with different legal entities) might have several Permanent Connections in its set.

All other Connections are called Transient Connections, as they are only in the set as long as they are open.

5.3. Connection Properties

Connections have the following properties:

Element Description Value in case of a Transient Connection Value in case of a Permanent Connection
isPermanent Flag indicating whether this Connection is a Permanent Connection (see 5.2) False True
connection Connection identifier Connection identifier VASP Identifier
inboundTopic Topic used to identify incoming Envelopes related to this Connection Randomly set Topic VASP Identifier
outboundTopic Topic used to label outgoing Envelopes related to this Connection Topic received from connected Node n/a
key Key used to encrypt/decrypt Envelopes sent/received over this Connection. Shared key to encrypt/decrypt outbound/inbound Envelopes Private key to decrypt inbound Envelopes

5.4. Outbound Envelope Queue

The Node maintains a queue of Envelopes sent in order to keep track whether their receipt has been acknowledged by the receiving Node. Only Envelopes that must be acknowledged are included in the queue (see 4.1.2).

Queue items have the following properties:

Element Description
envelopeID Envelope identifier
envelope Envelope
expiry Time when the waiting period for the acknowledgement of envelope ends and it is resent
resends Number of times envelope had to be resent
connection Identifier of the associated Connection
isCLOSE Flag whether the Envelope is of type CLOSE (see 4.1.1)

5.4.1. Periodical Check

The Node checks regularly for each item in the Outbound Envelope Queue whether its expiry time has been reached.

If this is the case, the respective Envelope is resent, the expiry time is reset and the value for resents is increased by one.

Nodes should resend Envelopes not being acknowledged with an increasingly larger TTL values (e.g. doubling the TTL with each resend).

5.4.2. Connection Interruption

Nodes must define a maximal number of resends for Envelopes not getting acknowledged.

If this limit is reached for an item in the Outbound Envelope Queue, the respective Connection is considered interrupted.

In such a case, the Node must:

  1. If the isCLOSE flag on the respective Outbound Envelope Queue item is True, then delete the respective Connection item from the Connection set.
  2. Delete the respective item from the Outbound Envelope Queue.
  3. If the isCLOSE flag on the respective Outbound Envelope Queue item is False, then notify the session layer's Exception Handling (see OVIP-7, 3.1) about the interruption.

5.5. Validating & Decrypting Inbound Envelopes

Inbound Envelopes must be validated as per following steps.

  1. Check whether Topic (see 3) is present as an inboundTopic in the Connection set (see 5.3).
  2. Check whether Data (see 3) can be decrypted with the associated key in the Connection set (see 5.3).
  3. Check whether the payload element of the decrypted message (see 4) conforms to the OpenVASP Payload (see 4.1).

If one of the above mentioned checks fail, the Envelope is ignored and deleted.

5.6. Acknowledging Inbound Envelopes

Nodes must acknowledge certain Envelopes (see 4.1.2) by returning an OpenVASP Envelope of type ACK.

If required, the Envelope is acknowledged as per following steps.

  1. Read connection value from the Payload of the Envelope to be acknowledged.

  2. Create the Payload out of the elements defined in 4.1 and the specified values in the table below.

    Element Value
    instruction 000
    connection connection value from the Payload of the Envelope to be acknowledged
    envelopeACK envelopeID value from the Payload of the Envelope to be acknowledged

  3. Create Envelope out of the elements defined in sections 4. and 3. and the specified values in the table below

    Element Value / Specification
    Topic outboundTopic value looked up in the Connection set based on matching connection values.
    Data Message inclusing Payload created in step 2, symmetrically encrypted (AES GCM algorithm as per Whisper standard) with key value looked up in the Connection set based on matching connection values unless specified otherwise.

  4. Send Envelope created in step 3.

5.7. Processing Acknowledgements for Sent Envelopes

Received OpenVASP Envelopes of type ACK are processed as per following steps.

  1. Read envelopeACK value from the Payload of the Envelope received.

  2. Lookup item in the Outbound Envelope Queue (see 5.4) based on matching envelopeID/envelopeACK values.

  3. If a match can be found with the isCLOSE flag set to False, then delete the item from the queue.

  4. If a match can be found with the isCLOSE flag set to True, then:

    a) delete respective item in the Connection set (see 5.3) based on matching connection/connectionID values, and

    b) delete the item from the queue.

6. Implementing the Session Layer

An OpenVASP Session knows four state changing operations:

  • Initiating a Session,
  • Responding to a Session Initiation,
  • Ending a Session, and
  • Aborting a Session.

In addition, the session layer defines Application Messages that are exchanged during an open session.

The reader is recommended to consult OVIP-7 to understand the session model in full detail. This section describes how a conformant Node must implement the four above listed state changing operations as well as the exchange of Application Messages.

6.1. Initiating a Session

6.1.1. Active Node Sends Session Invitation

6.1.1.1. Session Layer Input
Element Description See
receiver VASP Identifier of the Responder OVIP-7, section 2.1
sessionMessage Session Request Message OVIP-7, section 4.1
6.1.1.2. Processing steps

  1. Retrieve public transportKey available from the receiver's VASP Contract.

  2. Generate random connectionIdentifier.

  3. Generate random topicA the Node will listen for to identify incoming Envelopes sent over this Connection.

  4. Generate Secp256k1 ECDH private key (ecdhPrivateA) and ECDH public key (ecdhPublicA).

  5. Create the Payload out of the elements defined in 4.1 and the specified values in the table below.

    Element Value
    instruction 001
    connection connectionIdentifier
    returnTopic topicA
    ecdhPK ecdhPublicA
    ovMessage sessionMessage

  6. Create Envelope out of the elements defined in sections 4. and 3. and the specified values in the table below.

    Element Value / Specification
    Topic receiver
    Data Message inclusing Payload created in step 6, asymmetrically encrypted with the transportKey using SECP-256k1 as per Whisper standard.

  7. Add item to the set of Connections:

    Element Value
    isPermanent False
    connection connectionIdentifier
    inboundTopic topicA
    outboundTopic (empty)
    key ecdhPrivateA

  8. Add item to the Outbound Envelope Queue:

    Element Value
    envelopeID Envelope identifier set in step 6
    envelope Envelope created in step 7
    expiry Current time + 900 seconds
    resends 0
    connection connectionIdentifier
    isCLOSE False

  9. Make the Node listen to incoming Envelopes associated to this Connection.

  10. Send Envelope created in step 7.

6.1.1.3. Feedback to Session Layer
  • Return that session invitation has been sent.
  • Return Connection identifier (connectionID) so that the session layer can refer to it throughout the session lifecycle.

6.1.2. Passive Node Receives Session Invitation

6.1.2.1. Inbound Envelope Validation & Decryption

Validate and decrypt Envelope (see 5.5).

6.1.2.2. Acknowledge Envelope Receipt

Send acknowledgement (see 5.6), asymmetrically encrypted by ecdhPK, read from the Payload of received Envelope.

6.1.2.3. Processing Steps

  1. Read connection, envelopeID, returnTopic, ecdhPK and ovMessage from the Payload of received Envelope.

  2. Generate random topicB the Node will listen for to identify incoming Envelopes sent over this Connection.

  3. Generate Secp256k1 ECDH private key (ecdhPrivateB) and ECDH public key (ecdhPublicB).

  4. Derive sharedKey based on ecdhPrivateB and ecdhPublicA received in step 1 using the X25519 key-exchange protocol.

  5. Add item to the set of Connections:

    Element Value
    isPermanent False
    connection connection from the Payload of received Envelope
    inboundTopic topicB
    outboundTopic returnTopic
    key sharedKey

  6. Make the Node listen to incoming Envelopes associated to this Connection.

6.1.2.4. Notification to Session Layer
  • Notify that session invitation has been received.
  • Provide Connection identifier (connectionID) so that the session layer can refer to it throughout the session lifecycle.
  • Pass ovMessage to session layer.

6.2. Responding to a Session Initiation

6.2.1. Passive Node Sends Session Acceptance

6.2.1.1. Session Layer Input
Element Description See
connectionID Connection identifier
isAccepted True
sessionMessage Session Reply Message OVIP-7, section 4.2
6.2.1.2. Processing steps

  1. Create the Payload out of the elements defined in 4.1 and the specified values in the table below.

    Element Value
    instruction 010
    returnTopic inboundTopic value looked up in the Connection set based on matching connection/connectionID values.
    ovMessage sessionMessage
    ecdhPK ecdhPublicB

  2. Create Envelope out of the elements defined in sections 4. and 3. and the specified values in the table below

    Element Value / Specification
    Topic outboundTopic value looked up in the Connection set based on matching connection/connectionID values.
    Data Message inclusing Payload created in step 1, asymmetrically encrypted (ECIES algorithm as per Whisper standard) with ecdhpkA value.

  3. Add item to the Outbound Envelope Queue:

    Element Value
    envelopeID Envelope identifier set in step 1
    envelope Envelope created in step 2
    expiry Current time + 900 seconds
    resends 0
    connection connectionID
    isCLOSE False

  4. Send Envelope created in step 2.

6.2.1.3. Feedback to Session Layer
  • Return that session acceptance has been sent.

6.2.2. Active Node Receives Session Acceptance

6.2.2.1. Inbound Envelope Validation & Decryption

Validate and decrypt Envelope (see 5.5).

6.2.2.2. Processing Steps

  1. Read connection, returnTopic, ecdhPublicB and ovMessage from the Payload of received Envelope.

  2. Derive sharedKey from ecdhPublicB and ecdhPrivateA.

  3. Look up respective item in the Connection set (see 5.3) based on matching connection/connectionID values.

  4. Update respective Connection item:

    Element Value
    outboundTopic returnTopic
    key sharedKey
6.2.2.3. Acknowledge Envelope Receipt

Send acknowledgement (see 5.6). Encrypted symmetrically with sharedKey.

6.2.2.4. Notification to Session Layer
  • Notify that session invitation has been accepted.
  • Pass ovMessage to session layer.

6.2.3. Passive Node Sends Session Denial

6.2.3.1. Session Layer Input
Element Description See
connectionID Connection identifier
isAccepted False
sessionMessage Session Reply Message OVIP-7, section 4.2
6.2.3.2. Processing steps

  1. Create the Payload out of the elements defined in 4.1 and the specified values in the table below.

    Element Value
    instruction 011
    ovMessage sessionMessage

  2. Create Envelope out of the elements defined in sections 4. and 3. and the specified values in the table below

    Element Value / Specification
    Topic outboundTopic value looked up in the Connection set based on matching connection/connectionID values.
    Data Message inclusing Payload created in step 1, asymmetrically encrypted (ECIES algorithm as per Whisper standard) with ecdhpkA value.

  3. Send Envelope created in step 2.

  4. Delete respective item in the Connection set (see 5.3) based on matching connection/connectionID values.

6.2.3.3. Feedback to Session Layer
  • Return that session denial has been sent.

6.2.4. Active Node Receives Session Denial

6.2.4.1. Inbound Envelope Validation & Decryption

Validate and decrypt Envelope (see 5.5).

6.2.4.3. Processing Steps
  1. Read connection and ovMessage from the Payload of received Envelope.
  2. Delete respective item in the Connection set (see 5.3) based on matching connection/connectionID values.
6.2.4.4. Notification to Session Layer
  • Notify that session invitation has been denied.
  • Pass ovMessage to session layer.

6.3. Ending or Aborting a Session

On the level of Node Connections, terminating a session (see OVIP-7, 4.3) or aborting a session (see OVIP-7, 4.4) are implemented the same.

6.3.1. Node Sends Session Termination or Abort

6.3.1.1. Session Layer Input
Element Description See
connectionID Connection identifier
sessionMessage Termination Message or Session Abort Message OVIP-7, section 4.3/4.4
6.3.1.2. Processing steps

  1. Create the Payload out of the elements defined in 4.1 and the specified values in the table below.

    Element Value
    instruction 101
    ovMessage sessionMessage

  2. Create Envelope out of the elements defined in sections 4. and 3. and the specified values in the table below

    Element Value / Specification
    Topic outboundTopic value looked up in the Connection set based on matching connection/connectionID values.
    Data Message inclusing Payload created in step 1, symmetrically encrypted (AES GCM algorithm as per Whisper standard) with key value looked up in the Connection set based on matching connection/connectionID values.

  3. Add item to the Outbound Envelope Queue:

    Element Value
    envelopeID Envelope identifier set in step 1
    envelope Envelope created in step 2
    expiry Current time + 900 seconds
    resends 0
    connection connectionID
    isCLOSE True

  4. Send Envelope created in step 2.

6.3.1.3. Feedback to Session Layer
  • Return that session termination or session abort has been sent.

6.3.2. Node Receives Session Termination or Abort

6.3.2.1. Inbound Envelope Validation & Decryption

Validate and decrypt Envelope (see 5.5).

6.3.2.2. Acknowledge Envelope Receipt

Send acknowledgement (see 5.6).

6.3.2.3. Processing Steps
  1. Read connection and ovMessage from the Payload of received Envelope.
  2. Delete respective item in the Connection set (see 5.3) based on matching connection/connectionID values.
6.3.2.4. Notification to Session Layer
  • Notify that session has been terminated or aborted.
  • Pass ovMessage to session layer.

6.4. Sending Application Messages During a Session

6.4.1. Node Sends Application Message

6.4.1.1. Session Layer Input
Element Description See
connectionID Connection identifier
sessionMessage Application Message OVIP-7, section 5
6.4.1.2. Processing steps

  1. Create the Payload out of the elements defined in 4.1 and the specified values in the table below.

    Element Value
    instruction 100
    ovMessage sessionMessage

  2. Create Envelope out of the elements defined in sections 4. and 3. and the specified values in the table below

    Element Value / Specification
    Topic outboundTopic value looked up in the Connection set based on matching connection/connectionID values.
    Data Message inclusing Payload created in step 1, symmetrically encrypted (AES GCM algorithm as per Whisper standard) with key value looked up in the Connection set based on matching connection/connectionID values.

  3. Add item to the Outbound Envelope Queue:

    Element Value
    envelopeID Envelope identifier set in step 1
    envelope Envelope created in step 2
    expiry Current time + 900 seconds
    resends 0
    connection connectionID
    isCLOSE False

  4. Send Envelope created in step 2.

6.4.1.3. Feedback to Session Layer
  • Return that Application Message has been sent.

6.4.2. Node Receives Application Message

6.4.2.1. Inbound Envelope Validation & Decryption

Validate and decrypt Envelope (see 5.5).

6.4.2.2. Acknowledge Envelope Receipt

Send acknowledgement (see 5.6).

6.4.2.3. Processing Steps

Read connection and ovMessage from the Payload of received Envelope.

6.4.2.4. Notification to Session Layer
  • Notify that Application Message has been received.
  • Pass ovMessage to session layer.

Motivation

Transport layer reliability -- The original specification as per White Paper was amended by introducing acknowledgements in response to community feedback.

Alignment with new layer model -- A better separation between the different layers of OpenVASP was introduced by OVIP-9. This OVIP realigns the specification for using Whisper as transport layer with the new layer model.

Rationale

Separate encryption on transport layer -- Separating encryption on transport and session layers will allow for a better security architecture as the internet-facing Whisper could be decoupled from the server handling the sessions. Further, it allows the usage of a Whisper node by different session handlers without giving access to session layers details, particularly originator/beneficiary data.

Backwards Compatibility

The specification proposed in this OVIP is not backwards compatible.

Whisper/Waku Comment

This OVIP is only superseded by OVIP-0016 in terms of terminology. All consequences of this ovip hold true by replacing the word "Whisper" with the word "Waku".