End-to-End Encryption (E2EE)

PushGo supports End-to-End Encryption (E2EE) to ensure that only your devices can read your notification content. The gateway only handles encrypted blobs.

Encryption Standard

PushGo uses industry-standard AES-256-GCM for data encryption and authentication.

Component	Specification
Algorithm	AES-GCM (Galois/Counter Mode)
Key Size	256-bit (32 bytes)
Nonce (IV)	12 bytes
Auth Tag	16 bytes

---

1. Payload Structure

The plaintext payload must be a valid JSON object.

{
  "title": "Your Title",
  "body": "Your secret message content",
  "images": ["https://example.com/img1.jpg"]
}

---

2. Construction of ciphertext

To generate the ciphertext field for the API, follow these steps:

1. Encrypt: Encrypt the UTF-8 encoded JSON string using your secret key and a random 12-byte Nonce.
2. Concatenate: Append the Auth Tag and the Nonce to the end of the raw ciphertext.
   • Final Data = RawCiphertext + AuthTag + Nonce
3. Encode: Convert the concatenated binary data into a Base64 string.

Binary Layout

[ Raw Ciphertext (N bytes) ] [ Auth Tag (16 bytes) ] [ Nonce/IV (12 bytes) ]

---

3. Implementation Example (Python)

import base64
import json
import os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def encrypt_payload(key_hex, payload_dict):
    key = bytes.fromhex(key_hex)
    aesgcm = AESGCM(key)
    nonce = os.urandom(12)

    plaintext = json.dumps(payload_dict).encode('utf-8')
    # AESGCM.encrypt returns ciphertext + tag
    cipher_and_tag = aesgcm.encrypt(nonce, plaintext, None)

    # Concatenate: (ciphertext + tag) + nonce
    final_blob = cipher_and_tag + nonce
    return base64.b64encode(final_blob).decode('utf-8')

# Usage
payload = {"title": "Hello", "body": "Secret Message"}
token = "32_byte_hex_key_here..."
print(encrypt_payload(token, payload))

---

4. Usage in API

Pass the resulting Base64 string to the ciphertext field in the /message API. The client app will automatically detect this field and attempt decryption using your locally stored key.