DB2 security, Part 2: Understand the DB2 for Linux, UNIX, and Windows security plug-ins

Learn about the IBM® DB2® for Linux®, UNIX®, and Windows® (DB2) security plug-ins, a new feature introduced in Version 8.2. This article explains what the security plug-ins accomplish and teaches you how to enable and write your own security plug-ins.

Kevin Yeung-Kuen See (see@ca.ibm.com), Software Developer, IBM

Kevin See, CISSP, is a Staff Software Developer at the IBM Toronto Lab working on the DB2 FVT for Kernel team. Prior to that, he worked on the DB2 Security Development team and the DB2 SQL and Catalog Development team. He has been with IBM for nine years. His current focus includes access control and authentication models. He received a M.Math. (Software Engineering) from the University of Waterloo and a B.C.S. from Acadia University. He is an IBM Certified Solutions Developer for XML and Related Technologies, and a DB2 Certified Solutions Expert (DBA for OS/390, DBA for Linux/Unix/Windows, and DB2 Family Application Development). He is also a ISC2 Certified Information Systems Security Professional.



Sushma Narisetty (sushma.narisetty@utoronto.ca), Information Developer, IBM

Sushma Narisetty is a fourth-year Electrical Engineering student at the University of Toronto. She was an Information Developer at the IBM Toronto Lab before leaving to finish her degree. She is an IBM Certified Database Administrator and Application Developer for DB2 Universal Database V8.1 for Linux, UNIX, and Windows.



Raul F. Chong (rfchong@ca.ibm.com), DB2 UDB Specialist, IBM

Raul F. Chong's photoRaul F. Chong is a database specialist from the IBM Toronto Laboratory and works in DB2 UDB Technical Support. Raul has worked for eight years at IBM, and has extensive knowledge in DB2 UDB. Raul has written many articles and is the lead author of the book Understanding DB2: Learning Visually with Examples, and co-author of the book DB2 SQL PL (2nd edition). You can reach him at rfchong@ca.ibm.com.


developerWorks Contributing author
        level

Il-Sung Lee (ilsung@microsoft.com), Program Manager, Microsoft Corporation

Il-Sung Lee, P.Eng, is a Program Manager for Microsoft SQL Server. He was a Staff Software Engineer at the IBM Toronto Lab and had been with IBM for seven years before joining Microsoft. He was a member of the DB2 Security Development team where his areas of interest included Kerberos, authentication models, and code vulnerability exploitation. He received a M.Eng. from McGill University and a B.A.Sc. from the University of British Columbia, both in Electrical Engineering.



18 May 2011 (First published 01 December 2005)

Also available in Vietnamese

Introduction

Part 1 of this article series presents the DB2 security model, and discusses how user and group accounts interact with DB2 for Linux, UNIX, and Windows (DB2). Part 2 of this series focuses on DB2 security plug-ins, the new method that implements DB2 security. This article discusses everything you need to know to have a good understanding of DB2 security plug-ins, the different types of security plug-ins, why they are important, and how to use them. It also includes sample security plug-in programs, and shows you how to implement them step by step. After reading this article, you should be able to write a basic security plug-in and avoid common errors encountered when working with them.


DB2 security plug-ins — The big picture

Security plug-ins are dynamically loadable libraries that DB2 invokes when performing authentication or group membership lookup for a user. Prior to Version 8.2, these operations were managed by a facility external to DB2, such as the operating system, a domain controller, or a Kerberos security system. Figure 1 provides scenarios that illustrate how DB2 security worked prior to Version 8.2. The next sections describe what has changed with Version 8.2.

Figure 1. Security scenarios
Security scenarios

Figure 1 illustrates four security scenarios:

  1. Security considerations when connecting to a database from a client system to a server system
    On the left side of Figure 1, a user has issued the statement connect to mydb user raul using raulpsw from the Command Line Processor (CLP) window of a DB2 client system to connect to database mydb, which resides on the DB2 server Aries. The DB2 client communicates with the server and negotiates which authentication method to use. For simplicity, let's assume the client uses the authentication method returned by the server. In the figure, AUTHENTICATION is set to SERVER. This means that the operating system at the server (I) will perform the authentication by checking if the user ID and password supplied match according to the values stored in the operating system's security database. Once a user is authenticated, DB2 will obtain group membership information from the operating system. From this point forward, DB2 will no longer use the user ID or password for any further checking; instead, DB2 will use the authorization ID (authID). In general, an authID is the uppercase version of a user ID.
  2. Security considerations when performing SQL statements after connecting to the database
    The bottom left part of Figure 1 shows a SELECT statement issued while connected to database mydb with authID RAUL. In this case, the internal DB2 security facility performs an authorization check by reviewing the DB2 Catalog tables to confirm that authID RAUL has been granted the privilege to SELECT from table KEVIN.TABLE1. If authID RAUL and PUBLIC do not have this privilege granted, DB2 will check if this user is part of one of the special groups such as SYSADM, SYSCTRL, SYSMAINT or SYSMON. There are database manager configuration (dbm cfg) parameters for each of these groups, and you can set these parameters to the value of an operating system group. At connection time, the group information for the user is retrieved from the operating system and cached in memory. DB2 will then check that authID RAUL is part of one of these groups by reviewing this cached data (II). For example, if the authID is part of the SYSADM group, the SELECT can continue, otherwise an error message (SQLCODE -551) is returned.
  3. Security considerations when security is performed at the client
    If AUTHENTICATION were set to CLIENT in Figure 1, the operating system at the client machine would perform the authentication (III). The authorization check for the SELECT statement would be performed as before: DB2 would verify that authID RAUL has the SELECT privilege for the KEVIN.TABLE1 table in the DB2 Catalog tables of the database. If authID RAUL and PUBLIC do not have this privilege, group membership check is performed. At connection time, group membership information from the client is passed and cached at the server.
  4. Security considerations when issuing instance-level commands
    At the server in Figure 1, the DB2 instance owner db2inst1 issues the command db2stop. DB2 checks whether the current logged in user belongs to the group that is defined in SYSADM_GROUP, SYSCTRL_GROUP, or SYSMAINT_GROUP.(IV) If the user ID belongs to any of these groups, the db2stop command will successfully execute. Otherwise, an error message is returned. Depending on the instance level operation, the user may have to be part of the SYSADM, SYSCTRL, SYSMAINT or SYSMON groups.

In each scenario, the operating system is called to perform security checks. Starting with Version 8.2, security plug-ins can be used in each of these situations. Instead of the operating system always being invoked, a server and group plug-in could be invoked in scenario 1, a group plug-in may be invoked in scenario 2, and client and group plug-ins can be invoked in scenarios 3 and 4.

This example introduces the three categories of security plug-ins:

  • Server-side authentication security plug-in (server auth plug-in)
  • Client-side authentication security plug-in (client auth plug-in)
  • Group membership lookup security plug-in (group plug-in)

