Secure your conversations by encrypting your SMS messages end-to-end

January 21, 2024 • 10 min read

We have added support for end-to-end encryption for SMS messages so that no one can see the content of the messages you send using httpSMS except you.

You setup an encryption key which you use to encrypt your messages before making an API request to httpSMS and you also use the same key to decrypt the messages you receive from httpSMS via our webhook events. We are using the AES 256 encryption algorithm to encrypt and decrypt the messages.

Setup your encryption key

⬇️ Download and install the httpSMS Android app on your phone and set you encryption key under the App Settings page of the app.

Encrypt your SMS message

We use the AES-256 encryption algorithm to encrypt the SMS messages. This algorithm requires a an encryption key which is 256 bits to work around this, we will hash any encryption key you set on the mobile app using the sha-256 algorithm so that it will always produce a key which is 256 bits.

The AES algorithm also has an initialization vector (IV) parameter which is used to ensure that the same value encrypted multiple times will not produce the same encrypted value. The IV is 16 bits and it is appended to the encrypted message before encoding it in base64.

When you use our client libraries it will automatically take care of encrypting your message so you don't have to deal with creating the initialization vector and encoding the payload yourself.

import HttpSms from "httpsms"

const client = new HttpSms("" /* API Key from https://httpsms.com/settings */);

const key = "Password123";

const encryptedMessage = client.cipher.encrypt(key, "This is a sample text message");

// The encrypted message looks like this, note that you will get a different encrypted message when you run this code on your computer
// Qk3XGN5+Ax38Ig01m4AqaP6Y0b0wYpCXtx59sU23uVLWUU/c7axF7LozDg==

            

Send an encrypted message

After generating the encrypted message payload, you can send it directly using the httpSMS API. Make sure to set encrypted: true in the JSON request payload so that httpSMS knows that the message is encrypted and it will be decoded in the Android app before sending to your recipient.

import HttpSms from "httpsms"

client.messages.postSend({
    content:   encryptedMessage,
    from:      '+18005550199',
    encrypted: true,
    to:        '+18005550100',
})
.then((message) => {
    console.log(message.id); // log the ID of the sent message
});
            

When you make the API request, the message will be decrypted before sending to the recipient. This is a screenshot of the SMS message which is sent to the recipient.

Receiving an encrypted message

When your android phone receives a new message, it will be encrypted with the encryption Key on your Android phone before it is delivered to your server's webhook endpoint. You can configure webhooks by following this guide.

import HttpSms from "httpsms"

const client = new HttpSms("" /* API Key from https://httpsms.com/settings */);

// The payload in the webhook HTTP request looks like this
/*
{
  "specversion": "1.0",
  "id": "8dca3b0a-446a-4a5d-8d2a-95314926c4ed",
  "source": "/v1/messages/receive",
  "type": "message.phone.received",
  "datacontenttype": "application/json",
  "time": "2024-01-21T12:27:29.1605708Z",
  "data": {
    "message_id": "0681b838-4157-44bb-a4ea-721e40ee7ca7",
    "user_id": "XtABz6zdeFMoBLoltz6SREDvRSh2",
    "owner": "+37253920216",
    "encrypted": true,
    "contact": "+37253920216",
    "timestamp": "2024-01-21T12:27:17.949Z",
    "content": "bdmZ7n6JVf/ST+SoNlSaOGUL1DcL5705ETw8GAB4llYBgE9HOOL+Pu/h+w==",
    "sim": "SIM1"
  }
}
*/

const encryptedMessage = "bdmZ7n6JVf/ST+SoNlSaOGUL1DcL5705ETw8GAB4llYBgE9HOOL+Pu/h+w==" // get the encrypted message from the request payload
const encryptionkey = "Password123" // use the same key on the Android app
const decryptedMessage = client.cipher.decrypt(encryptionkey, encryptedMessage)

// This is a test text message

        

Conclusion

Congratulations, you have successfully configured your Android phone to send and receive SMS messages with end-to-end encryption. Don't hesitate to contact us if you face any problems while following this guide.