Return to secdownload.txt CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated

lighttpd 1.4.41

    1: ===========================
    2: Secure and Fast Downloading
    3: ===========================
    4: 
    5: -----------------------
    6: Module: mod_secdownload
    7: -----------------------
    8: 
    9: :Author: Jan Kneschke
   10: :Date: $Date: 2016/11/02 10:35:00 $
   11: :Revision: $Revision: 1.1.1.2 $
   12: 
   13: :abstract:
   14:   authenticated file requests and a countermeasure against
   15:   deep-linking can be achieved easily by using mod_secdownload
   16: 
   17: .. meta::
   18:   :keywords: lighttpd, secure, fast, downloads
   19: 
   20: .. contents:: Table of Contents
   21: 
   22: Options
   23: =======
   24: 
   25: ::
   26: 
   27:   secdownload.secret        = <string>
   28:   secdownload.document-root = <string>
   29:   secdownload.uri-prefix    = <string>  (default: /)
   30:   secdownload.timeout       = <short>   (default: 60 seconds)
   31: 
   32: Description
   33: ===========
   34: 
   35: there are multiple ways to handle secured download mechanisms:
   36: 
   37: 1. use the webserver and the internal HTTP authentication
   38: 2. use the application to authenticate and send the file
   39:    through the application
   40: 
   41: Both ways have limitations:
   42: 
   43: webserver:
   44: 
   45: - ``+`` fast download
   46: - ``+`` no additional system load
   47: - ``-`` inflexible authentication handling
   48: 
   49: application:
   50: 
   51: - ``+`` integrated into the overall layout
   52: - ``+`` very flexible permission management
   53: - ``-`` the download occupies an application thread/process
   54: 
   55: A simple way to combine the two ways could be:
   56: 
   57: 1. app authenticates user and checks permissions to
   58:    download the file.
   59: 2. app redirects user to the file accessable by the webserver
   60:    for further downloading.
   61: 3. the webserver transfers the file to the user.
   62: 
   63: As the webserver doesn't know anything about the permissions
   64: used in the app, the resulting URL would be available to every
   65: user who knows the URL.
   66: 
   67: mod_secdownload removes this problem by introducing a way to
   68: authenticate a URL for a specified time. The application has
   69: to generate a token and a timestamp which are checked by the
   70: webserver before it allows the file to be downloaded by the
   71: webserver.
   72: 
   73: The generated URL has to have the format:
   74: 
   75: <uri-prefix><token>/<timestamp-in-hex><rel-path>
   76: 
   77: <token> is an MD5 of
   78: 
   79: 1. a secret string (user supplied)
   80: 2. <rel-path> (starts with /)
   81: 3. <timestamp-in-hex>
   82: 
   83: 
   84: As you can see, the token is not bound to the user at all. The
   85: only limiting factor is the timestamp which is used to
   86: invalidate the URL after a given timeout (secdownload.timeout).
   87: 
   88: .. Note::
   89:   Be sure to choose a another secret than the one used in the
   90:   examples, as this is the only part of the token that is not
   91:   known to the user.
   92: 
   93: 
   94: 
   95: If the user tries to fake the URL by choosing a random token,
   96: status 403 'Forbidden' will be sent out.
   97: 
   98: If the timeout is reached, status 408 'Request Timeout' will be
   99: sent. (This does not really conform to the standard, but should
  100: do the trick).
  101: 
  102: If token and timeout are valid, the <rel-path> is appended to
  103: the configured (secdownload.document-root) and passed to the
  104: normal internal file transfer functionality. This might lead to
  105: status 200 or 404.
  106: 
  107: Example
  108: =======
  109: 
  110: Application
  111: -----------
  112: 
  113: Your application has to generate the correct URLs. The following sample
  114: code for PHP should be easily adaptable to any other language: ::
  115: 
  116:   <?php
  117: 
  118:   $secret = "verysecret";
  119:   $uri_prefix = "/dl/";
  120: 
  121:   # filename
  122:   $f = "/secret-file.txt";
  123: 
  124:   # current timestamp
  125:   $t = time();
  126: 
  127:   $t_hex = sprintf("%08x", $t);
  128:   $m = md5($secret.$f.$t_hex);
  129: 
  130:   # generate link
  131:   printf('<a href="%s%s/%s%s">%s</a>',
  132:          $uri_prefix, $m, $t_hex, $f, $f);
  133:   ?>
  134: 
  135: Webserver
  136: ---------
  137: 
  138: The server has to be configured in the same way. The URI prefix and
  139: secret have to match: ::
  140: 
  141:   server.modules = ( ..., "mod_secdownload", ... )
  142: 
  143:   secdownload.secret          = "verysecret"
  144:   secdownload.document-root   = "/home/www/servers/download-area/"
  145:   secdownload.uri-prefix      = "/dl/"
  146:   secdownload.timeout         = 120
  147:   secdownload.algorithm       = "md5"