Security

Kerberos

Kerberos is a network authentication protocol that uses encryption for authentication of client-server applications. Kerberos provides advantages for users and system administrators, including the following:

• A Kerberos database can serve as a centralized storehouse for users.
• Kerberos facilitates the single-sign-on (SSO) environment, in which a user system login provides the credentials necessary to access a database.
• Kerberos is an IETF standard. Interoperability is possible between different implementations of Kerberos.

Configuring jConnect applications for Kerberos

Before attempting to configure Kerberos for jConnect 6.0, make sure you have the following:

• JDK 1.4 or later (JDK 1.4.2 or later is recommended)
• A Java Generic Security Services (GSS) Manager:
  
  
  1. The default Sun GSS Manager, which is part of the JDK, or
  2. Wedgetail JCSI Kerberos version 2.6 or later, or
  3. CyberSafe TrustBroker Application Security Runtime Library version 3.1.0 or later, or
  4. A GSS Manager implementation from another vendor.
• A KDC that is supported and interoperable at the server side with your GSS library and at the client side with your GSSManager.

To enable Kerberos login with jConnect, use the following procedure.

Configuring Kerberos for jConnect

1. Set the REQUEST_KERBEROS_SESSION property to "true."
2. Set the SERVICE_PRINCIPAL_NAME property to the name that your Adaptive Server Enterprise is running under. In general, this is the name set with the -s option when the server is started. The service principal name must also be registered with the KDC. If you do not set a value for the SERVICE_PRINCIPAL_NAME property, jConnect defaults to using the host name of the client machine.
3. Optionally, set the GSSMANAGER_CLASS property.

For more information on the REQUEST_KERBEROS_SESSION and SERVICE_PRINCIPAL_NAME properties, see Chapter 2, "Programming Information" For more information on the GSSMANAGER_CLASS property, see GSSMANAGER_CLASS connection property

GSSMANAGER_CLASS connection property

When using Kerberos, jConnect relies on several Java classes that implement the Generic Security Services (GSS) API. Much of this functionality is provided by the org.ietf.jgss.GSSManager class.

Vendor implementations

Java allows vendors to provide their own implementations of the GSSManager class. Examples of vendor-supplied GSSManager implementations are those provided by Wedgetail Communications and CyberSafe Limited. Users can configure a vendor-written GSSManager class to work in a particular Kerberos environment. Vendor-supplied GSSManager classes may also offer more interoperability with Windows than the standard Java GSSManager class provides.

Before using a vendor-supplied implementation of GSSManager, be sure to read the vendor documentation. Vendors use system property settings other than the standard Java system properties used for Kerberos and may locate realm names and Key Distribution Center (KDC) entries without using configuration files.

Setting GSSMANAGER_CLASS

You can use a vendor implementation of GSSManager with jConnect by setting the GSSMANAGER_CLASS connection property. There are two ways to set this property:

• Create an instance of GSSManager, and set this instance as the value of the GSSMANAGER_CLASS property.
• Set the value of the GSSMANAGER_CLASS property as a string specifying the fully qualified class name of the GSSManager object. jConnect uses this string to call Class.forName().newInstance() and casts the returned object as a GSSManager class.

In either case, the application CLASSPATH variable must include the location of the classes and .jar files for the vendor implementation.

When you use the GSSMANAGER_CLASS connection property to pass in a fully qualified class name, jConnect calls the no-argument constructor for the GSSManager. This instantiates a GSSManager that is in the default configuration for the vendor implementation, so you do not have control over the exact configuration of the GSSManager object. If you create your own instance of GSSManager, you can use constructor arguments to set configuration options.

How jConnect uses GSSMANAGER_CLASS

First, jConnect checks the value of GSSMANAGER_CLASS for a GSSManager class object to use in Kerberos authentication.

If the value of GSSMANAGER_CLASS has been set to a string instead of a class object, jConnect uses the string to create an instance of the specified class and uses the new instance in Kerberos authentication.