A server auth plug-in performs authentication on the database server. It is also used to check if an authID is known to the plug-in. For example, consider the SQL statement grant select on table user1.t1 to FOO, where DB2 doesn't know whether FOO is a user or group. In this situation, DB2 consults with all server-side plug-ins and group membership plug-ins to check if FOO is a user, a group, unknown, or both, so that it can respond accordingly to the SQL statement.

A client auth plug-in performs authentication on the client. It is also used to perform instance-level local authorization on the database server when instance-level commands are executed (such as db2start, db2stop, db2trc, update dbm cfg, and so on). Therefore, it is common to see both a client auth plug-in and a server auth plug-in specified on a database server.

A group plug-in performs group membership lookup on both the client and the database server. It is also used to check if an authID is known to the plug-in.

Each security plug-in consists of a set of APIs that you need to implement. DB2 provides the security plug-in infrastructure and some default security plug-ins. The implementation of a customized security plug-in is left to your discretion.


Advantages of using security plug-ins

The main advantages of using the new DB2 security mechanism are the flexibility and extensibility that security plug-ins can provide. You can customize the security mechanisms to meet your individual needs, instead of relying on a standard facility like the operating system. For example, prior to Version 8.2, any operating system user logged on to the system could issue a connect statement without passing a user ID and password (known as an implicit connection), and assuming the user ID had the DB2 CONNECT privilege, he could connect successfully. With plug-ins you can change this behavior so that implicit connections are not allowed.

LDAP is another example. LDAP is not currently supported as an authentication method in DB2; however, you can always implement it using a security plug-in. A simple example, using Microsoft Active Directory to implement LDAP-based authentication, is presented later in this article.

Security plug-ins are implemented per instance, therefore you can create different instances, and have different security plug-in implementations. Figure 2 shows the flexibility and extensibility provided by using security plug-ins.

Figure 2. DB2 security plug-ins: Flexibility and extensibility
DB2 security plug-ins: Flexibility and extensibility

Default security plug-ins

After installing or migrating to DB2 Version 8.2, there is no need for you to write your own security plug-ins code or perform any setup. By default, DB2 is configured to use the default security plug-ins that are included. These default security plug-ins invoke the operating system's security APIs, so the default security behavior is exactly the same as in previous DB2 versions.

Figure 3 shows the default plug-ins shipped with DB2, and their locations on a Windows system.

Figure 3. Directory structure for the default security plug-in libraries on Windows
Directory structure for the default security plug-in libraries on Windows

The right panel in each of the windows of Figure 3 shows the different default plug-ins. Table 1 below describes each of these plug-ins.

Table 1. IBM DB2 default plug-ins
Plug-in nameDescription
1IBMOSauthclientThis is the client-side operating-system-based authentication plug-in.
2IBMOSauthserverThis is the server-side operating-system-based authentication plug-in.
3IBMOSgroupThis is the operating-system-based group membership plug-in.
4IBMkrb5This is the Kerberos security plug-in (it has both the client-side and server-side code in the same library).

Any plug-in in Figure 3 that has the suffix "TwoPart" implements the same authentication method as the one without the suffix, but it has added capability for handling two-part authIDs. Two-part authIDs allow for the use of namespaces[c1], so that multiple accounts can use the same authID as long as they are in different namespaces. For example, both DOMAIN1\SUSHMA and DOMAIN2\SUSHMA are valid authIDs for a plug-in that handles two-part authIDs. In the examples, DOMAIN1 and DOMAIN2 are the namespaces (which, in Windows, are generally Windows domains).

If you don't want to use the default plug-ins, you can either write your own security plug-ins, or buy them from a third-party vendor. Regardless of which method you choose, you need to conform to the basic rules set out by DB2 to write security plug-ins. This is discussed in more detail in a later section.


User ID/password plug-ins vs. GSS-API plug-ins

Before you start developing your own plug-ins, you need to understand that authentication using plug-ins can be done in two ways:

  • Using a plug-in based on user ID/password — This implies that a user ID and a password are passed for the plug-ins to check. This is a simpler implementation that is easy to understand; however, only the user ID and password can be sent to the server, and only one server plug-in or client plug-in can be supported.
  • Using a plug-in based on GSS-API— This implies that authentication uses the Generic Security Service Application Programming Interface (GSS-API) standard Version 2, as documented in RFCs 2743 and 2744. GSS-API is a generic API to perform client-server authentication. GSS-API is a standard that addresses the issue of the existence of similar but incompatible security services in use today. The main advantage of using the GSS-API is that by writing to this generic API, your implementation can interoperate with various security systems. Kerberos and PKI already support GSS-API, and in fact, Kerberos authentication in DB2 is implemented using the GSS-API model.
    Another advantage of using this type of plug-in authentication is that any authentication data (including binary data) can be transmitted between the client and the server. The authentication is performed at both the client and the server; therefore you should configure the client and the server to use the same GSS-API plug-in. To configure the client, simply copy the GSS-API plug-in into the client plug-in directory. At the server, an ordered list of GSS-API plug-ins is specified in the SRVCON_GSSPLUGIN_LIST database manager configuration parameter. If a client has more than one GSS-API plug-in copied, the server determines which one to use, based on the ordered list. Figure 4 illustrates this concept.
Figure 4. GSS-API plug-ins specified at the client and server systems.
GSS-API plug-ins specified at the client and server systems

The figure shows three DB2 clients using different GSS-API plug-ins, and a DB2 server with a list of the GSS-API plug-ins it supports. When client #1 connects to the server, it will go through the server's list of plug-ins in order from left to right until it finds the one that matches the client's, and then uses it. Thus for this client it finds that the first plug-in supported by the server is ABC, and it matches ABC.dll, so it chooses this one. There is no need to go further down the list, even though plug-in DEF is also supported at both client and server. For client #3, an error (sqlcode -30082 reason code 15) is returned, since there is no matching GSS-API plug-in between the client and the server.

A DB2 server instance will only be able to support one user ID/password authentication module, but will be able to support a list of GSS-API plug-ins. However, only one plug-in in the list can be a Kerberos plug-in. DB2 client applications will also only be able to support one user ID/password module, but will negotiate with the server for a particular GSS-API plug-in.

GSS-API plug-ins are more complex, and a good understanding of the non-trivial GSS-API concept is required.


New features available in customized security plug-ins

