JavaTM Platform
Standard Ed. 6

javax.security.auth.login
类 Configuration

java.lang.Object
  继承者 javax.security.auth.login.Configuration

public abstract class Configuration
extends Object

Configuration 对象负责指定应该将哪一个 LoginModule 用于某一特定应用程序,以及应该以什么样的顺序调用 LoginModule。

登录配置包含以下信息。注意,此示例仅表示 Configuration 的默认语法。此类的子类实现可以实现替代语法,也可以从任何源(比如文件、数据库或服务器)中检索 Configuration

      Name {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
      Name {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
other {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
 

Configuration 中的每个条目都是通过应用程序名(Name)进行索引的,并且每个条目都包含为该应用程序配置的 LoginModules 的列表。每个 LoginModule 都是通过其完全限定类名来指定的。验证是按指定的具体顺序沿着模块列表向下进行。如果应用程序没有特定条目,则验证的条目默认为用于“其他方面”的特定条目。

当顺着堆栈往下进行验证时,Flag 值控制整个行为。下面是 Flag 的有效值的描述和它们各自的语义:

1) Required - 要求 LoginModule 成功。
              不管它成功或失败,验证都将沿着 LoginModule 列表继续向下进行。
2) Requisite - 要求 LoginModule 成功。
               如果它成功,则验证沿着 LoginModule 列表继续向下进行。
               如果它失败,则该控制立即返回给应用程序(验证不再沿着 LoginModule 列表继续向下进行)。
3) Sufficient - 不要求 LoginModule 成功。
               如果成功,则控制立即返回到应用程序(验证不再沿着 LoginModule 列表继续向下进行)。
               如果失败,则验证沿着 LoginModule 列表继续向下进行。
4) Optional - 不要求 LoginModule 成功。
              不管它成功或失败,验证都将沿着 LoginModule 列表继续向下进行。

仅在所有 RequiredRequisite LoginModules 成功时,整个验证才成功。如果配置了 Sufficient LoginModule 并且获得成功,则只要 Sufficient LoginModule 之前的 RequiredRequisite LoginModules 是成功的,整个验证就会成功。如果没有为应用程序配置 RequiredRequisite LoginModules,那么至少有一个 SufficientOptional LoginModule 必须成功。

ModuleOptions 是特定于 LoginModule 的值的空格隔开列表,这些值被直接传递给底层 LoginModules。这些选项由 LoginModule 自身定义,并在其自身中控制它的行为。例如,LoginModule 可以定义一些选项,以便支持调试/测试功能。在 Configuration 中指定选项的正确方法是使用如下的键-值对:debug="true"。键和值应该用等号分隔,值应该用双引号括起来。如果在值中出现 ${system.property} 形式的 String,则将它扩展为系统属性值。注意,对 LoginModule 可以定义的选项个数的没有限制。

下面展示基于以上语法的示例 Configuration 条目:

 Login {
   com.sun.security.auth.module.UnixLoginModule required;
   com.sun.security.auth.module.Krb5LoginModule optional
                   useTicketCache="true"
                   ticketCache="${user.home}${/}tickets";
 };
 

Configuration 指定一个名称为 "Login" 的应用程序,要求用户首先对 com.sun.security.auth.module.UnixLoginModule 进行验证,该验证必须成功。即使 UnixLoginModule 验证失败,com.sun.security.auth.module.Krb5LoginModule 仍将被调用。这有助于隐藏失败源。由于 Krb5LoginModuleOptional,所以仅在 UnixLoginModule (Required) 成功时,整个验证才获得成功。

还要注意的是,特定于 LoginModule 的选项 useTicketCache="true"ticketCache=${user.home}${/}tickets" 被传递到 Krb5LoginModule。这些选项指示 Krb5LoginModule 使用指定位置处缓存的票据。系统属性 user.home/ (file.separator) 扩展成它们各自的值。

在任意给定时间,运行时中只安装了一个 Configuration 对象。可通过调用 setConfiguration 方法安装 Configuration 对象。已安装的 Configuration 对象可通过调用 getConfiguration 方法获取。