If the value of GSSMANAGER_CLASS is set to something that is neither a GSSManager class object nor a string, or if jConnect encounters a ClassCastException, jConnect throws a SQLException indicating the problem.

Examples

The following examples illustrate how to create your own instance of GSSManager and how to let jConnect create a GSSManager object when the GSSMANAGER_CLASS connection property is set to a fully qualified class name. Both examples use the Wedgetail GSSManager.

Example: Creating your own instance of GSSManager

1. Instantiate a GSSManager in your application code. For example:
   
   

   GSSManager gssMan =  new  com.dstc.security.kerberos.gssapi.GSSManager();

   
   
   This example uses the default constructor with no arguments. You can use other vendor-supplied constructors, which allow you to set various configuration options.
2. Pass the new GSSManager instance into the GSSMANAGER_CLASS connection property. For example:
   
   

   Properties props = new Properties();
   props.put("GSSMANAGER_CLASS",  gssMan);

3. Use these connection properties, including GSSMANAGER_CLASS, in your connection. For example:
   
   

   Connection conn = DriverManager.getConnection  (url, props);

Example: Passing a string to GSSMANAGER_CLASS

1. In your application code, create a string specifying the fully qualified class name of the GSSManager object. For example:
   
   

   String gssManClass = "com.dstc.security.kerberos.gssapi.GSSManager";

2. Pass the string to the GSSMANAGER_CLASS connection property. For example:
   
   

   Properties props = new Properties();
   props.put("GSSMANAGER_CLASS",  gssManClass);

3. Use these connection properties, including GSSMANAGER_CLASS, in your connection. For example,
   
   

   Connection conn = DriverManager.getConnection  (url, props);

Setting up the Kerberos environment

This section provides suggestions for setting up the environment to use jConnect 6.05 with three different implementations of Kerberos:

• CyberSafe
• MIT
• Microsoft Active Directory

CyberSafe

Encryption keys

Specify a Data Encryption Standard (DES) key when creating a principal to be used by Java in the CyberSafe KDC. The Java reference implementation does not support Triple Data Encryption Standard (3DES) keys.

Address mapping and realm information

CyberSafe Kerberos does not use a krb5.conf configuration file. By default, CyberSafe uses DNS records to locate KDC address mapping and realm information. Alternately, CyberSafe locates KDC address mapping and realm information in the krb.conf and krb.realms files, respectively. Refer to CyberSafe documentation for more information.

If you are using the standard Java GSSManager implementation, you must still create a krb5.conf file for use by Java. The CyberSafe krb.conf file is formatted differently from the krb5.conf file. Create a krb5.conf file as specified in the Sun manual pages or in the MIT documentation. You do not need a krb5.conf file if using the CyberSafe GSSManager.

For examples of the krb5.conf file, see white paper on setting up Kerberos. The URL for this document can be found in the jConnect for JDBC Release Bulletin.

Solaris

When using CyberSafe client libraries on Solaris, make sure your library search path includes the CyberSafe libraries before any other Kerberos libraries.

MIT

Encryption keys

Specify a DES key when creating a principal to be used by Java in the MIT KDC. The Java reference implementation does not support 3DES keys.

If you plan to use only the standard Java GSSManager implementation, specify an encryption key of type des-cbc-crc or des-cbc-md5 . Specify the encryption type as follows:

des-cbc-crc:normal

Here normal is the type of key salt. It may be possible to use other salt types.

Microsoft Active Directory

SSO

SSO using the Java reference implementation is available only for Windows 2000 and Windows XP clients, not for Windows NT clients using Microsoft Active Directory. However, SSO is possible for NT clients using a vendor-supplied GSSManager such as that provided by CyberSafe.

User accounts and service principal

Make sure that you have set up accounts in Active Directory for your user principals (the users) and service principals (the accounts that represent your database servers). Your user principals and service principals should both be created as 'Users' within Active Directory.

Encryption

If you intend to use the Java reference GSS Manager implementation, you must use DES encryption for both user and service principals.

Setting DES encryption

