Calling sequences for the security plug-in APIs

The sequence with which the Db2® database manager calls the security plug-in APIs varies according to the scenario in which the security plug-in API is called.

These are the main scenarios in which the Db2 database manager calls security plug-in APIs:
  • On a client for a database connection (implicit and explicit)
    • CLIENT
    • Server-based (SERVER, SERVER_ENCRYPT)
    • GSSAPI and Kerberos
  • On a client, server, or gateway for local authorization
  • On a server for a database connection
  • On a server for a grant statement
  • On a server to get a list of groups to which an authorization ID belongs
Note: The Db2 database servers treat database actions requiring local authorizations, such as db2start, db2stop, and db2trc like client applications.
For each of these operations, the sequence with which the Db2 database manager calls the security plug-in APIs is different. Following are the sequences of APIs called by the Db2 database manager for each of these scenarios.
CLIENT - implicit
When the user-configured authentication type is CLIENT, the Db2 client application calls the following security plug-in APIs:
  • db2secGetDefaultLoginContext();
  • db2secValidatePassword();
  • db2secFreetoken();

For an implicit authentication, that is, when you connect without specifying a particular user ID or password, the db2secValidatePassword API is called if you are using a user ID/password plug-in. This API permits plug-in developers to prohibit implicit authentication if necessary.

CLIENT - explicit
On an explicit authentication, that is, when you connect to a database in which both the user ID and password are specified, if the authentication database manager configuration parameter is set to CLIENT, the Db2 client application calls the following security plug-in APIs multiple times if the implementation requires it:
  • db2secRemapUserid();
  • db2secValidatePassword();
  • db2secFreeToken();
Server-based (SERVER, SERVER_ENCRYPT) - implicit
On an implicit authentication, when the client and server negotiate user ID/password authentication (for example, when the srvcon_auth parameter at the server is set to SERVER; SERVER_ENCRYPT), the client application calls the following security plug-in APIs:
  • db2secGetDefaultLoginContext();
  • db2secFreeToken();
Server-based (SERVER, SERVER_ENCRYPT) - explicit
On an explicit authentication, when the client and server negotiate userid/password authentication (for example, when the srvcon_auth parameter at the server is set to SERVER; SERVER_ENCRYPT), the client application calls the following security plug-in APIs:
  • db2secRemapUserid();
GSSAPI and Kerberos - implicit
On an implicit authentication, when the client and server negotiate GSS-API or Kerberos authentication (for example, when the srvcon_auth parameter at the server is set to KERBEROS; KRB_SERVER_ENCRYPT, GSSPLUGIN, or GSS_SERVER_ENCRYPT), the client application calls the following security plug-in APIs. (The call to gss_init_sec_context() uses GSS_C_NO_CREDENTIAL as the input credential.)
  • db2secGetDefaultLoginContext();
  • db2secProcessServerPrincipalName();
  • gss_init_sec_context();
  • gss_release_buffer();
  • gss_release_name();
  • gss_delete_sec_context();
  • db2secFreeToken();

With multi-flow GSS-API support, gss_init_sec_context() can be called multiple times if the implementation requires it.

GSSAPI and Kerberos - explicit
If the negotiated authentication type is GSS-API or Kerberos, the client application calls the following security plug-in APIs for GSS-API plug-ins in the following sequence. These APIs are used for both implicit and explicit authentication unless otherwise stated.
  • db2secProcessServerPrincipalName();
  • db2secGenerateInitialCred(); (For explicit authentication only)
  • gss_init_sec_context();
  • gss_release_buffer ();
  • gss_release_name();
  • gss_release_cred();
  • db2secFreeInitInfo();
  • gss_delete_sec_context();
  • db2secFreeToken();

The API gss_init_sec_context() might be called multiple times if a mutual authentication token is returned from the server and the implementation requires it.

On a client, server, or gateway for local authorization
For a local authorization, the Db2 command being used calls the following security plug-in APIs:
  • db2secGetDefaultLoginContext();
  • db2secGetGroupsForUser();
  • db2secFreeToken();
  • db2secFreeGroupList();
These APIs are called for both user ID/password and GSS-API authentication mechanisms.
On a server for a database connection
For a database connection on the database server, the Db2 agent process or thread calls the following security plug-in APIs for the user ID/password authentication mechanism:
  • db2secValidatePassword(); Only if the authentication database configuration parameter is not CLIENT
  • db2secGetAuthIDs();
  • db2secGetGroupsForUser();
  • db2secFreeToken();
  • db2secFreeGroupList();
For a CONNECT to a database, the Db2 agent process thread calls the following security plug-in APIs for the GSS-API authentication mechanism:
  • gss_accept_sec_context();
  • gss_release_buffer();
  • db2secGetAuthIDs();
  • db2secGetGroupsForUser();
  • gss_delete_sec_context();
  • db2secFreeGroupListMemory();
On a server for a GRANT statement
For a GRANT statement that does not specify the USER or GROUP keyword, (for example, "GRANT CONNECT ON DATABASE TO user1"), the Db2 agent process or thread must be able to determine if user1 is a user, a group, or both. Therefore, the Db2 agent process or thread calls the following security plug-in APIs:
  • db2secDoesGroupExist();
  • db2secDoesAuthIDExist();
On a server to get a list of groups to which an authid belongs
From your database server, when you need to get a list of groups to which an authorization ID belongs, the Db2 agent process or thread calls the following security plug-in API with only the authorization ID as input:
  • db2secGetGroupsForUser();
There will be no token from other security plug-ins.