Skip to main content

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.mechanismLogonDRDA mechanism
unset (default)User and password, encrypted when the server offers itEUSRIDPWD or USRIDPWD, negotiated
passwordUser and password, as sentUSRIDPWD only
encrypted_passwordUser and password, both encryptedEUSRIDPWD only
kerberosKerberos ticketKERSEC
tokenAccess token or API key in the password field, TLS requiredUSRIDPWD

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:

  1. The driver asks for the encrypted logon first. Servers with AUTHENTICATION=SERVER_ENCRYPT and Db2 for i accept it directly.

  2. If the server does not offer it (Db2's default AUTHENTICATION=SERVER takes a plain password only), the driver sends the password in clear on the same connection, unless auth.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.
  3. 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.

OptionMeaning
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.

A plain password needs TLS

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.encryptionCipherWhen
auto (default)AES when the server lists it, otherwise DESThe driver switches to the other algorithm if the server refuses the first.
aesAES-256-CBCNever uses DES. Needed for Db2 ALTERNATE_AUTH_ENC=AES_ONLY.
desDES-CBC (56-bit key)Older servers only.

Both are what IBM's own clients send (IBM CLI AUTHENTICATION=SERVER_ENCRYPT / SERVER_ENCRYPT_AES).

Protection against passive listening only

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.

OptionMeaning
adbc.arpedb2.kerberos.spnThe 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.credWhere the credential comes from: see the table below. Default default.
adbc.arpedb2.kerberos.keytabKeytab file path, for cred=keytab.
kerberos.credCredential sourceusername / passwordTypical use
default (alias ccache)The Kerberos credential cache of the process, that is, what kinit obtainednot neededInteractive use: run kinit user@REALM first.
keytabThe file named by kerberos.keytabnot neededService accounts, scheduled jobs. Linux only.
passwordThe driver obtains the ticket itselfrequired: the principal and its passwordCallers that hold a principal and a password and do not want to run kinit.
Python
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​

PlatformState
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.

OptionValue
adbc.arpedb2.auth.mechanismtoken
adbc.arpedb2.usernameThe Db2 authorization ID the service expects for a token logon.
adbc.arpedb2.passwordThe access token or API key, at most 255 bytes.
adbc.arpedb2.sslmodeverify-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​

sslmodeEncryptsVerifies the certificate chainVerifies the host name
disable (default)no——
requireyesonly with sslrootcertno
verify-cayesyes, against sslrootcert (required)no
verify-full (recommended)yesyesyes
  • require without sslrootcert accepts any certificate: it stops someone listening, not an attacker who can intercept the connection.
  • verify-ca checks the chain only, so it needs your own CA in sslrootcert. Against the system store it would accept any certificate a public CA signed, so verify-ca without sslrootcert is refused with INVALID_ARGUMENT.
  • verify-full is the mode that authenticates the server.
Python
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-full uses the system trust store. On Linux, the distribution's CA bundle (OpenSSL's SSL_CERT_FILE and SSL_CERT_DIR are 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​