src/ceph/doc/radosgw/swift/tempurl.rst

   1 ====================
   2  Temp URL Operations
   3 ====================
   4
   5 To allow temporary access (for eg for `GET` requests) to objects
   6 without the need to share credentials, temp url functionality is
   7 supported by swift endpoint of radosgw. For this functionality,
   8 initially the value of `X-Account-Meta-Temp-URL-Key` and optionally
   9 `X-Account-Meta-Temp-URL-Key-2` should be set. The Temp URL
  10 functionality relies on a HMAC-SHA1 signature against these secret
  11 keys.
  12
  13 POST Temp-URL Keys
  14 ==================
  15
  16 A ``POST`` request to the swift account with the required Key will set
  17 the secret temp url key for the account against which temporary url
  18 access can be provided to accounts. Up to two keys are supported, and
  19 signatures are checked against both the keys, if present, so that keys
  20 can be rotated without invalidating the temporary urls.
  21
  22 Syntax
  23 ~~~~~~
  24
  25 ::
  26
  27         POST /{api version}/{account} HTTP/1.1
  28         Host: {fqdn}
  29         X-Auth-Token: {auth-token}
  30
  31 Request Headers
  32 ~~~~~~~~~~~~~~~
  33
  34 ``X-Account-Meta-Temp-URL-Key``
  35
  36 :Description: A user-defined key that takes an arbitrary string value.
  37 :Type: String
  38 :Required: Yes
  39
  40 ``X-Account-Meta-Temp-URL-Key-2``
  41
  42 :Description: A user-defined key that takes an arbitrary string value.
  43 :Type: String
  44 :Required: No
  45
  46
  47 GET Temp-URL Objects
  48 ====================
  49
  50 Temporary URL uses a cryptographic HMAC-SHA1 signature, which includes
  51 the following elements:
  52
  53 #. The value of the Request method, "GET" for instance
  54 #. The expiry time, in format of seconds since the epoch, ie Unix time
  55 #. The request path starting from "v1" onwards
  56
  57 The above items are normalized with newlines appended between them,
  58 and a HMAC is generated using the SHA-1 hashing algorithm against one
  59 of the Temp URL Keys posted earlier.
  60
  61 A sample python script to demonstrate the above is given below:
  62
  63
  64 .. code-block:: python
  65
  66    import hmac
  67    from hashlib import sha1
  68    from time import time
  69
  70    method = 'GET'
  71    host = 'https://objectstore.example.com/swift'
  72    duration_in_seconds = 300  # Duration for which the url is valid
  73    expires = int(time() + duration_in_seconds)
  74    path = '/v1/your-bucket/your-object'
  75    key = 'secret'
  76    hmac_body = '%s\n%s\n%s' % (method, expires, path)
  77    sig = hmac.new(key, hmac_body, sha1).hexdigest()
  78    rest_uri = "{host}{path}?temp_url_sig={sig}&temp_url_expires={expires}".format(
  79                 host=host, path=path, sig=sig, expires=expires)
  80    print rest_uri
  81
  82    # Example Output
  83    # https://objectstore.example.com/swift/v1/your-bucket/your-object?temp_url_sig=ff4657876227fc6025f04fcf1e82818266d022c6&temp_url_expires=1423200992
  84