Signature Validation-V3
Introduction
All requests made to your application server by Plivo’s Voice platform contain X-Plivo-Signature-V3, X-Plivo-Signature-Ma-V3, and X-Plivo-Signature-V3-Nonce HTTP headers.
To verify that the request to your server has originated from Plivo and that it has not been altered en route, you may generate your own request signatures and compare them with the X-Plivo-Signature-V3 or X-Plivo-Signature-Ma-V3 HTTP headers passed by Plivo.
Signature Generation Logic
Plivo signs all HTTP requests from its servers to your application server. The logic used to generate these signatures is described below.
Assembling the complete request
Plivo assembles the request to your application server by concatenating the final request URL (the full URL with the scheme, port, and query string) and any POST parameters.
- If your request is a POST, Plivo takes all the POST parameters, sorts them alphabetically by name (using Unix style case sensitive sorting), and concatenates the parameter name and value pairs to the end of the URL.
- If the request is a GET, the final request URL would include all of Plivo’s request parameters appended in the query string of your original URL.
Example:
If your application URL is https://example.com/abcd?foo=bar and the list of Plivo POST params is:
- Digits:1234
- To:+15555555555
- From:+15551111111
- CallUUID:4vbcpem8-0u46-x1ha-9af1-438vc92bf374
Then the complete assembled request string would be:
- https://example.com/abcd?foo=bar.CallUuid4vbcpem8-0u46-x1ha-9af1-438vc92bf374Digits1234From+15551111111To+15555555555
Concatenating with Nonce value
The assembled request string from step one is then appended with a randomly generated ‘Nonce’ string which is unique for every request. This string is also passed separately in the HTTP header X-Plivo-Signature-V3-Nonce as part of the HTTP request to your application URL.
Example:
If the randomly generated Nonce value is:
kjsdhfsd87sd7yisud2
Then The following result would occur after concatenating it to the assembled request string from step one above
- https://example.com/abcd?foo=bar.CallUuid4vbcpem8-0u46-x1ha-9af1-438vc92bf374Caller+15551111111Digits1234From+15551111111To+15555555555.kjsdhfsd87sd7yisud2
Since Nonce values are unique, they are a great tool to protect your application server from replay attacks.
Signing with Auth Token
The output of step two above is then signed using HMAC-SHA256 and your Plivo Auth Tokens as the keys. The resulting signed hashes are Base 64 encoded and passed in HTTP headers with the request.
X-Plivo-Signature-V3 is generated using the Auth Token of the account or sub-account associated with the request entity.
For example, if the request is for an incoming call to a Plivo phone number mapped to one of your sub-accounts, then that sub-account’s Auth Token will be used when generating X-Plivo-Signature-V3.
X-Plivo-Signature-Ma-V3 on the other hand, is always generated using the Auth Token of your main Plivo account.
Validating requests on app server
Plivo Server SDKs include helper functions to validate incoming requests from the Plivo Voice platform using the X-Plivo-Signature HTTP headers.
Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
from flask import Flask, request, make_response, url_for
import plivo
from urllib.parse import urlparse, parse_qs
from plivo import utils
from plivo import plivoxml
app = Flask(__name__)
@app.route('/speak/', methods=['GET', 'POST'])
def validate_signature():
signature = request.headers.get('X-Plivo-Signature-V3', 'signature')
nonce = request.headers.get('X-Plivo-Signature-V3-Nonce', '12345')
url = url_for('validate_signature', _external=True)
auth_token = "your_auth_token"
method = request.method
if method == 'GET':
valid = plivo.utils.validate_v3_signature(
method, url, nonce, auth_token, signature)
else:
params = request.get_json()
valid = plivo.utils.validate_v3_signature(
method, url, nonce, auth_token, signature, params)
print(valid)
r = plivoxml.ResponseElement()
speak_params = {
'loop': '3'
}
r.add(plivoxml.SpeakElement("Hello, from Plivo", **speak_params))
response = make_response(r.to_string())
response.headers["Content-type"] = "text/xml"
print(r.to_string())
return response
if __name__ == "__main__":
app.run(host='0.0.0.0', debug=True)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
require 'sinatra'
require 'rubygems'
require 'plivo'
include Plivo
include Plivo::XML
get '/speak/' do
auth_token = "Your_Auth_Token"
signature = headers.fetch("X-Plivo-Signature-V3", "signature")
nonce = headers.fetch("X-Plivo-Signature-V3-Nonce", "12345")
url = request.url
method = "GET"
output = Plivo::Utils.valid_signatureV3?(url, nonce, signature, auth_token, method)
puts output
response = Response.new
response.addSpeak("Hello, Welcome to Plivo")
xml = PlivoXML.new(response)
content_type 'text/xml'
return xml.to_s
end
post '/speak/' do
auth_token = "your_auth_token"
signature = headers.fetch("X-Plivo-Signature-V3", "signature")
nonce = headers.fetch("X-Plivo-Signature-V3-Nonce", "12345")
url = request.url
method = "POST"
output = Plivo::Utils.valid_signatureV3?(url, nonce, signature, auth_token, method, params)
puts output
response = Response.new
response.addSpeak("Hello, Welcome to Plivo")
xml = PlivoXML.new(response)
content_type 'text/xml'
return xml.to_s
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
let express = require('express');
let app = express();
app.set('port', (process.env.PORT || 5000));
app.use(express.static(__dirname + '/public'));
app.all('/speak/', function (request, response) {
let headers = request.headers;
console.log(headers);
let signature = request["X-Plivo-Signature-V3"];
let nonce = request["X-Plivo-Signature-V3-Nonce"];
if (!signature) {
signature = "signature";
}
if (!nonce) {
nonce = "12345";
}
let url = request.url;
let auth_token = "your_auth_token";
console.log(signature, nonce);
let method = request.method;
let validate;
if (method == "GET") {
validate = plivo.validateV3Signature(method, url, nonce, auth_token, signature);
} else {
let params = request.body;
validate = plivo.validateV3Signature(method, url, nonce, auth_token, signature, params);
}
console.log(validate);
let r = plivo.Response();
r.addSpeak("Hello from Plivo");
console.log(r.toXML());
response.set({
'Content-Type': 'text/xml'
});
response.end(r.toXML());
});
app.listen(app.get('port'), function () {
console.log('Node app is running on port', app.get('port'));
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?php
require 'vendor/autoload.php';
use Plivo\Exceptions\PlivoValidationException;
use Plivo\Util\v3SignatureValidation;
use Plivo\XML\Response;
if (preg_match('/speak/', $_SERVER["REQUEST_URI"])) {
$auth_token = "your_auth_token";
$signature = @$_SERVER["X-Plivo-Signature-V3"] ?: 'signature';
$nonce = @$_SERVER["X-Plivo-Signature-V3-Nonce"] ?: 'nonce';
$url = 'http' . (isset($_SERVER['HTTPS']) ? 's' : '') . '://' . "{$_SERVER['HTTP_HOST']}{$_SERVER['REQUEST_URI']}";
$method = $_SERVER['REQUEST_METHOD'];
$SVUtil = new v3SignatureValidation();
if ($method == "GET") {
try {
$valid = $SVUtil->validateV3Signature($method, $url, $nonce, $auth_token, $signature);
} catch (PlivoValidationException $e) {
echo("error");
}
} else {
$body = file_get_contents("php://input");
$params = json_decode($body, true);
try {
$valid = $SVUtil->validateV3Signature($method, $url, $nonce, $auth_token, $signature, $params);
} catch (PlivoValidationException $e) {
echo("error");
}
}
echo $valid;
$body = 'Hi, Calling from Plivo';
$attributes = array(
'loop' => 3,
);
$r = new Response();
$r->addSpeak($body, $attributes);
echo($r->toXML());
} else {
echo "<p>Welcome to Plivo</p>";
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
package plivoexample;
import java.io.IOException;
import java.net.URLDecoder;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.plivo.helper.exception.PlivoException;
import com.plivo.helper.xml.elements.Message;
import com.plivo.helper.xml.elements.PlivoResponse;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import com.plivo.helper.util.*;
public class validateSignature extends HttpServlet {
private static final long serialVersionUID = 1L;
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
String auth_token = "your_auth_token";
String signature = req.getHeader("X-Plivo-Signature-V3");
String nonce = req.getHeader("X-Plivo-Signature-V3-Nonce");
String url = req.getRequestURL().toString();
String method = req.getMethod();
if(method == "GET") {
try {
Boolean isValid = Utils.validateSignatureV3(url, nonce, signature, auth_token, method);
System.out.println("Valid : " + isValid);
} catch (PlivoException e) {
e.printStackTrace();
}
}
else{
try {
Map<String, String> params = req.getParameterMap();
Boolean isValid = Utils.validateSignatureV3(url, nonce, signature, auth_token, method, params);
System.out.println("Valid : " + isValid);
} catch (PlivoException e) {
e.printStackTrace();
}
}
PlivoResponse response = new PlivoResponse();
Speak spk = new Speak("Hello, Welcome to Plivo");
try {
response.append(spk);
System.out.println(response.toXML());
resp.addHeader("Content-Type", "text/xml");
resp.getWriter().print(response.toXML());
} catch (PlivoException e) {
e.printStackTrace();
}
}
public static void main(String[] args) throws Exception {
String port = System.getenv("PORT");
if(port==null)
port ="8000";
Server server = new Server(Integer.valueOf(port));
ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
context.setContextPath("/");
server.setHandler(context);
context.addServlet(new ServletHolder(new validateSignature()),"/speak");
server.start();
server.join();
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"reflect"
"unsafe"
"github.com/plivo/plivo-go"
"github.com/plivo/plivo-go/xml"
"github.com/sirupsen/logrus"
)
type Message struct {
Id string `json:"id"`
Name string `json:"name"`
}
func BytesToString(b []byte) string {
bh := (*reflect.SliceHeader)(unsafe.Pointer(&b))
sh := reflect.StringHeader{bh.Data, bh.Len}
return *(*string)(unsafe.Pointer(&sh))
}
func speak(w http.ResponseWriter, request *http.Request) {
url := request.Host + request.RequestURI
signature := request.Header.Get("X-Plivo-Signature-V3")
nonce := request.Header.Get("X-Plivo-Signature-V3-Nonce")
method := request.Method
authToken := "your_auth_token"
var valid bool
if method == "GET" {
valid = plivo.ValidateSignatureV3(url, nonce, method, signature, authToken)
} else {
parameters := make(map[string]string)
b, err := ioutil.ReadAll(request.Body)
defer request.Body.Close()
if err != nil {
http.Error(w, err.Error(), 500)
return
}
var msg Message
err = json.Unmarshal(b, &msg)
if err != nil {
http.Error(w, err.Error(), 500)
return
}
var inInterface map[string]interface{}
inrec, _ := json.Marshal(msg)
json.Unmarshal(inrec, &inInterface)
for field, val := range inInterface {
parameters[field] = val.(string)
}
w.Header().Set("content-type", "text/xml")
valid = plivo.ValidateSignatureV3(url, nonce, method, signature, authToken, parameters)
}
logrus.Info(valid)
response := xml.ResponseElement{
Contents: []interface{}{
new(xml.SpeakElement).
SetContents("Go Green, Go Plivo."),
},
}
fmt.Fprintf(w, response.String())
}
func main() {
http.HandleFunc("/speak/", speak)
http.ListenAndServe(":5000", nil)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
using System;
using System.Collections.Generic;
using System.Diagnostics;
using RestSharp;
using Plivo.XML;
using Plivo;
using Nancy;
namespace plivo_dotnet_app
{
public sealed class Program : NancyModule
{
public Program()
{
Get("/speak/", x =>
{
string signature = Request.Headers["X-Plivo-Signature-V3"].ToString();
string nonce = Request.Headers["X-Plivo-Signature-V3_Nonce"].ToString();
string auth_token = "your_auth_token";
string method = Request.Method;
string url = Request.Url;
bool valid;
Dictionary<string, string> parameters = new Dictionary<string, string>();
valid = Plivo.Utilities.XPlivoSignatureV3.VerifySignature(url, nonce, signature, auth_token, method);
Debug.WriteLine("Valid : " + valid);
Plivo.XML.Response resp = new Plivo.XML.Response();
resp.AddSpeak("Hello, Welcome to Plivo", parameters);
Debug.WriteLine(resp.ToString());
var output = resp.ToString();
var res = (Nancy.Response) output;
res.ContentType = "text/xml";
return res;
});
Post<Response>("/speak/", x =>
{
string signature = Request.Headers["X-Plivo-Signature-V3"].ToString();
string nonce = Request.Headers["X-Plivo-Signature-V3_Nonce"].ToString();
string auth_token = "your_auth_token";
string method = Request.Method;
string url = Request.Url;
bool valid;
Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters = Request.Form;
valid = Plivo.Utilities.XPlivoSignatureV3.VerifySignature(url, nonce, signature, auth_token, method, parameters);
Debug.WriteLine("Valid : " + valid);
Plivo.XML.Response resp = new Plivo.XML.Response();
resp.AddSpeak("Hello, Welcome to Plivo", parameters);
Debug.WriteLine(resp.ToString());
var output = resp.ToString();
var res = (Nancy.Response) output;
res.ContentType = "text/xml";
return res;
});
}
static void Main(string[] args)
{
var p = new Program();
}
}
}
You may also write your own request validation code by generating request signatures based on the Signature Generation Logic explained above, and validating them against the signatures passed by Plivo in the HTTP request headers.
Deprecation notice: X-Plivo-Signature-V2
If you’re currently using Plivo’s V2 Signatures to validate requests, we highly recommend switching over to the new and enhanced X-Plivo-Signature-V3. V3 signatures offer improved protection against manipulation of POST request payloads en route.
Click here for more information on X-Plivo-Signature-V2.