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.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
        !           147: