Skip to main content

Nginx secure link with node.js

Serving static files is a natural task for web servers. They, especially ones, having asynchronous architecture (like Nginx), are very good at such tasks.
However, usually there is an additional security logic, which should restrict access to files you've published. IIS, for example, offers deep integration with application layer, which allows custom .NET "middleware" logic injection into the request pipeline.
Node.js applications are very often published behind Nginx for various reasons and, with the help of Nginx "Secure Link" module, it's possible to offload static file serving tasks from node.js to Nginx, even if the files are not public. This module uses "shared secret" string (known to Nginx and the application) and expects a hash, based on this secret, to be present in the request to decide whether to proceed or return an error.

Secure Link module may work in 2 alternative modes (
  1. Simpler mode, based on "secure_link_secret" directive. Hash value in the request is based on concatenation of link to file and the secret. In this mode we can only check whether client was given hash for particular link
  2. More complex mode, based on 2 directives ("secure_link" and "secure_link_md5"). In this mode, we can restrict validity time of the hash and some other client-specific parameters, known to Nginx (like IP address or a header value)
This article focuses on the second mode, since it is more powerful and therefore more useful. Following is an example of Nginx configuration, using this mode:

It expects requests like /img/file.doc?h=[hash]&e=[expire time]. Lines in the configuration should be read as follows:
(1) When accessing /img/.. links, Nginx will first perform the following checks
(2) "secure_link" directive describes the way Nginx should extract generated hash value and (optionally) link expire time from the request. In this example, we specify that hash value and link expire time should be extracted from query string arguments "h" and "e" respectively.
(3)"secure_link_md5" directive describes what hash value Nginx expects to see in the request. "$secure_link_expires" variable contains expire time extracted from the request (value of "e" argument in our case). So, to generate correct hash value, we should hash concatenation of link expire time (seconds since "Epoch time"), request uri, space and "shared secret" ("6q3R9jhzG5" in our case)
(5-7) if hash comparison fails, return 404 error status
(9-11) if hash comparison succeeds, but expire time is less than server time, return 404 error status
(13) otherwise, continue with the request

Before browser (or other user agent) can request a file from Nginx, application server needs to generate a hash to be passed to the web server (along with expire time, used in hash generation). Following is a node.js function which generates such hash:

It's important to note that generated hash is expected to be in base64url format, which is ensured by the last line of the function.


Nginx secure link module may not have the best documentation, but once you understand it, it's very easy to use. I have found it useful, because it allowed to significantly decrease number of requests to node.js server and database hits.

MD5 algorithm has a bad reputation in security and, of course, its a bad idea to use it to store passwords. However, if you have long-enough secret (which should be longer, than in this example), it is absolutely impractical to use any of primitive techniques (like brute force or rainbow tables) to find secret out of hash value. Collision attack is not relevant either, since user agent does not present a secret to be hashed, but hash value itself. That means, that using md5 is a reasonably secure solution for secure links. Also, its performance is very important for this module to be useful.


Popular posts from this blog

Performance of Redis sorted set operations

I was working on a feature recently, which involved several Redis "remove from sorted set" operations. Target production environment sorted sets are expected to be small and most of these calls would be trying to remove items, which do not exist in the sets. Although ZREM operation has documented LON(N) time complexity, ZSCORE has documented constant time complexity. This led me to believe, that Redis might have constant time complecity for ZREM calls when values to be removed do not exist in the set (if ZSCORE "knows" if item is NOT in the set in constant time, ZREM can do the same, right?). Not in this case, apparently. ZSCORE documented constant time complexity is actually misleading (as many cases of asymptotic time complexity documentation for small data sets). Redis stores small sorted sets (up to 128 items by default) as "ziplists", which are essentially linked lists, optimized for memory consumption. Browsing through Redis source code confirms th

Redis Lua scripts are not really transactions

Redis support of Lua scripts is a great feature. We use it a lot to build fast reliable queues with some very interesting requirements. You need it every time you want to decide your next Redis command, based on the result of a previous command, while guaranteeing that no one else has done anything with this result or anything else has changed in Redis. That is, the whole Redis script is an "atomic" operation. However, I put it in quotes intentionally. My understanding of phrase "atomic operation" is that not only no one else can see it half complete while it is executing (that works so great in Redis). It should also mean, that it should never be left half complete if an error occurs in the middle (or at least, that is my wishful thinking:) ). Yea, exactly, the second point doesn't work in Redis and there is no warning in the official docs. To be more polite (or precise), there is no rollback in Redis (referring to a comment in this SO question -  http://sta