Communication (transport) security

Kubling uses a transport-independent securing mechanism, which works at communication level using SSL (or TLS). The client gRPC, native and PostgreSQL compatibility transports can each use the same standard TLS configuration model while keeping independent certificates and network policies.

When a secure connection is established, traffic exchanged between clients and the Kubling instance is encrypted with TLS 1.3. Clients must still validate the server certificate and protect their session credentials.

Enabling security

In each transport configuration, you can enable security by activating the transports.[protocol].secure: true. However, when enabled, also a server certificate must be specified, otherwise the TLS configuration will be ignored.

Generate Certificate

kdv CLI provides a convenient command to generate certificates, that can be directly read by the engine, without having to convert formats.

kdv cert create -s /certs/server.ks -c /certs/client.ks -x myserverpass -p myclientpass -o

Command generates both client and server certificates. Client certificate is only required in case the client is configured to validate the server certificate.

When no password is provided for either the client or server certificates, kdv will automatically generate them and display the passwords in the console. Make sure to copy and store these passwords securely.

Configure transports

For security reasons, you may want to use a different certificate per transport, reason why their configurations are independent, as follows:

transports:
  nativeProtocol:
    bindAddress: "0.0.0.0"
    portNumber: 35482
    secure: true
    sslConfig:
      storeFilePath: "/certs/server-native.ks"
      storePassword: "123abc"
  pgProtocol:
    bindAddress: "0.0.0.0"
    portNumber: 35432
    secure: true
    sslConfig:
      storeFilePath: "/certs/server-pg.ks"
      storePassword: "456def"
  grpc:
    bindAddress: "0.0.0.0"
    portNumber: 50051
    secure: true
    sslConfig:
      storeFilePath: "/certs/server-grpc.ks"
      storePassword: "789ghi"

Configure IP Whitelist and Blacklist v25.4+

Kubling supports IP-level whitelisting and blacklisting for inbound connections at the transport layer. This filtering occurs before messages enter the transport pipeline (but after the TLS negotiation, if configured), allowing Kubling to reject unwanted traffic as early and efficiently as possible.

Filters are applied per protocol (grpc, nativeProtocol, pgProtocol) and are defined using CIDR blocks, which can match single IPs or entire subnets.

Filtering is evaluated immediately when a remote client attempts to connect. If the IP is not allowed (or explicitly blocked), the connection is terminated without processing any payload.

Example

transports:
  nativeProtocol:
    ...
    ipFilter:
      type: WHITELIST
      cidrBlocks:
        - 127.0.0.1                  # localhost only
        - 192.168.1.15               # single IP
        - 10.10.0.0/16               # entire subnet
        - 172.20.30.0/24             # class C block
 
  pgProtocol:
    ...
    ipFilter:
      type: BLACKLIST
      cidrBlocks:
        - 192.168.1.1                # explicitly deny this IP
        - 203.0.113.0/24             # deny this public test block
 
  grpc:
    ...
    ipFilter:
      type: WHITELIST
      cidrBlocks:
        - 10.20.0.0/16               # application network

Notes

• type must be either WHITELIST or BLACKLIST (case-sensitive).
• CIDR blocks can represent:
  • A single IP (e.g. 192.168.1.15)
  • A range/subnet (e.g. 10.10.0.0/16)
• Each protocol can define independent filters.