7.4.2. JDBC URL Parameters & Encryption
JDBC applications connect through a Virtuoso JDBC URL of the form:
jdbc:virtuoso://<host>[:<port>][,<host2>[:<port2>],.../<param>[=<value>/...
The default host is localhost and the default port is
1111. Parameter names are case-insensitive. A bare
flag such as /SSL needs no value. Boolean parameters
accept 1, Y or y
as true. Because / separates URL options, filesystem
paths in option values must use backslash separators (the driver remaps
them to the platform separator at connect time).
All Possible Parameters Summary
Recognised URL parameters (slash-separated options after the host list):
/CERT=<alias>
/CHARSET=<name>
/DATABASE=<qualifier>
/DELEGATE=<user>
/FBS=<rows>
/KPASS=<keystore_password>, /PASS=<keystore_password>
/KPATH=<keystore_path>
/LOG_ENABLE=<0-3>
/PROVIDER=<ssl_provider_classname>
/PSTMTPOOLSIZE=<n>
/PWD=<password>
/PWDCLEAR=<cleartext|encrypt|digest>, /PWDTYPE=<cleartext|encrypt|digest>
/RECVBS=<bytes>
/ROUNDROBIN=<0|1>
/SENDBS=<bytes>
/SSL
/TIMEOUT=<seconds>
/TS=<truststore_path>
/TSPASS=<truststore_password>
/UID=<user>
/USEPSTMTPOOL=<0|1>
Examples:
jdbc:virtuoso://localhost:1111/UID=dba/PWD=dba
jdbc:virtuoso://localhost:1112/SSL/UID=dba/PWD=dba
jdbc:virtuoso://db1:1112,db2:1112/SSL/UID=dba/PWD=dba/ROUNDROBIN=1
jdbc:virtuoso://localhost:1112/SSL/KPATH=\path\client.p12/PASS=secret/CERT=myclient
Individual Parameters
-
/CERT=<alias> -
Alias of the client certificate entry inside the keystore named by
/KPATH. Used with/SSL(or implied SSL via/KPATH) when presenting a client certificate. If omitted while/KPATHand/PASSare set, the driver uses the first key entry in the store. -
/CHARSET=<name> -
Character set for encoding Java Unicode strings on the wire. A value containing
UTF-8is treated specially and keeps UTF-8 handling enabled in the driver. -
/DATABASE=<qualifier> -
Initial database qualifier. After login the driver runs
use <qualifier>. -
/DELEGATE=<user> -
Delegation identity passed in the login handshake (login-info vector). Used when connecting under one account while acting on behalf of another, subject to server policy.
-
/FBS=<rows> -
Prefetch / fetch buffer size in rows. Default is 100.
-
/KPASS=<keystore_password>,/PASS=<keystore_password> -
Password for the keystore given by
/KPATH. Required to load and present a client certificate from that store. (This is not the SQL user password; that is/PWD.) -
/KPATH=<keystore_path> -
Path to a client keystore (JKS, or PKCS#12 when the path ends in
.p12/.pfx) holding the client certificate and private key. Presence of/KPATHcauses the driver to use a TLS socket even if/SSLis omitted; include/SSLanyway for clarity. Requires/PASS(or/KPASS). Use backslash path separators in the URL value; the driver remaps them to the platform separator at connect time. -
/LOG_ENABLE=<0-3> -
![[Warning]](images/warning.png)
Warning Warning: only use when recommended by OpenLink Support.
After connect, runs
log_enable(<n>)whennis between 0 and 3 inclusive.2auto-commits on every changed row and avoids holding a large rollback image in memory. -
/PROVIDER=<classname> -
Optional Java security provider class to register before creating the TLS context. Modern JDKs already provide TLS; set this only when a non-default provider must be loaded explicitly.
-
/PSTMTPOOLSIZE=<n> -
Size of the PreparedStatement cache when
/USEPSTMTPOOLis enabled. Default is 25. -
/PWD=<password> -
SQL user password (maps to the JDBC
passwordproperty). -
/PWDCLEAR=<cleartext|encrypt|digest>,/PWDTYPE=<cleartext|encrypt|digest> -
How the SQL password is sent during login.
/PWDTYPEis rewritten to/PWDCLEARwhen the URL is parsed. Values:-
cleartext— send the password as plaintext inside the login RPC. -
encrypt— send a Virtuoso password-magic encryption of the password. -
digest— send an MD5 digest of user, password and session material (default if unset and the server does not dictate otherwise).
The server may override the client setting via
SQL_ENCRYPTION_ON_PASSWORDin the caller-id reply. Prefer/SSLfor real confidentiality: without TLS the rest of the session is still plaintext. -
-
/RECVBS=<bytes> -
Socket receive buffer size in bytes. Default is 32768.
-
/ROUNDROBIN=<0|1> -
When the URL lists more than one
host:port,1picks the starting host round-robin; otherwise hosts are tried in order (failover). Ignored when only one host is given. -
/SENDBS=<bytes> -
Socket send buffer size in bytes. Default is 32768.
-
/SSL -
Adds SSL/TLS encryption to the transport layer. Connect to the server's SSLServerPort, not the plaintext SQL port. Optional for
/UID+/PWDconnections (but strongly recommended). Include it whenever you use client-certificate or truststore options; the driver also enables TLS automatically if/KPATHor/TSis set./SSLdoes not mean "anonymous SSL without authentication" — username/password login still applies unless you rely on certificate-based login on the server. -
/TIMEOUT=<seconds> -
Socket read timeout in seconds (
SO_TIMEOUT). When exceeded, I/O fails and the connection is treated as broken. -
/TS=<truststore_path> -
Path to a truststore used to verify the server certificate. JKS files are loaded with
/TSPASS; paths ending in.pem,.crtor.p7bare imported as X.509 certificates. Presence of/TSenables a TLS socket even without/SSL. Without/TS, the driver uses a trust-all manager (server certificate is not verified). Use backslash path separators in the URL value, as for/KPATH. -
/TSPASS=<truststore_password> -
Password for a JKS truststore named by
/TS. -
/UID=<user> -
SQL user name (maps to the JDBC
userproperty). -
/USEPSTMTPOOL=<0|1> -
Enable (
1) or disable the driver's PreparedStatement pool.
SSL Considerations
Four Levels of Connection Security
/SSL adds SSL encryption to the transport layer. It is
optional for plain /UID+/PWD use, and
should always be present (explicitly or implied via
/KPATH / /TS) when certificates are
involved.
Table 7.6. Four Levels of Connection Security
| Level | Method | Parameters | Explanation |
|---|---|---|---|
| 1 | Password only |
/UID, /PWD
|
Authenticates with username and password over a plaintext socket. Insecure outside a trusted network. |
| 2 | TLS transport |
/SSL, /UID, /PWD
|
Same password login, with SSL/TLS wrapping the transport. Recommended balance of security and ease. Connect to SSLServerPort. |
| 3 | TLS + client certificate |
/SSL, /CERT with
/KPATH and /PASS
|
TLS plus a client-side certificate. /CERT is
the keystore alias; /KPATH and
/PASS are required to load it (JKS or PKCS#12).
If /CERT is omitted, the first key entry is
used.
|
| 4 | TLS + client certificate + truststore |
/SSL, /KPATH, /PASS,
/CERT, /TS
|
Same as level 3, plus /TS to use a non-default
JDK truststore.
|
Example URLs:
jdbc:virtuoso://localhost:1111/UID=dba/PWD=dba
jdbc:virtuoso://localhost:1112/SSL/UID=dba/PWD=dba
jdbc:virtuoso://localhost:1112/SSL/KPATH=\path\client.p12/PASS=secret
jdbc:virtuoso://localhost:1112/SSL/KPATH=\path\client.keystore/PASS=secret/CERT=myclient/TS=\path\server.crt
Server-Side SSL Configuration
Before any SSL URL form will work, Virtuoso must listen on an SSL
port with a key and certificate. In the database working directory
(typically db/), generate them:
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -days 365 -nodes \
-keyout virtuoso.key \
-out virtuoso.crt \
-subj "/CN=virtuoso.local" \
-addext "subjectAltName=DNS:localhost,DNS:virtuoso.local,IP:127.0.0.1"
Then point the server at them (example using port 1112):
inifile -f virtuoso.ini -s Parameters -k SSLServerPort -v 1112
inifile -f virtuoso.ini -s Parameters -k SSLPrivateKey -v virtuoso.key
inifile -f virtuoso.ini -s Parameters -k SSLCertificate -v virtuoso.crt
Restart Virtuoso after changing these settings. JDBC clients use the
SSLServerPort value as the URL port together
with /SSL. For verifying client certificates on the
server, also configure X509ClientVerify,
X509ClientVerifyCAFile and related
Parameters as for secure
ODBC/CLI.