doc/outdated/secdownload.txt

   1 ===========================
   2 Secure and Fast Downloading
   3 ===========================
   4
   5 -----------------------
   6 Module: mod_secdownload
   7 -----------------------
   8
   9 :Author: Jan Kneschke
  10 :Date: $Date: 2004/08/01 07:01:29 $
  11 :Revision: $Revision: 1.1 $
  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"