Merge pull request #9 from jayadebaj/patch-1

Update draft-ietf-httpapi-idempotency-key-header.md

Author: sdatspun2

draft-ietf-httpapi-idempotency-key-header.md

@@ -123,15 +123,15 @@ For each request, server SHOULD
 
 ## Idempotency Enforcement Scenarios
 
-* First time request (idempotency key or fingerprint has not been seen)
+* First time request (idempotency key and fingerprint has not been seen)
 
   The resource server SHOULD process the request normally and respond with an appropriate response and status code.
 
-* Duplicate request (idempotency key or fingerprint has been seen)
+* Duplicate request (idempotency key and fingerprint has been seen)
 
   Retry
 
-  The request was retried after the original request completed. The resource server MUST respond with the result of the previously completed operation, success or an error.
+  The request was retried after the original request completed. The resource server SHOULD respond with the result of the previously completed operation, success or an error. See Error Scenarios for details on errors.
 
   Concurrent Request
 
@@ -158,8 +158,9 @@ If the request is retried, while the original request is still being processed,
     Link: <https://developer.example.com/idempotency>;
     rel="describedby"; type="text/html"
 
-For other errors, the resource MUST return the appropriate status code and error message.
+Error scenarios above describe the status of failed idempotent requests, after the resource server prcocesses them. Clients MUST correct the requests before performing a retry operation, or the the resource server MUST fail the request and return one of the above errors. 
 
+For other 4xx/5xx errors, such as 401, 403, 500, 502, 503, 504, 429, or any other HTTP error code that is not listed here, the client SHOULD act appropriately by following the resource server's documentation.
 
 
 # IANA Considerations
@@ -302,8 +303,16 @@ Organization: WebEngage
 This section is meant to inform developers, information providers,
 and users of known security concerns specific to the idempotency keys.
 
-For idempotent request handling, the resources MAY make use of the value in the idempotency key to look up a cache or a persistent store for duplicate requests matching the key. If the resource does not validate the value of the idempotency key prior to performing such a lookup, it MAY lead to various forms of security attacks and compromise. To avoid such situations, the resource SHOULD publish the expected format of the idempotency key, algorithm used to generate it and always validate the key value as per the published specification before processing any request.
+Resource servers that do not implement  strong idempotency keys, such as UUIDs, or have appropriate controls to validate the idempotency keys, could be victim to various forms of security attacks from malicious clients:
 
+* Injection attacks-When the resource server does not validate the idempotency key in the client request and performs a idempotent cache lookup, there can be security attacks (primarily in the form of injection), compromising the server.
+* Data leaks-When an idempotency implementation allows low entropy keys, attackers MAY determine other keys and use them to fetch existing idempotent cache entries, belonging to other clients.
+
+To prevent such situations, the specification recommends the following best practices for idempotency key implementation in the resource server.
+
+* Establish a fixed format for the idempotency key and publish the key’s specification.
+* Always validate the key as per its published specification before processing any request.
+* On the resource server, implement a unique composite key as the idempotent cache lookup key. For example, a composite key MAY be implemented by combining the idempotency key sent by the client with other client specific attributes known only to the resource server.
 
 
 # Examples