SCG now supports JWE (JSON Web Encryption) on Message and Message Request API calls.

This feature enables secure/encrypted transmission of API Calls by allowing you to send a JSON data structure as encrypted content for MT Messages.

Syniverse JWE application provides JWE public key through API to encrypt the payload for Message and Message Request.

The JWE standards allow a variety of encryption algorithms. Syniverse JWE supports RSA-based encryption algorithms. (RSA - 256).

This document describes how to use the JWE Encryption feature and provide guidance and API Call examples to facilitate feature use.

 

Steps To send encrypted payload (MT Messages)

The standard encryption flow can be separated on two steps.

1. encryption of the JSON payload (the body of the SCG API Call).
2. submission of the encrypted payload as text to our SCG API (/jwe) call.

It’s important to check the original JSON payload is correct before proceeding to test the encryption, since an encrypted payload that doesn’t comply with SCG specification would result in an error when submitting the encrypted message described in step 2.

 

Requesting Syniverse Public Certificate

To encrypt the payload, you need to download the Syniverse public key/certificate and install it on your production environment.

Syniverse public key API call may return single key or multiple keys. You can use any one of the available public keys to encrypt the body when multiple keys are returned.  Public keys URL is exposed through the API gateway and can be accessed without bearer token. 

 

Public key can be retrieved by a GET request to endpoint:

API URL: https://api.syniverse.com/event-manager-jwt/v1/jwks?use=enc

Curl Example:

curl --location --request GET 'https://api.syniverse.com/event-manager-jwt/v1/jwks?use=enc' \
--data-raw ''

R/
{
  "keys": [
    {
      "kty": "RSA",
      "x5t#S256": "hqU9j_6LDHJ1SD4QeE-J-gY2CtbSx-l2kDlbKEw8SfI",
      "e": "AQAB",
      "use": "enc",
      "kid": "syniverseessprdjwe2024",
      "x5c": [
        "MIIFejCCBGKgAwIBAgIQDVQ ... 7HAm0vYEVPZ1UA="
      ],
      "alg": "RS256",
      "n": "zGNJaAgDOlscC8MHol12WH ... TTvBDIvk0MJ0QmWwJ7z6fopnRTS-hVuna-RiKYV9eUkOSuk9e4K0w"
    }
  ]
}

This Syniverse public key can be used to encrypt the payload.

 

Sending Encrypted Payload to Syniverse SCG Messaging API

Depending on use case, the encrypted payload must be sent by adding /jwe to the SCG Messaging API URL.

 

API Requirement:

• Encrypted content is sent as text/plain. (Examples Below)
• API call headers need to include authorization token & use content-type as text/plain

Single Message/recipient

https://api.syniverse.com/scg-external-api/api/v1/messaging/messages/jwe

Multiple Recipients:

https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests/jwe

 

Example:

Original JSON payload for single message

{
"from":"sender_id:ID",
"to":"+number",
"body":"message 1",
"message_type":"mdn"
}

Encrypted JSON payload 

'eyJ4NXQiOiI2cDlsNl8tQjZ1cElTTzdXSmNfV3d4NHRoaWREYkhxdWlnMVNOa0x5Mm1zIiwia2lkIjoic3luaXZlcnN
lZXNzcHJkandlMjAyMiIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.KkzFCo_7ENxdoFLx8Kgo
9CjYd5KXgKcS7T4OCAuMTy1Rmec0iOp8uXMB39bfnSa6cloDqc90_ohvwppbhSNi5NkaKGpW_2oyEXU6d84o7-izio9_
IypHJkI_6-bJZln_LcPu2v4uJ5Smwp-MglcQKvYwFGdWN99N_GJVPOb2zK8AjZpE9ISYRuvjFjX3Cj3Yh-27wueENhqL
Z0xk4LLp3kFRsJCf-CkkTWtQkPZ1AXKKFP5Wk2lo9YaztBMHbohk8Yx-yCmJ9Pwjb9RjiKMr8mjlVQ5jSahXo5aUigDU0
jlK2Thj-ShcuThI4Yv9Gh6quQqbk04TBWMIM3iAoAwyqA.OOq6NfEdzwa0YAht.KUDBo_c_muG2yLDtx7rG_iZgCG96Zp
Ml96f-lctMQ01uIu3XAiDFXg5hl5Rlmp4yZ7heZF-n70DF2U9DhPPQK-6h4R7otX7rnNfXoI4Hx6X5Jfs.9-NQcIZust9
_MRfbbrw6bg'

SCG encrypted payload API call:

curl --location --request 
POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages/jwe' \
--header 'Authorization: Bearer XXXX' \
--header 'Content-Type: text/plain' \
-d 'eyJ4NXQiOiI2cDlsNl8tQjZ1cElTTzdXSmNfV3d4NHRoaWREYkhxdWlnMVNOa0x5Mm1zIiwia2lkIjoic3luaXZlcnN
lZXNzcHJkandlMjAyMiIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.KkzFCo_7ENxdoFLx8Kgo
9CjYd5KXgKcS7T4OCAuMTy1Rmec0iOp8uXMB39bfnSa6cloDqc90_ohvwppbhSNi5NkaKGpW_2oyEXU6d84o7-izio9_
IypHJkI_6-bJZln_LcPu2v4uJ5Smwp-MglcQKvYwFGdWN99N_GJVPOb2zK8AjZpE9ISYRuvjFjX3Cj3Yh-27wueENhqL
Z0xk4LLp3kFRsJCf-CkkTWtQkPZ1AXKKFP5Wk2lo9YaztBMHbohk8Yx-yCmJ9Pwjb9RjiKMr8mjlVQ5jSahXo5aUigDU0
jlK2Thj-ShcuThI4Yv9Gh6quQqbk04TBWMIM3iAoAwyqA.OOq6NfEdzwa0YAht.KUDBo_c_muG2yLDtx7rG_iZgCG96Zp
Ml96f-lctMQ01uIu3XAiDFXg5hl5Rlmp4yZ7heZF-n70DF2U9DhPPQK-6h4R7otX7rnNfXoI4Hx6X5Jfs.9-NQcIZust9
_MRfbbrw6bg'

 

Useful Links

Syniverse SCG SMS-MMS User Guide

JWE specification is RFC 7516

Nested signed and encrypted JSON Web Token (JWT)

How to generate a JSON Web Key (JWK)