1. Right-click on the specific user principal or service principal name in the Active Directory Users list.
2. Select Properties.
3. Click the Account tab. The Account Options list appears.
4. For both the user principal and service principal, specify that DES encryption types should be used.

Client machines

If you plan to use the Java reference implementation to set up an SSO environment on Windows 2000 clients, you may need to modify the Windows Registry according to instructions specified at the following URL:

http://support.microsoft.com/default.aspx?scid=kb;en-us;308339.

Configuration file

On Windows, the Kerberos configuration file is called krb5.ini. Java looks for krb5.ini by default at C:\WINNT\krb5.ini. Java allows you to specify the location of this file. The format of krb5.ini is identical to that of krb5.conf.

For examples of the krb5.conf file, see white paper on setting up Kerberos. The URL for this document can be found in the jConnect for JDBC Release Bulletin.

For more information on Kerberos for Microsoft Active Directory, see the following document:

www.microsoft.com/windows2000/techinfo/planning/security/kerbsteps.asp

Sample applications

The following two commented code samples are provided in the jConnect-6_0/sample2 directory to illustrate how to establish a Kerberos connection to Adaptive Server Enterprise:

• ConnectKerberos.java - A simple Kerberos login to Adaptive Server Enterprise
• ConnectKerberosJAAS.java - A more detailed sample showing how a Kerberos login might be implemented within application-server code

ConnectKerberos.java

To run the ConnectKerberos.java sample application, use the following procedure.

Running ConnectKerberos.java

1. Make sure your machine has valid Kerberos credentials. This task varies depending on your machine and environment.
   
   Windows - You can establish Kerberos credentials for a Windows 2000 or XP machine running in an Active Directory environment by successfully logging in using Kerberos authentication.
   
   UNIX or Linux - You can establish Kerberos credentials for a UNIX or Linux machine using the kinit utility for your Kerberos client. If you do not obtain an initial credential using kinit, you are prompted for a user name and password when you attempt to run the sample application.
   
   
      The Sun JDK can use only the DES_CBC_MD5 and DES_CBC_CRC encryption types. You may be able to use other encryption types by using third-party software and setting the GSSMANAGER_CLASS property.
   
   
2. Determine the location of the credentials for your machine.
   
   Windows - For a Windows 2000 or XP machine running in an Active Directory environment, Kerberos credentials are stored in an in-memory ticket cache.
   
   UNIX or Linux - For a UNIX or Linux machine using the Sun Java, CyberSafe, Solaris, or MIT implementations of Kerberos, kinit places credentials by default in /tmp/krb5cc_{user_id_number}, where {user_id_number} is unique to your user name.
   
   If the credentials are placed elsewhere, you must specify that location in the sample2/exampleLogin.conf file by setting the ticketCache property.
3. Specify to the Java reference implementation the default realm and host name of the KDC machine. Java may obtain this information from the krb5.conf or krb5.ini configuration files or from Java System properties. If you use a vendor GSS Manager implementation, that implementation may obtain host and realm information from DNS SRV records.
   
   Sybase recommends that you use a Kerberos configuration file, which allows for more control of the Kerberos environment, including the ability to specify to Java the type of encryption to request during authentication.
   
   
      On Linux, the Java reference implementation looks for the Kerberos configuration file in /etc/krb5.conf.
   
   
   
   If you do not use a Kerberos configuration file, and your Kerberos configuration is not set up to use DNS SRV records, you can specify the realm and KDC using the java.security.krb5.realm and java.security.krb5.kdc system properties.
4. Edit ConnectKerberos.java so that the connection URL points to your database.
5. Compile ConnectKerberos.java.
   
   Be sure to use JDK version 1.4 or later. Sybase recommends using JDK 1.4.2 or later. Read through the source code comments, and make sure the jconn3.jar from your jConnect installation is specified in your CLASSPATH environment variable.
