docs/bucket_policy.md

@@ -0,0 +1,131 @@
+# Bucket policy
+
+A bucket policy is a resource-based policy that you can use to grant access permissions to your S3 bucket and the
+objects in it https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html.
+
+## Conditions
+
+In AWS there are a lot of condition
+keys https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.htm
+but s3-gw currently supports only the following conditions in bucket policy:
+
+> Note: all condition keys and values must be string formatted in json policy (even if they are numbers).
+
+| Condition key                 | Description                                                               |
+|-------------------------------|---------------------------------------------------------------------------|
+| [s3:max-keys](#s3-max-keys)   | Filters access by maximum number of keys returned in a ListBucket request |
+| [s3:delimiter](#s3-delimiter) | Filters access by delimiter parameter                                     |
+| [s3:prefix](#s3-prefix)       | Filters access by key name prefix                                         |
+| [s3:VersionId](#s3-versionid) | Filters access by a specific object version                               |
+
+Each key can be used only with specific set of
+operators https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html
+(it depends on type of key).
+
+### s3 max-keys
+
+**Key:** `s3:max-keys`
+
+**Type:** `Numeric`
+
+**Description:** Filters access by maximum number of keys returned in a ListBucket request
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Principal": "*",
+    "Action": "s3:ListBucket",
+    "Resource": "arn:aws:s3:::example_bucket",
+    "Condition": {
+      "NumericLessThanEquals": {
+        "s3:max-keys": "10"
+      }
+    }
+  }
+}
+```
+
+### s3 delimiter
+
+**Key:** `s3:delimiter`
+
+**Type:** `String`
+
+**Description:** Filters access by delimiter parameter
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Principal": "*",
+    "Action": "s3:ListBucket",
+    "Resource": "arn:aws:s3:::example_bucket",
+    "Condition": {
+      "StringEquals": {
+        "s3:delimiter": "/"
+      }
+    }
+  }
+}
+```
+
+### s3 prefix
+
+**Key:** `s3:prefix`
+
+**Type:** `String`
+
+**Description:** Filters access by key name prefix
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Principal": {
+      "AWS": [
+        "arn:aws:iam::111122223333:user/JohnDoe"
+      ]
+    },
+    "Action": "s3:ListBucket",
+    "Resource": "arn:aws:s3:::example_bucket",
+    "Condition": {
+      "StringEquals": {
+        "s3:prefix": "home/JohnDoe"
+      }
+    }
+  }
+}
+``` 
+
+### s3 VersionId
+
+**Key:** `s3:VersionId`
+
+**Type:** `String`
+
+**Description:** Filters access by a specific object version
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Principal": {
+      "AWS": [
+        "arn:aws:iam::111122223333:user/JohnDoe"
+      ]
+    },
+    "Action": "s3:GetObjectVersion",
+    "Resource": "arn:aws:s3:::example_bucket/some-file.txt",
+    "Condition": {
+      "StringEquals": {
+        "s3:VersionId": "AT2L3qER7CHGk4TDooocEzkz2RyqTm4Zh2b1QLzAhLbH"
+      }
+    }
+  }
+}
+```