apache_secure_download 0.0.3.217 → 0.0.4.218

data/ChangeLog

@@ -1,10 +1,13 @@
 = Revision history for apache_secure_download
 
+== 0.0.4 [2008-02-26]
+
+* Some documentation, at last
+
 == 0.0.3 [2008-02-25]
 
-* Apache::SecureDownload::Util.secure_url
-** also takes a hash with options instead of explicit expiration time
-** can create cacheable URLs by setting the <tt>:cache</tt> option
+* Apache::SecureDownload::Util.secure_url also takes a hash with options instead of explicit expiration time
+* Apache::SecureDownload::Util.secure_url can create cacheable URLs by setting the <tt>:cache</tt> option
 
 == 0.0.2 [2008-02-20]
 

data/README

@@ -2,7 +2,7 @@
 
 == VERSION
 
-This documentation refers to apache_secure_download version 0.0.3
+This documentation refers to apache_secure_download version 0.0.4
 
 
 == DESCRIPTION
@@ -38,6 +38,8 @@ And create links to your resources with timestamp and token:
   # specify expiration time using an offset (results in Time.now + 60; also includes caching for 60 seconds):
   url = Apache::SecureDownload::Util.secure_url("secret", path, :offset => 60)
 
+See Apache::SecureDownload::Util.secure_url for more examples.
+
 
 == AUTHORS
 

data/lib/apache/secure_download/util.rb

@@ -37,10 +37,54 @@ module Apache
 
       extend self
 
+      # Computes the token from +secret+, +path+, and +timestamp+.
       def token(secret, path, timestamp)
         Digest::SHA1.hexdigest(secret + path + timestamp.to_s)
       end
 
+      # Creates a valid URL to the secured resource, identified by +url+. The
+      # argument +secret+ is the shared secret string that has been passed to
+      # the relevant RubyAccessHandler instance (cf. SecureDownload.new).
+      #
+      # The expiration time may be either given as a Time (or Integer), or as
+      # a Hash with the following parameters:
+      #
+      # <tt>:expires</tt>:: Same as for the simple +expires+ argument
+      # <tt>:offset</tt>::  The amount of seconds in the future (only if
+      #                     <tt>:expires</tt> is not given)
+      # <tt>:cache</tt>::   A time window for which identical URLs shall be
+      #                     produced, on average (defaults to <tt>:offset</tt>,
+      #                     if given)
+      #
+      # Examples (<tt>s = "secret"</tt>):
+      #
+      #   # Only the path component (and an optional query component) will be taken into account
+      #   secure_url(s, "/secure/url")                    #=> "/secure/url?timestamp=1204024618&token=4dd9ebe9d3c9bc0efbeea7e1ee453a8c41d5e04d"
+      #   secure_url(s, "http://example.com/secure/url")  #=> "http://example.com/secure/url?timestamp=1204024618&token=4dd9ebe9d3c9bc0efbeea7e1ee453a8c41d5e04d"
+      #   secure_url(s, "/secure/url?query=value")        #=> "/secure/url?query=value&timestamp=1204024618&token=4732b30f5899821426bd0c15da363c60cc4f943b"
+      #
+      #   # Expires in 10 minutes
+      #   secure_url(s, "/secure/url", Time.now + 600)  #=> "/secure/url?timestamp=1204025158&token=efefcd93f8065836cf576b34e1849075c3d56bbf"
+      #   secure_url(s, "/secure/url", :offset => 600)  #=> "/secure/url?timestamp=1204026000&token=58eb12f9fc3fcd984fe4e918d3fd0590392c172d"
+      #
+      #   # Setting an offset will also allow caching; turn it off explicitly
+      #   secure_url(s, "/secure/url", :offset => 600, :cache => false)  #=> "/secure/url?timestamp=1204025158&token=efefcd93f8065836cf576b34e1849075c3d56bbf"
+      #
+      #   # Produce identical URLs for a window of 1 minute (on average)
+      #   t = Time.now
+      #   secure_url(s, "/secure/url", :expires => t,      :cache => 60)  #=> "/secure/url?timestamp=1204024620&token=d4f9145f45c5826b50506c770cc204e22c3b7a21"
+      #   secure_url(s, "/secure/url", :expires => t + 30, :cache => 60)  #=> "/secure/url?timestamp=1204024620&token=d4f9145f45c5826b50506c770cc204e22c3b7a21"
+      #   secure_url(s, "/secure/url", :expires => t + 60, :cache => 60)  #=> "/secure/url?timestamp=1204024680&token=ccf279daf1787d34ad063cbf5851ee88aae967fb"
+      #   secure_url(s, "/secure/url", :expires => t + 90, :cache => 60)  #=> "/secure/url?timestamp=1204024680&token=ccf279daf1787d34ad063cbf5851ee88aae967fb"
+      #
+      #   # Same as before, but use offset
+      #   secure_url(s, "/secure/url", :offset => 60) #=> "/secure/url?timestamp=1204024680&token=ccf279daf1787d34ad063cbf5851ee88aae967fb"
+      #   # 30 seconds later...
+      #   secure_url(s, "/secure/url", :offset => 60) #=> "/secure/url?timestamp=1204024680&token=ccf279daf1787d34ad063cbf5851ee88aae967fb"
+      #   # 30 seconds later...
+      #   secure_url(s, "/secure/url", :offset => 60) #=> "/secure/url?timestamp=1204024740&token=c7dcea5679ad539a7bad1dc4b7f44eb3dd36d6e8"
+      #   # 30 seconds later...
+      #   secure_url(s, "/secure/url", :offset => 60) #=> "/secure/url?timestamp=1204024740&token=c7dcea5679ad539a7bad1dc4b7f44eb3dd36d6e8"
       def secure_url(secret, url, expires = Time.now + 60)
         path, _, query = URI.split(url)[5..7]
         path << '?' << query if query

data/lib/apache/secure_download/version.rb

@@ -6,7 +6,7 @@ module Apache
 
       MAJOR = 0
       MINOR = 0
-      TINY  = 3
+      TINY  = 4
 
       class << self
 

data/lib/apache/secure_download.rb

@@ -34,10 +34,20 @@ module Apache
 
   class SecureDownload
 
+    # Creates a new RubyAccessHandler instance for the Apache web server.
+    # The argument +secret+ is the shared secret string that the application
+    # uses to create valid URLs (tokens).
     def initialize(secret)
       raise ArgumentError, 'secret string missing' unless @secret = secret
     end
 
+    # Checks whether the current +request+ satisfies the following requirements:
+    #
+    # 1. The expiration time lies in the future (i.e., not expired)
+    # 2. The token is valid for the requested URL and the given timestamp
+    #
+    # If either condition doesn't hold true, access to the requested resource
+    # is forbidden!
     def check_access(request)
       timestamp = request.param('timestamp')
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: apache_secure_download
 version: !ruby/object:Gem::Version 
-  version: 0.0.3.217
+  version: 0.0.4.218
 platform: ruby
 authors: 
 - Jens Wille
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-02-25 00:00:00 +01:00
+date: 2008-02-26 00:00:00 +01:00
 default_executable: 
 dependencies: []