Signieren von Nachrichten

Sie können Signaturen mit der SMS API beim Senden und Empfangen von SMS-Nachrichten verwenden. Beim Senden erzeugen Sie eine Signatur, die Sie mit Ihrer Nachricht versenden. Beim Empfang enthält der eingehende Webhook die Signatur und alle Felder, die Sie benötigen, um die Signatur in Ihrer Anwendung zu generieren und die Übereinstimmung der beiden Signaturen zu überprüfen.

Sie verwenden eine Signatur, um:

• Verify, dass eine Anfrage von einer vertrauenswürdigen Quelle stammt
• Sicherstellen, dass die Nachricht unterwegs nicht verfälscht wurde
• Abwehr von Abhörmaßnahmen und späterer Wiederholung

Inhalt

In diesem Dokument wird beschrieben, wie Signaturen mit Nachrichten verwendet werden, und zwar sowohl zum Signieren der von Ihnen gesendeten Nachrichten als auch zum Verifizieren, dass eingehende Nachrichten eine korrekte Signatur aufweisen.

• Nachrichten mit Signaturen senden. Verwenden Sie die Client-Bibliotheken um die signierte Nachricht zu erzeugen und zu versenden.
• Verify Signaturen auf eingehenden Nachrichten um die Authentizität der Nachricht im eingehenden Webhook zu gewährleisten.
• Manuelle Erstellung einer Signatur wenn Sie die vorhandenen Bibliotheken nicht verwenden können, ist hier der manuelle Prozess der Signaturerstellung enthalten.

Verwendung von Signaturen beim Senden von Nachrichten

Um eine Nachricht mit einer Signatur zu versenden, müssen Sie die SIGNATURE_SECRET anstelle Ihrer API_SECRET beim Senden der Nachricht. Das Signaturgeheimnis und den zu verwendenden Signieralgorithmus finden Sie auf der Seite Dashboard. Der Standardalgorithmus ist'.MD5-Hash' und wir unterstützen auch MD5 HMAC, SHA1 HMAC, SHA-256 HMAC und SHA-512 HMAC.

Vonage empfiehlt dringend die Verwendung eines unserer Client-Bibliotheken um Signaturen zu erzeugen oder zu validieren. Wenn Sie kann nicht dies aus irgendeinem Grund tun, müssen Sie kann Signaturen selbst generieren und validieren, aber das kann kompliziert und potenziell fehleranfällig sein. Lesen Sie die Abschnitt über die manuelle Erstellung von Signaturen.

Das Verfahren zum Versenden einer signierten Nachricht ist wie folgt

1. Erstellen Sie eine signierte Anfrage um eine SMS zu senden.
2. Prüfen Sie die Antwortcodes und vergewissern Sie sich, dass Sie die Anfrage korrekt gesendet haben.
3. Ihre Nachricht wird an das Mobilteil zugestellt. Das Mobilteil des Benutzers sendet eine Empfangsbestätigung zurück.
4. (fakultativ) Wenn Sie signierte Empfangsbestätigungen und eingehende Nachrichten angefordert haben, müssen Sie die Signatur für jede eingehende Anforderung validieren.

Wenn Sie die Signatur nicht korrekt erstellt haben, wird die Status ist 14, invalid signature. Weitere Informationen finden Sie in der Fehlersuche Abschnitt dieses Leitfadens.

Das folgende Codebeispiel zeigt, wie eine signierte Nachricht mit der SMS API gesendet wird.

npm install @vonage/server-sdk

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
  // By passing in the signature, the SDK will sign the request for you
  // Isn't that neat?!
  signature: {
    secret: SMS_SIGNATURE,
    algorithm: 'md5hash',
  },
});

const sendMessage = async () => {
  try {
    const result = await vonage.sms.send({
      from: SMS_SENDER_ID,
      to: SMS_TO_NUMBER,
      text: 'A text message sent using the Vonage SMS API',
    });

    console.log('Message sent successfully.');
    console.log(result);
  } catch (error) {
    console.error(`Message failed with error: ${error.message}`);
  }
};

