ArpeDb2 authentication
ArpeDb2 logs on to Db2 with a user and password (the encrypted logon is negotiated by default), with Kerberos, or with an access token sent as the password. Any of them can run inside TLS. This page describes each method, its options, and what protects the password on the network.
For the full option tables, see Connection → Authentication.
Authentication methods
Db2 negotiates the logon as a DRDA security mechanism. The driver implements
three of them and chooses with adbc.arpedb2.auth.mechanism:
auth.mechanism | Logon | DRDA mechanism |
|---|---|---|
| unset (default) | User and password, encrypted when the server offers it | EUSRIDPWD or USRIDPWD, negotiated |
password | User and password, as sent | USRIDPWD only |
encrypted_password | User and password, both encrypted | EUSRIDPWD only |
kerberos | Kerberos ticket | KERSEC |
token | Access token or API key in the password field, TLS required | USRIDPWD |
An explicit value is never switched or downgraded. If the server does not accept it, the connection fails and the error lists the mechanisms the server offers.
After the logon, the read-only connection options
adbc.arpedb2.auth.negotiated_mechanism and
adbc.arpedb2.auth.negotiated_encryption report what was used.
User and password
The default. With auth.mechanism unset the driver negotiates with the
server, and the order depends on whether the connection uses TLS.
Without TLS (sslmode=disable, the default), the password is kept off the
network whenever the server can take it encrypted, in the order IBM's own
clients use:
-
The driver asks for the encrypted logon first. Servers with
AUTHENTICATION=SERVER_ENCRYPTand Db2 for i accept it directly. -
If the server does not offer it (Db2's default
AUTHENTICATION=SERVERtakes a plain password only), the driver sends the password in clear on the same connection, unlessauth.require_encryption=true. Before it does, it prints one line on standard error:ArpeDb2: sending a clear-text password over an UNENCRYPTED connection (the server does not offer encrypted password logon); an active network attacker could capture it. Use TLS (adbc.arpedb2.sslmode=require or higher) or set adbc.arpedb2.require_password_encryption to refuse. -
Anything else fails with the list of mechanisms the server offers.
Inside TLS (any sslmode but disable), TLS already protects the
password, so the driver asks for the plain logon first and moves to the
encrypted one only when the server requires it.
No credential is sent before the server has accepted the mechanism.
| Option | Meaning |
|---|---|
adbc.arpedb2.username (or username) | Db2 authorization ID. |
adbc.arpedb2.password (or password) | Password. |
adbc.arpedb2.auth.require_encryption (alias adbc.arpedb2.require_password_encryption) | true: never send the password in clear. Without TLS only the encrypted logon is used, and a server that does not offer it fails the connection with UNAUTHENTICATED. auth.mechanism=password or token without TLS is refused with INVALID_ARGUMENT. Inside TLS it changes nothing. Default false. |
The user and password can also be given in a connection string or a URI
(db2://user:pw@host:port/db): see
Three ways to connect.
Without TLS, a server that only takes a plain password receives it in clear,
and so does an attacker on the network path who removes the encrypted logon
from the server's answer. Use TLS with sslmode=verify-full on any network
you do not fully trust, and set auth.require_encryption=true to refuse the
clear-text fallback.
Encrypted user and password
With the encrypted logon (EUSRIDPWD), the client and the server agree on a
key with Diffie-Hellman, then the user ID and the password travel encrypted
with that key. Data after the logon is not encrypted: that is what TLS is
for. Since v0.3.3.
auth.encryption | Cipher | When |
|---|---|---|
auto (default) | AES when the server lists it, otherwise DES | The driver switches to the other algorithm if the server refuses the first. |
aes | AES-256-CBC | Never uses DES. Needed for Db2 ALTERNATE_AUTH_ENC=AES_ONLY. |
des | DES-CBC (56-bit key) | Older servers only. |
Both are what IBM's own clients send (IBM CLI
AUTHENTICATION=SERVER_ENCRYPT / SERVER_ENCRYPT_AES).
The limits come from the DRDA protocol, and IBM's clients share them:
- The key exchange is not authenticated: nothing proves the server's key is the server's. An attacker on the network path can run the exchange with each side and read the password.
- The Diffie-Hellman groups are small and fixed (256-bit for DES, 512-bit for AES), so a recorded logon can be attacked offline.
- With
auth.encryption=auto, an active attacker can force DES by announcing that the server supports nothing else.
TLS with sslmode=verify-full is the real protection. It authenticates
the server and encrypts the whole session, logon and data. Without TLS,
auth.encryption=aes refuses DES and auth.require_encryption=true refuses
the clear-text fallback.
On the server side (Db2 for LUW), AUTHENTICATION=SERVER_ENCRYPT refuses a
plain password and accepts AES or DES; ALTERNATE_AUTH_ENC=AES_ONLY refuses
DES.
Kerberos
Set adbc.arpedb2.auth.mechanism to kerberos. The driver sends a Kerberos
ticket instead of a user name and password, and requires mutual
authentication.
| Option | Meaning |
|---|---|
adbc.arpedb2.kerberos.spn | The Db2 server's service principal name, <DB2INSTANCE>/<fqdn>@<REALM>. Required. It is never derived from server, because the Db2 instance name cannot be guessed from a host name. |
adbc.arpedb2.kerberos.cred | Where the credential comes from: see the table below. Default default. |
adbc.arpedb2.kerberos.keytab | Keytab file path, for cred=keytab. |
kerberos.cred | Credential source | username / password | Typical use |
|---|---|---|---|
default (alias ccache) | The Kerberos credential cache of the process, that is, what kinit obtained | not needed | Interactive use: run kinit user@REALM first. |
keytab | The file named by kerberos.keytab | not needed | Service accounts, scheduled jobs. Linux only. |
password | The driver obtains the ticket itself | required: the principal and its password | Callers that hold a principal and a password and do not want to run kinit. |
import adbc_driver_manager.dbapi as dbapi
# Credential cache (run `kinit db2user@EXAMPLE.COM` first)
conn = dbapi.connect(driver="arpedb2", db_kwargs={
"adbc.arpedb2.server": "db2.example.com",
"adbc.arpedb2.database": "sample",
"adbc.arpedb2.auth.mechanism": "kerberos",
"adbc.arpedb2.kerberos.spn": "db2inst1/db2.example.com@EXAMPLE.COM",
}, autocommit=True)
# Keytab (service accounts)
conn = dbapi.connect(driver="arpedb2", db_kwargs={
"adbc.arpedb2.server": "db2.example.com",
"adbc.arpedb2.database": "sample",
"adbc.arpedb2.auth.mechanism": "kerberos",
"adbc.arpedb2.kerberos.cred": "keytab",
"adbc.arpedb2.kerberos.keytab": "/etc/keytabs/svc-db2.keytab",
"adbc.arpedb2.kerberos.spn": "db2inst1/db2.example.com@EXAMPLE.COM",
}, autocommit=True)
Kerberos and TLS are independent: set sslmode as well to encrypt the
connection.
Platform support
| Platform | State |
|---|---|
| Linux | ✅ Built into the released .so. The driver does not link MIT Kerberos: the first Kerberos logon loads libgssapi_krb5.so.2 and libkrb5.so.3 from the host (package krb5-libs on RHEL, Rocky and Fedora; libgssapi-krb5-2 on Debian and Ubuntu), so it follows the host's krb5.conf and security updates. On a host without them, the other logons work and only a Kerberos logon fails, with NOT_IMPLEMENTED and a message naming the package to install. The three credential modes work; they need MIT Kerberos 1.11 or later. Since v0.3.3. |
| Windows | 🟡 Through SSPI, Windows' own Kerberos client, so there is nothing to install. Not yet validated: it has not yet logged on to a Db2 server from a Windows host in an Active Directory domain. Treat it as a preview. cred=default uses the tickets of the Windows user the application runs as; cred=password takes username as user@REALM or DOMAIN\user; cred=keytab is not supported (run the application as the service account instead). It uses the Kerberos package directly, never NTLM. Since v0.3.7. |
Token
Db2 has no bearer-token logon in the DRDA protocol. IBM Cloud Db2 and Microsoft Entra integrations take the access token or API key in the password field of an ordinary user/password logon, and a security plugin on the server validates it.
That works with a plain password logon, but auth.mechanism=token states the
intent and enforces TLS that verifies the server: a long-lived token must
never travel in clear, nor reach a server that has not proved its identity.
| Option | Value |
|---|---|
adbc.arpedb2.auth.mechanism | token |
adbc.arpedb2.username | The Db2 authorization ID the service expects for a token logon. |
adbc.arpedb2.password | The access token or API key, at most 255 bytes. |
adbc.arpedb2.sslmode | verify-full (recommended), or verify-ca or require with sslrootcert. disable, and require without sslrootcert, are refused with INVALID_ARGUMENT before a socket is opened. |
TLS
TLS is not an authentication method: it encrypts the DRDA connection and can
carry any of the logons above. It is opt-in: with sslmode unset the
connection is not encrypted.
Db2 uses implicit TLS. There is no upgrade inside the connection, so
adbc.arpedb2.port must be the server's SSL port (for example 50001 next to a
plain 50000, depending on the server's configuration). The TLS handshake runs
right after the TCP connect, before any DRDA byte.
Modes
sslmode | Encrypts | Verifies the certificate chain | Verifies the host name |
|---|---|---|---|
disable (default) | no | — | — |
require | yes | only with sslrootcert | no |
verify-ca | yes | yes, against sslrootcert (required) | no |
verify-full (recommended) | yes | yes | yes |
requirewithoutsslrootcertaccepts any certificate: it stops someone listening, not an attacker who can intercept the connection.verify-cachecks the chain only, so it needs your own CA insslrootcert. Against the system store it would accept any certificate a public CA signed, soverify-cawithoutsslrootcertis refused withINVALID_ARGUMENT.verify-fullis the mode that authenticates the server.
conn = dbapi.connect(driver="arpedb2", db_kwargs={
"adbc.arpedb2.server": "db2.example.com",
"adbc.arpedb2.port": "50001",
"adbc.arpedb2.database": "sample",
"adbc.arpedb2.username": "db2inst1",
"adbc.arpedb2.password": "<pw>",
"adbc.arpedb2.sslmode": "verify-full",
"adbc.arpedb2.sslrootcert": "/path/to/ca.pem",
}, autocommit=True)
Protocol versions
The minimum is TLS 1.2, and TLS 1.3 is used whenever the server supports it.
With the released binaries, the hybrid post-quantum key exchange
X25519MLKEM768 is offered first and used when the server supports it. The
read-only connection options adbc.arpedb2.tls.version, tls.group and
tls.cipher report what a connection negotiated. Since v0.3.2.
Independent of the host's TLS stack
The released binaries link OpenSSL 3.5 statically, so the driver does not
depend on, or interfere with, the OpenSSL of the host application. The
read-only database option adbc.arpedb2.openssl_version gives the exact
version.
Where trusted certificates come from
- With
adbc.arpedb2.sslrootcert: that PEM file only. - Without it,
verify-fulluses the system trust store. On Linux, the distribution's CA bundle (OpenSSL'sSSL_CERT_FILEandSSL_CERT_DIRare honoured). On Windows, the Trusted Root Certification Authorities of the machine and of the user, with the Intermediate Certification Authorities used to complete the chain. Windows certificate store since v0.3.7.
For a private or self-signed CA that is not in the system store, set
sslrootcert to your CA's PEM file.
Host name check
verify-full checks the name you connect to against the certificate (its
common name or a DNS or IP subject alternative name). Connecting by IP
address to a certificate issued for a DNS name fails that check even though
the chain is trusted. Connect with the name the certificate was issued for,
or set adbc.arpedb2.sslhostname to that name when you reach the server
through an IP address, an alias, a load balancer or an SSH tunnel. Since
v0.3.6.
See also
- Connection: every connection option
- Compatibility: the support state of each method
- Troubleshooting: logon and TLS errors