grpcauth

README

GRPC Authorization Layer

For a complete example, see the example/ directory and setup.sh script.

Overview

This package provides WAVE-based authentication + authorization for GRPC services. All GRPC connections happen over TLS (currently using self-signed certs) Services and clients possess WAVE entities. Services provide a proof during the handshake that they are authorized to provide a GRPC service on a given namespace. Clients provide a proof during the handshake that they are authorized to call that GRPC service on that namespace.

This is indicated with the serve_grpc and call_grpc permissions on the XBOS GyC5wUUGKON6uC4gxuH6TpzU9vvuKHGeJa1jUr4G-j_NbA== permission set.

# grant to server to serve all methods
wv rtgrant --attester namespace.ent \
           --subject service.ent \
           GyC5wUUGKON6uC4gxuH6TpzU9vvuKHGeJa1jUr4G-j_NbA==:serve_grpc@namespace.ent/\
           <package name>/<service name>/*

# grant to client to call all methods
wv rtgrant --attester namespace.ent \
           --subject client.ent \
           GyC5wUUGKON6uC4gxuH6TpzU9vvuKHGeJa1jUr4G-j_NbA==:call_grpc@namespace.ent/\
           <package name>/<service name>/*

The implementation is adapted from https://github.com/immesys/wavemq

TODO

• use hash of WAVE entity to bootstrap TLS connection
  • avoids self-signed TLS, which we have now
• additional app-specific metadata in WAVE proofs
  • time bound on historical timeseries retrieval
  • limiting which streams can be returned
• Develop Python bindings:
  • start here ?
• build proof automatically (easy)
• client provides proof of authorization
  • am I allowed to call this method?

Usage

Server (simplified):

import (
    "github.com/gtfierro/xboswave/grpcauth"
)

func main() {

    // setup WAVE perspective and create credentials object
    server_perspective := loadPerspective("service.ent")
    serverwavecreds, _ := grpcauth.NewServerCredentials(server_perspective, "localhost:410")

    // register generic GRPC server with service
    xbospb.RegisterTestServer(grpcServer, testserver{})

    // inject a description of the service into the credentials object
    serverwavecreds.AddServiceInfo(grpcServer)

    // add the service authorization proof (see below)
    serverwavecreds.AddGRPCProofFile("serviceproof.pem")

    // serve GRPC
    grpcServer.Serve(l)
}

Client (simplified):

import (
    "github.com/gtfierro/xboswave/grpcauth"
)

func main() {

    // setup WAVE perspective and create CLIENT credentials object
    client_perspective := loadPerspective("client.ent")

    // namespace, GRPC service descriptor
    clientcred, err := grpcauth.NewClientCredentials(client_perspective, "localhost:410", "GyBHxjkpzmGxXk9qgJW6AJHCXleNifvhgusCs0v1MLFWJg==", "xbospb/Test/*")
    if err != nil {
        log.Fatal(err)
    }

    // add service authorization proof
	clientcred.AddGRPCProofFile("clientproof.pem")

    // add credentials object to normal GRPC dial
    clientconn, err := grpc.Dial("localhost:7373", grpc.WithTransportCredentials(clientcred), grpc.FailOnNonTempDialError(true), grpc.WithBlock(), grpc.WithTimeout(30*time.Second))
    if err != nil {
        log.Fatal(err)
    }
    testclient := xbospb.NewTestClient(clientconn)
}

Documentation

Index

• Constants
• type ClientCredentials
  • func NewClientCredentials(perspective *pb.Perspective, agent string, namespace string, ...) (*ClientCredentials, error)
  • func (cc *ClientCredentials) AddGRPCProofFile(filename string) (ns string, proof []byte, err error)
  • func (cc *ClientCredentials) ClientHandshake(ctx context.Context, authority string, rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)
  • func (cc *ClientCredentials) Clone() credentials.TransportCredentials
  • func (cc *ClientCredentials) GeneratePeerHeader() ([]byte, error)
  • func (cc *ClientCredentials) Info() credentials.ProtocolInfo
  • func (cc *ClientCredentials) OverrideServerName(name string) error
  • func (cc *ClientCredentials) ReadPeerHeader(conn io.Reader) (serverHeader, error)
  • func (cc *ClientCredentials) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error)
  • func (cc *ClientCredentials) VerifyServerHandshake(nsString string, hdr serverHeader, cert []byte) error
• type WaveCredentials
  • func NewServerCredentials(perspective *pb.Perspective, agent string) (*WaveCredentials, error)
  • func (wc *WaveCredentials) AddGRPCProofFile(filename string) (ns string, proof []byte, err error)
  • func (wc *WaveCredentials) AddServiceInfo(server *grpc.Server)
  • func (wc *WaveCredentials) ClientHandshake(ctx context.Context, authority string, rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)
  • func (wc *WaveCredentials) Clone() credentials.TransportCredentials
  • func (wc *WaveCredentials) GeneratePeerHeader(ns []byte, cert []byte) ([]byte, error)
  • func (wc *WaveCredentials) Info() credentials.ProtocolInfo
  • func (wc *WaveCredentials) OverrideServerName(name string) error
  • func (wc *WaveCredentials) ReadPeerHeader(conn io.Reader) (clientHeader, error)
  • func (wc *WaveCredentials) ServerHandshake(rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)
  • func (wc *WaveCredentials) ServerTransportCredentials() credentials.TransportCredentials
  • func (wc *WaveCredentials) VerifyClientHandshake(nsString string, hdr clientHeader) error

Constants

const GRPCCallPermission = "call_grpc"

const GRPCServePermission = "serve_grpc"

const XBOSPermissionSet = "" /* 136-byte string literal not displayed */

