Security model and trust boundaries

graph TD
    subgraph P["Workstation: application process, rights of the Windows user"]
        A["Application (Access, DAO, ADO.NET)"] -->|"ODBC call"| D["Driver Wkl OData"]
        D -->|"reads and stores key or password"| C["Windows Credential Manager (per user)"]
        D -->|"tracing, only when turned on"| T["Trace file"]
    end
    D -->|"HTTPS: request with sign-in, session, identity, transaction"| S["OData service checks sign-in and rights"]
    S -->|"statement under a database login"| B[("Database")]

Figure: The driver runs in the application's process. Between the workstation and the service lies the network boundary, protected by TLS; between the service and the database lies the boundary at which the service decides what's executed. The arrows show where credentials and statements go.

The driver isn't a security filter. What a caller may read, change, or execute is decided by the service alone; an application that bypasses the driver and addresses the service directly over HTTP has the same rights. The driver protects the credentials it holds and the data in transit. This page describes which measures the driver takes for this, which the service must take, how you verify each measure, and which risks remain.

Key features

No secret in the Access file: Windows sign-in and a saved personal key need no value in the connection string.
Secrets only encrypted or local: password, personal key, and session go only over https or to your own computer; otherwise the driver stops before sending.
Secrets only to the addresses of the connection: next pages, addresses from the schema document, and redirects to another computer receive no credentials, not even a Windows sign-in.
Certificate validation without an off switch: a certificate that Windows doesn't trust ends the connection with 08S01.
Second-factor session only in memory: it ends with the process.

Basic concepts

Assets to protect

Asset	Who holds it	Consequence of a loss
Personal key, password of a login	the user's Credential Manager or the connection string	A third party signs in as this person until the key is blocked or the password is changed
Service key (`APIKEY`, `APIKEYENV`)	connection string or environment variable	A third party receives the rights of the key; it applies not to a person but to a program
Second-factor session	memory of the process	A third party who also has the first factor bypasses the second until the session expires
Business data in transit	TLS connection	Eavesdropping on or altering requests and responses
Business data in the trace	file, when turned on	Statements, filter values, and sign-in names in plain text (see Tracing)

Responsibility between driver and service

Check	Driver	Service
Who is signed in	passes the sign-in on	checks it (password, key, Windows sign-in, second factor)
Which tables someone sees	shows what `$metadata` names	names in `$metadata` only what the caller may read
Whether a change is allowed	translates it	allows or refuses it (`403`)
Whether a custom statement (pass-through) may run	doesn't check or classify it	names the address only to callers that may send statements and decides per statement; the data service Wkl.Data.Gateway checks every object the statement names against the caller's rights (checked statements)
How long a session is valid	holds it as long as the process lives	sets the validity and refuses an expired one
Whether TLS is used	sends secrets only over `https` or locally	offers `https` with a trusted certificate

The driver deliberately doesn't check a passed-through statement: whether it's permitted depends on the permissions under which it would run in the database, and only the service knows those. A check in the driver would also be ineffective, because anyone who can reach the service can also call it without the driver.

Credentials on the workstation

Saved key and saved password. If the user selects „Save key“ or „Save password“ in the dialog, the driver stores the value in Windows Credential Manager – as a generic credential with the persistence „local machine“ (Microsoft: CREDENTIALW, Persist). It follows that:

The value applies only to this Windows account on this computer and doesn't roam with a roaming profile.
Windows protects it with the user's sign-in. Another user of the same computer can't read it.
Every program that runs under the same Windows account can read it. Credential Manager doesn't separate by program. Malware in the user's account therefore reaches the key just as it reaches the service itself.

Connection string. PWD and APIKEY are in plain text wherever the string is: in an Access file if the link is to save the password (dbAttachSavePWD), in a program, or in a data source that an application writes itself. The driver's setup dialog never writes a password into a data source.

Second-factor session. The driver holds it in the memory of the process, per service and sign-in, and writes it nowhere: not into the returned connection string, not into the trace, not to disk. When the process ends, it's gone.