As a result of the new security plug-in model introduced in Version 8.2, you can:

  • Perform userID, password, and namespace remapping on the client. This is only applicable to plug-ins based on user ID/password. This feature finds particular use in a three-tier system where the Web server and the DB2 client form the middle tier. An example of user ID, password, and namespace remapping is illustrated in example 1 of the Examples section, where user sugsc1ch and his password are remapped by the client plug-in to user Newton and his password before sending the connect request to the server.
  • Perform authID remapping on the server. This feature allows different user IDs to share the same authorization ID on the database server once authenticated. This feature is demonstrated in the tests for example 1 of the Examples section. This feature is useful, for example, when there are employees in a department who have rotating shifts and perform similar tasks every day requiring the same privileges. By using this feature, you can authenticate them all independently and use the privileges associated with the common authID to perform their tasks. To find out which employee performed which task and when, DB2 allows the server-side plug-in to return the real name, which is then audited. For more information, refer to the db2secGetAuthid API documentation.
  • Use user namespaces (for example, DOMAIN\user). This was discussed earlier in the section Default security plug-ins.
  • Refuse connections based on communications information. This feature can be used when you want to allow only a few IP addresses to be logged into the database at a particular time. Example 2 in the Examples section illustrates how you can implement this.

Steps to create a DB2 security plug-in

There are six steps to create a DB2 security plug-in. Each of these steps is explained in more detail in the following sections:

  1. Include the security plug-in header files in your plug-in:
    • sqllib/include/db2secPlugin.h
    • sqllib/include/gssapiDB2.h
      Note: You need gssapiDB2.h only if you are implementing the GSS-API-based security plug-in.
  2. Write the APIs constituting your plug-in. You need to write an appropriate initialization API and the remaining set of APIs required for your server, client, or group plug-in.
  3. Populate the function pointer structure before returning to DB2.
    • Indicate the plug-in API version used by the plug-in.
    • Indicate the plug-in type, such as user ID/password, GSS-API, Kerberos
  4. Compile the plug-in source and create a shared library. Compile as 32-bit or 64-bit to correspond with the application/server instance.
  5. Place the library in the appropriate directory.
  6. Enable the plug-ins by updating database manager parameters.

Step 1: Include the security plug-in header files in your plug-in

db2secPlugin.h and gssapiDB2.h are the two header files needed to implement customized security plug-ins. The gssapiDB2.h header file is needed only if you are building a GSS-API plug-in. Figure 5 shows the location of the two required header files for implementing security plug-ins on a Windows system.

Figure 5. The plug-in header files location on a Windows system
The plug-in header files location on a Windows system

Step 2: Write the APIs constituting your plug-in

Depending on whether you are working on a server plug-in, client plug-in, or group plug-in, you will need to code the following APIs respectively to initialize the plug-in:

  • db2secServerAuthPluginInit
  • db2secClientAuthPluginInit
  • db2secGroupPluginInit

For example, db2secServerAuthPluginInit API can be coded in the following way:

Listing 1. db2secServerAuthPluginInit
SQL_API_RC SQL_API_FN db2secServerAuthPluginInit(
   db2int32             version,
   void*                server_fns,
   db2secGetConDetails* getConDetails_fn,
   db2secLogMessage*    logMessage_fn,
   char**               errormsg,
   db2int32*            errormsglen)
{
   struct userid_password_server_auth_functions_1
      *fns = (struct userid_password_server_auth_functions_1*) server_fns;

   condetails_fn = getConDetails_fn;
   logMessage_Fn = logMessage_fn;

   fns->version    = DB2SEC_API_VERSION;
   fns->plugintype = DB2SEC_PLUGIN_TYPE_USERID_PASSWORD;
   fns->db2secDoesAuthIDExist      = &is_user;
   fns->db2secFreeErrormsg         = &free_error_message;
   fns->db2secFreeToken            = &free_token;
   fns->db2secGetAuthIDs           = &getauthids;
   fns->db2secServerAuthPluginTerm = &terminate_plugin;
   fns->db2secValidatePassword     = &validatePassword;

   /* Example on how to use logMessage_fn */
   /* Will log the init successful information into db2diag.log at DIAGLEVEL 3 */
   (logMessage_Fn)(DB2SEC_LOG_WARNING,
                   "db2secServerAuthPluginInit successful",
                   strlen("db2secServerAuthPluginInit successful"));

   return DB2SEC_PLUGIN_OK;
}

DB2 calls the db2secServerAuthPluginInit API to initialize the server plug-in library after it is loaded by DB2. The above code is obtained from the file txtserver.c, which is included in the ZIP file attached at the end of this article.

In addition to the initialization functions, there are several plug-in APIs that you need to implement for the server, client, and group plug-ins. In addition, there are specific APIs for user ID/password authentication, and for GSS-API authentication. Figures 6, 7, and 8 describe what these functions do.

Note: The DB2 manuals have a section that describes in detail how to develop security plug-ins, as well as explanations of the security plug-in APIs. Those details are outside the scope of this article. This section presents only a simplified plug-in API overview.

Figure 6. Group membership lookup plug-in
Group membership lookup plug-in
Figure 7. Client plug-in
Client plug-in
Figure 8. Server plug-in
Server plug-in

Step 3: Populate the function pointer structure before returning to DB2

The function pointer returns pointers to all the APIs required for the particular plug-in library that you have implemented. For example, in the case of group plug-ins, it contains pointers to your implementations of the db2secDoesGroupExist, db2secFreeErrormsg, db2secFreeGroupListMemory, db2secGetGroupsForUser, and db2secPluginTerm APIs.

The file txtgroup.c, which is included in the ZIP file attached at the end of this article, provides an example of how you can populate the functions pointer for the group plug-in library. Here is a snippet of this code.

fns->version = DB2SEC_API_VERSION;
fns->db2secDoesGroupExist      = &is_group;
fns->db2secFreeErrormsg        = &free_error_message;
fns->db2secFreeGroupListMemory = &free_group_list;
fns->db2secGetGroupsForUser    = &get_groups;
fns->db2secPluginTerm          = &terminate_plugin;

Step 4: Compile the plug-in source and create a shared library

