TLS Security

Syntra defaults to unencrypted connections on 127.0.0.1, which is safe because traffic never leaves the host. The moment you open Syntra to other machines — or run it on a shared server — you should turn TLS on. TLS encrypts the entire session (credentials, queries, result data) and lets clients verify they’re talking to the server they expect.

Generate a certificate

Option 1 — self-signed (internal use)

Good for internal networks where the client trusts the server by IP or hostname. Generate with OpenSSL:

openssl req -new -x509 -days 3650 -nodes \
  -out syntra-server.crt \
  -keyout syntra-server.key \
  -subj "/CN=<hostname-or-ip-clients-will-use>"

Replace <hostname-or-ip-clients-will-use> with exactly what you’ll type on the client side (e.g. syntra.corp.local or 10.0.0.42). If the CN doesn’t match, SSLMode=verify-full will reject the connection.

Option 2 — CA-signed (production)

Use a certificate issued by a trusted CA (Let’s Encrypt, your organisation’s internal CA, etc.). The CA chain needs to be available to clients; for machine-local CAs, install the CA’s root certificate into the client’s trust store.

Configure Syntra

Edit C:\ProgramData\SyntraODBC\config.toml:

[server]
host = "0.0.0.0"                  # if accepting non-local clients
port = 5433
tls_cert = "C:\\ProgramData\\SyntraODBC\\certs\\syntra-server.crt"
tls_key  = "C:\\ProgramData\\SyntraODBC\\certs\\syntra-server.key"

Restart the Syntra service after editing.

Lock the private key down so only the service account can read it:

icacls "C:\ProgramData\SyntraODBC\certs\syntra-server.key" /inheritance:r /grant:r "NT SERVICE\SyntraODBC:(R)"

Configure the client

All Syntra clients go through the bundled ODBC driver. Append SSLMode=require (or stricter — see the table below) to your connection string:

DSN=Syntra QuickBooks;SSLMode=require;

Driver-direct:

Driver={Syntra ODBC - QuickBooks ODBC};Server=<host>;Port=5433;Database=qbconnect;Uid=qbconnect;Pwd=<password>;SSLMode=require;

.NET / VB.NET

Dim cs As String = "DSN=Syntra QuickBooks;SSLMode=require;"
Using conn As New System.Data.Odbc.OdbcConnection(cs)
    conn.Open()
End Using

Python (pyodbc)

import pyodbc

conn = pyodbc.connect(
    "Driver={Syntra ODBC - QuickBooks ODBC};"
    "Server=syntra.corp.local;Port=5433;"
    "Database=qbconnect;Uid=qbconnect;Pwd=<password>;"
    "SSLMode=require;"
)

Node.js (odbc)

const odbc = require('odbc');
const conn = await odbc.connect(
  "Driver={Syntra ODBC - QuickBooks ODBC};" +
  "Server=syntra.corp.local;Port=5433;Database=qbconnect;" +
  "Uid=qbconnect;Pwd=<password>;SSLMode=require;"
);

Excel / Power BI / Tableau / Crystal Reports

When editing the DSN in ODBC Data Source Administrator (odbcad32), tick the Use SSL Mode option and pick require (or higher). The tick-box wording varies by driver UI version but the option is always on the “SSL” or “Data Source” tab of the DSN dialog.

SSL modes

Pick the strongest mode the client can validate:

Mode	Encryption	Server cert validation	Use case
disable	No	—	Local-only, no TLS configured
allow	If server offers it	No	Almost never — prefer prefer or stronger
prefer	If server offers it	No	Default when tls_cert is set but client doesn’t care
require	Yes	Accepts any cert, including self-signed	Encrypted session, trust assumed
verify-ca	Yes	Cert must chain to a trusted CA	Production with a known CA
verify-full	Yes	CA chain AND hostname match	Maximum — recommended when the cert has a proper CN / SAN

For self-signed certs, stop at require. verify-ca and verify-full need the client to trust the issuing CA.

Troubleshooting

• “Could not open certificate file” on startup. The path in config.toml doesn’t exist or isn’t readable by the service account. Double-check the path and the icacls grant.
• “server does not support SSL, but SSL was required”. tls_cert/tls_key aren’t set in config.toml, or the service wasn’t restarted after the change.
• “certificate verify failed: self signed certificate”. Client is set to verify-ca or verify-full but the cert is self-signed. Either drop to require or install the self-signed cert in the client’s OS trust store.
• “hostname mismatch”. SSLMode=verify-full needs the CN/SAN on the cert to match the server hostname in the connection string exactly (including localhost vs. 127.0.0.1).
• Handshake takes several seconds. Usually a DNS resolution issue on the server side during the initial connection log — unrelated to TLS itself. Check logs/syntra-odbc.log.

Rotating certificates

Swap tls_cert / tls_key files (same paths or update config.toml to new paths) and restart the service. Existing sessions continue using the previous certificate until they close; new sessions pick up the new cert on the next connect.

When TLS is not enough

TLS protects data in transit. It does not protect against:

• A compromised Syntra host. Anyone with local read access to config.toml has the auth password. Store the config under an ACL that restricts read to the service account and administrators.
• Credential reuse. If the same qbconnect user / password pair is shared across every client, anyone with the string has full access. Consider a per-client user once that feature ships.
• Query-level access control. Syntra authenticates clients once at connection time; it does not yet gate individual tables by role. If you need row-level or table-level access control, terminate queries in an application tier that does its own authorisation, not directly from the reporting tool.