# 26/WAKU2-PAYLOAD | Vac Research
- Status: draft

Skip to main content

# 26/WAKU2-PAYLOAD

- Status: draft
- Editor: Oskar Thoren <oskarth@titanproxy.com>
- Contributors:
  - Oskar Thoren <oskarth@titanproxy.com>

## Abstract​

This specification describes how Waku provides confidentiality, authenticity, and integrity, as well as some form of unlinkability. Specifically, it describes how encryption, decryption and signing works in 6/WAKU1 and in 10/WAKU2 with 14/WAKU-MESSAGE.

This specification effectively replaces 7/WAKU-DATA as well as 6/WAKU1 Payload encryption but written in a way that is agnostic and self-contained for 6/WAKU1 and 10/WAKU2.

Large sections of the specification originate from EIP-627: Whisper spec as well from RLPx Transport Protocol spec (ECIES encryption) with some modifications.

## Specification​

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

For 6/WAKU1, the `data` field is used in the waku envelope and the field MAY contain the encrypted payload.

For 10/WAKU2, the `payload` field is used in `WakuMessage` and MAY contain the encrypted payload.

The fields that are concatenated and encrypted as part of the `data` (Waku legacy) or `payload` (Waku) field are:

- `flags`
- `payload-length`
- `payload`
- `padding`
- `signature`

## Design requirements​

- Confidentiality: The adversary SHOULD NOT be able to learn what data is being sent from one Waku node to one or several other Waku nodes.
- Authenticity: The adversary SHOULD NOT be able to cause Waku endpoint to accept data from any third party as though it came from the other endpoint.
- Integrity: The adversary SHOULD NOT be able to cause a Waku endpoint to accept data that has been tampered with.

Notable, forward secrecy is not provided for at this layer. If this property is desired, a more fully featured secure communication protocol can be used on top.

It also provides some form of unlinkability since:

- only participants who are able to decrypt a message can see its signature
- payload are padded to a fixed length

## Cryptographic primitives​

- AES-256-GCM (for symmetric encryption)
- ECIES
- ECDSA
- KECCAK-256

ECIES is using the following cryptosystem:

- Curve: secp256k1
- KDF: NIST SP 800-56 Concatenation Key Derivation Function, with SHA-256 option
- MAC: HMAC with SHA-256
- AES: AES-128-CTR

### ABNF​

Using Augmented Backus-Naur form (ABNF) we have the following format:

    ; 1 byte; first two bits contain the size of payload-length field,
    ; third bit indicates whether the signature is present.
    flags           = 1OCTET

    ; contains the size of payload.
    payload-length  = 4*OCTET

    ; byte array of arbitrary size (may be zero).
    payload         = *OCTET

    ; byte array of arbitrary size (may be zero).
    padding         = *OCTET

    ; 65 bytes, if present.
    signature       = 65OCTET

    data            = flags payload-length payload padding [signature]

    ; This field is called payload in Waku
    payload         = data

### Signature​

Those unable to decrypt the payload/data are also unable to access the signature. The signature, if provided, SHOULD be the ECDSA signature of the Keccak-256 hash of the unencrypted data using the secret key of the originator identity. The signature is serialized as the concatenation of the `r`, `s` and `v` parameters of the SECP-256k1 ECDSA signature, in that order. `r` and `s` MUST be big-endian encoded, fixed-width 256-bit unsigned. `v` MUST be an 8-bit big-endian encoded, non-normalized and should be either 27 or 28.

See Ethereum "Yellow paper": Appendix F Signing transactions for more information on signature generation, parameters and public key recovery.

### Encryption​

#### Symmetric​

Symmetric encryption uses AES-256-GCM for authenticated encryption. The output of encryption is of the form (`ciphertext`, `tag`, `iv`) where `ciphertext` is the encrypted message, `tag` is a 16 byte message authentication tag and `iv` is a 12 byte initialization vector (nonce). The message authentication `tag` and initialization vector `iv` field MUST be appended to the resulting `ciphertext`, in that order. Note that previous specifications and some implementations might refer to `iv` as `nonce` or `salt`.

#### Asymmetric​

Asymmetric encryption uses the standard Elliptic Curve Integrated Encryption Scheme (ECIES) with SECP-256k1 public key.

#### ECIES​

This section originates from the RLPx Transport Protocol spec specification with minor modifications.

The cryptosystem used is:

- The elliptic curve secp256k1 with generator `G`.
- `KDF(k, len)`: the NIST SP 800-56 Concatenation Key Derivation Function.
- `MAC(k, m)`: HMAC using the SHA-256 hash function.
- `AES(k, iv, m)`: the AES-128 encryption function in CTR mode.

Special notation used: `X || Y` denotes concatenation of `X` and `Y`.

Alice wants to send an encrypted message that can be decrypted by Bob's static private key `kB`. Alice knows about Bobs static public key `KB`.

To encrypt the message `m`, Alice generates a random number `r` and corresponding elliptic curve public key `R = r * G` and computes the shared secret `S = Px` where `(Px, Py) = r * KB`. She derives key material for encryption and authentication as `kE || kM = KDF(S, 32)` as well as a random initialization vector `iv`. Alice sends the encrypted message `R || iv || c || d` where `c = AES(kE, iv , m)` and `d = MAC(sha256(kM), iv || c)` to Bob.

For Bob to decrypt the message `R || iv || c || d`, he derives the shared secret `S = Px` where `(Px, Py) = kB * R` as well as the encryption and authentication keys `kE || kM = KDF(S, 32)`. Bob verifies the authenticity of the message by checking whether `d == MAC(sha256(kM), iv || c)` then obtains the plaintext as `m = AES(kE, iv || c)`.

### Padding​

The `padding` field is used to align data size, since data size alone might reveal important metainformation. Padding can be arbitrary size. However, it is recommended that the size of `data` field (excluding the `iv` and `tag`) before encryption (i.e. plain text) SHOULD be a multiple of 256 bytes.

### Decoding a message​

In order to decode a message, a node SHOULD try to apply both symmetric and asymmetric decryption operations. This is because the type of encryption is not included in the message.

## Copyright​

Copyright and related rights waived via CC0.

## References​

1. 6/WAKU1
2. 10/WAKU2 spec
3. 14/WAKU-MESSAGE version 1
4. 7/WAKU-DATA
5. EIP-627: Whisper spec
6. RLPx Transport Protocol spec (ECIES encryption)
7. Status 5/SECURE-TRANSPORT
8. Augmented Backus-Naur form (ABNF)
9. Ethereum "Yellow paper": Appendix F Signing transactions
10. authenticated encryption