Functionality: Add comments and change params to pointers

Author: Juanita De La Cuesta

signature/signature.go

@@ -13,6 +13,10 @@ import (
 	"time"
 )
 
+// ValidityPeriod is the time in hours after which a request is descarded
+type ValidityPeriod *float64
+
+// StringToTime converts from Unicod Epoch enconded timestamps to time.Time Go objects
 func StringToTime(s string) (time.Time, error) {
 	sec, err := strconv.ParseInt(s, 10, 64)
 	if err != nil {
@@ -21,31 +25,53 @@ func StringToTime(s string) (time.Time, error) {
 	return time.Unix(sec, 0), nil
 }
 
-func HMACSHA256(message, signingKey []byte) ([]byte, error) {
-	mac := hmac.New(sha256.New, []byte(signingKey))
+// HMACSHA256 generates HMACS enconded hashes using the provided Key and SHA256
+// encoding for the message
+func HMACSHA256(message, key []byte) ([]byte, error) {
+	mac := hmac.New(sha256.New, []byte(key))
 	if _, err := mac.Write(message); err != nil {
 		return nil, err
 	}
 	return mac.Sum(nil), nil
 }
 
+// Validator type represents a MessageBird signature validator
 type Validator struct {
-	SigningKey  string
-	Period      float64
+	SigningKey  string         // Signing Key provided by MessageBird
+	Period      ValidityPeriod // Period in hours for a message to be accepted as real, set to nil to bypass the timestamp validator
 	Log         *log.Logger
-	LogMesssage string
+	LogMesssage *string
+}
+
+// NewValidator returns a signature validator object
+func NewValidator(signingKey string, period float64, log *log.Logger, message *string) *Validator {
+	return &Validator{
+		SigningKey:  signingKey,
+		Period:      &period,
+		Log:         log,
+		LogMesssage: message,
+	}
 }
 
-func (v *Validator) ValidTimestamp(ts time.Time) bool {
-	if v.Period != 0 {
+// ValidTimestamp validates if the MessageBird-Request-Timestamp is a valid
+// date and if the request is older than the validator Period.
+func (v *Validator) ValidTimestamp(ts string) bool {
+	if v.Period != nil {
 		now := time.Now()
-		if diff := now.Sub(ts); diff.Hours() > v.Period {
+		t, err := StringToTime(ts)
+		diff := now.Sub(t)
+		if err != nil || diff.Hours() > *v.Period {
 			return false
 		}
 	}
 	return true
 }
 
+// CalculateSignature calculates the MessageBird-Signature using HMAC_SHA_256
+// encoding and the timestamp, query params and body from the request:
+// signature = HMAC_SHA_256(
+//	TIMESTAMP + \n + QUERY_PARAMS + \n + SHA_256_SUM(BODY),
+//	signing_key)
 func (v *Validator) CalculateSignature(ts, qp string, b []byte) ([]byte, error) {
 	var m bytes.Buffer
 	bh := sha256.Sum256(b)
@@ -57,24 +83,38 @@ func (v *Validator) CalculateSignature(ts, qp string, b []byte) ([]byte, error)
 	return s, nil
 }
 
+// ValidSignature takes the timestamp, query params and body from the request,
+// calculates the expected signature and compares it to the one sent by MessageBird.
 func (v *Validator) ValidSignature(ts, qp, rs string, b []byte) bool {
 	es, _ := v.CalculateSignature(ts, qp, b)
 	drs, _ := base64.StdEncoding.DecodeString(rs)
 	return hmac.Equal(drs, es)
 }
 
-func (v *Validator) Wrapper(h http.Handler) http.Handler {
+func (v *Validator) Error(w http.ResponseWriter, r *http.Request) {
+	if v.Log != nil {
+		v.Log.Println(v.LogMesssage, r.Host)
+	}
+	http.Error(w, "Request not allowed", http.StatusUnauthorized)
+	return
+}
+
+// Validate is a handler wrapper that takes care of the signature validation of
+// incoming requests and rejects them if invalid or pass them on to your handler
+// otherwise.
+// To use just wrappe your handler with it:
+//  http.Handle("/path", signature.Validate(handleThing))
+func (v *Validator) Validate(h http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		ts := r.Header.Get("MessageBird-Request-Timestamp")
 		rs := r.Header.Get("MessageBird-Request-Signature")
 		if ts == "" || rs == "" {
-			http.Error(w, "Request not allowed", http.StatusUnauthorized)
+			v.Error(w, r)
 			return
 		}
-		t, _ := StringToTime(ts)
 		b, _ := ioutil.ReadAll(r.Body)
-		if v.ValidTimestamp(t) == false || v.ValidSignature(ts, r.URL.RawQuery, rs, b) == false {
-			http.Error(w, "Request not allowed", http.StatusUnauthorized)
+		if v.ValidTimestamp(ts) == false || v.ValidSignature(ts, r.URL.RawQuery, rs, b) == false {
+			v.Error(w, r)
 			return
 		}
 		h.ServeHTTP(w, r)