httpbakery

Documentation

Overview

The httpbakery package layers on top of the bakery package - it provides an HTTP-based implementation of a macaroon client and server.

Index

• Variables
• func Do(c *http.Client, req *http.Request) (*http.Response, error)
• func WriteDischargeRequiredError(w http.ResponseWriter, m *macaroon.Macaroon, originalErr error) error
• type KeyPair
  • func GenerateKey() (*KeyPair, error)
• type NewServiceParams
• type Service
  • func NewService(p NewServiceParams) (*Service, error)
  • func (svc *Service) AddDischargeHandler(root string, mux *http.ServeMux, ...)
  • func (svc *Service) AddPublicKeyForLocation(loc string, prefix bool, publicKey *[32]byte)
  • func (svc *Service) NewRequest(httpReq *http.Request, checker bakery.FirstPartyChecker) *bakery.Request

Variables

var DefaultHTTPClient = defaultHTTPClient()

DefaultHTTPClient is an http.Client that ensures that headers are sent to the server even when the server redirects.

Functions

func Do

func Do(c *http.Client, req *http.Request) (*http.Response, error)

Do makes an http request to the given client. If the request fails with a discharge-required error, any required discharge macaroons will be acquired, and the request will be repeated with those attached.

If c.Jar field is non-nil, the macaroons will be stored there and made available to subsequent requests.

func WriteDischargeRequiredError

func WriteDischargeRequiredError(w http.ResponseWriter, m *macaroon.Macaroon, originalErr error) error

WriteDischargeRequiredError writes a response to w that reports the given error and sends the given macaroon to the client, indicating that it should be discharged to allow the original request to be accepted.

If it returns an error, it will have written the http response anyway.

The cookie value is a base-64-encoded JSON serialization of the macaroon.

TODO(rog) consider an alternative approach - perhaps it would be better to include the macaroon directly in the response and leave it up to the client to add it to the cookies along with the discharge macaroons.

Types

type KeyPair

type KeyPair struct {
	// contains filtered or unexported fields
}

KeyPair holds a public/private pair of keys. TODO(rog) marshal/unmarshal functions for KeyPair

func GenerateKey

func GenerateKey() (*KeyPair, error)

GenerateKey generates a new key pair.

type NewServiceParams

type NewServiceParams struct {
	// Location holds the location of the service.
	// Macaroons minted by the service will have this location.
	Location string

	// Store defines where macaroons are stored.
	Store bakery.Storage

	// Key holds the private/public key pair for
	// the service to use. If it is nil, a new key pair
	// will be generated.
	Key *KeyPair

	// HTTPClient holds the http client to use when
	// creating new third party caveats for third
	// parties. If it is nil, DefaultHTTPClient will be used.
	HTTPClient *http.Client
}

NewServiceParams holds parameters for the NewService call.

type Service

type Service struct {
	*bakery.Service
	// contains filtered or unexported fields
}

Service represents a service that can use client-provided macaroons to authorize requests. It layers on top of *bakery.Service, providing http-based methods to create third-party caveats.

func NewService

func NewService(p NewServiceParams) (*Service, error)

NewService returns a new Service.

func (*Service) AddDischargeHandler

func (svc *Service) AddDischargeHandler(
	root string,
	mux *http.ServeMux,
	checker func(req *http.Request, cav string) ([]bakery.Caveat, error),
)

AddDischargeHandler handles adds handlers to the given ServeMux to service third party caveats.

The check function is used to check whether a client making the given request should be allowed a discharge for the given caveat. If it does not return an error, the caveat will be discharged, with any returned caveats also added to the discharge macaroon.

The name space served by DischargeHandler is as follows. All parameters can be provided either as URL attributes or form attributes. The result is always formatted as a JSON object.

POST /discharge

params:
	id: id of macaroon to discharge
	location: location of original macaroon (optional (?))
result:
	{
		Macaroon: macaroon in json format
		Error: string
	}

POST /create

params:
	condition: caveat condition to discharge
	rootkey: root key of discharge caveat
result:
	{
		CaveatID: string
		Error: string
	}

GET /publickey

result:
	public key of service
	expiry time of key

func (*Service) AddPublicKeyForLocation

func (svc *Service) AddPublicKeyForLocation(loc string, prefix bool, publicKey *[32]byte)

AddPublicKeyForLocation specifies that third party caveats for the given location will be encrypted with the given public key. If prefix is true, any locations with loc as a prefix will be also associated with the given key. The longest prefix match will be chosen. TODO(rog) perhaps string might be a better representation of public keys?

func (*Service) NewRequest

func (svc *Service) NewRequest(httpReq *http.Request, checker bakery.FirstPartyChecker) *bakery.Request

NewRequest returns a new request, converting cookies from the HTTP request into macaroons in the bakery request when they're found. Mmm.