sping

README

Secure Ping

This is a simple example of setting up secured communication with gRPC.

For more, see the write up at “Secure gRPC with TLS/SSL”.

NOTE: the certificates in this repository are for example only. They were generated on the command-line and only work for the localhost. If you actually wanted to set up this ping across a network, you'd have to generate your own certificates. Here are two good resources for this:

• Golang TLS examples
• certstrap

Demo Quick Start

First clone the repository (using go get would work, but the demo only works from the repository working directory) and install the various dependencies:

$ git clone https://github.com/bbengfort/sping.git
$ cd sping
$ go get ./...

Now that you're in the working directory, you'll have to create two processes (the server and the client). I recommend opening up a second terminal tab. In the first tab:

$ go run cmd/sping serve

This will run the server on the localhost with the default port and options. If you'd like to see all the options for either of the commands just use --help. Then in the second terminal:

$ go run cmd/sping echo localhost

You should see the result in both the server and client windows. You have just conducted a secure Echo RPC request between client and server using mutual authentication with TLS.

The client will automatically shutdown after 8 messages. Shut the server down with an INTERRUPT (CTRL+C).

Documentation

Overview

Package sping is a simple example of a client and server that conduct communication using gRPC in a secure fashion with SSL/TLS.

Index

• Constants
• func Insecure(addr string) (*grpc.ClientConn, error)
• func MutualTLS(addr string) (*grpc.ClientConn, error)
• func Output(format string, args ...interface{})
• func TLS(addr string) (*grpc.ClientConn, error)
• type Dailer
• type PingClient
  • func NewClient(dailer Dailer, address, name string, delay int64, limit uint) *PingClient
  • func (c *PingClient) Next() *pb.Ping
  • func (c *PingClient) Ping(addr string) (*pb.Pong, error)
  • func (c *PingClient) PingMutualTLS(addr string) (*pb.Pong, error)
  • func (c *PingClient) Run() error
• type PingServer
  • func NewServer() *PingServer
  • func (s *PingServer) Echo(ctx context.Context, ping *pb.Ping) (*pb.Pong, error)
  • func (s *PingServer) Serve(port uint) error
  • func (s *PingServer) ServeInsecure(port uint) error
  • func (s *PingServer) ServeMutualTLS(port uint) error
  • func (s *PingServer) ServeTLS(port uint) error
  • func (s *PingServer) Shutdown()

Constants

const (
	ClientCert = "cert/client.crt"
	ClientKey  = "cert/client.key"
)

Client Certificates

const (
	ServerCert = "cert/server.crt"
	ServerKey  = "cert/server.key"
	ServerName = "localhost"
	ExampleCA  = "cert/sping_example.crt"
)

Server Certificates

Functions

func Insecure

func Insecure(addr string) (*grpc.ClientConn, error)

PingInsecure is a helper method for no server-side encryption. It is mostly here for benchmarking.

func MutualTLS

func MutualTLS(addr string) (*grpc.ClientConn, error)

func Output

func Output(format string, args ...interface{})

Output a message if logmsgs is true.

func TLS

func TLS(addr string) (*grpc.ClientConn, error)

PingTLS is a helper method for server-side encryption that does not expect client authentication or credentials. It is mostly here for benchmarking.

Types

type Dailer

type Dailer func(target string) (*grpc.ClientConn, error)

type PingClient

type PingClient struct {
	Name  string
	Delay time.Duration
	Limit uint

	Connection *grpc.ClientConn
	pb.SecurePingClient
	// contains filtered or unexported fields
}

PingClient sends echo requests to the ping server on demand.

func NewClient

func NewClient(dailer Dailer, address, name string, delay int64, limit uint) *PingClient

NewClient returns a ping client with the specified options.

func (*PingClient) Next

func (c *PingClient) Next() *pb.Ping

Next returns the next ping request in the sequence

func (*PingClient) Ping

func (c *PingClient) Ping(addr string) (*pb.Pong, error)

Ping sends an Ping request to the server and awaits a response. Right now we create a new connection for every single ping.

func (*PingClient) PingMutualTLS

func (c *PingClient) PingMutualTLS(addr string) (*pb.Pong, error)

PingMutualTLS is an alias for Ping. It is mostly here for benchmarking.

func (*PingClient) Run

func (c *PingClient) Run() error

Run the ping client against the server.

type PingServer

type PingServer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

PingServer responds to Ping requests and tracks the number of messages sent per sender (responding with the correct sequence).

func NewServer

func NewServer() *PingServer

NewServer returns a ping server with specified options.

func (*PingServer) Echo

func (s *PingServer) Echo(ctx context.Context, ping *pb.Ping) (*pb.Pong, error)

Echo implements echo.SecurePing

func (*PingServer) Serve

func (s *PingServer) Serve(port uint) error

Serve ping requests from gRPC messages

func (*PingServer) ServeInsecure

func (s *PingServer) ServeInsecure(port uint) error

ServeInsecure is a helper method for no server-side encryption. It is mostly here for benchmarking.

func (*PingServer) ServeMutualTLS

func (s *PingServer) ServeMutualTLS(port uint) error

ServeMutualTLS is an alias for Serve. It is mostly here for benchmarking.

func (*PingServer) ServeTLS

func (s *PingServer) ServeTLS(port uint) error

ServeTLS is a helper method for server-side encryption that does not expect client authentication or credentials. It is mostly here for benchmarking.

func (*PingServer) Shutdown

func (s *PingServer) Shutdown()

Shutdown the grpc server instance