krishnasrinivas · September 9, 2017 19:51 · Aug 16, 2017 · Aug 16, 2017 · Jun 15, 2017
diff --git a/bucket-policies-primer.md b/bucket-policies-primer.md
@@ -1,11 +1,11 @@
 ## Bucket Policy
 Bucket policy is an access policy available for you to grant anonymous permissions to your Minio resources. Bucket policy uses JSON-based access policy language.
 
-This section presents a few examples of typical use cases for bucket policies. The policies use `bucket` and `examplebucket` strings in the resource value. To test these policies, you need to replace these strings with your bucket name. For more information please read Amazon S3 [access policy language](http://docs.aws.amazon.com/AmazonS3/latest/dev/access-policy-language-overview.html)
+This section presents a few examples of typical use cases for bucket policies. The policies use `testbucket` strings in the resource value. To test these policies, you need to replace these strings with your bucket name. For more information please read Amazon S3 [access policy language](http://docs.aws.amazon.com/AmazonS3/latest/dev/access-policy-language-overview.html)
 
 ### Granting Read-Only Permission to an Anonymous User 
 
-The following example policy grants the s3:GetObject permission to any public anonymous users. This permission allows anyone to read the object data under `testbucket`, which is useful for when you have publicly readable assets. A typical example is a website assets stored in `testbucket`.
+The following example policy grants the `s3:GetObject` permission to any public anonymous users. This permission allows anyone to read the object data under `testbucket`, which is useful for when you have publicly readable assets. A typical example is a website assets stored in `testbucket`.
 
 ```json
 {
@@ -30,36 +30,66 @@ The following example policy grants the s3:GetObject permission to any public an
 }
 ```
 
+The following example policy grants the `s3:GetObject` permission to any public anonymous users. This permission allows anyone to read the object data under `testbucket` matching all the prefixes under `user` further matching everything inside `files/public/*`, which is useful for when you want to organize `user` assets from your application to be publicly available. Most probably a social media profile picture which is kept under public assets in `/user/{username}/files/public/{image.jpg}` .
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": [
+        "s3:GetObject"
+      ],
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": [
+          "*"
+        ]
+      },
+      "Resource": [
+        "arn:aws:s3:::testbucket/user/*/files/public/*"
+      ],
+      "Sid": ""
+    }
+  ]
+}
+```
+
 Now you can set this policy on your bucket using `aws cli` , following command assumes Minio is running locally at port `9000`  and bucket is `testbucket`.
 ```sh
 aws --endpoint-url http://localhost:9000 s3api put-bucket-policy --bucket testbucket --policy file:///tmp/policy.json
 ```
 
-There are two types of key matches are allowed in bucket policies one is `*` and another is `?` 
+### Advanced
 
-Now if you have this in your Resource 
+In Bucket policy JSON there are two types of key matches are allowed one is `*` and another is `?` 
+
+Now lets say if you have following value in your bucket policy `Resource`
 ```
 arn:aws:s3:::testbucket/user/*/files/public/*
 ```
-then the policies will match 
+
+Then the policies will match an object named `user/harsha/files/public/issue` 
 ```
 arn:aws:s3:::testbucket/user/harsha/files/public/issue
 ```
-Here the user is `harsha` 
 
-Now if you have this in your Resource
+Now lets say if you have following value in your bucket policy `Resource`
 ```
 arn:aws:s3:::testbucket/user/?/files/public/*
 ```
-then the policies will match
+
+Then the policies will match an object named `user/1/files/public/issue`, `?` is different from `*` in meaning - `?` only means to match single character match in wildcard terms.
 ```
 arn:aws:s3:::testbucket/user/1/files/public/issue
 ```
-Here the user is `1`  You can even repeat `?` to restrict the character length of the users as well. Lets say if you have 6 repeated `?` 
+
+You can even repeat `?` to restrict the username length of the users as well. Lets say if you have 6 repeated `?` 
 ```
 arn:aws:s3:::testbucket/user/??????/files/public/*
 ```
-then the policies will match
+
+Then the policies will match
 ```
 arn:aws:s3:::testbucket/user/harsha/files/public/issue
 ```
diff --git a/bucket-policies-primer.md b/bucket-policies-primer.md
@@ -1,4 +1,11 @@
-It would be like this `/user/*/files/public/*`  in your bucket policy, for private you don't need since by default all objects are indeed private. Since the key regex is a flat key match should work properly for all users.
+## Bucket Policy
+Bucket policy is an access policy available for you to grant anonymous permissions to your Minio resources. Bucket policy uses JSON-based access policy language.
+
+This section presents a few examples of typical use cases for bucket policies. The policies use `bucket` and `examplebucket` strings in the resource value. To test these policies, you need to replace these strings with your bucket name. For more information please read Amazon S3 [access policy language](http://docs.aws.amazon.com/AmazonS3/latest/dev/access-policy-language-overview.html)
+
+### Granting Read-Only Permission to an Anonymous User 
+
+The following example policy grants the s3:GetObject permission to any public anonymous users. This permission allows anyone to read the object data under `testbucket`, which is useful for when you have publicly readable assets. A typical example is a website assets stored in `testbucket`.
 
 ```json
 {
@@ -15,16 +22,17 @@ It would be like this `/user/*/files/public/*`  in your bucket policy, for priva
         ]
       },
       "Resource": [
-        "arn:aws:s3:::testbucket/user/*/files/public/*"
+        "arn:aws:s3:::testbucket/*"
       ],
       "Sid": ""
     }
   ]
 }
 ```
 
-```
-aws s3api --no-verify-ssl put-bucket-policy --bucket testbucket --policy file:///tmp/policy.json
+Now you can set this policy on your bucket using `aws cli` , following command assumes Minio is running locally at port `9000`  and bucket is `testbucket`.
+```sh
+aws --endpoint-url http://localhost:9000 s3api put-bucket-policy --bucket testbucket --policy file:///tmp/policy.json
 ```
 
 There are two types of key matches are allowed in bucket policies one is `*` and another is `?` 

diff --git a/bucket-policies-primer.md b/bucket-policies-primer.md
@@ -0,0 +1,57 @@
+It would be like this `/user/*/files/public/*`  in your bucket policy, for private you don't need since by default all objects are indeed private. Since the key regex is a flat key match should work properly for all users.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": [
+        "s3:GetObject"
+      ],
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": [
+          "*"
+        ]
+      },
+      "Resource": [
+        "arn:aws:s3:::testbucket/user/*/files/public/*"
+      ],
+      "Sid": ""
+    }
+  ]
+}
+```
+
+```
+aws s3api --no-verify-ssl put-bucket-policy --bucket testbucket --policy file:///tmp/policy.json
+```
+
+There are two types of key matches are allowed in bucket policies one is `*` and another is `?` 
+
+Now if you have this in your Resource 
+```
+arn:aws:s3:::testbucket/user/*/files/public/*
+```
+then the policies will match 
+```
+arn:aws:s3:::testbucket/user/harsha/files/public/issue
+```
+Here the user is `harsha` 
+
+Now if you have this in your Resource
+```
+arn:aws:s3:::testbucket/user/?/files/public/*
+```
+then the policies will match
+```
+arn:aws:s3:::testbucket/user/1/files/public/issue
+```
+Here the user is `1`  You can even repeat `?` to restrict the character length of the users as well. Lets say if you have 6 repeated `?` 
+```
+arn:aws:s3:::testbucket/user/??????/files/public/*
+```
+then the policies will match
+```
+arn:aws:s3:::testbucket/user/harsha/files/public/issue
+```