Return to secdownload.txt CVS log

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

Annotation of embedaddon/lighttpd/doc/outdated/secdownload.txt, revision 1.1.1.2

1.1       misho       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
1.1.1.2 ! misho     147:   secdownload.algorithm       = "md5"