object-api/openstack-object-storage-dev/section_object-api-formpost.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!ENTITY POST   '<command xmlns="http://docbook.org/ns/docbook">POST</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="form-post">
    <title>Form POST middleware</title>
    <?dbhtml stop-chunking?>
    <para>To discover whether your Object Storage system supports
        this feature, see <xref linkend="discoverability"
        />. Alternatively, check with your service provider.</para>
    <para>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
            <literal>X-Auth-Token</literal> header to perform the
        request.</para>
    <para>The form &POST; middleware uses the same secret keys as the
        temporary URL middleware uses. For information about how to
        set these keys, see <xref
            linkend="account-secret-keys-temp-url"/>.</para>
    <para>For information about the form &POST; middleware
        configuration options, see <link
            xlink:href="http://docs.openstack.org/havana/config-reference/content/object-storage-form-post.html"
            >Form post</link> in the <citetitle>OpenStack
            Configuration Reference</citetitle>.</para>
    <section xml:id="form-post-format">
        <title>Form POST format</title>
        <para>To upload objects to a cluster, you can use an HTML form
            &POST; request.</para>
        <para>The format of the form &POST; request is:</para>
        <example xml:id="formpost-example">
            <title>Form POST format</title>
            <programlistingco>
                <areaspec>
                    <area xml:id="formpost.txt.action"
                        units="linecolumn" coords="2 26"/>
                    <area xml:id="formpost.txt.method"
                        units="linecolumn" coords="3 19"/>
                    <area xml:id="formpost.txt.enctype"
                        units="linecolumn" coords="4 36"/>
                    <area xml:id="formpost.txt.redirect"
                        units="linecolumn" coords="5 65"/>
                    <area xml:id="formpost.txt.max_file_size"
                        units="linecolumn" coords="6 63"/>
                    <area xml:id="formpost.txt.max_file_count"
                        units="linecolumn" coords="7 64"/>
                    <area xml:id="formpost.txt.expires"
                        units="linecolumn" coords="8 66"/>
                    <area xml:id="formpost.txt.signature"
                        units="linecolumn" coords="9 58"/>
                    <area xml:id="formpost.txt.file"
                        units="linecolumn" coords="10 39"/>
                    <area xml:id="formpost.txt.submit"
                        units="linecolumn" coords="12 28"/>
                </areaspec>
                <programlisting language="bash"><xi:include href="samples/formpost.txt" parse="text"/></programlisting>
            </programlistingco>
        </example>
        <para>The example shows these attributes:</para>
        <calloutlist>
            <callout arearefs="formpost.txt.action">
                <para><emphasis role="bold"
                                ><literal>action="<replaceable>SWIFT_URL</replaceable>"</literal></emphasis></para>
                <para>Set to full URL where the objects are to be
                    uploaded. The names of uploaded files are appended
                    to the specified
                        <replaceable>SWIFT_URL</replaceable>. So, you
                    can upload directly to the root of a container
                    with a URL like:</para>
                <screen><userinput>https://swift-cluster.example.com/v1/my_account/container/</userinput></screen>
                <para>Optionally, you can include an object prefix to
                    separate uploads, such as:</para>
                <screen><userinput>https://swift-cluster.example.com/v1/my_account/container/<replaceable>OBJECT_PREFIX</replaceable></userinput></screen>
            </callout>
            <callout arearefs="formpost.txt.method">
                <para><emphasis role="bold"
                    >method="POST"</emphasis></para>
                <para>Must be <literal>POST</literal>.</para>
            </callout>
            <callout arearefs="formpost.txt.enctype">
                <para><emphasis role="bold"
                        >enctype="multipart/form-data"</emphasis></para>
                <para>Must be
                    <literal>multipart/form-data</literal>.</para>
            </callout>
            <callout arearefs="formpost.txt.redirect">
                <para><emphasis role="bold">name="redirect"
                            value="<replaceable>REDIRECT_URL</replaceable>"</emphasis></para>
                <para>Redirects the browser to the
                        <replaceable>REDIRECT_URL</replaceable> 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
                        2<replaceable>nn</replaceable> status code
                    indicates success.</para>
                <para>The <replaceable>REDIRECT_URL</replaceable> can
                    be an empty string. If so, the
                        <literal>Location</literal> response header is
                    not set.</para>
            </callout>
            <callout arearefs="formpost.txt.max_file_size">
                <para><emphasis role="bold">name="max_file_size"
                            value="<replaceable>BYTES</replaceable>"</emphasis></para>
                <para>Required. Indicates the size, in bytes, of the
                    maximum single file upload.</para>
            </callout>
            <callout arearefs="formpost.txt.max_file_count">
                <para><emphasis role="bold">name="max_file_count"
                        value=
                        "<replaceable>COUNT</replaceable>"</emphasis></para>
                <para>Required. Indicates the maximum number of files
                    that can be uploaded with the form.</para>
            </callout>
            <callout arearefs="formpost.txt.expires">
                <para><emphasis role="bold">name="expires"
                            value="<replaceable>UNIX_TIMESTAMP</replaceable>"</emphasis></para>
                <para>The UNIX timestamp that specifies the time
                    before which the form must be submitted before it
                    becomes no longer valid.</para>
            </callout>
            <callout arearefs="formpost.txt.signature">
                <para><emphasis role="bold">name="signature"
                            value="<replaceable>HMAC</replaceable>"</emphasis></para>
                <para>The HMAC-SHA1 signature of the form. See <xref
                        linkend="signature-form-post"/>.</para>
            </callout>
            <callout arearefs="formpost.txt.file">
                <para><emphasis role="bold">type="file"
                            name="<replaceable>FILE_NAME</replaceable>"</emphasis></para>
                <para>File name of the file to be uploaded. You can
                    include from one to the
                        <literal>max_file_count</literal> value of
                    files.</para>
                <para>The file attributes must appear <emphasis
                        role="italic">after</emphasis> the other
                    attributes to be processed correctly.</para>
                <para>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.</para>
            </callout>
            <callout arearefs="formpost.txt.submit">
                <para><emphasis role="bold">type=
                    "submit"</emphasis></para>
                <para>Must be <literal>submit</literal>.</para>
            </callout>
        </calloutlist>
    </section>
    <section xml:id="signature-form-post">
        <title>HMAC-SHA1 signature for form POST</title>
        <para>Form &POST; middleware uses an HMAC-SHA1 cryptographic
            signature. This signature includes these elements from the
            form:</para>
        <itemizedlist>
            <listitem>
                <para>The path. Starting with <literal>/v1/</literal>
                    onwards and including a container name and,
                    optionally, an object prefix. In <xref
                        linkend="signature-example-form-post"/>, the
                    path is
                        <literal>/v1/my_account/container/object_prefix</literal>.
                    Do not URL-encode the path at this stage.</para>
            </listitem>
            <listitem>
                <para>A redirect URL. If there is no redirect URL, use
                    the empty string.</para>
            </listitem>
            <listitem>
                <para>Maximum file size. In <xref
                        linkend="signature-example-form-post"/>, the
                        <literal>max_file_size</literal> is
                        <literal>104857600</literal> bytes.</para>
            </listitem>
            <listitem>
                <para>The maximum number of objects to upload. In
                        <xref linkend="signature-example-form-post"/>,
                        <literal>max_file_count</literal> is
                        <literal>10</literal>.</para>
            </listitem>
            <listitem>
                <para>Expiry time. In <xref
                        linkend="signature-example-form-post"/>, the
                    expiry time is set to <literal>600</literal>
                    seconds into the future.</para>
            </listitem>
            <listitem>
                <para>The secret key. Set as the
                        <literal>X-Account-Meta-Temp-URL-Key</literal>
                    header value.</para>
            </listitem>
        </itemizedlist>
        <para>The following example code generates a signature for use
            with form &POST;:</para>
        <example xml:id="signature-example-form-post">
            <title>HMAC-SHA1 signature for form POST</title>
            <programlisting language="python">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 = '<replaceable>MYKEY</replaceable>'
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()</programlisting>
        </example>
        <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="form-post-curl">
        <title>Form POST example</title>
        <para>The following example shows how to submit a form by
            using a cURL command. In this example, the object prefix
            is <literal>photos/</literal> and the file being uploaded
            is called <filename>flower.jpg</filename>.</para>
        <para>This example uses the
                <command>swift-form-signature</command> script to
            compute the <literal>expires</literal> and
                <literal>signature</literal> values.</para>
        <screen><prompt>$</prompt> <userinput>bin/swift-form-signature /v1/my_account/container/photos/ https://example.com/done.html 5373952000 1 200 <replaceable>MYKEY</replaceable>
Expires: 1390825338
Signature: 35129416ebda2f1a21b3c2b8939850dfc63d8f43</userinput></screen>
        <screen><prompt>$</prompt> <userinput>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</userinput></screen>
    </section>
</section>