Add documentation for V4 Signature Post Policy (#40)

frankyn · web-flow · commit d505e92d98f4 · 2020-09-17T16:10:01.000Z
diff --git a/storage/v1/README.md b/storage/v1/README.md
@@ -0,0 +1,12 @@
+# Storage Conformance Tests
+
+Collection of conformance tests to exercise Storage library V4 Signatures support.
+
+# Verify Proto Unmarshable Conformance Tests
+
+Read [validator documentation](../conformance-tests/README.md#validator)
+in the parent README.md.
+
+# Conformance Tests Design
+
+Review [tests.proto](proto/google/cloud/conformance/storage/v1/tests.proto)
diff --git a/storage/v1/proto/google/cloud/conformance/storage/v1/tests.proto b/storage/v1/proto/google/cloud/conformance/storage/v1/tests.proto
@@ -60,21 +60,95 @@ message PolicyConditions {
   repeated string startsWith = 2;
 }
 
+// Specification documentation is located at:
+// https://cloud.google.com/storage/docs/authentication/signatures
+
 message PolicyInput {
+  // http or https
   string scheme = 1;
   UrlStyle urlStyle = 2;
   string bucketBoundHostname = 3;
   string bucket = 4;
   string object = 5;
   int32 expiration = 6;
   google.protobuf.Timestamp timestamp = 7;
+  /*
+    fields with strict equivalence which are added into
+    PolicyOutput.expectedDecodedPolicy to generate the
+    signature.
+
+    Expectations
+
+    E.1: Order them in lexigraphical order so it's the
+    signature can be verified across different language
+    implementations.
+
+  */
   map<string, string> fields = 8;
   PolicyConditions conditions = 9;
 }
 
 message PolicyOutput {
   string url = 1;
   map<string, string> fields = 2;
+  /*
+    Expectations
+
+    E.1: PolicyInput.fields must be prepended to form expectedDecodedPolicy
+    for consistent result across languages. Ordering doesn't matter to the
+    service but the decision is made to make it easier to conform implementations
+    in implementation.
+
+    Example:
+
+    # Step 1
+
+    PolicyInput.fields has:
+    {
+      "content-disposition":"attachment; filename=\"~._-%=/é0Aa\"",
+      "content-encoding":"gzip",
+      "content-type":"text/plain",
+      "success_action_redirect":"http://www.google.com/"
+    }
+
+    # Step 2
+
+    The expectedDecodedPolicy before prepending the PolicyInput.fields
+    would look like this:
+
+    {
+      "conditions":[
+        ...prepend here in the same order provided in PolicyInput.fields...
+        {"bucket":"bucket-name"},
+        {"key":"test-object"},
+        {"x-goog-date":"20200123T043530Z"},
+        {"x-goog-credential":"test-iam-credentials@dummy-project-id.iam.gserviceaccount.com/20200123/auto/storage/goog4_request"},
+        {"x-goog-algorithm":"GOOG4-RSA-SHA256"}
+      ],
+      "expiration":"2020-01-23T04:35:40Z"
+    }
+
+    # Step 3
+
+    Then expectedDecodedPolicy should prepends PolicyInput.fields in
+    the same order to PolicyOutput.expectedDecodedPolicy `conditions` key.
+
+    {
+      "conditions":[
+        {"content-disposition":"attachment; filename=\"~._-%=/é0Aa\""},
+        {"content-encoding":"gzip"},
+        {"content-type":"text/plain"},
+        {"success_action_redirect":"http://www.google.com/"},
+        {"bucket":"bucket-name"},
+        {"key":"test-object"},
+        {"x-goog-date":"20200123T043530Z"},
+        {"x-goog-credential":"test-iam-credentials@dummy-project-id.iam.gserviceaccount.com/20200123/auto/storage/goog4_request"},
+        {"x-goog-algorithm":"GOOG4-RSA-SHA256"}
+      ],
+      "expiration":"2020-01-23T04:35:40Z"
+    }
+  */
+
   string expectedDecodedPolicy = 3;
 }
 
