The Bazaarvoice Displayable Content Export (DCE) provides an HTTP interface for bulk requesting Bazaarvoice Conversations data intended for public display. To learn more, go to the DCE documentation home page.

Contents

(+ show- hide)

The Displayble Content Export (DCE) uses an access signature to verify that an incoming request originated from a trusted source. The access signature is a hash-based message authentication code (HMAC) consisting of values used in the request encrypted with a shared secret.

Bazaarvoice will use the values in the request along with our version of the shared secret to create our own access signature. If ours matches the one in the request, then we can be reasonably confident the request came from a trusted source.

Signature contents

The message to be encrypted will vary based on the DCE request. The two possible variations are demonstrated below:

Without path passkey={DCE_PASSKEY}&timestamp={TIMESTAMP}
With path path={PATH_VALUE}&passkey={DCE_PASSKEY}&timestamp={TIMESTAMP}

The tokens above should be replaced with the appropriate values as described below:

Name Description
{PATH_VALUE}

This is the same value communicated in the path query string parameter. Refer to the Workflow Walk-Through for more information.

{DCE_PASSKEY}

This is the same value communicated with the X-Bazaarvoice-Passkey header.

{TIMESTAMP}

A Unix timestamp in milliseconds. This is the same value communicated by the X-Bazaarvoice-Timestamp header.

Using seconds or any increment other than milliseconds will cause your request to fail

Pseudo-code implementation

This pseudo-code demonstrates how to create an access signature:

message = utf8_encode("{MESSAGE}")
shared_secret = utf8_encode("{SHARED_SECRET}")
hmac =  hmac_sha256(shared_secret, message)
access_signature = hex(hmac)

Defer to your programming language's documentation for the exact implementation.

Verification values

Use the following values to verify your implementation:

Token Value
{MESSAGE}

passkey=3412n4c4n243023nc03924nc0&timestamp=1502488941011

{SHARED_SECRET}

c73270c70932n09n09rn0r9n7

Using the verification values above in your implementation should output the following:

b6a597270d65be4e57de826ef10ac670c6fb195c09a0c4b488f51ab32f278ac9

Code samples

The code samples below are for educational purposes only. They are not intended to be used in a production environment and are provided "as is" without warranty of any kind.

The following code samples demonstrate how to encrypt the access signature. Defer to your programming language's documentation for the exact implementation.

This code sample was created using Java 8.

        // Usage:
        // 1. path/to/file$ javac HmacAccessSignExample.java
        // 2. path/to/file$ java HmacAccessSignExample "message" "sharedSecret"

        import javax.crypto.Mac;
        import javax.crypto.spec.SecretKeySpec;
        import javax.xml.bind.DatatypeConverter;
        import java.io.UnsupportedEncodingException;
        import java.security.InvalidKeyException;
        import java.security.NoSuchAlgorithmException;

        public class HmacAccessSignExample {

            public static void main( String[] args ) throws Exception {
                String message = args[0];
                String sharedSecret = args[1];
                String digest = null;

                try {
                    SecretKeySpec key = new SecretKeySpec(sharedSecret.getBytes("UTF-8"), "HmacSHA256");
                    Mac mac = Mac.getInstance("HmacSHA256");
                    mac.init(key);
                    byte[] bytes = mac.doFinal(message.getBytes("UTF-8"));
                    digest = DatatypeConverter.printHexBinary(bytes);
                }
                catch (UnsupportedEncodingException e) {}
                catch (InvalidKeyException e) {}
                catch (NoSuchAlgorithmException e) {}

                System.out.println(digest.toLowerCase());
            }
        }
        

This code sample was created using C# 6.0.

        // Usage:
        // 1. path\to\file> csc HmacAccessSignExample.cs
        // 2. path\to\file> HmacAccessSignExample.exe "message" "sharedSecret"

        using System;
        using System.Text;
        using System.Security.Cryptography;

        public class HmacAccessSignExample
        {
            static void Main(string[] args)
            {
                string message = args[0];
                string key = args[1];
                string digest = null;

                var hmac = new HMACSHA256(UTF8Encode(key));
                byte[] bytes = hmac.ComputeHash(UTF8Encode(message));
                digest = HexEncode(bytes);

                Console.WriteLine(digest.ToLower());
            }

            public static byte[] UTF8Encode(string text)
            {
                var encoding = new UTF8Encoding();
                return encoding.GetBytes(text);
            }

            public static string HexEncode(byte[] bytes)
            {
                return BitConverter.ToString(bytes).Replace("-", "");
            }
        }
        

This code sample was created using Node v4.4.

        // Usage: $ node HmacAccessSignExample.js "message" "sharedSecret"

        var crypto = require('crypto');

        var message = new Buffer(process.argv[2], "utf8");
        var sharedSecret = new Buffer(process.argv[3], "utf8");

        var hmac = crypto.createHmac('sha256', sharedSecret).update(message);
        var digest = hmac.digest('hex');

        console.log(digest);
        

This code sample was created using Python 2.7.

        # Usage: path/to/file$ python HmacAccessSignExample.py "message" "sharedSecret"

        import sys
        import hmac
        import hashlib

        message =  unicode(sys.argv[1], 'utf-8')
        sharedSecret =  unicode(sys.argv[2], 'utf-8')

        digest = hmac.new(sharedSecret.encode('utf-8'), message.encode('utf-8'), hashlib.sha256).hexdigest()

        print digest
        

This code sample was created using PHP 5.5.

        <?php
        // usage: path/to/file$  php HmacAccessSignExample.php "message" "sharedSecret"

        // utf8_encode() assumes input is ISO-8859-1 encoded. Your implementation may
        // require a different technique.
        $message =  utf8_encode($argv[1]);
        $sharedSecret =  utf8_encode($argv[2]);

        $digest =  hash_hmac("sha256", $message, $sharedSecret);
        echo $digest . "\n";
        

Next steps

Take a step-by-step walk-through of the DCE workflow.