如果运行时中没有安装 Configuration 对象,则对 getConfiguration 的调用将安装一个默认 Configuration 实现的实例(此抽象类的默认子类实现)。通过将 "login.configuration.provider" 的安全属性(在 Java 安全属性文件中)的值设置为所需的 Configuration 子类实现的完全限定名,可以更改默认的 Configuration 实现。Java 安全属性文件位于名称为 <JAVA_HOME>/lib/security/java.security 的文件中。<JAVA_HOME> 是指 java.home 系统属型的值,也指定安装 JRE 的目录。

应用程序代码可直接子类化 Configuration 以提供自定义实现。此外,可通过调用带标准类型的某一个 getInstance 工厂方法构造 Configuration 对象的实例。默认策略类型为 "JavaLoginConfig"。有关标准 Configuration 类型的列表,请参见 Java Cryptography Architecture API Specification & Reference 的附录 A。

另请参见:
LoginContext

嵌套类摘要
static interface Configuration.Parameters
          此类表示 Configuration 参数的标记接口。
 
构造方法摘要
protected Configuration()
          唯一的构造方法。
 
方法摘要
abstract  AppConfigurationEntry[] getAppConfigurationEntry(String name)
          获取此 Configuration 中指定 name 的 AppConfigurationEntry。
static Configuration getConfiguration()
          获取已安装的登录 Configuration。
static Configuration getInstance(String type, Configuration.Parameters params)
          返回指定类型的 Configuration 对象。
static Configuration getInstance(String type, Configuration.Parameters params, Provider provider)
          返回指定类型的 Configuration 对象。
static Configuration getInstance(String type, Configuration.Parameters params, String provider)
          返回指定类型的 Configuration 对象。
 Configuration.Parameters getParameters()
          返回 Configuration 参数。
 Provider getProvider()
          返回此 Configuration 的 Provider。
 String getType()
          返回此 Configuration 的类型。
 void refresh()
          刷新和重新加载 Configuration。
static void setConfiguration(Configuration configuration)
          设置登录 Configuration
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

Configuration

protected Configuration()
唯一的构造方法。(由子类构造方法调用,通常是隐式的)。

方法详细信息

getConfiguration

public static Configuration getConfiguration()
获取已安装的登录 Configuration。

返回:
登录 Configuration。如果 Configuration 对象是由 Configuration.setConfiguration 方法设置的,则返回该对象。否则返回默认的 Configuration 对象。
抛出:
SecurityException - 如果调用者没有检索此 Configuration 的权限。
另请参见:
setConfiguration(javax.security.auth.login.Configuration)

setConfiguration

public static void setConfiguration(Configuration configuration)
设置登录 Configuration

参数:
configuration - 新的 Configuration
抛出:
SecurityException - 如果当前线程没有设置 Configuration 的 Permission。
另请参见:
getConfiguration()

getInstance

public static Configuration getInstance(String type,
                                        Configuration.Parameters params)
                                 throws NoSuchAlgorithmException
返回指定类型的 Configuration 对象。

此方法从首选 Provider 开始遍历已注册安全提供者列表。返回一个封装 ConfigurationSpi 实现的新 Configuration 对象,该实现取自支持指定类型的第一个 Provider。

注意,可以通过 Security.getProviders() 方法获取已注册提供者列表。

参数:
type - 指定的 Configuration 类型。有关标准 Configuration 类型的列表,请参见 Java Cryptography Architecture API Specification & Reference 的附录 A。
params - Configuration 的参数,可以为 null。
返回:
新的 Configuration 对象。
抛出:
SecurityException - 如果调用者没有获取指定类型的 Configuration 实例的权限。
NullPointerException - 如果指定类型为 null。
IllegalArgumentException - 如果取自选定 Provider 的 ConfigurationSpi 实现不理解指定参数。
NoSuchAlgorithmException - 如果没有 Provider 支持指定类型的 ConfigurationSpi 实现。
从以下版本开始:
1.6
另请参见:
Provider

getInstance

