README
¶
goe2ee
End-to-end encryption (E2EE) library in Go language. It will use Diffie–Hellman key exchange to define the shared secret.
The library is flexible on how the client retrieves the public key. It will make available out-of-the-box the following strategies:
-
Use the DNSKEY resource record of the target domain name. The resource record should be trusted following the DNSSEC chain of trust. To make sure the resolution between the resolver and the recursive DNS is also safe the library will use DNS over HTTPS.
-
Rely on an x509 certificate with validating against a certification authority. The certificate can be retrieved from an HTTPS connection with the target domain.
-
Directly retrieve the key from the server using the protocol. This is not safe, as it can be vulnerable to man-in-the-middle attacks.
-
Manually provided.
Other benefits of this protocol:
-
Use the same shared secret between connections of the same host. This saves time in the handshake process. The library already provides a client connection pool to better use this feature.
-
Allow TCP or UDP connections. When working with small packages and don't mind about delivery guarantees, you could use UDP, which has less network overhead.
-
Optionally bypass server response. This special flag allows the client to fire and forget, saving a network overhead.
Details about the protocol can be found here.
Documentation
¶
Overview ¶
Package goe2ee provides the server and the client for the GoE2EE protocol.
Index ¶
- func ClientWithExpectReply(expectReply bool) func(*ClientOptions)
- func ClientWithKeepAlive(keepAlive bool) func(*ClientOptions)
- func ClientWithKeyFetcher(keyFetcher key.ClientFetcher) func(*ClientOptions)
- func ClientWithReadTimeout(timeout time.Duration) func(*ClientOptions)
- func ClientWithWriteTimeout(timeout time.Duration) func(*ClientOptions)
- func ServerWithKeyManager(keyManager key.ServerManager) func(*ServerOptions)
- func ServerWithLogger(logger *log.Logger) func(*ServerOptions)
- func ServerWithReadTimeout(timeout time.Duration) func(*ServerOptions)
- func ServerWithSecretManager(secretManager secret.Manager) func(*ServerOptions)
- func ServerWithWriteTimeout(timeout time.Duration) func(*ServerOptions)
- type Client
- func (c *Client) Close() error
- func (c *Client) LocalAddr() net.Addr
- func (c *Client) Read(p []byte) (int, error)
- func (c *Client) RemoteAddr() net.Addr
- func (c *Client) SetDeadline(t time.Time) error
- func (c *Client) SetReadDeadline(t time.Time) error
- func (c *Client) SetWriteDeadline(t time.Time) error
- func (c *Client) Write(p []byte) (n int, err error)
- type ClientOptions
- type ClientPool
- type Server
- type ServerHandler
- type ServerHandlerFunc
- type ServerOptions
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClientWithExpectReply ¶
func ClientWithExpectReply(expectReply bool) func(*ClientOptions)
ClientWithExpectReply sets the expect-reply option for the client. By default it is true.
func ClientWithKeepAlive ¶
func ClientWithKeepAlive(keepAlive bool) func(*ClientOptions)
ClientWithKeepAlive sets the keep-alive option for the client. By default it is false.
func ClientWithKeyFetcher ¶
func ClientWithKeyFetcher(keyFetcher key.ClientFetcher) func(*ClientOptions)
ClientWithKeyFetcher sets the strategy used to retrieve the server's public key. By default it will use DNS over HTTPS to retrieve the DNSKEY resource record of the host using Google's provider.
func ClientWithReadTimeout ¶
func ClientWithReadTimeout(timeout time.Duration) func(*ClientOptions)
ClientWithReadTimeout sets the read timeout for the client. By default it is 5 seconds.
func ClientWithWriteTimeout ¶
func ClientWithWriteTimeout(timeout time.Duration) func(*ClientOptions)
ClientWithWriteTimeout sets the write timeout for the client. By default it is 5 seconds.
func ServerWithKeyManager ¶
func ServerWithKeyManager(keyManager key.ServerManager) func(*ServerOptions)
ServerWithKeyManager sets the key manager for the server. By default it will use on-the-fly key generation that is not recommended for production environment.
func ServerWithLogger ¶
func ServerWithLogger(logger *log.Logger) func(*ServerOptions)
ServerWithLogger sets the logger used when handling errors. By default it will use the standard logger with "goe2eee" prefix.
func ServerWithReadTimeout ¶
func ServerWithReadTimeout(timeout time.Duration) func(*ServerOptions)
ServerWithReadTimeout sets the read timeout for the server. By default it is 60 seconds.
func ServerWithSecretManager ¶
func ServerWithSecretManager(secretManager secret.Manager) func(*ServerOptions)
ServerWithSecretManager sets the secret manager for the server. By default it will use an in-memory manager.
func ServerWithWriteTimeout ¶
func ServerWithWriteTimeout(timeout time.Duration) func(*ServerOptions)
ServerWithWriteTimeout sets the write timeout for the server. By default it is 5 seconds.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the client-side of the E2EE protocol. It implements the net.Conn interface to be used as a regular connection.
func DialTCP ¶
func DialTCP(hostport string, optFunc ...func(*ClientOptions)) (*Client, error)
DialTCP connects to the server using TCP. The hostport follows the pattern "host:port", the host can be a domain name or an IP address.
func DialUDP ¶
func DialUDP(hostport string, optFunc ...func(*ClientOptions)) (*Client, error)
DialUDP connects to the server using UDP. The hostport follows the pattern "host:port", the host can be a domain name or an IP address.
func (*Client) RemoteAddr ¶
RemoteAddr returns the remote network address, if known.
func (*Client) SetDeadline ¶
SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
A deadline is an absolute time after which I/O operations fail instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Read or Write or to other I/O methods will return an error that wraps os.ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded). The error's Timeout method will return true, but note that there are other possible errors for which the Timeout method will return true even if the deadline has not been exceeded.
An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.
A zero value for t means I/O operations will not time out.
func (*Client) SetReadDeadline ¶
SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.
func (*Client) SetWriteDeadline ¶
SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.
type ClientOptions ¶
type ClientOptions struct {
// contains filtered or unexported fields
}
ClientOptions contains options for the client. You cannot modify the properties directly, instead use auxiliary functions when connecting to the server.
type ClientPool ¶
type ClientPool struct {
// contains filtered or unexported fields
}
ClientPool is a pool of clients. It is useful when you need to connect to the same host multiple times.
Example ¶
package main
import (
"log"
"github.com/rafaeljusto/goe2ee"
"github.com/rafaeljusto/goe2ee/key"
)
func main() {
hostport := "example.com:123"
pool := goe2ee.NewClientPool(hostport, 10, 10,
goe2ee.ClientWithKeyFetcher(key.NewClientFetcherProtocol("tcp", hostport)),
)
defer func() {
if err := pool.Close(); err != nil {
log.Println(err)
}
}()
client, err := pool.Get()
if err != nil {
log.Println(err)
return
}
defer func() {
if err := client.Close(); err != nil {
log.Println(err)
}
}()
// do something with the client
}
Output:
func NewClientPool ¶
func NewClientPool( hostport string, maxIdleClients int64, maxOpenClients int64, optFunc ...func(*ClientOptions), ) ClientPool
NewClientPool creates a new client pool.
func (*ClientPool) Close ¶
func (cp *ClientPool) Close() error
Close closes all the clients in the pool.
func (*ClientPool) Get ¶
func (cp *ClientPool) Get() (*Client, error)
Get retrieves a client from the pool. If there is no idle client available, a new one will be created. If the maximum number of clients is reached, it will wait until a client is available.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the server-side of the E2EE protocol.
func NewServer ¶
func NewServer(handler ServerHandler, optFuncs ...func(*ServerOptions)) *Server
NewServer returns a new server. The handler is called whenever a new message arrives, so it should handle a single round-trip.
type ServerHandler ¶
ServerHandler is the interface that wraps the Handle method.
type ServerHandlerFunc ¶
ServerHandlerFunc is an adapter to allow the use of ordinary functions as a server handler.
type ServerOptions ¶
type ServerOptions struct {
// contains filtered or unexported fields
}
ServerOptions contains options for the server. You cannot modify the properties directly, instead use auxiliary functions when connecting to the server.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
internal
|
|
|
client
Package client provides client utilities.
|
Package client provides client utilities. |
|
dns/dnssec
Package dnssec implements DNSSEC related functions.
|
Package dnssec implements DNSSEC related functions. |
|
dns/doh
Package doh provides a DNS-over-HTTPS client.
|
Package doh provides a DNS-over-HTTPS client. |
|
net
Package net provides a net.Conn implementation for UDP packets.
|
Package net provides a net.Conn implementation for UDP packets. |
|
server
Package server provides the server handlers for the protocol version 1.
|
Package server provides the server handlers for the protocol version 1. |
|
Package key provides the key management for the server and the client.
|
Package key provides the key management for the server and the client. |
|
Package protocol provides the protocol used by the server and the client.
|
Package protocol provides the protocol used by the server and the client. |
|
Package secret provides a simple interface to store and load secrets.
|
Package secret provides a simple interface to store and load secrets. |