sendMessage();

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

fun main() {
    val client = Vonage {
        apiKey(VONAGE_API_KEY)
        signatureSecret(VONAGE_SIGNATURE_SECRET)
        hashType(HashType.HMAC_SHA256)

val response = client.sms.sendText(
    from = SMS_SENDER_ID,
    to = SMS_TO_NUMBER,
    message = "Hello from Vonage SMS API"
)

if (response.wasSuccessfullySent()) {
    println("Message sent successfully.")
}
else {
    println("Message failed with error: ${response[0].errorText}")

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

implementation 'com.vonage:server-sdk:9.3.1'

import com.vonage.client.VonageClient;
import com.vonage.client.auth.hashutils.HashType;
import com.vonage.client.sms.MessageStatus;
import com.vonage.client.sms.SmsSubmissionResponse;
import com.vonage.client.sms.messages.TextMessage;

);

SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);

            System.out.println("Message sent successfully.");
        } else {
            System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
        }
    }
}

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

var credentials = Credentials.FromApiKeySignatureSecretAndMethod(
    vonageApiKey,
    vonageApiSignatureSecret,
    Vonage.Cryptography.SmsSignatureGenerator.Method.md5hash
    );

var credentials = Credentials.FromApiKeySignatureSecretAndMethod(
    vonageApiKey,
    vonageApiSignatureSecret,
    Vonage.Cryptography.SmsSignatureGenerator.Method.md5hash
    );

var vonageClient = new VonageClient(credentials);

var response = await vonageClient.SmsClient.SendAnSmsAsync(new Vonage.Messaging.SendSmsRequest()
{
    To = SMS_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "This is a Signed SMS"
});

composer require vonage/client

$signed = new Nexmo\Client\Credentials\SignatureSecret(
    VONAGE_API_KEY,
    VONAGE_API_SIGNATURE_SECRET,
    'md5hash'
);
$client = new \Vonage\Client($signed);

$response = $client->sms()->send(
    new \Vonage\SMS\Message\SMS(TO_NUMBER, FROM_NUMBER, 'Super interesting message')
);

echo "Message status: " . $response->current()->getStatus() . "\n";

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_sms import SmsMessage, SmsResponse

client = Vonage(Auth(api_key=VONAGE_API_KEY, signature_secret=SMS_SIGNATURE))

message = SmsMessage(
    to=SMS_TO_NUMBER,
    from_=SMS_SENDER_ID,
    text="A text message sent using the Vonage SMS API.",
)

response: SmsResponse = client.sms.send(message)
print(response)

Validierung der Unterschrift auf eingehenden Nachrichten

Um die Herkunft eingehender Webhooks an Ihrem SMS-Endpunkt zu verifizieren, können Sie die Nachrichtensignierung für eingehende Nachrichten aktivieren - wenden Sie sich an Unterstützung um zu verlangen, dass eingehende Nachrichten mit einer Signatur versehen werden. Wenn diese Einstellung aktiviert ist, enthalten die Webhooks sowohl für eingehende SMS als auch für Zustellungsbestätigungen eine sig Parameter. Verwenden Sie die anderen Parameter in der Anfrage zusammen mit Ihrem Signaturgeheimnis, um die Signatur zu generieren und sie mit der gesendeten Signatur zu vergleichen. Wenn die beiden übereinstimmen, ist die Anfrage gültig.

Das folgende Codebeispiel zeigt, wie eine Signatur für eine eingehende SMS-Nachricht verifiziert wird, indem die sig Parameter in der Abfragezeichenfolge.

npm install express @vonage/server-sdk

const { Vonage } = require('@vonage/server-sdk');

const app = require('express')();
const bodyParser = require('body-parser');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true,
}));

app
  .route('/webhooks/inbound-sms')
  .get(handleInboundSms)
  .post(handleInboundSms);

