Alpha

These pages are built from turborel-java’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Connecting

A program talks to a Turborel server over a connection, and a connection is one of the server's sessions. This chapter tells how a connection is made: where to, over TCP, a Unix socket or a Windows named pipe; as which user, and how that user is proved; over TLS; within which timeouts; what it asks of the server and what the server tells it; and how it ends, or its statement is cancelled.

Through JDBC a program connects by a jdbc:turborel: URL, whose settings are the ones this chapter tells of (Driver, Installing). This chapter shows the driver's low-level client, which JDBC's classes rest on, as it shows what a connection does step by step. It lives in packages the module does not export (RULES.md D2), so its names may change; the examples run with the driver's classes on the class path. The server of the examples listens at 127.0.0.1, port 17434, and at the Unix socket turborel.sock, with TLS, its owner ANN, whose password is ann's.

Where to

Connect.tcp connects over TCP to a host and port, trying each of the host's addresses in turn. A server listens at port 7422 unless told another (Connect.PORT). Connect.local connects over the Unix socket at a path, or on Windows over a named pipe, as \\.\pipe\turborel. Connect.tls connects over TCP and begins TLS on the same port.

Connection conn = Connect.tcp("127.0.0.1", 17434, "ann", new Trust());
System.out.println(conn.server() + ", as " + conn.authorization());
conn.terminate();
turborel 0.0.0 (alpha), as ANN

server gives the server's product and version, and authorization the session's authorization identifier, as the server told them as the session began. A user's name is an identifier, so ann is the user ANN.

Who connects

Each way of connecting takes the user and a mechanism that proves it:

  • Scram, of a password, by SCRAM-SHA-256: what a password should be proved by. The password never travels, and the connection is refused (SQLSTATE 08006) unless the server proves it knows the user's verifier. An exchange overheard lets the password be guessed at leisure, so it is used only over TLS, a Unix socket or a named pipe, unless inTheClear() asks for it over plain TCP too, for a server whose SERVER.SCRAM_WITHOUT_TLS is ON. Over TLS it is SCRAM-SHA-256-PLUS, bound to the connection, so a server in the middle cannot relay it.
  • Password, of a password, sent whole, only over TLS, a Unix socket or a named pipe.
  • Certificate, which proves the user by the certificate the client presents over TLS.
  • Trust, which asks the server to trust the user as it names itself, as a server does only of a client of its own machine, and only if its setting SERVER.TRUST_LOCAL is ON, not its default.

To a server over plain TCP, Password, and Scram not in the clear, are refused before anything is connected (SQLCODE -919, SQLSTATE 28000). A server refuses credentials it does not take with the same SQLSTATE, and closes the connection.

try {
    Connect.tcp("127.0.0.1", 17434, "ann", new Password("ann's"));
} catch (TurborelException e) {
    System.out.println(e.sqlcode() + " " + e.getSQLState() + ": " + e.getMessage());
}
try {
    Connect.local(Path.of("turborel.sock"), "ann", new Scram("not ann's"));
} catch (TurborelException e) {
    System.out.println(e.sqlcode() + " " + e.getSQLState() + ": " + e.getMessage());
}
-919 28000: [CLIENT Connecting] password is sent only over TLS, a Unix socket or a named pipe, never over plain TCP
-919 28000: the user or the password is wrong

Over TLS

A TlsConfig says what a client's TLS trusts, and what it presents. TlsConfig.trusting trusts the certificate authorities of a PEM file; TlsConfig.presenting trusts them too, and presents the certificate chain and private key of two more, the key as PKCS #8, PKCS #1 or SEC 1. Connect.tls takes the name the server's certificate must be of, which it also sends as the server's name.

TlsConfig config = TlsConfig.trusting(Path.of("certs/ca.pem"));
Connection conn = Connect.tls("127.0.0.1", 17434, "localhost", config, new Login("ann", new Scram("ann's")));
System.out.println(conn.authorization() + " over TLS");
conn.terminate();
ANN over TLS
TlsConfig config = TlsConfig.presenting(
        Path.of("certs/ca.pem"), Path.of("certs/client-chain.pem"), Path.of("certs/client-key.pem"));
Connection conn = Connect.tls("127.0.0.1", 17434, "localhost", config, new Login("ann", new Certificate()));
System.out.println(conn.authorization() + ", by its certificate");
conn.terminate();
ANN, by its certificate

The authorities trusted may be a file's, the platform's, or both: Roots.of makes a store of them, for TlsConfig.of. The platform's are those of the files the environment's SSL_CERT_FILE and SSL_CERT_DIR name, if either is set, SSL_CERT_DIR a list of directories apart by the platform's path separator, each that cannot be read passed over; else the JDK's own trusted authorities (RULES.md D13). A certificate not of the name, or of an authority not trusted, fails the handshake (SQLSTATE 08006).

