Zephr User Guide

Create Trusted Links

6 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:

https://www.your-website.com/protected-content.html?btr=17e74b9e49e66282e55d4b7ec73de951

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.