ed4f3c4db9
Point to WADL files that generate the API Reference
page so that the method descriptions and request
and response parameters are consistent between
these two docs:
http://api.openstack.org/api-ref-objectstorage.html
(API Reference page for Object Storage)
http://docs.openstack.org/api/openstack-object-storage/1.0/
(API Reference (or spec) for Object Storage)
Add descriptions of ACLs, FormPOST, TempURLs,
StaticWeb, Bulk Upload, Bulk Delete, the OPTIONS operation
(though this is implicit in CORS support)
Validate all code examples
Remove duplication.
Co-Author: Donagh McCabe
Closes-Bug: #1187119
Closes-Bug: #1214139
Closes-Bug: #1074198
Partial-Bug: #1255770
Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce
author: diane fleming
220 lines
11 KiB
XML
220 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section [
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY HEAD '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
]>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml"
|
|
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
|
xml:id="tempurl">
|
|
<?dbhtml stop-chunking?>
|
|
<title>Temporary URL middleware</title>
|
|
<para>To discover whether your Object Storage system supports
|
|
this feature, see <xref linkend="discoverability"
|
|
/>. Alternatively, check with your service provider.</para><para>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.</para>
|
|
<para>Ask your cloud administrator to enable the temporary URL
|
|
feature. For information, see <link
|
|
xlink:href="http://docs.openstack.org/havana/config-reference/content/object-storage-tempurl.html"
|
|
>Temporary URL</link> in the <citetitle>OpenStack
|
|
Configuration Reference</citetitle>.</para>
|
|
<note>
|
|
<para>To use &POST; requests to upload objects to specific
|
|
Object Storage locations, use form &POST; instead of
|
|
temporary URL middleware. See <xref linkend="form-post"
|
|
/>.</para>
|
|
</note>
|
|
<section xml:id="temp-url-format">
|
|
<title>Temporary URL format</title>
|
|
<para>A temporary URL is comprised of the URL for an object
|
|
with added query parameters:</para>
|
|
<example xml:id="tempurl-example">
|
|
<title>Temporary URL format</title>
|
|
<programlistingco>
|
|
<areaspec>
|
|
<area xml:id="tempurl.txt.object_url"
|
|
units="linecolumn" coords="1 66"/>
|
|
<area xml:id="tempurl.txt.temp_url_sig"
|
|
units="linecolumn" coords="2 56"/>
|
|
<area xml:id="tempurl.txt.temp_url_expires"
|
|
units="linecolumn" coords="3 31"/>
|
|
<area xml:id="tempurl.txt.filename"
|
|
units="linecolumn" coords="4 28"/>
|
|
</areaspec>
|
|
<programlisting language="bash"><xi:include href="samples/tempurl.txt" parse="text"/></programlisting>
|
|
</programlistingco>
|
|
</example>
|
|
<para>The example shows
|
|
these elements:</para>
|
|
<calloutlist>
|
|
<callout arearefs="tempurl.txt.object_url">
|
|
<para><emphasis role="bold">Object
|
|
URL</emphasis></para>
|
|
<para>Required. The full path URL to the
|
|
object.</para>
|
|
</callout>
|
|
<callout arearefs="tempurl.txt.temp_url_sig">
|
|
<para><emphasis role="bold"
|
|
>temp_url_sig</emphasis></para>
|
|
<para>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.</para>
|
|
<para>For more information about secret keys, see
|
|
<xref linkend="account-secret-keys-temp-url"
|
|
/>.</para>
|
|
<para>For more information about signatures, see <xref
|
|
linkend="signature-temp-url"/>.</para>
|
|
</callout>
|
|
<callout arearefs="tempurl.txt.temp_url_expires">
|
|
<para><emphasis role="bold"
|
|
>temp_url_expires</emphasis></para>
|
|
<para>Required. An expiration date as a UNIX Epoch
|
|
timestamp, which is an integer value. For example,
|
|
<literal>1390852007</literal> represents
|
|
<literal>Mon, 27 Jan 2014 19:46:47
|
|
GMT</literal>.</para>
|
|
<para>For more information, see <link
|
|
xlink:href="http://www.epochconverter.com/"
|
|
>Epoch & Unix Timestamp Conversion
|
|
Tools</link>.</para>
|
|
</callout>
|
|
<callout arearefs="tempurl.txt.temp_url_expires">
|
|
<para><emphasis role="bold">filename</emphasis></para>
|
|
<para>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
|
|
<literal>Content-Disposition</literal>
|
|
response header. Browsers can interpret this file
|
|
name value as a file attachment to be
|
|
saved.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</section>
|
|
<section xml:id="account-secret-keys-temp-url">
|
|
<title>Account secret keys</title>
|
|
<para>Object Storage supports up to two secret keys. You set
|
|
secret keys at the account level.</para>
|
|
<para>To set these keys, set one or both of the following
|
|
request headers to arbitrary values:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>X-Account-Meta-Temp-URL-Key</literal></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>X-Account-Meta-Temp-URL-Key-2</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The arbitrary values serve as the secret keys.</para>
|
|
<para>Object Storage checks signatures against both keys, if
|
|
present, to enable key rotation without invalidating
|
|
existing temporary URLs.</para>
|
|
<para>For example, use the <command>swift post</command>
|
|
command to set the secret key to
|
|
<replaceable>MYKEY</replaceable>:</para>
|
|
<screen><prompt>$</prompt> <userinput>swift post -m "X-Account-Meta-Temp-URL-Key: <replaceable>MYKEY</replaceable>"</userinput></screen>
|
|
<note>
|
|
<para>Changing these headers invalidates any previously
|
|
generated temporary URLs within 60 seconds, which is
|
|
the memcache time for the key.</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="signature-temp-url">
|
|
<title>HMAC-SHA1 signature for temporary URLs</title>
|
|
<para>Temporary URL middleware uses an HMAC-SHA1 cryptographic
|
|
signature. This signature includes
|
|
these elements:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The allowed method. Typically, &GET; or
|
|
&PUT;.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Expiry time. In <xref
|
|
linkend="signature-example-temporary-urls"/>,
|
|
the expiry time is set to <literal>86400</literal>
|
|
seconds (or 1 day) into the future.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The path. Starting with <literal>/v1/</literal>
|
|
onwards and including a container name and object.
|
|
In <xref
|
|
linkend="signature-example-temporary-urls"/>,
|
|
the path is
|
|
<literal>/v1/my_account/container/object</literal>.
|
|
Do not URL-encode the path at this stage.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The secret key. Set as the
|
|
<literal>X-Account-Meta-Temp-URL-Key</literal>
|
|
header value.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>This sample Python code shows how to compute a signature
|
|
for use with temporary URLs:</para>
|
|
<example xml:id="signature-example-temporary-urls">
|
|
<title>HMAC-SHA1 signature for temporary URLs</title>
|
|
<programlisting language="python">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 = '<replaceable>MYKEY</replaceable>'
|
|
hmac_body = '%s\n%s\n%s' % (method, expires, path)
|
|
signature = hmac.new(key, hmac_body, sha1).hexdigest()</programlisting>
|
|
</example>
|
|
<para>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.</para>
|
|
<para>The <replaceable>MYKEY</replaceable> value is the value
|
|
you set in the
|
|
<literal>X-Account-Meta-Temp-URL-Key</literal> request
|
|
header on the account.</para>
|
|
<para>For more information, see <link
|
|
xlink:href="http://www.ietf.org/rfc/rfc2104.txt">RFC
|
|
2104: HMAC: Keyed-Hashing for Message
|
|
Authentication</link>.</para>
|
|
</section>
|
|
<section xml:id="swift-temp-url-script">
|
|
<title>swift-temp-url script</title>
|
|
<para>Object Storage provides the
|
|
<command>swift-temp-url</command> script that
|
|
auto-generates the <parameter>temp_url_sig</parameter> and
|
|
<parameter>temp_url_expires</parameter> query
|
|
parameters. For example, you might run this
|
|
command:</para>
|
|
<screen><prompt>$</prompt> <userinput>bin/swift-temp-url GET 3600 /v1/my_account/container/object <replaceable>MYKEY</replaceable></userinput></screen>
|
|
<para>This command returns the path:</para>
|
|
<screen><computeroutput>/v1/my_account/container/object
|
|
?temp_url_sig=5c4cc8886f36a9d0919d708ade98bf0cc71c9e91
|
|
&temp_url_expires=1374497657</computeroutput></screen>
|
|
<para>To create the temporary URL, prefix this path with the
|
|
Object Storage storage host name. For example, prefix the
|
|
path with
|
|
<literal>https://swift-cluster.example.com</literal>,
|
|
as follows:</para>
|
|
<screen><computeroutput>https://swift-cluster.example.com/v1/my_account/container/object
|
|
?temp_url_sig=5c4cc8886f36a9d0919d708ade98bf0cc71c9e91
|
|
&temp_url_expires=1374497657</computeroutput></screen>
|
|
</section>
|
|
|
|
</section>
|