Zephr User Guide

Create Trusted Links

5 views 0

A trusted link uses a btr token, using the btr=<token> format, which must be generated server-side for each link by the referrer. The link only works when followed from a page on the referrer’s domain. A trusted link looks similar to the following:


Zephr uses the Referrer HTTP header to validate the btr token. Zephr cannot validate the btr token if the link is copied and pasted, sent by email or published on a different site.

To generate btr tokens, your trusted referrer must use server-side code.

To obtain the btr token for a specific link, use MD5 to hash the path in the link with the secret generated in the Add a Trusted Referrer dialog box. The two parts are separated with a pipe (|) symbol.

The following examples show the code required for a trusted referrer with a website of trusted-forum.biz and a generated secret of 89b4c0e4-e95f-4981-b872-b85ea5aec0ff who want to generate a link to http://your-website.com/stories/article228.html.

Java Example

public String createBTRToken(String path, String secret) {
    try {
        return DatatypeConverter.printHexBinary(MessageDigest.getInstance("MD5").digest((path + "|" + secret).getBytes(StandardCharsets.UTF_8);
    } catch (Exception e) {
        return "";
String trustedLink = "https://www.your-website.com/stories/article228.html?btr=" + createBTRToken("/stories/article228.html", "89b4c0e4-e95f-4981-b872-b85ea5aec0ff");

PHP Example

<?php echo 'https://www.your-website.com/stories/article228.html?btr=' . md5('/stories/article228.html|89b4c0e4-e95f-4981-b872-b85ea5aec0ff') ?>

JavaScript Example

Note: This is the node.js code required server-side.

 // assumes md5 was installed with npm install md5

var md5 = require('md5');

var trustedLink = 'https://www.your-website.com?btr=' + md5('/stories/article228.html' + | + '89b4c0e4-e95f-4981-b872-b85ea5aec0ff');

The trusted referrer must use JavaScript client-side to generate trusted links, or users can potentially create their own trusted links and spoof the Referrer HTTP header to access content.