const  handleInboundSms = (request, response) => {
  const params = Object.assign(request.query, request.body);
  const { sig } = params;

  if (Vonage.sms.verifySignature(
    sig,
    params,
    VONAGE_SIGNATURE_SECRET,
    'md5hash', // one of md5hash, md5, sha1, sha256, or sha512
  )) {
    console.log('Valid signature');
  } else {
    console.log('Invalid signature');
  }

  response.status(204).send();
};

app.listen(process.env.PORT || 3000);

implementation 'com.vonage:server-sdk:9.3.1'

import com.vonage.client.auth.RequestSigning;
import spark.Route;
import spark.Spark;

     * Route to handle incoming SMS GET request.
     */
    Route inboundSmsAsGet = (req, res) -> {
        String signatureSecret = VONAGE_SIGNATURE_SECRET;
        System.out.println(signatureSecret);
        if (RequestSigning.verifyRequestSignature(
                req.raw().getInputStream(),
                req.contentType(),
                req.queryMap().toMap(),
                signatureSecret
        )) {
            System.out.println("msisdn: " + req.queryParams("msisdn"));
            System.out.println("messageId: " + req.queryParams("messageId"));
            System.out.println("text: " + req.queryParams("text"));
            System.out.println("type: " + req.queryParams("type"));
            System.out.println("keyword: " + req.queryParams("keyword"));
            System.out.println("messageTimestamp: " + req.queryParams("message-timestamp"));

            res.status(204);    
        }
        else {
            System.out.println("Bad signature");
            res.status(401);
        }
        
        return "";
    };        

    Spark.port(5000);
    Spark.get("/webhooks/inbound-sms", inboundSmsAsGet);        
}

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

{
    [HttpGet("webhooks/inbound-sms")]        

        public IActionResult VerifySms()
        {
            var vonageApiSignatureSecret = Environment.GetEnvironmentVariable("VONAGE_API_SIGNATURE_SECRET") ?? "VONAGE_API_SIGNATURE_SECRET";
            var sms = WebhookParser.ParseQuery<InboundSms>(Request.Query);
            if (sms.ValidateSignature(vonageApiSignatureSecret, Vonage.Cryptography.SmsSignatureGenerator.Method.md5hash))
            {
                Console.WriteLine("Signature is valid");
            }
            else
            {
                Console.WriteLine("Signature not valid");
            }
            return NoContent();
        }
    }
}

composer require vonage/client

$inbound = \Vonage\Message\InboundMessage::createFromGlobals();

if ($inbound->isValid()) {
    $params = $inbound->getRequestData();
    $signature = new Vonage\Client\Signature(
        $params,
        VONAGE_API_SIGNATURE_SECRET,
        'md5hash'
    );
    $validSig = $signature->check($params['sig']);

    if($validSig) {
        error_log("Valid signature");
    } else {
        error_log("Invalid signature");
    }

} else {
    error_log('Invalid message');
}

pip install vonage python-dotenv fastapi[standard]

import os
from os.path import dirname, join

from dotenv import load_dotenv

envpath = join(dirname(__file__), '../.env')
load_dotenv(envpath)

VONAGE_API_KEY = os.getenv("VONAGE_API_KEY")
VONAGE_SIGNATURE_SECRET = os.getenv("VONAGE_SIGNATURE_SECRET")

from fastapi import FastAPI, Request
from vonage import Auth, Vonage

client = Vonage(Auth(api_key=VONAGE_API_KEY, signature_secret=VONAGE_SIGNATURE_SECRET))

app = FastAPI()


@app.post('/')
async def verify_signed_webhook(request: Request):
    data = await request.json()

    if client.http_client.auth.check_signature(data):
        print('Valid signature')
    else:
        print('Invalid signature')

Manuelle Erstellung einer Signatur

Sie ist sehr empfehlenswert dass Sie die vorhandenen Funktionen Ihrer Vonage-Bibliothek zur Erzeugung und Validierung von Signaturen verwenden. Wenn Sie keine Bibliothek mit dieser Funktion verwenden, müssen Sie die Signatur selbst generieren. Die Technik ist etwas anders, wenn Sie eine MD5-Hash-Signatur oder eine HMAC-Signatur erzeugen.

