webidrsa

README

webid-rsa

WebID-RSA authentication library in Go

Install

go get -u github.com/deiu/webid-rsa

Example

package main

import (
	"net/http"
	"github.com/deiu/webid-rsa"
)

func main() {
	handler := http.NewServeMux()

	handler.Handle("/admin", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
		user := ""
		authz := req.Header.Get("Authorization")
		if len(authz) > 0 {
			user, _ = webidrsa.Authenticate(req)
		}
		if len(user) == 0 {
			authn := webidrsa.NewAuthenticateHeader(req)
			w.Header().Set("WWW-Authenticate", authn)
			w.WriteHeader(401)
			return
		}

		w.Write([]byte(user))
		w.WriteHeader(200)
		return
	}))

	http.ListenAndServe(":8888", handler)
}

Protocol details

WebID-RSA is somewhat similar to WebID-TLS, in that a public RSA key is published in the WebID profile, and the user will sign a token with the corresponding private key that matches the public key in the profile.

The client receives a secure token from the server, which it signs and then sends back to the server. The implementation of WebID-RSA is similar to Digest access authentication in HTTP, in that it reuses similar headers.

Here is a step by step example that covers the authentication handshake.

First, a client attempts to access a protected resource at https://example.org/data/.

REQUEST:

GET /data/ HTTP/1.1
Host: example.org

RESPONSE:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: WebID-RSA source="example.org", nonce="somethingSecure"

Next, the client sets the username value to the user's WebID and signs the SHA1 hash of the concatenated value of source + username + nonce before resending the request. The signature must use the PKCS1v15 standard and it must be base64 encoded.

It is important that clients return the proper source value they received from the server, in order to avoid man-in-the-middle attacks on non-HTTPS connections. Also note that the server must send it's own URI (source) together with the token, otherwise a MitM can forward the claim to the client; the server will also expect that clients return the same server URI.

REQUEST:

GET /data/ HTTP/1.1
Host: example.org
Authorization: WebID-RSA source="example.org",
                         username="https://alice.example.org/card#me",
                         nonce="somethingSecure",
                         sig="base64(sig(SHA1(SourceUsernameNonce)))"

RESPONSE:

HTTP/1.1 200 OK

Documentation

Index

• Variables
• func Authenticate(req *http.Request) (string, error)
• func GetOrigin(req *http.Request) string
• func NewAuthenticateHeader(req *http.Request) string
• func NewRandomID() string
• func ValidateToken(auth *Authorization) error
• type Authentication
  • func ParseAuthenticateHeader(header string) (*Authentication, error)
• type Authorization
  • func ParseAuthorizationHeader(header string) (*Authorization, error)
• type NS
  • func NewNS(base string) (ns NS)
  • func (ns NS) Get(name string) (term rdf.Term)
• type Signer
  • func ParsePrivateKey(key *rsa.PrivateKey) (Signer, error)
  • func ParsePrivatePEMKey(pemBytes []byte) (Signer, error)
• type Token
  • func NewToken(req *http.Request) *Token
• type Verifier
  • func ParsePublicKey(key *rsa.PublicKey) (Verifier, error)
  • func ParsePublicKeyNE(keyT, keyN, keyE string) (Verifier, error)
  • func ParsePublicPEMKey(pemBytes []byte) (Verifier, error)

Variables

var (

	// token validity in minutes
	TokenDuration = 1
	DurationScale = time.Minute
)

Functions

func Authenticate

func Authenticate(req *http.Request) (string, error)

Authenticate authenticates a user using WebID-RSA

func GetOrigin

func GetOrigin(req *http.Request) string

func NewAuthenticateHeader

func NewAuthenticateHeader(req *http.Request) string

func NewRandomID

func NewRandomID() string

func ValidateToken

func ValidateToken(auth *Authorization) error

Types

type Authentication

type Authentication struct {
	Source, Nonce, Username string
}

Authentication structure

func ParseAuthenticateHeader

func ParseAuthenticateHeader(header string) (*Authentication, error)

ParseAuthenticateHeader parses an Authenticate header and returns an Authentication object

type Authorization

type Authorization struct {
	Type, Source, Username, Nonce, Signature string
}

Authorization structure

func ParseAuthorizationHeader

func ParseAuthorizationHeader(header string) (*Authorization, error)

ParseAuthorizationHeader parses an Authorization header into a local Authorization structure

type NS

type NS string

NS is a generic namespace type

func NewNS

func NewNS(base string) (ns NS)

NewNS is used to set a new namespace

func (NS) Get

func (ns NS) Get(name string) (term rdf.Term)

Get is used to return the prefix for a namespace

type Signer

type Signer interface {
	Sign(data []byte) ([]byte, error)
}

Signer creates signatures that verify against a public key.

func ParsePrivateKey

func ParsePrivateKey(key *rsa.PrivateKey) (Signer, error)

ParsePrivateKey parses an RSA private key and returns a new signer object

func ParsePrivatePEMKey

func ParsePrivatePEMKey(pemBytes []byte) (Signer, error)

ParsePrivatePEMKey parses a PEM encoded private key and returns a Signer.

type Token

type Token struct {
	Source string
	Nonce  string
	Valid  int64
}

func NewToken

func NewToken(req *http.Request) *Token

type Verifier

type Verifier interface {
	Verify(data []byte, sig []byte) error
}

Verifier verifies signatures against a public key.

func ParsePublicKey

func ParsePublicKey(key *rsa.PublicKey) (Verifier, error)

ParsePublicKey parses an RSA public key and returns a new verifier object

func ParsePublicKeyNE

func ParsePublicKeyNE(keyT, keyN, keyE string) (Verifier, error)

ParsePublicKeyNE parses a modulus and exponent and returns a new verifier object

func ParsePublicPEMKey

func ParsePublicPEMKey(pemBytes []byte) (Verifier, error)

ParsePublicPEMKey parses a PEM encoded private key and returns a new verifier object