6. Execute ConnectKerberos.class:
   
   

   java ConnectKerberos

   
   
   Be sure to use the 1.4.2 java executable. The sample application output explains that a successful connection has been established and executes the following SQL:
   
   

   select 1

   
   
   
   • To execute the sample without using a Kerberos configuration file , use the following command:
     
     

     java -Djava.security.krb5.realm=your_realm
     -Djava.security.krb5.kdc=your_kdc ConnectKerberos

     
     
     where your_realm is your default realm, and your_kdc is your KDC.
   • If necessary, you can run the sample application in debug mode to see debug output from the Java Kerberos layer:
     
     

     java -Dsun.security.krb5.debug=true ConnectKerberos

   
   
   You can also make a Kerberos connection using IsqlApp, the Java version of isql, located in the jConnect-6_0/classes directory:
   
   

   java IsqlApp -S jdbc:sybase:Tds:hostName:portNum 
   -K service_principal_name 
   -F path_to_JAAS_login_module_config_file

   For details on using IsqlApp, see

Interoperability

Table 3-1 shows combinations of KDCs, GSS libraries, and platforms on which Sybase has successfully established a connection to Adaptive Server Enterprise. The absence of any particular combination does not indicate that a connection cannot be established with that combination. Interoperability testing is ongoing, and you can find the most recent status at the jConnect for JDBC Web site:

http://www.sybase.com/products/middleware/jconnectforjdbc

Sybase recommends that you use the latest versions of these libraries. Contact the vendor if you intend to use older versions or if you have problems with non-Sybase products.

Encryption types

The standard Java GSS implementation provided by Sun supports only DES encryption. If you intend to use the 3DES, RC4-HMAC, AES-256, or AES-128 encryption standards, you must use the CyberSafe or Wedgetail GSSManagers.

Refer to the respective documentation for more information about Wedgetail and CyberSafe.

Troubleshooting

This section documents issues to consider when troubleshooting Kerberos security.

Kerberos

Consider the following when troubleshooting problems with Kerberos security:

• The Java reference implementation supports only the DES encryption type. You must configure your Active Directory and KDC principals to use DES encryption.
• The value of the SERVICE_PRINCIPAL_NAME property must be set to the same name you specify with the -s option when you start your data server.
• Check the krb5.conf and krb5.ini files. For CyberSafe clients, check the krb.conf and krb.realms files or DNS SRV records.
• You can set the debug property to "true" in the JAAS login configuration file.
• You can set the debug property to "true" at the command line:
  
  

  -Dsun.security.krb5.debug=true

• The JAAS login configuration file provides several options that you can set for your particular needs. For information on this configuration file, refer to the following links:http://java.sun.com/j2se/1.4.2/docs/guide/security/jgss/tutorials/LoginConfigFile.htmlhttp://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html

For further information on troubleshooting JAAS and the Java GSS API, refer to the following link:

http://java.sun.com/j2se/1.4.2/docs/guide/security/jgss/tutorials/Troubleshooting.html

Related documents

The following documents provide additional information on Kerberos security.

• Java tutorial on JAAS and the Java GSS API:
  
  http://java.sun.com/j2se/1.4.2/docs/guide/security/jgss/tutorials/index.html
• MIT Kerberos documentation and download site:
  
  http://web.mit.edu/kerberos/www/index.html
• CyberSafe Limited:
  
  http://www.cybersafe.ltd.uk
• CyberSafe Limited document on Windows-Kerberos interoperability:
  
  www.cybersafe.ltd.uk/docs_cybersafe/Kerberos%20Interoperability%20-%20Microsoft%20W2k%20&%20ActiveTRUST.pdf
• Wedgetail Communications Kerberos FAQ:
  
  http://www.wedgetail.com/jcsi/kerberos/FAQ.html
• Description of how Windows implements authentication, including information about Active Directory Kerberos:
  
  http://www.windowsitlibrary.com/Content/617/06/1.html
• Description of Windows Kerberos:
  
  http://www.microsoft.com/windows2000/techinfo/howitworks/security/kerberos.asp
• Kerberos RFC 1510:
  
  http://www.linuxdig.com/rfc/individual/1510.php

Copyright (C) 2005. Sybase Inc. All rights reserved.