Schritt 1: Sowohl für Hash- als auch für HMAC-Signaturen

Wenn Sie eine Signatur zu erzeugen: Hinzufügen des aktuellen Zeitstempels zur Parameterliste mit dem Schlüssel timestamp. Dies sollte eine ganze Zahl sein, die die Anzahl der Sekunden seit der Epoche enthält (dies wird manchmal auch als UNIX-Zeit bezeichnet).

Wenn Sie Validierung einer Unterschrift von Vonage: Entfernen Sie die sig bevor Sie Ihre Signatur erstellen, und verwenden Sie den Parameter timestamp in den Anfrageparametern angegeben.

Dann:

• Schleife durch jeden der Parameter, sortiert nach Schlüssel
• Ersetzen Sie für jeden Wert in der Parameterliste alle Instanzen von & und = mit einem Unterstrich _.
• Erzeugen Sie eine Zeichenkette bestehend aus &akey=value&bkey=value. Beachten Sie, dass es ein kaufmännisches Und gibt & am Anfang der Zeichenkette!

Zu diesem Zeitpunkt wird das Verfahren zur MD5 und HMAC Hashing unterschiedlich sein wird. Folgen Sie Schritt 2 unten, um zu entscheiden, welches Hashing-Verfahren verwendet werden soll.

Schritt 2

• MD5-Hash

  1. Fügen Sie das Unterschriftsgeheimnis an das Ende der Zeichenkette, direkt nach dem letzten Wert. Sie sollte nun etwa so aussehen: &akey=value&bkey=valueyour_signature_secret
  2. Führen Sie nun die Zeichenkette durch eine md5-Hash-Funktion und wandeln Sie die resultierenden Bytes in eine Zeichenkette aus Hexadezimalziffern um. Dies ist Ihre MD5-Hash-Signatur, die Sie in die HTTP-Parameter Ihrer Anfrage als sig Parameter.

• HMAC

  1. Erstellen Sie einen HMAC-Generator mit dem von Ihnen gewünschten Algorithmus und Ihrem Signaturgeheimnis als Schlüssel.
  2. Lassen Sie nun die Zeichenfolge durch einen HMAC-Generator laufen und wandeln Sie die resultierenden Bytes in eine Zeichenfolge aus Hexadezimalziffern um. Dies ist Ihre HMAC-Signatur, die Sie in die HTTP-Parameter Ihrer Anfrage als sig Parameter (für PHP sieht das z.B. so aus hash_hmac($algorithm, $data, $secret)).

Schritt 3: Zusätzliche Hinweise

Beachten Sie, dass die als HTTP-Parameter übergebenen Werte, auch wenn Sie die Parameterwerte bei der Erstellung der Signatur geändert haben, gleich bleiben sollten unverändert wenn diese Parameter an die SMS API gesendet werden.

Fehlersuche bei Signaturen

Im Folgenden finden Sie einige Tipps und Fallstricke, auf die Sie bei der Arbeit mit signierten Nachrichten achten sollten.

Einzelheiten finden Sie in der Antwort

Wenn die Nachricht nicht wie erwartet gesendet wird, prüfen Sie die Antwort auf etwaige Fehlercodes die zurückgegeben wurden. Dadurch erhalten Sie in der Regel genauere Informationen darüber, was als nächstes zu tun ist.

Fehler 14: Ungültige Signatur

Enthält der gesendete Text Sonderzeichen wie z. B. & (Ampersand) oder = (Gleichheitszeichen), dann müssen diese in dem für die Erstellung der Signatur verwendeten Text ersetzt werden.

Gehen Sie dazu wie folgt vor:

• Stellen Sie fest, dass der Text Folgendes enthält & oder =.
• Erstellen Sie eine Version des Textes, in der _ (Unterstrich) anstelle dieser Sonderzeichen.
• Verwenden Sie die bereinigte Version des Textes, um die Signatur zu erstellen.

Der Originaltext kann weiterhin gesendet/empfangen werden, die Zeichenersetzungen werden nur für die Erstellung der Signatur benötigt.