Updated the documentation.

Author: Michael Khmelnitsky

doc_source/AccessPolicyLanguage_ArchitecturalOverview.md

@@ -0,0 +1,14 @@
+# Architectural Overview<a name="AccessPolicyLanguage_ArchitecturalOverview"></a>
+
+The following figure and table describe the main components that interact to provide access control for your resources\.
+
+![\[Architectural Overview\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Arch_Overview.gif)
+
+
+|  |  | 
+| --- |--- |
+| 1 |  You, the resource owner\.  | 
+| 2 |  Your resources \(contained within the AWS service; e\.g\., Amazon SQS queues\)\.  | 
+| 3 |  Your policies\. Typically you have one policy per resource, although you could have multiple\. The AWS service itself provides an API you use to upload and manage your policies\.  | 
+| 4 |  Requesters and their incoming requests to the AWS service\.  | 
+| 5 |  The access policy language evaluation code\. This is the set of code within the AWS service that evaluates incoming requests against the applicable policies and determines whether the requester is allowed access to the resource\. For information about how the service makes the decision, see [Evaluation Logic](AccessPolicyLanguage_EvaluationLogic.md)\.  | 

doc_source/AccessPolicyLanguage_EvaluationLogic.md

@@ -0,0 +1,46 @@
+# Evaluation Logic<a name="AccessPolicyLanguage_EvaluationLogic"></a>
+
+The goal at evaluation time is to decide whether a given request should be allowed or denied\. The evaluation logic follows several basic rules:
++ By default, all requests to use your resource coming from anyone but you are denied
++ An allow overrides any default denies
++ An explicit deny overrides any allows
++ The order in which the policies are evaluated is not important
+
+The following flow chart and discussion describe in more detail how the decision is made\.
+
+![\[Evaluation flow chart\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Evaluation_Flow.gif)
+
+
+|  |  | 
+| --- |--- |
+| 1 |  The decision starts with a default deny\.  | 
+| 2 |   The enforcement code then evaluates all the policies that are applicable to the request \(based on the resource, principal, action, and conditions\)\.  The order in which the enforcement code evaluates the policies is not important\.  | 
+| 3 |   In all those policies, the enforcement code looks for an explicit deny instruction that would apply to the request\. If it finds even one, the enforcement code returns a decision of "deny" and the process is finished \(this is an explicit deny; for more information, see [Explicit Deny](AccessPolicyLanguage_KeyConcepts.md#Define_HardDeny)\)\.  | 
+| 4 |  If no explicit deny is found, the enforcement code looks for any "allow" instructions that would apply to the request\. If it finds even one, the enforcement code returns a decision of "allow" and the process is done \(the service continues to process the request\)\.   | 
+| 5 |  If no allow is found, then the final decision is "deny" \(because there was no explicit deny or allow, this is considered a *default deny* \(for more information, see [Default Deny](AccessPolicyLanguage_KeyConcepts.md#Define_SoftDeny)\)\.  | 
+
+## The Interplay of Explicit and Default Denials<a name="denials"></a>
+
+A policy results in a default deny if it doesn't directly apply to the request\. For example, if a user requests to use Amazon SNS, but the policy on the topic doesn't refer to the user's AWS account at all, then that policy results in a default deny\.
+
+A policy also results in a default deny if a condition in a statement isn't met\. If all conditions in the statement are met, then the policy results in either an allow or an explicit deny, based on the value of the Effect element in the policy\. Policies don't specify what to do if a condition isn't met, and so the default result in that case is a default deny\.
+
+For example, let's say you want to prevent requests coming in from Antarctica\. You write a policy \(called Policy A1\) that allows a request only if it doesn't come from Antarctica\. The following diagram illustrates the policy\.
+
+![\[Policy allowing request if it's not from Antarctica\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Allow_Override_1.gif)
+
+If someone sends a request from the U\.S\., the condition is met \(the request is not from Antarctica\)\. Therefore, the request is allowed\. But, if someone sends a request from Antarctica, the condition isn't met, and the policy's result is therefore a default deny\. 
+
+You could turn the result into an explicit deny by rewriting the policy \(named Policy A2\) as in the following diagram\. Here, the policy explicitly denies a request if it comes from Antarctica\.
+
+![\[Policy denying request if it's from Antarctica\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Allow_Override_2.gif)
+
+If someone sends a request from Antarctica, the condition is met, and the policy's result is therefore an explicit deny\.
+
+The distinction between a default deny and an explicit deny is important because a default deny can be overridden by an allow, but an explicit deny can't\. For example, let's say there's another policy that allows requests if they arrive on June 1, 2010\. How does this policy affect the overall outcome when coupled with the policy restricting access from Antarctica? We'll compare the overall outcome when coupling the date\-based policy \(we'll call Policy B\) with the preceding policies A1 and A2\. Scenario 1 couples Policy A1 with Policy B, and Scenario 2 couples Policy A2 with Policy B\. The following figure and discussion show the results when a request comes in from Antarctica on June 1, 2010\.
+
+![\[Override of default deny\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Allow_Override.gif)
+
+In Scenario 1, Policy A1 returns a default deny, as described earlier in this section\. Policy B returns an allow because the policy \(by definition\) allows requests that come in on June 1, 2010\. The allow from Policy B overrides the default deny from Policy A1, and the request is therefore allowed\.
+
+In Scenario 2, Policy A2 returns an explicit deny, as described earlier in this section\. Again, Policy B returns an allow\. The explicit deny from Policy A2 overrides the allow from Policy B, and the request is therefore denied\.

doc_source/AccessPolicyLanguage_KeyConcepts.md

@@ -0,0 +1,71 @@
+# Key Concepts<a name="AccessPolicyLanguage_KeyConcepts"></a>
+
+The following sections describe the concepts you need to understand to use the access policy language\. They're presented in a logical order, with the first terms you need to know at the top of the list\.
+
+## Permission<a name="permissions"></a>
+
+A *permission* is the concept of allowing or disallowing some kind of access to a particular resource\. Permissions essentially follow this form: "A is/isn't allowed to do B to C where D applies\." For example, *Jane* \(A\) has permission to *publish* \(B\) to *TopicA* \(C\) as long as *she uses the HTTP protocol* \(D\)\. Whenever Jane publishes to TopicA, the service checks to see if she has permission and if the request satisfies the conditions set forth in the permission\.
+
+## Statement<a name="statement"></a>
+
+A *statement* is the formal description of a single permission, written in the access policy language\. You always write a statement as part of a broader container document known as a *policy* \(see the next concept\)\.
+
+## Policy<a name="policy"></a>
+
+A *policy* is a document \(written in the access policy language\) that acts as a container for one or more statements\. For example, a policy could have two statements in it: one that states that Jane can subscribe using the email protocol, and another that states that Bob cannot publish to TopicA\. As shown in the following figure, an equivalent scenario would be to have two policies, one that states that Jane can subscribe using the email protocol, and another that states that Bob cannot publish to TopicA\.
+
+![\[Policy diagram\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Statement_and_Policy.gif)
+
+## Issuer<a name="issuer"></a>
+
+The *issuer* is the person who writes a policy to grant permissions for a resource\. The issuer \(by definition\) is always the resource owner\. AWS does not permit AWS service users to create policies for resources they don't own\. If John is the resource owner, AWS authenticates John's identity when he submits the policy he's written to grant permissions for that resource\.
+
+## Principal<a name="principal"></a>
+
+The *principal* is the person or persons who receive the permission in the policy\. The principal is A in the statement "A has permission to do B to C where D applies\." In a policy, you can set the principal to "anyone" \(i\.e\., you can specify a wildcard to represent all people\)\. You might do this, for example, if you don't want to restrict access based on the actual identity of the requester, but instead on some other identifying characteristic such as the requester's IP address\.
+
+## Action<a name="action"></a>
+
+The *action* is the activity the principal has permission to perform\. The action is B in the statement "A has permission to do B to C where D applies\." Typically, the action is just the operation in the request to AWS\. For example, Jane sends a request to Amazon SNS with `Action``=Subscribe`\. You can specify one or multiple actions in a policy\.
+
+## Resource<a name="resource"></a>
+
+The *resource* is the object the principal is requesting access to\. The resource is C in the statement "A has permission to do B to C where D applies\."
+
+## Conditions and Keys<a name="conditions"></a>
+
+The *conditions* are any restrictions or details about the permission\. The condition is D in the statement "A has permission to do B to C where D applies\." The part of the policy that specifies the conditions can be the most detailed and complex of all the parts\. Typical conditions are related to:
++ Date and time \(e\.g\., the request must arrive before a specific day\)
++ IP address \(e\.g\., the requester's IP address must be part of a particular CIDR range\)
+
+A *key* is the specific characteristic that is the basis for access restriction\. For example, the date and time of request\.
+
+You use both *conditions* and *keys* together to express the restriction\. The easiest way to understand how you actually implement a restriction is with an example: If you want to restrict access to before May 30, 2010, you use the condition called `DateLessThan`\. You use the key called `aws:CurrentTime` and set it to the value `2010-05-30T00:00:00Z`\. AWS defines the conditions and keys you can use\. The AWS service itself \(e\.g\., Amazon SQS or Amazon SNS\) might also define service\-specific keys\. For more information, see [Special Information for Amazon SNS Policies](AccessPolicyLanguage_SpecialInfo.md)\.
+
+## Requester<a name="requester"></a>
+
+The *requester* is the person who sends a request to an AWS service and asks for access to a particular resource\. The requester sends a request to AWS that essentially says: "Will you allow me to do B to C where D applies?"
+
+## Evaluation<a name="evaluation"></a>
+
+*Evaluation* is the process the AWS service uses to determine if an incoming request should be denied or allowed based on the applicable policies\. For information about the evaluation logic, see [Evaluation Logic](AccessPolicyLanguage_EvaluationLogic.md)\.
+
+## Effect<a name="effect"></a>
+
+The *effect* is the result that you want a policy statement to return at evaluation time\. You specify this value when you write the statements in a policy, and the possible values are *deny* and *allow*\.
+
+ For example, you could write a policy that has a statement that *denies* all requests that come from Antarctica \(effect=deny given that the request uses an IP address allocated to Antarctica\)\. Alternately, you could write a policy that has a statement that *allows* all requests that *don't* come from Antarctica \(effect=allow, given that the request doesn't come from Antarctica\)\. Although the two statements sound like they do the same thing, in the access policy language logic, they are different\. For more information, see [Evaluation Logic](AccessPolicyLanguage_EvaluationLogic.md)\.
+
+Although there are only two possible values you can specify for the effect \(allow or deny\), there can be three different results at policy evaluation time: *default deny*, *allow*, or *explicit deny*\. For more information, see the following concepts and [Evaluation Logic](AccessPolicyLanguage_EvaluationLogic.md)\.
+
+## Default Deny<a name="Define_SoftDeny"></a>
+
+A *default deny* is the default result from a policy in the absence of an allow or explicit deny\. 
+
+## Allow<a name="allow"></a>
+
+An *allow* results from a statement that has effect=allow, assuming any stated conditions are met\. Example: Allow requests if they are received before 1:00 p\.m\. on April 30, 2010\. An allow overrides all default denies, but never an explicit deny\.
+
+## Explicit Deny<a name="Define_HardDeny"></a>
+
+An *explicit deny* results from a statement that has effect=deny, assuming any stated conditions are met\. Example: Deny all requests if they are from Antarctica\. Any request that comes from Antarctica will always be denied no matter what any other policies might allow\.

doc_source/AccessPolicyLanguage_OverallFlow.md

@@ -0,0 +1,20 @@
+# Using the Access Policy Language<a name="AccessPolicyLanguage_OverallFlow"></a>
+
+The following figure and table describe the general process of how access control works with the access policy language\. 
+
+![\[Basic flow for access control with the access policy language\]](http://docs.aws.amazon.com/sns/latest/dg/images/AccessPolicyLanguage_Basic_Flow.gif)
+
+
+**Process for Using Access Control with the Access Policy Language**  
+
+|  |  | 
+| --- |--- |
+|  1  |  You write a policy for your resource\. For example, you write a policy to specify permissions for your Amazon SNS topics\.  | 
+|  2  |  You upload your policy to AWS\. The AWS service itself provides an API you use to upload your policies\. For example, you use the Amazon SNS `SetTopicAttributes` action to upload a policy for a particular Amazon SNS topic\.  | 
+|  3  |  Someone sends a request to use your resource\. For example, a user sends a request to Amazon SNS to use one of your topics\.   | 
+|  4  |  The AWS service determines which policies are applicable to the request\. For example, Amazon SNS looks at all the available Amazon SNS policies and determines which ones are applicable \(based on what the resource is, who the requester is, etc\.\)\.  | 
+|  5  |  The AWS service evaluates the policies\. For example, Amazon SNS evaluates the policies and determines if the requester is allowed to use your topic or not\. For information about the decision logic, see [Evaluation Logic](AccessPolicyLanguage_EvaluationLogic.md)\.  | 
+|  6  |  The AWS service either denies the request or continues to process it\.  For example, based on the policy evaluation result, the service either returns an "Access denied" error to the requester or continues to process the request\.  | 
+
+**Related Topics**
++  [Architectural Overview](AccessPolicyLanguage_ArchitecturalOverview.md) 

doc_source/AccessPolicyLanguage_SpecialInfo.md

@@ -0,0 +1,43 @@
+# Special Information for Amazon SNS Policies<a name="AccessPolicyLanguage_SpecialInfo"></a>
+
+The following list gives information specific to the Amazon SNS implementation of access control:
++ Each policy must cover only a single topic \(when writing a policy, don't include statements that cover different topics\)
++ Each policy must have a unique policy `Id`
++ Each statement in a policy must have a unique statement `sid`
+
+## Amazon SNS Policy Limits<a name="w3aac28b7c11b7"></a>
+
+The following table lists the maximum limits for policy information\.
+
+
+| Name | Maximum Limit | 
+| --- | --- | 
+|  Bytes  |  30 kb  | 
+|  Statements  |  100  | 
+|  Principals  |  1 to 200 \(0 is invalid\.\)  | 
+|  Resource  |  1 \(0 is invalid\. The value must match the ARN of the policy's topic\.\)  | 
+
+## Valid Amazon SNS Policy Actions<a name="sns_aspen_actions"></a>
+
+Amazon SNS supports the actions shown in the following table\.
+
+
+| Action | Description | 
+| --- | --- | 
+|  sns:AddPermission  | Grants permission to add permissions to the topic policy\. | 
+|  sns:DeleteTopic  | Grants permission to delete a topic\. | 
+|  sns:GetTopicAttributes  | Grants permission to receive all of the topic attributes\. | 
+|  sns:ListSubscriptionsByTopic  | Grants permission to retrieve all the subscriptions to a specific topic\. | 
+|  sns:Publish  | Grants permission to publish to a topic or endpoint\. For more information, see [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) in the Amazon Simple Notification Service API Reference  | 
+|  sns:RemovePermission  | Grants permission to remove any permissions in the topic policy\. | 
+|  sns:SetTopicAttributes  | Grants permission to set a topic's attributes\. | 
+|  sns:Subscribe  | Grants permission to subscribe to a topic\. | 
+
+## Amazon SNS Keys<a name="sns_aspen_keys"></a>
+
+Amazon SNS uses the following service\-specific keys\. You can use these in policies that restrict access to `Subscribe` requests\.
++ **sns:Endpoint—**The URL, email address, or ARN from a `Subscribe` request or a previously confirmed subscription\. Use with string conditions \(see [Example Policies for Amazon SNS](sns-using-identity-based-policies.md#ExamplePolicies_SNS)\) to restrict access to specific endpoints \(e\.g\., \*@example\.com\)\.
++ **sns:Protocol—**The `protocol` value from a `Subscribe` request or a previously confirmed subscription\. Use with string conditions \(see [Example Policies for Amazon SNS](sns-using-identity-based-policies.md#ExamplePolicies_SNS)\) to restrict publication to specific delivery protocols \(e\.g\., https\)\.
+
+**Important**  
+When you use a policy to control access by sns:Endpoint, be aware that DNS issues might affect the endpoint's name resolution in the future\.