Transferring blueprint from apiary.io

Author: Inflatablewoman

apiary.apib

@@ -3,6 +3,61 @@ FORMAT: 1A
 # Blocker API
 A block based filesystem microservice written in go
 
+# Group API Authentication
+All requests must contain an 'Auth Token'.
+
+##Authorization
+
+Authorization is done via a *Authorization* header sent in a request.  Anonymous requests are not allowed.  To authenticate a request, you must sign the request with the shared key when making the request and pass that signature as part of the request.  
+
+Here you can see an example of a Authorization header
+```
+Authorization=RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk=
+```
+
+You construct the signature is built in the following format:
+
+```
+authRequestSig = method + "\n" +
+                 Date + "\n" +
+                 resource
+```
+
+This would result in the following signature to be signed:
+
+```
+COPY\nWed, 28 Jan 2015 10:42:13 UTC\n/api/v1/blocker/6f90d707-3b6a-4321-b32c-3c1d37915c1b
+```
+
+Note that you MUST past the same date value in the request.  Date should be supplied in UTC using RFC1123 format.
+
+```
+x-blocker-date=Wed, 28 Jan 2015 10:42:13 UTC
+```
+
+  The signature must be exactly in the same order and include the new line character.  
+
+Now encode the signature using the [HMAC-SHA256](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) algorithm using the shared key.
+
+This will result in a key like this:
+```
+RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk="
+```
+
+Example go code to create the signature
+
+```go
+date := time.Now().UTC().Format(time.RFC1123) // UTC time
+request.Header.Add("x-blocker-date", date)
+
+authRequestKey := fmt.Sprintf("%s\n%s\n%s", method, date, resource)
+
+// See package http://golang.org/pkg/crypto/hmac/ on how golang creates hmacs
+hmac := crypto.GetHmac256(authRequestKey, SharedKey)  
+
+request.Header.Add("Authorization", hmac)
+```
+
 # Group Blocker
 Blocker related resources of the **Blocker API**
 
@@ -14,6 +69,7 @@ This is usually done via a form.
     + Header
 
             Authorization: RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk=
+            x-blocker-date: Wed, 28 Jan 2015 10:42:13 UTC
             Content-type: content-type
 
     + Body
@@ -31,6 +87,7 @@ Typically a raw upload
     + Header
 
             Authorization: RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk=
+            x-blocker-date: Wed, 28 Jan 2015 10:42:13 UTC
             Content-type: content-type
 
     + Body
@@ -73,7 +130,8 @@ Get a specific BlockFile.
 + Request 
     + Header
 
-            Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+            Authorization: RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk=
+            x-blocker-date: Wed, 28 Jan 2015 10:42:13 UTC
 
 + Response 200 (application/json)
 
@@ -86,6 +144,7 @@ Copy a BlockedFile.  The returned BlockedFile is the new BlockedFile.
     + Header
 
             Authorization: RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk=
+            x-blocker-date: Wed, 28 Jan 2015 10:42:13 UTC
 
 + Response 200 (application/json)
 
@@ -99,5 +158,6 @@ Delete a BlockedFile.
     + Header
 
             Authorization: RvPtP0QB7iIun1ehwheD4YUo7+fYfw7/ywl+HsC5Ddk=
+            x-blocker-date: Wed, 28 Jan 2015 10:42:13 UTC
 
 + Response 204