Polishes docs for RSA algorithms

Author: ejholmes

examples_test.go

@@ -1,11 +1,38 @@
 package httpsignatures_test
 
 import (
+	"crypto/rsa"
+	"crypto/x509"
+	"encoding/pem"
 	"net/http"
 
 	"github.com/99designs/httpsignatures-go"
 )
 
+const (
+	ExamplePrivateKey = `-----BEGIN RSA PRIVATE KEY-----
+MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF
+NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F
+UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB
+AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA
+QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK
+kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg
+f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u
+412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc
+mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7
+kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA
+gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW
+G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI
+7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA==
+-----END RSA PRIVATE KEY-----`
+	ExamplePublicyKey = `-----BEGIN PUBLIC KEY-----
+MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3
+6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6
+Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw
+oYi+1hqp1fIekaxsyQIDAQAB
+-----END PUBLIC KEY-----`
+)
+
 func Example_signing() {
 	r, _ := http.NewRequest("GET", "http://example.com/some-api", nil)
 
@@ -17,6 +44,20 @@ func Example_signing() {
 	http.DefaultClient.Do(r)
 }
 
+func Example_signingRSA() {
+	block, _ := pem.Decode([]byte(ExamplePrivateKey))
+	privateKey, _ := x509.ParsePKCS1PrivateKey(block.Bytes)
+
+	r, _ := http.NewRequest("GET", "http://example.com/some-api", nil)
+
+	// Sign using the 'Signature' header
+	httpsignatures.DefaultRsaSha256Signer.SignRequestRSA("KeyId", privateKey, r)
+	// OR Sign using the 'Authorization' header
+	httpsignatures.DefaultRsaSha256Signer.AuthRequestRSA("KeyId", privateKey, r)
+
+	http.DefaultClient.Do(r)
+}
+
 func Example_customSigning() {
 	signer := httpsignatures.NewSigner(
 		httpsignatures.AlgorithmHmacSha256,
@@ -51,3 +92,28 @@ func Example_verification() {
 		// request was signed correctly.
 	}
 }
+
+func Example_verificationRSA() {
+	_ = func(w http.ResponseWriter, r *http.Request) {
+		sig, err := httpsignatures.FromRequest(r)
+		if err != nil {
+			// Probably a malformed header
+			http.Error(w, "Bad Request", http.StatusBadRequest)
+			panic(err)
+		}
+
+		// if you have headers that must be signed check
+		// that they are in sig.Headers
+
+		var pemPublicKeyBytes []byte // = lookup using sig.KeyID
+		block, _ := pem.Decode(pemPublicKeyBytes)
+		publicKey, _ := x509.ParsePKIXPublicKey(block.Bytes)
+
+		if !sig.IsValidRSA(publicKey.(*rsa.PublicKey), r) {
+			http.Error(w, "Forbidden", http.StatusForbidden)
+			return
+		}
+
+		// request was signed correctly.
+	}
+}

signature.go

@@ -136,7 +136,9 @@ func (s Signature) IsValid(key string, r *http.Request) bool {
 	return s.isValid(key, r)
 }
 
-// IsValidRSA validates that the signature was signed by an RSA private key.
+// IsValidRSA validates that the request was signed by an RSA private key, using
+// the public key for verification. This method should only be called when the
+// underlying Algorithm is an RSA backed implementation.
 func (s Signature) IsValidRSA(key *rsa.PublicKey, r *http.Request) bool {
 	return s.isValid(key, r)
 }

signer.go

@@ -49,7 +49,8 @@ func (s Signer) SignRequest(id, key string, r *http.Request) error {
 	return s.signRequest(id, key, r)
 }
 
-// SignRequestRSA signs a request with an RSA private key.
+// SignRequestRSA signs a request with an RSA private key. This method should
+// only be called when the underlying Algorithm is an RSA backed implementation.
 func (s Signer) SignRequestRSA(id string, key *rsa.PrivateKey, r *http.Request) error {
 	return s.signRequest(id, key, r)
 }
@@ -67,7 +68,18 @@ func (s Signer) signRequest(keyId string, key interface{}, r *http.Request) erro
 
 // AuthRequest adds a http signature to the Authorization: HTTP Header
 func (s Signer) AuthRequest(id, key string, r *http.Request) error {
-	sig, err := s.buildSignature(id, key, r)
+	return s.authRequest(id, key, r)
+}
+
+// AuthRequestRSA adds an http signature to the Authorization: HTTP Header using
+// an RSA private key to generate the signature.This method should only be
+// called when the underlying Algorithm is an RSA backed implementation.
+func (s Signer) AuthRequestRSA(id string, key *rsa.PrivateKey, r *http.Request) error {
+	return s.authRequest(id, key, r)
+}
+
+func (s Signer) authRequest(keyId string, key interface{}, r *http.Request) error {
+	sig, err := s.buildSignature(keyId, key, r)
 	if err != nil {
 		return err
 	}

signer_test.go

@@ -56,6 +56,55 @@ func TestSignHmacSha256(t *testing.T) {
 	)
 }
 
+func TestSignRsaSha1(t *testing.T) {
+	r := &http.Request{
+		Header: http.Header{
+			"Date": []string{"Thu, 05 Jan 2012 21:31:40 GMT"},
+		},
+	}
+
+	block, _ := pem.Decode([]byte(TEST_PRIVATE_KEY))
+	privateKey, _ := x509.ParsePKCS1PrivateKey(block.Bytes)
+
+	err := DefaultRsaSha1Signer.SignRequestRSA(TEST_KEY_ID, privateKey, r)
+	assert.Nil(t, err)
+
+	s, err := FromRequest(r)
+	assert.Nil(t, err)
+
+	assert.Equal(t, TEST_KEY_ID, s.KeyID)
+
+	assert.Equal(t,
+		"KcypPq/UJBlvY9WR/zb6pGS2vkhlzKX1OUjtImOG8d4CynptmMxXWuzi3LeJW8jOnEmjC00Ga2tOruaSDo8MuDlXEy7JrYIqqD39XYKt5pFQ7dScpZARIrQ4H0n8bn4uIQFLMxkNt2aeuDogyUPcRMxBr6mVe0OHw8MY1y5xdpQ=",
+		s.Signature,
+	)
+}
+
+func TestSignRsaSha256(t *testing.T) {
+	r := &http.Request{
+		Header: http.Header{
+			"Date": []string{"Thu, 05 Jan 2012 21:31:40 GMT"},
+		},
+	}
+
+	block, _ := pem.Decode([]byte(TEST_PRIVATE_KEY))
+	privateKey, _ := x509.ParsePKCS1PrivateKey(block.Bytes)
+
+	err := DefaultRsaSha256Signer.SignRequestRSA(TEST_KEY_ID, privateKey, r)
+	assert.Nil(t, err)
+
+	s, err := FromRequest(r)
+	assert.Nil(t, err)
+
+	assert.Equal(t, TEST_KEY_ID, s.KeyID)
+
+	assert.Equal(t,
+		"TQZq1wGaOdAT3kiSOUq29jh6UG0DgZH2TW6aHYVNrHwKiACi1b9U58la/0SeDqEt6mKe836tHVKXouzNM5LaRiXWW13lZstdg/rXYxZ6N46jZKwVKRXcw9sc6/nZfjnDsxWs6/Zi4Si8hdEZx4CczUjPWBGDi+EaY+PPyZWSibs=",
+		s.Signature,
+	)
+}
+
+// Tests conformance with the test cases provided in the RFC document.
 func TestSignRsaSha256_RFC(t *testing.T) {
 	block, _ := pem.Decode([]byte(TEST_PRIVATE_KEY))
 	privateKey, _ := x509.ParsePKCS1PrivateKey(block.Bytes)
@@ -101,27 +150,6 @@ func TestSignRsaSha256_RFC(t *testing.T) {
 	}
 }
 
-func TestSignRsaSha256_BasicTest(t *testing.T) {
-	r := newRFCRequest()
-
-	block, _ := pem.Decode([]byte(TEST_PRIVATE_KEY))
-	privateKey, _ := x509.ParsePKCS1PrivateKey(block.Bytes)
-
-	signer := NewSigner(AlgorithmRsaSha256, RequestTarget, "host", "date")
-	err := signer.SignRequestRSA(TEST_KEY_ID, privateKey, r)
-	assert.Nil(t, err)
-
-	s, err := FromRequest(r)
-	assert.Nil(t, err)
-
-	assert.Equal(t, TEST_KEY_ID, s.KeyID)
-
-	assert.Equal(t,
-		"HUxc9BS3P/kPhSmJo+0pQ4IsCo007vkv6bUm4Qehrx+B1Eo4Mq5/6KylET72ZpMUS80XvjlOPjKzxfeTQj4DiKbAzwJAb4HX3qX6obQTa00/qPDXlMepD2JtTw33yNnm/0xV7fQuvILN/ys+378Ysi082+4xBQFwvhNvSoVsGv4=",
-		s.Signature,
-	)
-}
-
 func TestSignWithMissingDateHeader(t *testing.T) {
 	r := &http.Request{Header: http.Header{}}