README
¶
kbtls
Key-Based TLS - Mutually Trusted TLS Connections Based on a Pre-Shared Connection Key
This library allows to create mutually trusted client and server certificates based on a pre-shared connection key. This is possible because the pre-shared connection key can be used on both sides to derive the same CA certificate which is then used to sign the server and client certificates that are generated on the spot.
Warning: This library is not meant for production use. It was developed to be used in offensive security tools to conveniently provide an encrypted connection ad-hoc without certificate management. While we are unaware of any security risks with the library's approach, it uses TLS in an unconventional way which may introduce subtle vulnerabilities. Please contact us if you are aware of any security considerations regarding this library.
Usage:
The following example shows how a connection key can be generated in order to generate a listener:
key, err := kbtls.GenerateConnectionKey()
// error handling
fmt.Println(key) // tvyFtKR0Y2IY/sN5EbxYscr15fGxa8Mx2NeelZUCpn0
listener, err := kbtls.Listen("tcp", "localhost:8443", key.String())
// error handling
In most cases, one endpoint generates and outputs the key like this. The user then passes the generated key to the other endpoint where it can be used as follows:
key := "tvyFtKR0Y2IY/sN5EbxYscr15fGxa8Mx2NeelZUCpn0"
conn, err := kbtls.Dial("tcp", "localhost:8443", key)
// error handling
A full server and client example can be found here. For custom listeners or for custom TLS configuration lower-level functions are provided, as demonstrated here.
Documentation
¶
Overview ¶
Package kbtls implements key-based TLS.
Index ¶
- func ClientTLSConfig(key ConnectionKey) (*tls.Config, error)
- func ClientTLSConfigForClientName(key ConnectionKey, clientName string) (*tls.Config, error)
- func Dial(network string, address string, connectionKey string) (net.Conn, error)
- func DialContext(ctx context.Context, network string, address string, connectionKey string) (net.Conn, error)
- func GenerateCA(key ConnectionKey) (caCert *x509.Certificate, caKey crypto.PrivateKey, err error)
- func Listen(network string, address, connectionKey string) (net.Listener, error)
- func ServerTLSConfig(key ConnectionKey) (*tls.Config, error)
- func ServerTLSConfigForServerName(key ConnectionKey, hostname string) (*tls.Config, error)
- type ConnectionKey
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClientTLSConfig ¶
func ClientTLSConfig(key ConnectionKey) (*tls.Config, error)
ClientTLSConfig generates a TLS client config based on the connection key. The client certificate's DNS name will be the connection keys's public key which is also set as ServerName in the returned *tls.Config.
func ClientTLSConfigForClientName ¶
func ClientTLSConfigForClientName(key ConnectionKey, clientName string) (*tls.Config, error)
ClientTLSConfigForClientName generates a TLS client config for an arbitrary client DNS name. Note that the ServerName attribute is still set to the connection key's public key.
func DialContext ¶ added in v0.1.2
func DialContext(ctx context.Context, network string, address string, connectionKey string) (net.Conn, error)
DialContext works like tls.Dial with a TLS config based on the provided connection key and a context.
func GenerateCA ¶
func GenerateCA(key ConnectionKey) (caCert *x509.Certificate, caKey crypto.PrivateKey, err error)
GenerateCA generates a deterministic CA certificate that never expires. Identical connection keys will always result in identical ceritificates.
func ServerTLSConfig ¶
func ServerTLSConfig(key ConnectionKey) (*tls.Config, error)
ServerTLSConfig generates a TLS server config based on the connection key. The server certificate will use the connection keys public key as server DNS name.
func ServerTLSConfigForServerName ¶
func ServerTLSConfigForServerName(key ConnectionKey, hostname string) (*tls.Config, error)
ServerTLSConfigForServerName generates a TLS server config based on the connection key with the provided hostname in the server certificate's DNS name section.
Types ¶
type ConnectionKey ¶
ConnectionKey is a seed for an ed25519 private key with which the fundamental CA certificate is signed. The all-zero connection key is considered invalid in order to avoid accidentally using an uninitialized key. Due to the fixed size, connection keys are comparable.
func GenerateConnectionKey ¶
func GenerateConnectionKey() (ConnectionKey, error)
GenerateConnectionKey generates a new connection key.
func ParseConnectionKey ¶
func ParseConnectionKey(key string) (ConnectionKey, error)
ParseConnectionKey parses a base64-encoded connection key.
func (ConnectionKey) PublicKey ¶
func (key ConnectionKey) PublicKey() string
PublicKey returns the base64-encoded ed25519 public key that corresponds to the connection key.
func (ConnectionKey) String ¶
func (key ConnectionKey) String() string
String returns the connection key as a base64-encoded string.
func (ConnectionKey) Valid ¶
func (key ConnectionKey) Valid() bool
Valid returns falls if every byte in the connection key is zero.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
custom
Package main demonstrates how the fine-grained API can be used to customize the connection details.
|
Package main demonstrates how the fine-grained API can be used to customize the connection details. |
|
simple
Package main implements a simple kbtls client and server.
|
Package main implements a simple kbtls client and server. |