public static Configuration getInstance(String type,
                                        Configuration.Parameters params,
                                        String provider)
                                 throws NoSuchProviderException,
                                        NoSuchAlgorithmException
返回指定类型的 Configuration 对象。

返回一个封装 ConfigurationSpi 实现的新 Configuration 对象,该实现取自指定的提供者。指定的提供者必须在安全提供者列表中注册。

注意,可以通过 Security.getProviders() 方法获取已注册提供者列表。

参数:
type - 指定的 Configuration 类型。有关标准 Configuration 类型的列表,请参见 Java Cryptography Architecture API Specification & Reference 的附录 A。
params - Configuration 的参数,可以为 null。
provider - 提供者。
返回:
新的 Configuration 对象。
抛出:
SecurityException - 如果调用者没有获取指定类型的 Configuration 实例的权限。
NullPointerException - 如果指定类型为 null。
IllegalArgumentException - 如果指定提供者为 null 或空,或者取自指定提供者的 ConfigurationSpi 实现不理解指定参数。
NoSuchProviderException - 如果指定提供者未在安全提供者列表中注册。
NoSuchAlgorithmException - 如果指定提供者不支持指定类型的 ConfigurationSpi 实现。
从以下版本开始:
1.6
另请参见:
Provider

getInstance

public static Configuration getInstance(String type,
                                        Configuration.Parameters params,
                                        Provider provider)
                                 throws NoSuchAlgorithmException
返回指定类型的 Configuration 对象。

返回一个封装 ConfigurationSpi 实现的新 Configuration 对象,该实现取自指定的 Provider 对象。 注意,指定的 Provider 对象无需在提供者列表中注册。

参数:
type - 指定的 Configuration 类型。有关标准 Configuration 类型的列表,请参见 Java Cryptography Architecture API Specification & Reference 的附录 A。
params - Configuration 的参数,可以为 null。
provider - Provider。
返回:
新的 Configuration 对象。
抛出:
SecurityException - 如果调用者没有获取指定类型的 Configuration 实例的权限。
NullPointerException - 如果指定类型为 null。
IllegalArgumentException - 如果指定的 Provider 为 null,或者取自指定 Provider 的 ConfigurationSpi 实现不理解指定参数。
NoSuchAlgorithmException - 如果指定 Provider 不支持指定类型的 ConfigurationSpi 实现。
从以下版本开始:
1.6
另请参见:
Provider

getProvider

public Provider getProvider()
返回此 Configuration 的 Provider。

只有在此 Configuration 实例是通过调用 Configuration.getInstance 获得的时,它才有 Provider。否则,此方法返回 null。

返回:
此 Configuration 的 Provider,或者返回 null。
从以下版本开始:
1.6

getType

public String getType()
返回此 Configuration 的类型。

只有在此 Configuration 实例是通过调用 Configuration.getInstance 获得的时,它才有类型。否则,此方法返回 null。

返回:
此 Configuration 的类型,或者返回 null。
从以下版本开始:
1.6

getParameters

public Configuration.Parameters getParameters()
返回 Configuration 参数。

只有在此 Configuration 实例是通过调用 Configuration.getInstance 获得的时,它才有参数。否则,此方法返回 null。

返回:
Configuration 参数,或者返回 null。
从以下版本开始:
1.6

getAppConfigurationEntry

public abstract AppConfigurationEntry[] getAppConfigurationEntry(String name)
获取此 Configuration 中指定 name 的 AppConfigurationEntry。

参数:
name - 用于索引 Configuration 的名称。
返回:
对应于此 Configuration 中指定 name 的 AppConfigurationEntries 数组,如果不存在指定的 name 条目,则返回 null。

refresh

public void refresh()
刷新和重新加载 Configuration。

此方法导致此 Configuration 对象以与实现有关的方式刷新/重新加载其内容。例如,如果此 Configuration 对象将其条目存储在文件中,则调用 refresh 可能导致重新读取该文件。

此方法的默认实现不执行任何操作。如果该实现支持刷新操作,则应该重写此方法。

抛出:
SecurityException - 如果调用者没有刷新此 Configuration 的权限。

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策