SCRAM-SHA-256-PLUS binds by tls-exporter where the JDK exports TLS 1.3's keying material, JDK 25 and later, and by the server's certificate before it. channelBinding(ChannelBinding.REQUIRE) refuses to go on unbound; DISABLE binds nothing; PREFER, the default, binds where it can.

Timeouts

Timeouts says how long a connection waits on its server: connect, to connect, begin TLS, and for each step of the login, 30 seconds by default; read, for each read or write after, no limit by default, as a statement may run as long as it must. Connect.tcp, local and tls wait as Timeouts.DEFAULT says; Connect.to takes timeouts of its own, and setReadTimeout changes a connection's read timeout. A wait that runs out loses the connection (SQLSTATE 08006), saying the server did not answer in time. A named pipe is bounded only as it is opened, while every instance of it is busy: its reads and writes wait as long as they must.

A reply is taken up to 16 MiB, the protocol's longest; setMaxBody takes replies of at most as many bytes as it says, a longer one losing the connection.

What a connection asks for, and what the server tells

A connection asks the server for capabilities as it opens, and the server grants those it serves. Offer.standard() asks for every one but compression, as the ways of connecting above do. Connect.to takes an offer of its own: Offer.none() asks for none, compressed() adds compression, and attribute(name, value) adds a connection attribute, which the server shows in INFORMATION_SCHEMA.CONNECTION_ATTRIBUTES. granted gives what was granted.

Granted status, setting(name) gives one of the session's settings as the server last told it, with no round trip, and settings all of them. The server tells them as the session begins, and again as a statement changes one. Besides the settings it tells AUTHORIZATION, SCHEMA, READ_ONLY, SERVER_VERSION, SERVER_READ_ONLY, CATALOG and OWNER.

Timeouts within = new Timeouts(Duration.ofSeconds(5), Duration.ofSeconds(60));
Offer offer = Offer.standard().attribute(Offer.APPLICATION, "payroll");
Target target = new Target.Tcp(new InetSocketAddress("127.0.0.1", 17434));
Connection conn = Connect.to(target, "ann", new Trust(), within, offer);
System.out.println("read timeout " + conn.readTimeout());
System.out.println("compression granted: " + conn.granted().contains(Capability.COMPRESSION));
System.out.println("SCHEMA " + conn.setting("SCHEMA") + ", READ_ONLY " + conn.setting("READ_ONLY"));
conn.terminate();
read timeout PT1M
compression granted: false
SCHEMA ANN, READ_ONLY NO

The SCRAM key cache

A SCRAM login derives its keys from the password by PBKDF2, made slow so a stolen exchange is slow to guess from. A server sends a user the same salt and iterations at each login, so a KeyCache keeps the keys a password derived after a login the server proved, and a later login of the same salt and iterations skips the derivation. Scram.withCache gives a mechanism one.

KeyCache cache = new KeyCache();
for (int i = 0; i < 2; i++) {
    Connect.local(Path.of("turborel.sock"), "ann", new Scram("ann's").withCache(cache)).terminate();
    long[] lookups = cache.lookups();
    System.out.println("hits " + lookups[0] + ", misses " + lookups[1]);
}
hits 0, misses 1
hits 1, misses 1

An entry is found by the salt, the iterations and a tag of the password made under a random secret of the cache's own, so a wrong password finds nothing, and the cache holds neither the password nor anything it could be guessed from offline. It holds 64 entries at most, the oldest dropped first, drops an entry when a login that used it fails, and is held in the process's memory alone.

Ending a connection, and cancelling a statement

terminate ends the session, its transaction as the setting SESSION.COMMIT_AT_END says. A commit that fails then, as one of a deferred constraint not satisfied (SQLSTATE 40002), rolls the transaction back, and terminate gives its failure. It waits for the server to close at most the read timeout, else 60 seconds. close closes the connection at once, without Terminate, and the server then ends the session.

canceller gives what cancels the statement the connection runs, from another thread: it opens a connection of its own, carrying the key the server gave as the session began, and the statement fails with SQLCODE -920, SQLSTATE TB920. cancel gives up after 10 seconds if the server does not answer, cancelWithin after a limit of its own. A connection over a stream the program opened itself has no canceller, since the driver cannot reach its server again.

A connection lost, by a failure of its stream, an Error that ends it, or a wait that runs out, takes no more: isLost says so, and each later request fails with the failure that lost it.

The low-level client's classes are told in full in the API Reference, Connections.