const XBOSPermissionSet_b64 = "GyC5wUUGKON6uC4gxuH6TpzU9vvuKHGeJa1jUr4G-j_NbA=="

Types

type ClientCredentials

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

func NewClientCredentials

func NewClientCredentials(perspective *pb.Perspective, agent string, namespace string, grpcservice string) (*ClientCredentials, error)

func (*ClientCredentials) AddGRPCProofFile

func (cc *ClientCredentials) AddGRPCProofFile(filename string) (ns string, proof []byte, err error)

func (*ClientCredentials) ClientHandshake

func (cc *ClientCredentials) ClientHandshake(ctx context.Context, authority string, rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)

func (*ClientCredentials) Clone

func (cc *ClientCredentials) Clone() credentials.TransportCredentials

func (*ClientCredentials) GeneratePeerHeader

func (cc *ClientCredentials) GeneratePeerHeader() ([]byte, error)

client hash signature length signature (over proof) proof length proof

func (*ClientCredentials) Info

func (cc *ClientCredentials) Info() credentials.ProtocolInfo

func (*ClientCredentials) OverrideServerName

func (cc *ClientCredentials) OverrideServerName(name string) error

func (*ClientCredentials) ReadPeerHeader

func (cc *ClientCredentials) ReadPeerHeader(conn io.Reader) (serverHeader, error)

func (*ClientCredentials) ServerHandshake

func (cc *ClientCredentials) ServerHandshake(net.Conn) (net.Conn, credentials.AuthInfo, error)

func (*ClientCredentials) VerifyServerHandshake

func (cc *ClientCredentials) VerifyServerHandshake(nsString string, hdr serverHeader, cert []byte) error

type WaveCredentials

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

func NewServerCredentials

func NewServerCredentials(perspective *pb.Perspective, agent string) (*WaveCredentials, error)

func (*WaveCredentials) AddGRPCProofFile

func (wc *WaveCredentials) AddGRPCProofFile(filename string) (ns string, proof []byte, err error)

func (*WaveCredentials) AddServiceInfo

func (wc *WaveCredentials) AddServiceInfo(server *grpc.Server)

func (*WaveCredentials) ClientHandshake

func (wc *WaveCredentials) ClientHandshake(ctx context.Context, authority string, rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)

func (*WaveCredentials) Clone

func (wc *WaveCredentials) Clone() credentials.TransportCredentials

func (*WaveCredentials) GeneratePeerHeader

func (wc *WaveCredentials) GeneratePeerHeader(ns []byte, cert []byte) ([]byte, error)

A 34 byte multihash

func (*WaveCredentials) Info

func (wc *WaveCredentials) Info() credentials.ProtocolInfo

func (*WaveCredentials) OverrideServerName

func (wc *WaveCredentials) OverrideServerName(name string) error

func (*WaveCredentials) ReadPeerHeader

func (wc *WaveCredentials) ReadPeerHeader(conn io.Reader) (clientHeader, error)

func (*WaveCredentials) ServerHandshake

func (wc *WaveCredentials) ServerHandshake(rawConn net.Conn) (net.Conn, credentials.AuthInfo, error)

func (*WaveCredentials) ServerTransportCredentials

func (wc *WaveCredentials) ServerTransportCredentials() credentials.TransportCredentials

func (*WaveCredentials) VerifyClientHandshake

func (wc *WaveCredentials) VerifyClientHandshake(nsString string, hdr clientHeader) error