Summary

Remove the fallback description from KeyTab::exists.

Problem

The KeyTab::exists spec contains a sentence

The caller can use the result to determine if it should fallback to another mechanism to read the keys

This is vague and not instructive. It might have a false impression that if a JAAS Subject has both KeyTab and KerberosKey objects in its private credential set, then the KerberosKey objects will be ignored if the KeyTab object has its exists() method returning true (since they are only fallbacks), but even in our own Kerberos implementation this is not true and we read both. Some people might intepret it as that when a KeyTab object is created with a specified file with KeyTab.getInstance(File f) but the file does not exist then it would point to a default keytab location. This is even more incorrect. All getInstance calls are very clear on whether the object is a "default instance" or one "from a File object", and there is no fallback between them.

Solution

See spec.

Specification

diff --git a/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyTab.java b/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyTab.java
--- a/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyTab.java
+++ b/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyTab.java
     /**
      * Checks if the keytab file exists. Implementation of this method
      * should make sure that the result matches the latest status of the
      * keytab file.
-     * <p>
-     * The caller can use the result to determine if it should fallback to
-     * another mechanism to read the keys.
+     *
      * @return true if the keytab file exists; false otherwise.
      * @throws SecurityException if a security manager exists and the read
      * access to the keytab file is not permitted
      */
     public boolean exists();