Credentials in transit

Rule	Effect	Verification
Password, personal key, and session only over `https` or to your own computer – to `URL` and `PASSTHROUGH` alike	Over `http` to another computer, the connection fails before a request is sent: `28000`. If a service asks for a second factor over `http`, the driver sends neither the code nor the session and reports `28000`	Connect with `URL=http://<other-host>/…;AUTH=KEY`: error, no request in the trace
Credentials only to the scheme, host, and port of the addresses that the connection names (`URL`, `PASSTHROUGH`)	A next page, a pass-through address from `$metadata`, or an address for the second factor at another origin receives no credentials	Trace: „Schluessel und Kennwort gehen nicht an …“ (Key and password don't go to …)
Certificate against the Windows certificate stores	An untrusted certificate results in `08S01` with the reason („UntrustedRoot“) and isn't retried	see 08S01 "UntrustedRoot"
The driver itself follows a redirect (`3xx`), not the HTTP library: only when reading and only at the same origin, at most five times	A redirect to another host, port, or scheme stops with `08S01` and a message that names the target; nothing is sent there. A redirected change isn't repeated	see "The service redirects to …"
Windows sign-in (Negotiate) only when the service requests it, and only to the addresses of the connection	The driver answers a `401 Negotiate` or `NTLM` challenge only if it comes from the scheme, host, and port of `URL` or `PASSTHROUGH`; any other host gets no Windows sign-in, and its challenge ends with `28000`	Trace: „Die Windows-Anmeldung geht nicht an …“ (The Windows sign-in doesn't go to …)

A service key follows the same origin rules, but also goes over http to another computer. If you use APIKEY or APIKEYENV, you must ensure https yourself.

Expired session, retry, and transaction

The session expires during work. The service refuses the next request with 401 and the Wkl-Totp challenge before it executes anything. The driver asks for a new code and sends the same request again once – for a change, with the same Idempotency-Key and in the same transaction. An application without a dialog receives 28000; a code passed with TOTP= applies only to the first challenge.
The connection drops. The driver retries after 1 and 3 seconds: reads always, changes with the same Idempotency-Key. If the service honors this key, no second record is created. It never retries a streamed pass-through; the application receives 08S01.
A transaction lapses. If the service rolls back a transaction after its idle time, SQLEndTran with commit reports 40001; nothing from the transaction is saved. See Transactions.

These three commitments apply only if the service refuses before it executes and honors Idempotency-Key (see Requirements for an OData service). A service that ignores the header can create a record twice after a dropped connection; the driver doesn't detect that.

Residual risks

Limits of the measures that you need to know about and mitigate yourself when you use the driver.

Residual risk	Cause	Condition under which it occurs	Mitigation
No check for revoked certificates	The driver doesn't query revocation lists or OCSP (default of the HTTP library, which the driver doesn't change)	A certificate of the service was revoked but is still valid and trusted	Keep certificates short-lived; additionally remove a stolen certificate from the workstations' trust
No certificate pinning	Every certificate that Windows trusts is accepted	A certification authority trusted by the workstation issues a false certificate, for example a TLS inspection device in the corporate network	Manage the workstations' trust stores
Saved credentials readable by all of the user's programs	Property of Credential Manager	Malware runs in the user's account	Have keys issued with an expiry and, where possible, bound to a network; require a second factor
Trace contains business data	intended; it serves troubleshooting	turned on and not deleted	see Tracing
Unsigned or replaced DLL	The driver is a DLL in the application's process; the file properties show whether a version is signed	An application control (AppLocker, WDAC) requires a signature, or someone replaces the DLL in the installation folder	Keep the installation folder writable only by administrators; the installation package installs to `Program Files`, where this applies. With setup for one user only, the DLL is in a folder that the user can change themselves

The measures on this page concern the driver. How secure the overall system of driver, service, and database is depends just as much on the service and the database.