Once you've finished coding your security plug-in, compile it as either a 32-bit or 64-bit library to correspond with your DB2 instance. The library must have the same name as the plug-in name. Libraries must be shared libraries with the appropriate platform-specific extension. For example, if the name of your plug-in is myPlugin, then the following extensions are required:

  • myPlugin.dll (Windows)
  • myPlugin.a (AIX)
  • myPlugin.so (Linux, AIX, Sun Solaris, HP-UX
  • myPlugin.sl (HP-UX)

Libraries must be threadsafe (re-entrant) and C-linkage must be used (at least for the initialization functions).

Step 5: Place the library in the appropriate directory

You must place security plug-in libraries in specific directories:

  1. Windows:
    • sqllib\security\plugin\<instance name>\client
    • sqllib\security\plugin\<instance name>\server
    • sqllib\security\plugin\<instance name>\group

    For the IBM supplied default plug-ins:

    • sqllib\security\plugin\IBM\client
    • sqllib\security\plugin\IBM\server
    • sqllib\security\plugin\IBM\group
  2. 32-bit Linux and UNIX:
    • sqllib/security32/plugin/client
    • sqllib/security32/plugin/server
    • sqllib/security32/plugin/group

    For the IBM supplied default plug-ins:

    • sqllib/security32/plugin/IBM/client
    • sqllib/security32/plugin/IBM/server
    • sqllib/security32/plugin/IBM/group

In Linux and UNIX, similar directories for 64-bit libraries are used as above, except that the subdirectory name security64 is used instead of security32. On Windows 64-bit instances, both 32-bit and 64-bit plug-ins will be in the same directory, but the 64-bit plug-ins will be added with a '64' suffix, for example, myplugin64.dll.

Note: The IBM subdirectory (under the plugin directory) is reserved for the default plug-ins provided by IBM. Any other customized plug-in placed in this directory will be ignored.

Step 6: Enable the plug-ins by updating database manager parameters

Prior to Version 8.2, the authentication database manager configuration parameter dictated the location and mechanism with which CONNECT/ATTACH, group lookup, and local authorization checks were performed. With Version 8.2, more configuration parameters are available, providing more flexibility in choosing the authentication options.

Table 2 provides a list of the database manager configuration parameters that apply to plug-ins, and an explanation of how they apply to security plug-ins.

Table 2. Security plug-in database manager configuration parameters description
Parameter nameDescription
1Client user ID/password plug-in (CLNT_PW_PLUGIN) If this value is set at the client, and the AUTHENTICATION parameter at the server is set to CLIENT, this parameter indicates the user ID/password plug-in to use for authentication to be performed at the client. If this value is set at the server, this parameter indicates the user ID/password plug-in to use for checking of authorization of instance operations such as db2start. The client side plug-in is also used on the database server during a database connection issued locally on the database server (local connection).
2Client Kerberos plug-in (CLNT_KRB_PLUGIN) The value of this parameter specifies the name of the Kerberos plug-in library to be used for client-side authentication and local authorization. This plug-in is used when the client is authenticated using KERBEROS or KRB_SERVER_ENCRYPT authentication. The default value on Windows is IBMkrb5. On other platforms, the default value is NULL.
3Group plug-in (GROUP_PLUGIN) The value of this parameter specifies the group plug-in library to be used for group membership lookup.
4GSS-API plug-in for local authorization (LOCAL_GSSPLUGIN) The value of this parameter specifies the name of the GSS-API plug-in library to be used for instance-level local authorization when the value of the AUTHENTICATION database manager configuration parameter is set to GSSPLUGIN or GSS_SERVER_ENCRYPT.
GSSPLUGIN indicates that the server will only authenticate using a GSS-API based plug-in with which it is familiar.
GSSPLUGIN_SERVER_ENCRYPT indicates that the server will additionally accept encrypted user ID/password requests; this type is made available primarily for down-level compatibility.
5Server plug-in mode (SRV_PLUGIN_MODE)This parameter specifies whether to run in fenced or unfenced mode. The default value — and the only supported value — is UNFENCED.
6Server list of GSS-API plug-ins (SRVCON_GSSPLUGIN_LIST)This parameter specifies a comma-separated list of GSS-API plug-in libraries that are supported by the database server. The list can contain only one Kerberos plug-in. If this parameter is blank, and AUTHENTICATION is set to KERBEROS or KRB_SVR_ENCRYPT, the default DB2 Kerberos plug-in (IBMkrb5) will be used.
7Server user ID/password plug-in (SRVCON_PW_PLUGIN) The value of this parameter specifies the user ID/password plug-in library to be used for server-side authentication.
8Server connection authentication (SRVCON_AUTH)The value of this parameter is used for connections only. It overrides the authentication method that is specified in AUTHENTICATION. Local instance operations still use the method specified in AUTHENTICATION. The default value is NOT_SPECIFIED.
9Database manager authentication (AUTHENTICATION)The value of this parameter specifies how and where a user's authentication is going to take place for checking a local instance authorization. The default value is SERVER.

Table 3 shows the steps you would take to enable user ID/password authentication plug-ins using the above listed configuration parameters.

Table 3. Steps to enable user ID/password authentication plug-ins
Steps on the clientSteps on the server
1Update CLNT_PW_PLUGIN with the client plug-in name.
If CLNT_PW_PLUGIN is left blank, it will default to IBMOSauthclient, the plug-in provided by IBM.
Update SRVCON_PW_PLUGIN with the server plugin name.
2
Set SRVCON_AUTH to a system authentication type (CLIENT, SERVER, SERVER_ENCRYPT, DATA_ENCRYPT, or DATA_ENCRYPT_CMP), or set SRVCON_AUTH to NOT_SPECIFIED and set AUTHENTICATION to a system authentication type.
If SRVCON_PW_PLUGIN is left blank, it will default to IBMOSauthserver, the plug-in provided by IBM.

Table 4 shows the steps you would take to enable group membership lookup plug-ins using the above listed configuration parameters.

Table 4. Steps to enable group membership lookup plug-ins
Steps on the clientSteps on the server
1Update GROUP_PLUGIN with the name of the group plug-in.
If GROUP_PLUGIN is left blank, it will default to IBMOSgroups, the plug-in provided by IBM.
Update GROUP_PLUGIN with the name of the group plug-in.
If GROUP_PLUGIN is left blank, it will default to IBMOSgroups, the plug-in provided by IBM.

Table 5 shows the steps you would take to enable GSS-API authentication plug-ins using the above listed configuration parameters.

Table 5. Steps to enable GSS-API authentication plug-ins
Steps on the clientSteps on the server
1Place the plug-in library in the client plug-in directory.Place the plug-in library in the server plug-in directory.
2Optional: Catalog a database indicating that the client will only use a GSS-API plug-in for authentication. For example: db2 catalog db testdb at node testnode authentication gssplugin
Multiple plug-ins may exist on the client. In this case, the server will dictate which one is used.
Update SRVCON_GSSPLUGIN_LIST with an ordered list of supported plug-in names. To enable the GSS-API plug-in, you can either:
  • Set SRVCON_AUTH to a GSSPLUGIN, or
  • Set SRVCON_AUTH to NOT_SPECIFIED, and set AUTHENTICATION to GSSPLUGIN.
To enable local authorization:
  1. Place the client plug-in library in the client plug-in directory.
  2. Update LOCAL_GSSPLUGIN with the name of this plug-in.

Table 6 shows the steps you would take to enable Kerberos authentication plug-ins using the above listed configuration parameters.

Table 6. Steps to enable Kerberos plug-ins
Steps on the clientSteps on the server
1Place the plug-in library in the client plug-in directory.Place the plug-in library in the server plug-in directory.
2Update CLNT_KRB_PLUGIN with the name of the Kerberos plug-in.
  • If CLNT_KRB_PLUGIN is blank, then DB2 assumes that the client is incapable of using Kerberos.
  • The default Kerberos plug-in provided by DB2 is named IBMkrb5.
  • For platforms supporting Kerberos, the IBMkrb5 library will already be present in the client plug-in directory.
Update SRVCON_GSSPLUGIN_LIST with the server Kerberos plug-in name.
3Optional: Catalog a database indicating that the client will use the Kerberos plug-in for authentication. For example: db2 catalog db testdb at node testnode authentication kerberos target principal service/host@REALMSet SRVCON_AUTH to KERBEROS or KRB_SERVER_ENCRYPT, or set SRVCON_AUTH to NOT_SPECIFIED and set AUTHENTICATION to KERBEROS or KRB_SERVER_ENCRYPT.

Examples that demonstrate how to implement simple security plug-ins

The ZIP file accompanying this article includes the source code of the plug-ins used in this section and a README file with more information about them.

Example 1: Implementing a simple user ID/password security plug-in

Required files: txtserver.c, txtclient.c, txtcommon.c, and txtplugin_makefile.

You will need to implement both a server-side and a client-side plug-in as follows.

  1. Open txtcommon.c and modify the following line to include your user ID and password. Leave the authID as REMAP. Change myuserid to your user ID and er9etw0 to your password.
    { 0, 0, "REMAP", "REMAP", "myuserid", "er9etw0", "build" }
  2. Create a subdirectory under the C:\...\sqllib\security\plugins directory, naming the new directory after your instance name.
  3. Create two subdirectories called client and server under the subdirectory you created in the previous step.
  4. Issue the following commands from a DB2 Command Window to create the noplatos and sample databases:
    • db2start
    • db2 create db noplatos
    • db2sampl
    • db2stop
  5. Rename the file txtplugin_makefile as makefile.
  6. Compile txtserver.c by issuing the following command:
    nmake /f makefile txtserver
    Copy the generated txtserver.dll to the C:\...\sqllib\security\plugins\<instance_name>\server directory so that DB2 can find it.
  7. Update the database manager configuration parameters by issuing the following command from the DB2 Command Window:
    db2 update dbm cfg using srvcon_auth server srvcon_pw_plugin txtserver
  8. Issue the following commands from the DB2 Command Window to ensure that your configuration changes come into effect:
    • db2 terminate
    • db2stop
    • db2start
  9. You are now ready to test your server-side user ID/password authentication plug-in. Issue the following commands/statements from the DB2 Command Window.
    1. db2 connect to sample user <your user ID> using <your password>
      This statement should return the authID mapping for your user ID. The db2secGetAuthIDs API retrieves the authID from the table in txtcommon.c. You should get the output shown in Figure 9:
Figure 9. Test db2secGetAuthIDs API
Test db2secGetAuthIDs API
  1. db2 connect to noplatos user plato using er9etw0
    This statement will fail with sqlcode 30082 reason code 25. The user ID plato cannot access the noplatos database if the server side plug-in is invoked for authentication. This occurs because of the code in the validatePassword function in txtserver.c, which restricts the user plato from accessing the noplatos database.
  2. db2 connect to sample user plato using er9etw0
    This statement will succeed. User ID plato can access databases other than noplatos when the server side plug-in is invoked for authentication. Figure 10 shows the output for this case.
Figure 10. Test to show plato's restricted access to noplatos
Test to show plato's restricted access to noplatos
  1. Compile txtclient.c by issuing the following command:
    nmake /f makefile txtclient
    Copy the generated txtclient.dll to the C:\...\sqllib\security\plugins\<instance_name>\client directory so that DB2 can find it.
  2. Update the database manager configuration parameters by issuing the following command from the DB2 Command Window:
    db2 update dbm cfg using srvcon_auth client clnt_pw_plugin txtclient
  3. Issue the following commands from the DB2 Command Window to ensure that your configuration changes come into effect:
    • db2 terminate
    • db2stop
    • db2start
  4. You are now ready to test your client-side user ID/password authentication plug-in. Issue the following commands from the DB2 Command Window.
    1. db2 connect to sample user sugsc1ch using cdsecpwd

      The db2secRemapUserid API is called, and user sugsc1ch with password cdsecpwd is remapped to user newton with password er9etw0 and then the authID for newton is used to connect to the database. This functionality is implemented in the remap_userid function of txtclient.c as follows:

      /* remap the userid sugsc1ch to newton */
      else if (!strncmp("sugsc1ch", userid, 8) &&
              !strncmp("cdsecpwd", password, 8))
      {
           /* this is for testing purposes only: userid sugsc1ch/cdsecpwd
            normally has no privileges, but I am going to remap it to
            newton/er9etw0 so that it will be allowed to connect if
            server plugin is txtserver, and fail if the os plugin is used */
      
            strcpy(userid, "newton");
            strcpy(password, "er9etw0");
            *useridlen = strlen(userid);
            *passwordlen = strlen(password);
      }

      This statement will succeed and the output should like in Figure 11.

Figure 11. Test db2secRemapUserid API
Test db2secRemapUserid API
  1. db2 connect to noplatos user plato using er9etw0
    This statement will succeed, as the restriction on user 'plato' to connect to 'noplatos' is implemented in the server-side plug-in and not in the client-side plug-in.
  2. db2 connect to sample
    This statement will succeed. It calls the db2secGetDefaultLoginContext API to get the authID of the user invoking the connection, and uses it to connect to the database sample.

Example 2: Implementing a simple group security plug-in

Required files: txtgroup.c, txtserver,c, txtclient.c, txtcommon.c, and txtplugin_makefile.

This example builds on example 1, so perform the steps in example 1 before proceeding with the following steps.

  1. Create a subdirectory called "group" under the "DB2" subdirectory created in step 2 of example 1.
  2. Compile txtgroup.c by issuing the following command:
    nmake /f makefile txtgroup
    Copy the generated txtgroup.dll to the C:\...\sqllib\security\plugins\<instance_name>\group directory so that DB2 can find it.
  3. Update the database manager configuration parameters by issuing the following commands from the DB2 Command Window:
    • db2 update dbm cfg using srvcon_auth server
    • db2 update dbm cfg using srvcon_pw_plugin txtserve
    • db2 update dbm cfg using sysadm_group build
    • db2 update dbm cfg using group_plugin txtgroup
  4. Issue the following commands from the DB2 Command Window to ensure that your configuration changes come into effect:
    • db2 terminate
    • db2stop
    • db2start
  5. You are ready to test your group plug-in now. Issue the following commands/statements from the DB2 Command Window. (Note: The user newton belongs to the group build, which is sysadm, and user2 belongs to the group doody and some other groups)
    • db2 connect to sample user newton using er9etw0
      db2 "create table t1 (x int)"
      db2 terminate

      Figure 12 shows the output of this step:
Figure 12. Test newton's group membership and authorizations
Test newton's group membership and authorizations
  • db2 connect to sample user user2 using er9etw0
    db2 "select * from newton.t1"
    db2 terminate

    Figure 13 shows the output of this step:
Figure 13. Test user2's authorizations
Test user2's authorizations
  • db2 connect to sample user newton using er9etw0
    db2 grant select on t1 to group doody
    db2 terminate

    Figure 14 shows the output of this step:
Figure 14. Test newton's authorizations to grant privileges
Test newton's authorizations to grant privileges
  • db2 connect to sample user user2 using er9etw0
    db2 "select * from newton.t1"
    db2 terminate

    Figure 15 shows the output of this step:
Figure 15. Test user2's newly granted privileges
Test user2's newly granted privileges

Steps to test connection restriction ability of the plug-in

This will test all the three (server, client, and group membership lookup) plug-ins.

Add the following lines to your C:\windows\system32\drivers\etc\services file:
xregress 23542/tcp
xregress_int 23543/tcp

Issue the following commands from the DB2 Command Window as illustrated in Figure 16:
db2 terminate
db2stop
db2 update dbm cfg using clnt_pw_plugin txtclient srvcon_pw_plugin txtserver group_plugin txtgroup sysadm_group build
db2set DB2COMM=TCPIP
db2 update dbm cfg using svcename xregress
db2 catalog tcpip node thisnode remote <your machine name> server xregress
db2 catalog db sample as loopback at node thisnode
db2 terminate
db2start

Figure 16. Set up connection restriction ability
Steps to setup connection restriction ability

The above steps let you call back to DB2 to get the client IP address. You can then add your required logic and block any connection that does not fit the allowed pattern.

Now if you issue db2 connect to loopbackdb user beauvoir using er9etw0, you should get the output illustrated in Figure 17.

Figure 17. Test connection restriction ability
Test connection restriction ability

The above scenario calls the validatePassword function (which corresponds to the db2secValidatePassword API) in txtserver.c. The implementation of this function says if the userid beauvoir tries to connect from a remote client that has an IP address that is the same as the IP address of the database server, then block it. In a real-life scenario, you would code validatePassword function such that you have a list of allowed IP addresses or disallowed IP addresses, and check against that list before blocking a particular user from accessing the database.

Example 3: Implementing a plug-in based on Active Directory

Required files: ldap.c, ldap_makefile.

Active Directory is Microsoft's implementation of an LDAP server and is present on all domain controllers. It contains domain account, group, and computer information. Active Directory supports the LDAP v2 and v3 API set. This example will use LDAP_VERSION3.

This example assumes that you understand the basic concepts of LDAP and know how to set up an active directory. The serverwatch.com tutorial "Quick Start Guide to Setting up Active Directory" (see Resources) provides a good reference.

When an application uses the LDAP server for authentication, it generally uses the binding to communicate with the server, and unbinding from the server to close the connection.

Typically, the 4 steps taken by an application during authentication using active directory are:

  1. Open a connection to the LDAP server.
  2. Authenticate against the LDAP server.
  3. Perform some operations, such as obtaining search results.
  4. Close the connection.

This example plug-in uses the following API functions:

  1. ldap_init — Initializes for a connection to the LDAP server.
  2. ldap_connect — Connects to an LDAP server.
  3. ldap_bind_s — Synchronously binds to the LDAP server.
  4. ldap_unbind_s — Closes the connection to the LDAP server.

This example is a server-side authentication plug-in that authenticates the user ID and password against a LDAP server.

This example assumes an IP address of 199.43.208.178 and a port number of 389 for the LDAP server. All 4 steps are implemented in db2secValidatePassword.

Steps in db2secValidatePassword:

  1. Call ldap_init using the default port and the IP address of the LDAP server.
  2. Call ldap_set_option to set the protocol version to LDAP_VERSION3.
  3. Connect to the LDAP server using ldap_connect.
  4. Before you can bind to the LDAP server, you must translate from a Microsoft Security Accounts Manager (SAM) account name form (optionally with a namespace) to LDAP distinguished name format. An example of distinguished name is "cn = Il-Sung Lee, o = Microsoft, cn = US". If a namespace is not provided as part of the user ID string when connecting, you will need to call the Windows API function LookupAccountNameA to locate the namespace where this user ID is defined. Once the namespace and user ID are both available, call the Windows API function TranslateNameA to perform the translation.
  5. Bind to the LDAP server. The authentication method used is LDAP_AUTH_SIMPLE. If the user-supplied password matches the LDAP server password for the corresponding distinguished name, then the bind function will return LDAP_SUCCESS. Otherwise, the bind function can return one of the return codes listed on the Microsoft Developer Network (see Resources).
  6. Close the connection to the LDAP server using ldap_unbind.

All other required security plug-in API calls are straightforward to implement and similar to the simple user ID/password authentication plug-in. This article will not go into those details.

Also note that DB2 allows local connection to succeed without a user ID and password being provided. This is known as implicit connect. In an implicit connection, DB2 will provide the current logged-in user details to the server-side security plug-in. To determine which user is currently logged in, DB2 calls the client-side authentication plug-in API function db2secGetDefaultLoginContext. In this example, we will default to the client-side plug-in provided by IBM to do the work.

In order to enable the plug-in to handle this case, you need to perform one more step before calling ldap_init. Use the "get client connection details" callback function, provided by DB2, to find out if the client is local to this machine. The code to do this is shown below.

rc = pConDetails( DB2SEC_API_VERSION, &conDetails);
if( rc == DB2SEC_PLUGIN_OK )
{
  if( ( conDetails.connect_info_bitmap & DB2SEC_CONNECTION_ISLOCAL ) 
  && ( conDetails.connect_info_bitmap &
  (DB2SEC_VALIDATING_ON_SERVER_SIDE ) && ( passwordlen == 0 ) )
  {
    goto exit;
  }
}

To compile and build this plug-in library, you can use the ldap_makefile supplied in the download below. Rename it as makefile, and copy in bldplugin.bat from sqllib\samples\security\plugins directory. Issue the make ldap command that will use the make with bldplugin.bat to build the library.

Perform the following steps to use this simple LDAP-based server-side user ID/password authentication plug-in:

To set up the server-side plug-in:

  1. Install the LDAP plug-in library in the correct location mentioned earlier in this article.
  2. Update the srvcon_pw_plugin parameter with the name of the LDAP plug-in.
  3. Set either the srvcon_auth parameter or the AUTHENTICATION database manager configuration parameter to server.

To set up the client-side plug-in:

  1. Log in to the domain
  2. Update the database manager configuration parameter clnt_pw_plugin to NULL, to default to the client-side authentication plug-in provided by IBM.

If you are planning to test the plug-in locally on the database server, you will have to perform the client-side setup on the database server machine too. The reason for this is that, for local authorization, this example uses the client plug-in on the database server. Therefore, you should have a client version of the appropriate plug-in type, according to the value you specified in the database manager configuration parameter AUTHENTICATION. For example, if you have a database server where authentication is specified as kerberos, you will need to ensure that clnt_krb_plugin is set to either IBMkrb5 (the IBM-supplied Kerberos plug-in) or the name of your Kerberos plug-in. You also need to ensure that the plug-in is installed into the client plug-in directory on the database server. Otherwise, instance-level operations such as db2start will fail.

Once you have set up the plug-in on both the client and database server, issue a connect statement to test the plug-in.

Example 4: Using the Kerberos plug-in to further explain the DB2 implementation of GSS-API standard and DB2 specific extension

Kerberos is a third-party network authentication protocol that employs a system of shared secret keys to securely authenticate a user in an insecure network environment. It uses a three-tier system in which encrypted tickets (provided by a separate server called the Kerberos Key Distribution Center, or KDC for short) are exchanged between the application server and client rather than text user ID and password pairs. These encrypted service tickets (credentials) are only understood by the client and the server, so there is minimal security risk, even in the event that the ticket is intercepted from the network.

One key feature of Kerberos is that it permits a single sign-on environment whereby a user need only verify his identity to the resources within the Kerberos realm once. With DB2, this means that a user will be able to connect to a DB2 server without providing a user ID or password. Single sign-on connection is a feature often requested by customers and currently not available through DB2 (client authentication is normally not a consideration as it is often not a viable option for customers). Another strong incentive for using Kerberos is that it provides a central repository for user IDs (or principals) thus centralizing and simplifying principal administration. Furthermore, Kerberos supports mutual authentication, which allows the client to validate the identity of the server.

In Version 8.2, with the new DB2 security plug-in paradigm, Kerberos support will be provided as a GSS-API plug-in. The existing Windows 2000 support is re-implemented as a GSS-API plug-in, and three additional platforms will be supported: AIX 5.2, Solaris 8, and Red Hat Enterprise Linux Advanced Server 2.1.

The basic idea of how Kerberos works is illustrated in Figure 18.

Figure 18. Kerberos authentication overview
Kerberos authentication overview

The purpose of this section is to use the Kerberos plug-in to demonstrate how a GSS-API based authentication plug-in is expected to behave. For Kerberos, a credential is referred to the Kerberos ticket. There are other forms of credentials, depending on the specific GSS-API implementation. For example, in a Public Key Infrastructure implementation (PKI), a credential is a certificate that is granted by the Certificate Authority (CA) or Registration Authority (RA).

Basic GSS-API authentication flow

Table 7 provides a simplified illustration of the basic client-server flows involved in the GSS-API authentication process. Note that the tokens are opaque binary data, and only the underlying security mechanism needs to be able to interpret them.

Table 7. Client-server flows involved in the GSS-API authentication process
ClientServer
1. Obtain the client's initial credentials (not covered by GSS-API).
1. Obtain the server's credentials (gss_acquire_cred).
2. Obtain the credentials from the server (gss_init_sec_context).-->3. Verify and accept client credentials (gss_accept_sec_context). Return mutual authentication token if requested.
4. Establish context, or mutual authentication (gss_init_sec_context).<--
5. Delete context and clean up.
5. Delete context and clean up.

DB2 and GSS-API -- Basic Flow

Table 8 shows the steps involved in a client-server flow when DB2 is involved in the GSS-API authentication process. The server obtains its principal name and credential handle at plug-in initialization time (db2secServerAuthPluginInit). Note that on the server, plug-ins are loaded and initialized as part of the start database manager operation (db2start).

Table 8. Client-server flows when DB2 is involved in the GSS-API authentication process
ClientServer
1. Obtain the client's initial credentials if necessary (db2secGenerateInitialCreds), otherwise, obtain the default login context (db2secGetDefaultLoginContext).
2 . Process the server principal name (db2secProcessServerPrincipalName)
3. Obtain the credentials from the server (gss_init_sec_context)


--> 4. Local authorization problem
5. Obtain the authIDs for the principal initiating the context (db2GetAuthIDs) and obtain group membership information for the principal by calling the group membership plug-in (db2secGetGroupsForUser).
6. Perform mutual authentication if required (gss_init_sec_context) <--
7. Delete the context (gss_delete_sec_context) and clean up by calling gss_release_buffer, gss_release_name, and db2secFreeToken. If the user ID and password are explicitly specified, also call db2secFreeInitInfo during the cleanup phase.
7. Delete the context (gss_delete_sec_context) and clean up by calling db2secFreeToken. Also call the group membership plug-in API function db2secFreeGroupList, to clean up memory that was allocated during the call to get group membership.

The source code of the Kerberos plug-in for UNIX and Linux is provided as a sample under sqllib/samples/security/plugins/IBMkrb5.c.

Restrictions imposed on GSS-API plug-ins by DB2

GSS-API is a standard that DB2 supports. However, DB2 imposes restrictions on how the GSS-API functions are implemented. These restrictions include:

  1. The default security mechanism is assumed, thus there is no OID consideration.
  2. The only GSS services requested in gss_init_sec_context() are mutual authentication and delegation. DB2 will request a ticket for delegation, but will never use that ticket to generate a new ticket.
  3. Only the default context time is requested.
  4. Context tokens from gss_delete_sec_context() are not sent from the client to the server and vice-versa.
  5. Anonymity is not supported.
  6. Channel binding is not supported.
  7. If initial credentials expire, DB2 will not automatically renew them.
  8. GSS-API requires that even if gss_init_sec_context() or gss_accept_sec_context() fails, it may return a token to send to the peer. In such a case, you must send a token. However, because of the limitations within a DRDA framework, you can only manage to do this if gss_init_sec_context() fails and generates a token on the first call.

Usage restrictions on security plug-ins

  1. The admin server is not enabled for plug-ins. Therefore, any action through the Control Center (or another Center) that occurs through the admin server (rather than over a database connection) will prompt for a user ID and password that will be validated against the local OS (on Unix, /etc/passwd). Unfortunately, when the Control Center prompts for a user ID and password, it is not clear if it will be used for a database connection or to connect to the admin server, and it's often hard to predict which one will be used.
  2. Java client (JCC) does not support the GSS-API plug-in for versions prior to V8 FP11. From V8 FP11 onwards, the type 4 native Java client can implement a Java version of GSS-API plug-in. However, the type 4 driver supports Kerberos for versions prior to V8 FP11. Note that the JCC client does not support customized user ID/password-based security plug-ins for authentication or customized group lookup security plug-ins.
  3. Other DB2 products (such as DB2 on Z-series, I-series, or VM/VSE) do not support any form of security plug-ins. They also do not support the GSS-API plug-in authentication method, except Kerberos.
  4. Q replication does not work with security plug-ins.
  5. The default plug-ins shipped with DB2 do not support LDAP authentication. Thus, to be able to use LDAP authentication, you need to write your own plug-in and enable it for DB2 to use it.

Real-life scenarios

Scenario 1: Use of down-level and upgraded clients with GSS-API plug-in

You have a lot of clients, some of which are upgraded and some of them are not upgraded, and they all want to use the GSS-API plug-in on the database server. Prior to using the GSS-API plug-in, they used client, server, or server_encrypt authentication. (The following example uses down-level client c1, V8.2 client c2 and V8.2 server s1 to illustrate the scenario).

Down-level client c1:

  1. No need to do anything if the database is not catalogued with authentication client. If it is catalogued with the authentication client, re-catalog the database without specifying an authentication clause, or use the server or server_encrypt authentication options.

Version 8.2 client c2:

  1. Install the client-side GSS-API plug-in(s) in the client plug-in directory.

Version 8.2 server s2:

  1. Install the server-side GSS-API plug-in(s) in the server plug-in directory.
  2. Update the database manager configuration parameter srvcon_gssplugin_list with the ordered list of the supported GSS-API plug-in name. Note that the list should be in the order of preference.
  3. Update the database manager configuration parameter srvcon_auth to GSS_SERVER_ENCRYPT. This will enable the server to handle the new client using the GSS-API plug-in, and still use the SERVER_ENCRYPT to deal with other clients (including down-level clients) that do not support the GSS-API plug-in.

Scenario 2: V8.2 client communicating with a database in a different instance with different authentication setting

This scenario uses Version 8.2 client (c1) and three databases (dbase1, dbase2, dbase3, which belong to instances inst1, inst2, inst3, respectively).

Instance inst1 wants to use srvcon_auth = server_encrypt.

  1. Install the server-side user ID/password authentication plug-in (for example, server_upw) in the server plug-in directory.
  2. Update the database manager configuration parameter server_pw_plugin with the name of the plug-in.
  3. Update the database manager configuration parameter srvcon_auth to server_encrypt.

Instance inst2 wants to use srvcon_auth = kerberos.

  1. Install the server-side Kerberos plug-in (for example, krb) in the server plug-in directory.
  2. Update the database manager configuration parameter srvcon_gssplugin_list with the name of the server-side Kerberos plug-in.
  3. Update the database manager configuration parameter srvcon_auth to Kerberos.

Instance inst3 wants to use srvcon_auth = gssplugin.

  1. Install the server-side GSS-API plug-in (for example, krb, gss1, or gss2, or any combination) in the server plug-in directory.
  2. Update the database manager configuration parameter srvcon_gssplugin_list with the name of the server-side GSS-API plug-ins in the order of preference. For example, if you prefer gss2 to krb to gss1, update the database manager configuration parameter using srvcon_gssplugin_list 'gss2,krb,gss1'. Notice that the krb can be the same Kerberos-based plug-in from inst2. Since Kerberos is implemented using a GSS-API infrastructure, it can be used as a GSS-API plug-in.
  3. Update the database manager configuration parameter srvcon_auth to gssplugin.

Suppose the client wants to communicate with the databases in all three instances. You need to:

  1. Update the database manager configuration parameter clnt_pw_plugin with the client-side user ID/password plug-in (for example, clnt_upw).
  2. Update the database manager configuration parameter clnt_krb_plugin with the client-side Kerberos plug-in (for example, krb).
  3. Install client-side plug-ins (clnt_upw, krb, and gss2).
  4. Catalog database dbase1 (without specifying authentication, or specifying authentication as server_encrypt).
  5. Catalog database dbase2 (without specifying authentication, or specifying authentication as kerberos).
  6. Catalog database dbase3 (without specifying authentication, or specifying authentication as gssplugin).
  7. Issue the statement 'connect to dbase1 user <user ID> using <password>'
    This connection will use server_encrypt; on the client it uses clnt_upw (from clnt_pw_plugin), and on the server it uses server_upw (from server_pw_plugin).
  8. Issue the statement 'connect to dbase2 user <user ID> using <password>'
    This connection will use Kerberos; on the client it uses krb (from clnt_krb_plugin), and on the server it uses krb (from rvcon_gssplugin_list).
  9. Issue the statement 'connect to dbase3 user <user ID> using <password>'
    This connection will use gssplugin; on the client it selects gss2 even though both gss2 and krb are listed; the srvcon_gssplugin_list dictates the preference order. The server will then be notified by the client to use gss2. Thus, both the client and the server will use gss2.

Note that unlike the user ID/password plug-in, the GSS-API based plug-in needs to have the same name on both client and the server.


Common problems working with security plug-ins

This section provides tips on debugging problems with security plug-ins:

Check the administrative log for messages specific to security plug-ins. On UNIX, check sqllib/db2dump/<instance name>.nfy. On Windows, use the Event Viewer to view the Windows event log.

Table 9 lists the administration log values that are specific to security plug-ins.

Table 9. Administration log values that are specific to security plug-ins
Log valueReason
13000A call to a GSS-API security plug-in API failed with an error.
13001A call to a DB2 security plug-in API failed with an error.
13002DB2 failed to unload a plug-in.
13003The principal name is not valid.
13004The plug-in name is not valid.
13005DB2 failed to load the plug-in.
13006An unexpected plug-in error was encountered.

Check the error messages and the associated SQLSTATE value for diagnosis on the message. Any message related to security plug-ins will have the following SQLCODE values:

Table 10. SQLCODES related to security plug-ins
SQLCODEReason
-1365Plug-in error during db2start or db2stop
-1366Local authorization problem
-30082Connection-related plug-in errors

If you are using the plug-in on a Windows 64-bit platform and are seeing plug-in load errors, ensure that the 64-bit plug-in library has a '64' suffix on the library name, and the database manager configuration parameter does not. Remember that 32-bit application must use 32-bit plug-ins and 64-bit applications must use 64-bit plug-ins.

Apart from the above, you may encounter errors caused by limitations of the security plug-ins. Refer to the "Restrictions" section above to ensure that what you are trying to accomplish is not a DB2 restriction on how security plug-ins operate.


Summary

This article provided you with an overview of security plug-ins, starting with the benefits of security plug-ins and their advantages over standard security facilities. The article explained in detail the various types of plug-ins supported by DB2, and how you would go about enabling them. The series of examples walked you through the creation of the various types of security plug-ins, the code for which is available for download below. You learned about restrictions on security plug-ins, and common errors encountered while working with them to help you debug problems when implementing security plug-ins on your own.


Download

DescriptionNameSize
Sample code for this articlesecurity.zip16KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=99528
ArticleTitle=DB2 security, Part 2: Understand the DB2 for Linux, UNIX, and Windows security plug-ins
publish-date=05182011