Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fix up of README

Proper spell-checking and re-read for sense. A couple of minor additions but mostly spelling/grammer
  • Loading branch information...
commit c135144cba1c3b7aff9167ec4f2169fd86e281de 1 parent 6664d2a
@hypernumbers authored
Showing with 22 additions and 19 deletions.
  1. +22 −19 examples/hmac_api/README
View
41 examples/hmac_api/README
@@ -9,7 +9,7 @@ Purpose
The purpose of this example is to:
* make it easy to implement an API in mochiweb
- using a proven approach so that 'amateurs' don't have to reinvent crypto
-* make it easy to generate client libraries for that API so that client-side implementors can:
+* make it easy to generate client libraries for that API so that client-side implementers can:
- reuse closely related code examples
- build compatibility unit tests instead of fiddling around debugging their library against live implementations of the system
@@ -18,9 +18,9 @@ Scope
The scope of this document is:
* a description of the client-server exchange
-* an reference implementation of
+* a reference implementation of
- the server-side implementation of the exchange
- - the client-side implemtation of the exchange
+ - the client-side implementation of the exchange
* developing a custom implementation of an API
* deploying that implementation to new client-side users to build their client libraries
@@ -38,7 +38,7 @@ The Client-Server Exchange
OVERVIEW
-This section describes the client-server exchange for an Amazon-style API authentication schema. It has the following characterisics:
+This section describes the client-server exchange for an Amazon-style API authentication schema. It has the following characteristics:
* based on a public key/private key
* used to authenticate non-SSL api requests
* not a full once-use schema and is vulnerable to replay attacks within a short time window
@@ -50,12 +50,12 @@ The api described in this document is:
The api described in this document is NOT:
* an implementation of 2-legged OAUTH
- - see URL HERE
+ - see https://github.com/tim/erlang-oauth
* an implementation of 3-legged OAUTH
It is not suitable for use in applications where an end user has to log into a service and piggy-back on top of a keypair security system.
-THE CLIENT LIBRARY HERE IS **NOT** AN AMAZON CLIENT LIBRARY. AMAZON DOES FUNKY STUFF WITH HOSTNAMES AND PUSHES THEM ONTO THE URL IN CANONICALISATION! THE CLIENT LIBRARY IS AMAZON-A-LIKE ENOUGH TO USE THE AMAZON DOCOS TO BUILD A TEST SUITE.
+THE CLIENT LIBRARY HERE IS **NOT** AN AMAZON CLIENT LIBRARY. AMAZON DOES FUNKY STUFF WITH HOSTNAMES AND PUSHES THEM ONTO THE URL IN CANONICALIZATION! THE CLIENT LIBRARY IS AMAZON-A-LIKE ENOUGH TO USE THE AMAZON DOCOS TO BUILD A TEST SUITE.
STEP 1
@@ -74,7 +74,7 @@ This function returns cryptographically strong random numbers using the openSSL
The public key is used as a declaration of identity, "I am bcaa49..."
-The private key is never passed over the wire and is used to construct hash client side and server side.
+The private key is never passed over the wire and is used to construct the same hash on both the client- and the server-side.
STEP 2
@@ -88,23 +88,23 @@ The client prepares their request:
These components are then turned into a string called the canonical form.
-The HTTP protocol is permissive, it treats different requests as if they were the same. For instance it doesn't care about the order in which headers are sent, and allows the same header to contain multiple values as a list or be specified multiple times as a key, value pair.
+The HTTP protocol is permissive; it treats different requests as if they were the same. For instance it doesn't care about the order in which headers are sent, and allows the same header to contain multiple values as a list or be specified multiple times as a key-value pair.
-Intermediate machines betweeen the client and server MAY pack and repack the HTTP request as long as they don't alter its meaning in a narrow sense. This means that the format of the HTTP request is not guaranteed to be maintained.
+Intermediate machines between the client and server MAY pack and repack the HTTP request as long as they don't alter its meaning in a narrow sense. This means that the format of the HTTP request is not guaranteed to be maintained.
The canonical form simply ensures that all the valid ways of making the same request are represented by the same string - irrespective of how this is done.
-The canonical form handles POST bodies and query paramters and silently discards anchors in URL's.
+The canonical form handles POST bodies and query parameters and silently discards anchors in URL's.
A hash of this string is made with the private key.
STEP 3
The client makes the request to the server:
-* the signature is included in the request in the standard HTTPAuthorisation header. (As the Amazon documentation points out this is infelicituous as it is being used for Authentication not Authorization, but hey!).
+* the signature is included in the request in the standard HTTPAuthorization header. (As the Amazon documentation points out this is infelicitous as it is being used for Authentication not Authorization, but hey!).
The Authorization header constructed has the form:
-<scheme name><space><public key><colon><signature>
+<schema name><space><public key><colon><signature>
An Amazon one looks like:
Authorization: AWS 0PN5J17HBGZHT7JJ3X82:frJIUN8DYpKDtOLCwo//yllqDzg=
@@ -115,7 +115,7 @@ The HTTP request is made.
STEP 4
-The request is processes:
+The request is processed:
* the server receives the request
* the server constructs the canonical form from the attributes of the request:
- url
@@ -131,9 +131,9 @@ The request is processes:
- the time encoded in the request with the server time
* the request is accepted or denied
-The time comparison is 'fuzzy' different server's clocks will be out of synch to a degree, the request may have acquired a time from an intermediate machine along the way, etc, etc. Normally a 'clock skew' time is allowed - in Amazon's case this if 15 minutes.
+The time comparison is 'fuzzy'. Different server's clocks will be out of sync to a degree, the request may have acquired a time from an intermediate machine along the way, etc, etc. Normally a 'clock skew' time is allowed - in Amazon's case this is 15 minutes.
-NOTA BENE: THIS CLOCK SKEW TIME ALLOWS FOR REPLAY ATTACKS WHERE A BAD GUY SIMPLY CAPTURES A REPLAYS TRAFFIC.
+NOTA BENE: THIS CLOCK SKEW TIME ALLOWS FOR REPLAY ATTACKS WHERE A BAD GUY SIMPLY CAPTURES AND REPLAYS TRAFFIC.
EXTENSION
@@ -179,19 +179,21 @@ The reference implementation uses 5 constants defined in hmac_api.hrl.
Building A Custom Implementation
--------------------------------
-The simplest custom implementation is simply take the existing code and change the values of the following constants:
+The simplest custom implementation is to simply take the existing code and change the values of the following constants:
* schema
* headerprefix
* dateheader
-It the API is to be used 'as is' please use the values which are commented out in hmac_api.hrl
+If the API is to be used 'as is', please use the values which are commented out in hmac_api.hrl. This will make easier for software developers to work out which version of which client-side libraries they can use.
-Client libraries written in other languges than Erlang can reimplement the test suite in hmac_api_lib.erl.
+Client libraries written in other languages than Erlang can reemployment the test suite in hmac_api_lib.erl.
-More sophisticated changes will involve changes to the canonicalisation functions.
+More sophisticated changes will involve changes to the canonicalization functions.
Use of a generic schema should make reuse of client libraries easier across different platforms.
+If you develop an ‘as-is’ client-side library in another language please consider submitting its code to this example.
+
Deploying A Custom Implementation
---------------------------------
@@ -201,3 +203,4 @@ In addition to that you will need to specify:
* description of how the API works:
- ie the acceptable methods and urls
- custom headers and their usage (if appropriate)
+
Please sign in to comment.
Something went wrong with that request. Please try again.