From d67873474231668a4ca3710750e16c1c1e282d2a Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Fri, 24 Jan 2014 15:17:28 -0600 Subject: [PATCH] Add temp URL and form POST to dev guide Rewrote the existing text from Configuration Reference to suit a developer audience Closes-Bug: #1233917 Change-Id: I79cddeb0a2dc53856caf58487ea58dc679145bc7 author: diane fleming --- .../bk_os-objectstorage-devguide.xml | 16 +- .../ch_object-api-general.xml | 4 +- openstack-object-storage-dev/pom.xml | 2 +- ...ch_object-api-overview.xml => preface.xml} | 0 .../samples/formpost.txt | 14 + .../samples/tempurl.txt | 4 + .../section_object_api_formpost.xml | 243 ++++++++++++++++++ .../section_object_api_tempurl.xml | 217 ++++++++++++++++ 8 files changed, 495 insertions(+), 5 deletions(-) rename openstack-object-storage-dev/{ch_object-api-overview.xml => preface.xml} (100%) create mode 100644 openstack-object-storage-dev/samples/formpost.txt create mode 100644 openstack-object-storage-dev/samples/tempurl.txt create mode 100644 openstack-object-storage-dev/section_object_api_formpost.xml create mode 100644 openstack-object-storage-dev/section_object_api_tempurl.xml diff --git a/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml b/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml index 8923980..479e169 100644 --- a/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml +++ b/openstack-object-storage-dev/bk_os-objectstorage-devguide.xml @@ -49,6 +49,7 @@ 2011 2012 2013 + 2014 OpenStack Foundation API v1 @@ -66,6 +67,17 @@ Application Programming Interface (API) v1. + + 2014-01-24 + + + + Added information about form &POST; and + temporary URL middleware. + + + + 2013-10-16 @@ -173,7 +185,7 @@ Revised for OpenStack Object Storage use by removing CDN references, Rackspace Cloud references, and revised account examples and URLs for generic - implementations. Clarified that container and object + implementations. Clarified that container and object names must be UTF-8 encoded. @@ -217,7 +229,7 @@ - + diff --git a/openstack-object-storage-dev/ch_object-api-general.xml b/openstack-object-storage-dev/ch_object-api-general.xml index 1ef5120..9a68c24 100644 --- a/openstack-object-storage-dev/ch_object-api-general.xml +++ b/openstack-object-storage-dev/ch_object-api-general.xml @@ -186,7 +186,7 @@ format="SVG" scale="60"/> OpenStack Object Storage are performed using SSL over HTTP (HTTPS) on TCP port 443. - - + + diff --git a/openstack-object-storage-dev/pom.xml b/openstack-object-storage-dev/pom.xml index efb6666..2e7fc1b 100644 --- a/openstack-object-storage-dev/pom.xml +++ b/openstack-object-storage-dev/pom.xml @@ -23,7 +23,7 @@ com.rackspace.cloud.api clouddocs-maven-plugin - 1.12.2 + 1.13.0 diff --git a/openstack-object-storage-dev/ch_object-api-overview.xml b/openstack-object-storage-dev/preface.xml similarity index 100% rename from openstack-object-storage-dev/ch_object-api-overview.xml rename to openstack-object-storage-dev/preface.xml diff --git a/openstack-object-storage-dev/samples/formpost.txt b/openstack-object-storage-dev/samples/formpost.txt new file mode 100644 index 0000000..62179d1 --- /dev/null +++ b/openstack-object-storage-dev/samples/formpost.txt @@ -0,0 +1,14 @@ +<![CDATA[ +
+ + + + + + +
+ +
+]]> \ No newline at end of file diff --git a/openstack-object-storage-dev/samples/tempurl.txt b/openstack-object-storage-dev/samples/tempurl.txt new file mode 100644 index 0000000..6197e07 --- /dev/null +++ b/openstack-object-storage-dev/samples/tempurl.txt @@ -0,0 +1,4 @@ +https://swift-cluster.example.com/v1/my_account/container/object +?temp_url_sig=da39a3ee5e6b4b0d3255bfef95601890afd80709 +&temp_url_expires=1323479485 +&filename=My+Test+File.pdf \ No newline at end of file diff --git a/openstack-object-storage-dev/section_object_api_formpost.xml b/openstack-object-storage-dev/section_object_api_formpost.xml new file mode 100644 index 0000000..7301344 --- /dev/null +++ b/openstack-object-storage-dev/section_object_api_formpost.xml @@ -0,0 +1,243 @@ + + +POST'> +]> +
+ Form POST middleware + + You can upload objects directly to the Object Storage system + from a browser by using the form &POST; middleware. This + middleware uses account secret keys to generate a + cryptographic signature for the request. This means that you + do not need to send an authentication token in the + X-Auth-Token header to perform the + request. + The form &POST; middleware uses the same secret keys as the + temporary URL middleware uses. For information about how to + set these keys, see . + For information about the form &POST; middleware + configuration options, see Form post in the OpenStack + Configuration Reference. +
+ Form POST format + To upload objects to a cluster, you can use an HTML form + &POST; request. + The format of the form &POST; request is: + + Form POST format + + + + + + + + + + + + + + + + + The example shows these attributes: + + + action="SWIFT_URL" + Set to full URL where the objects are to be + uploaded. The names of uploaded files are appended + to the specified + SWIFT_URL. So, you + can upload directly to the root of a container + with a URL like: + https://swift-cluster.example.com/v1/my_account/container/ + Optionally, you can include an object prefix to + separate uploads, such as: + https://swift-cluster.example.com/v1/my_account/container/OBJECT_PREFIX + + + method="POST" + Must be POST. + + + enctype="multipart/form-data" + Must be + multipart/form-data. + + + name="redirect" + value="REDIRECT_URL" + Redirects the browser to the + REDIRECT_URL after + the upload completes. The URL has status and + message query parameters added to it, which + specify the HTTP status code for the upload and an + optional error message. The + 2nn status code + indicates success. + The REDIRECT_URL can + be an empty string. If so, the + Location response header is + not set. + + + name="max_file_size" + value="BYTES" + Required. Indicates the size, in bytes, of the + maximum single file upload. + + + name="max_file_count" + value= + "COUNT" + Required. Indicates the maximum number of files + that can be uploaded with the form. + + + name="expires" + value="UNIX_TIMESTAMP" + The UNIX timestamp that specifies the time + before which the form must be submitted before it + becomes no longer valid. + + + name="signature" + value="HMAC" + The HMAC-SHA1 signature of the form. See . + + + type="file" + name="FILE_NAME" + File name of the file to be uploaded. You can + include from one to the + max_file_count value of + files. + The file attributes must appear after the other + attributes to be processed correctly. + If attributes appear after the file attributes, + they are not sent with the sub-request because all + attributes in the file cannot be parsed on the + server side unless the whole file is read into + memory; the server does not have enough memory to + service these requests. Attributes that follow the + file attributes are ignored. + + + type= + "submit" + Must be submit. + + +
+
+ HMAC-SHA1 signature for form POST + Form &POST; middleware uses an HMAC-SHA1 cryptographic + signature. This signature includes these elements from the + form: + + + The path. Starting with /v1/ + onwards and including a container name and, + optionally, an object prefix. In , the + path is + /v1/my_account/container/object_prefix. + Do not URL-encode the path at this stage. + + + A redirect URL. If there is no redirect URL, use + the empty string. + + + Maximum file size. In , the + max_file_size is + 104857600 bytes. + + + The maximum number of objects to upload. In + , + max_file_count is + 10. + + + Expiry time. In , the + expiry time is set to 600 + seconds into the future. + + + The secret key. Set as the + X-Account-Meta-Temp-URL-Key + header value. + + + The following example code generates a signature for use + with form &POST;: + + HMAC-SHA1 signature for form POST + import hmac +from hashlib import sha1 +from time import time +path = '/v1/my_account/container/object_prefix' +redirect = 'https://myserver.com/some-page' +max_file_size = 104857600 +max_file_count = 10 +expires = int(time() + 600) +key = 'MYKEY' +hmac_body = '%s\n%s\n%s\n%s\n%s' % (path, redirect, +max_file_size, max_file_count, expires) +signature = hmac.new(key, hmac_body, sha1).hexdigest() + + For more information, see RFC + 2104: HMAC: Keyed-Hashing for Message + Authentication. +
+
+ Form POST example + The following example shows how to submit a form by + using a cURL command. In this example, the object prefix + is photos/ and the file being uploaded + is called flower.jpg. + This example uses the + swift-form-signature script to + compute the expires and + signature values. + $ bin/swift-form-signature /v1/my_account/container/photos/ https://example.com/done.html 5373952000 1 200 MYKEY +Expires: 1390825338 +Signature: 35129416ebda2f1a21b3c2b8939850dfc63d8f43 + $ curl -i https://swift-cluster.example.com/v1/my_account/container/photos/ -X POST \ + -F max_file_size=5373952000 -F max_file_count=1 -F expires=1390825338 \ + -F signature=35129416ebda2f1a21b3c2b8939850dfc63d8f43 \ + -F redirect=https://example.com/done.html \ + -F file=@flower.jpg +
+
diff --git a/openstack-object-storage-dev/section_object_api_tempurl.xml b/openstack-object-storage-dev/section_object_api_tempurl.xml new file mode 100644 index 0000000..32c4e6d --- /dev/null +++ b/openstack-object-storage-dev/section_object_api_tempurl.xml @@ -0,0 +1,217 @@ + + +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> +]> +
+ + Temporary URL middleware + A temporary URL gives users temporary access to objects. For + example, a website might want to provide a link to download a + large object in Object Storage, but the Object Storage account + has no public access. The website can generate a URL that + provides time-limited &GET; access to the object. When the web + browser user clicks on the link, the browser downloads the + object directly from Object Storage, eliminating the need for + the website to act as a proxy for the request. + Ask your cloud administrator to enable the temporary URL + feature. For information, see Temporary URL in the OpenStack + Configuration Reference. + + To use &POST; requests to upload objects to specific + Object Storage locations, use form &POST; instead of + temporary URL middleware. See . + +
+ Temporary URL format + A temporary URL is comprised of the URL for an object + with added query parameters: + + Temporary URL format + + + + + + + + + + + The example shows + these elements: + + + Object + URL + Required. The full path URL to the + object. + + + temp_url_sig + Required. An HMAC-SHA1 cryptographic signature + that defines the allowed HTTP method, expiration + date, full path to the object, and the secret key + for the temporary URL. + For more information about secret keys, see + . + For more information about signatures, see . + + + temp_url_expires + Required. An expiration date as a UNIX Epoch + timestamp, which is an integer value. For example, + 1390852007 represents + Mon, 27 Jan 2014 19:46:47 + GMT. + For more information, see Epoch & Unix Timestamp Conversion + Tools. + + + filename + Optional. Overrides the default file name. + Object Storage generates a default file name for + &GET; temporary URLs that is based on the object + name. Object Storage returns this value in the + Content-Disposition + response header. Browsers can interpret this file + name value as a file attachment to be + saved. + + +
+
+ Account secret keys + Object Storage supports up to two secret keys. You set + secret keys at the account level. + To set these keys, set one or both of the following + request headers to arbitrary values: + + + X-Account-Meta-Temp-URL-Key + + + X-Account-Meta-Temp-URL-Key-2 + + + The arbitrary values serve as the secret keys. + Object Storage checks signatures against both keys, if + present, to enable key rotation without invalidating + existing temporary URLs. + For example, use the swift post + command to set the secret key to + MYKEY: + $ swift post -m "X-Account-Meta-Temp-URL-Key: MYKEY" + + Changing these headers invalidates any previously + generated temporary URLs within 60 seconds, which is + the memcache time for the key. + +
+
+ HMAC-SHA1 signature for temporary URLs + Temporary URL middleware uses an HMAC-SHA1 cryptographic + signature. This signature includes + these elements: + + + The allowed method. Typically, &GET; or + &PUT;. + + + Expiry time. In , + the expiry time is set to 86400 + seconds (or 1 day) into the future. + + + The path. Starting with /v1/ + onwards and including a container name and object. + In , + the path is + /v1/my_account/container/object. + Do not URL-encode the path at this stage. + + + The secret key. Set as the + X-Account-Meta-Temp-URL-Key + header value. + + + This sample Python code shows how to compute a signature + for use with temporary URLs: + + HMAC-SHA1 signature for temporary URLs + import hmac +from hashlib import sha1 +from time import time +method = 'GET' +duration_in_seconds = 60*60*24 +expires = int(time() + duration_in_seconds) +path = '/v1/my_account/container/object' +key = 'MYKEY' +hmac_body = '%s\n%s\n%s' % (method, expires, path) +signature = hmac.new(key, hmac_body, sha1).hexdigest() + + Do not URL-encode the path when you generate the + HMAC-SHA1 signature. However, when you make the actual + HTTP request, you should properly URL-encode the + URL. + The MYKEY value is the value + you set in the + X-Account-Meta-Temp-URL-Key request + header on the account. + For more information, see RFC + 2104: HMAC: Keyed-Hashing for Message + Authentication. +
+
+ swift-temp-url script + Object Storage provides the + swift-temp-url script that + auto-generates the temp_url_sig and + temp_url_expires query + parameters. For example, you might run this + command: + $ bin/swift-temp-url GET 3600 /v1/my_account/container/object MYKEY + This command returns the path: + /v1/my_account/container/object +?temp_url_sig=5c4cc8886f36a9d0919d708ade98bf0cc71c9e91 +&temp_url_expires=1374497657 + To create the temporary URL, prefix this path with the + Object Storage storage host name. For example, prefix the + path with + https://swift-cluster.example.com, + as follows: + https://swift-cluster.example.com/v1/my_account/container/object +?temp_url_sig=5c4cc8886f36a9d0919d708ade98bf0cc71c9e91 +&temp_url_expires=1374497657 +
+ +