TLS and DTLS

MapsMessaging supports TLS (over TCP) and DTLS (over UDP). Both transports share the same certificate / trust / CRL configuration via SslConfigDTO, so you only have to learn this pain once.

• TLS endpoint type: ssl
• DTLS endpoint type: dtls

---

Where this configuration is used

SslConfigDTO is referenced by both the TLS and DTLS endpoint DTOs.

• TLS endpoint (type: ssl) uses SslConfigDTO for server certificate + trust decisions
• DTLS endpoint (type: dtls) uses the same SslConfigDTO for certificate + trust decisions

Note: the property name that holds the SslConfigDTO object depends on the endpoint DTO (for example ssl, tls, or sslConfig). Use whatever your generated schema shows for the TLS/DTLS endpoint, and place the object there.

---

Common endpoint fields

Both TLS and DTLS endpoints also inherit common endpoint settings from EndPointConfigDTO.

Typical shared fields include:

• discoverable
• selectorThreadCount
• serverReadBufferSize
• serverWriteBufferSize
• proxyProtocolMode
• allowedProxyHosts
• connectionTimeout

(See the TCP/UDP docs for full descriptions of these inherited fields.)

---

SSL/TLS Configuration (SslConfigDTO)

Fields

Field	Description
clientCertificateRequired	If true, clients must present a valid client certificate
clientCertificateWanted	If true, client certificates are requested but optional (ignored when clientCertificateRequired=true)
crlUrl	CRL URL (if unset, CRL checking is disabled)
crlInterval	CRL refresh interval in milliseconds
context	SSL context identifier / protocol profile (pattern: TLS, TLSv1.2, TLSv1.3)
keyStore	Server certificate + private key (KeyStoreConfigDTO)
trustStore	Trusted Certificate Authorities (KeyStoreConfigDTO)

---

Key Store Configuration (KeyStoreConfigDTO)

Used for both keyStore and trustStore.

Fields

Field	Description
alias	Alias in the keystore (optional)
type	Keystore type (JKS, PKCS11, PKCS12, JCEKS, BKS, UBER, BCFKS)
providerName	Security provider name (optional, e.g. SunJSSE, BC)
managerFactory	KeyManagerFactory algorithm (optional; commonly SunX509, PKIX)
path	Keystore file path (not required for PKCS11)
passphrase	Keystore passphrase (optional depending on type/provider)
provider	Provider identifier (optional)

---

Example: TLS over TCP

transport:
  tlsEndpoint:
    type: ssl
    port: 8883

    # EndPointConfigDTO (common fields)
    discoverable: false
    selectorThreadCount: 2
    proxyProtocolMode: DISABLED
    allowedProxyHosts: ""
    connectionTimeout: 5000

    # SslConfigDTO (the property name here is an example)
    ssl:
      context: TLSv1.3
      clientCertificateRequired: false
      clientCertificateWanted: false

      keyStore:
        type: PKCS12
        path: /etc/maps/certs/server.p12
        passphrase: changeit
        alias: server

      trustStore:
        type: PKCS12
        path: /etc/maps/certs/trust.p12
        passphrase: changeit

      crlUrl: http://example.com/crl.pem
      crlInterval: 3600000

---

Example: DTLS over UDP

transport:
  dtlsEndpoint:
    type: dtls
    port: 5684

    # EndPointConfigDTO (common fields)
    discoverable: false
    selectorThreadCount: 2
    proxyProtocolMode: DISABLED
    allowedProxyHosts: ""
    connectionTimeout: 5000

    # SslConfigDTO (the property name here is an example)
    ssl:
      context: TLSv1.2
      clientCertificateRequired: false
      clientCertificateWanted: false

      keyStore:
        type: PKCS12
        path: /etc/maps/certs/dtls-server.p12
        passphrase: changeit
        alias: server

      trustStore:
        type: PKCS12
        path: /etc/maps/certs/trust.p12
        passphrase: changeit

---

Notes

• clientCertificateRequired=true is mutual TLS (mTLS). If you enable this, make sure your trustStore is correctly configured.
• crlUrl + crlInterval enable periodic CRL refresh. If crlUrl is unset, CRL checks are disabled.
• context is constrained to TLS, TLSv1.2, or TLSv1.3 by schema pattern.
• If you’re running behind a proxy/load balancer, proxyProtocolMode and allowedProxyHosts can be used to control PROXY header handling.