X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/f569984ab4f48b393901fe3295218e576e81b9eb..3ac9fd0c91fe202a59e7c3611156bb1a9b8118fe:/services/api/app/models/blob.rb

diff --git a/services/api/app/models/blob.rb b/services/api/app/models/blob.rb
index 0ba299a45b..5decd77261 100644
--- a/services/api/app/models/blob.rb
+++ b/services/api/app/models/blob.rb
@@ -1,25 +1,57 @@
 class Blob
+
+  # In order to get a Blob from Keep, you have to prove either
+  # [a] you have recently written it to Keep yourself, or
+  # [b] apiserver has recently decided that you should be able to read it
+  #
+  # To ensure that the requestor of a blob is authorized to read it,
+  # Keep requires clients to timestamp the blob locator with an expiry
+  # time, and to sign the timestamped locator with their API token.
+  #
+  # A signed blob locator has the form:
+  #     locator_hash +A blob_signature @ timestamp
+  # where the timestamp is a Unix time expressed as a hexadecimal value,
+  # and the blob_signature is the signed locator_hash + API token + timestamp.
+  # 
   class InvalidSignatureError < StandardError
   end
 
+  # Blob.sign_locator: return a signed and timestamped blob locator.
+  #
+  # The 'opts' argument should include:
+  #   [required] :key       - the Arvados server-side blobstore key
+  #   [required] :api_token - user's API token
+  #   [optional] :ttl       - number of seconds before signature should expire
+  #   [optional] :expire    - unix timestamp when signature should expire
+  #
   def self.sign_locator blob_locator, opts
     # We only use the hash portion for signatures.
     blob_hash = blob_locator.split('+').first
 
-    # Generate an expiry timestamp (seconds since epoch, base 16)
-    timestamp = (Time.now.to_i + (opts[:ttl] || 600)).to_s(16)
+    # Generate an expiry timestamp (seconds after epoch, base 16)
+    if opts[:expire]
+      if opts[:ttl]
+        raise "Cannot specify both :ttl and :expire options"
+      end
+      timestamp = opts[:expire]
+    else
+      timestamp = Time.now.to_i + (opts[:ttl] || 600)
+    end
+    timestamp_hex = timestamp.to_s(16)
     # => "53163cb4"
 
     # Generate a signature.
     signature =
-      OpenSSL::HMAC.hexdigest('sha1', opts[:key],
-                              [blob_hash,
-                               opts[:api_token],
-                               timestamp].join('@'))
+      generate_signature opts[:key], blob_hash, opts[:api_token], timestamp_hex
 
-    blob_locator + '+A' + signature + '@' + timestamp
+    blob_locator + '+A' + signature + '@' + timestamp_hex
   end
 
+  # Blob.verify_signature
+  #   Safely verify the signature on a blob locator.
+  #   Return value: true if the locator has a valid signature, false otherwise
+  #   Arguments: signed_blob_locator, opts
+  #
   def self.verify_signature *args
     begin
       self.verify_signature! *args
@@ -29,6 +61,14 @@ class Blob
     end
   end
 
+  # Blob.verify_signature!
+  #   Verify the signature on a blob locator.
+  #   Return value: true if the locator has a valid signature
+  #   Arguments: signed_blob_locator, opts
+  #   Exceptions:
+  #     Blob::InvalidSignatureError if the blob locator does not include a
+  #     valid signature
+  #
   def self.verify_signature! signed_blob_locator, opts
     blob_hash = signed_blob_locator.split('+').first
     given_signature, timestamp = signed_blob_locator.
@@ -47,14 +87,19 @@ class Blob
     end
 
     my_signature =
-      OpenSSL::HMAC.hexdigest('sha1', opts[:key],
-                              [blob_hash,
-                               opts[:api_token],
-                               timestamp].join('@'))
+      generate_signature opts[:key], blob_hash, opts[:api_token], timestamp
+
     if my_signature != given_signature
       raise Blob::InvalidSignatureError.new 'Signature is invalid.'
     end
 
     true
   end
+
+  def self.generate_signature key, blob_hash, api_token, timestamp
+    OpenSSL::HMAC.hexdigest('sha1', key,
+                            [blob_hash,
+                             api_token,
+                             timestamp].join('@'))
+  end
 end