Java org.ietf.jgss 接口 GSSContext（JDK5）

所有类

org.ietf.jgss
接口 GSSContext

public interface GSSContext

此接口将封装 GSS-API 安全上下文，并提供可通过上下文提供的安全服务。安全上下文是使用本地获取的凭据在同位体之间创建的。在一对同位体之间可能会同时存在多个上下文，它们使用一套相同或不同的凭据。GSS-API 的执行方式与基础传输协议无关，而是取决于其对传输标记的应用程序的调用，这些标记由同位体之间的安全上下文生成。

如果调用方使用默认的 GSSManager 实例实例化上下文，则可保证 Kerberos v5 GSS-API 机制可用于上下文创建。此机制由 Oid "1.2.840.113554.1.2.2" 标识，并在 RFC 1964 中被进行定义。

在初始化上下文创建阶段之前，上下文初始化程序会请求已创建的上下文所需要的特定特征。并非所有的基础机制都支持调用方所需要的全部特征。在创建上下文之后，调用方可以通过多种查询方法来检查由该上下文提供的实际特征和服务。当使用由默认的 GSSManager 实例提供的 Kerberos v5 GSS-API 机制时，所有的可选服务都可本地提供。它们是相互身份验证、凭据委托、机密性和完整性保护、以及 per-message 重放检测和排序。注意，在 GSS-API 中，消息完整性是消息机密性的先决条件。

上下文创建必须在这样一个环路中进行：初始端调用 initSecContext，接受端调用 acceptSecContext，直到创建好该上下文。同时，在此环路中，initSecContext 和 acceptSecContext 方法将产生应用程序发送给同位体的标记。同位体将根据情况将任何这样的标记作为输入传递给它的 acceptSecContext 或 initSecContext。

在上下文创建阶段，可能会调用 isProtReady 方法来确定是否可以将该上下文用于 wrap 和 getMIC 的 per-message 操作。这将允许应用程序在尚未完全创建的上下文上使用 per-message 操作。

在上下文创建好或 isProtReady 方法返回 true后，可调用查询例程来确定已创建上下文的实际特征和服务。还可以通过使用 wrap 和 getMIC 的 per-message 方法来启动应用程序，以获取对应用程序提供的数据的加密操作。

当不再需要上下文时，应用程序必须调用 dispose 来释放该上下文可能正在使用的任何系统资源。

安全上下文一般都维护有关它所处理的标记的排序和重放检测方面的信息。因此，将标记呈现给此上下文以进行处理的顺序非常重要。还要注意的是，此接口中的任何方法都不同步。因此，除非已经实施了某些应用程序级的同步，否则建议不要在几个线程之间共享 GSSContext。

最后一点是，不同的机制提供商可能会对使用 GSS-API 上下文提出不同的安全限制。这些将由机制提供商记入文档。应用程序需要确保是否具有适当的权限在机制层中进行此类检查。

下面呈现的示例代码演示了使用 GSSContext 接口初始化同位体的情况。它呈现了在 GSSContext 对象上的不同操作，其中包括：对象初始化、所需标志的设置、上下文创建、对实际上下文标志的查询、对应用程序数据的 per-message 操作和最终的上下文删除。

    // Create a context using default credentials 
    // and the implementation specific default mechanism
    GSSManager manager ...
    GSSName targetName ...
    GSSContext context = manager.createContext(targetName, null, null,
                                           GSSContext.INDEFINITE_LIFETIME);
 
    // set desired context options prior to context establishment
    context.requestConf(true);
    context.requestMutualAuth(true);
    context.requestReplayDet(true);
    context.requestSequenceDet(true);
    
    // establish a context between peers

    byte []inToken = new byte[0];

    // Loop while there still is a token to be processed

    while (!context.isEstablished()) {

        byte[] outToken 
            = context.initSecContext(inToken, 0, inToken.length);
        
        // send the output token if generated
        if (outToken != null)
            sendToken(outToken);
  
        if (!context.isEstablished()) {
            inToken = readToken();
    }
    
     // display context information
     System.out.println("Remaining lifetime in seconds = " 
                                          + context.getLifetime());
     System.out.println("Context mechanism = " + context.getMech());
     System.out.println("Initiator = " + context.getSrcName());
     System.out.println("Acceptor = " + context.getTargName());
  
     if (context.getConfState())
             System.out.println("Confidentiality (i.e., privacy) is available");
  
     if (context.getIntegState())
             System.out.println("Integrity is available");
  
     // perform wrap on an application supplied message, appMsg,
     // using QOP = 0, and requesting privacy service
     byte [] appMsg ...
  
     MessageProp mProp = new MessageProp(0, true);
  
     byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);
  
     sendToken(tok);
  
     // release the local-end of the context
     context.dispose();

 

从以下版本开始：

1.4

DEFAULT_LIFETIME

static final int DEFAULT_LIFETIME

一个表示默认的上下文生存期的生存期常量。此值被设置为 0。

另请参见：

常量字段值

INDEFINITE_LIFETIME

static final int INDEFINITE_LIFETIME

一个表示不确定的上下文生存期的生存期常量。在 Java 中必须将此值设置为最大整数值 -- Integer.MAX_VALUE。

另请参见：

常量字段值

initSecContext

byte[] initSecContext(byte[] inputBuf,
                      int offset,
                      int len)
                      throws GSSException

由上下文初始端调用，以启动上下文创建阶段，处理由同位体的 acceptSecContext 方法生成的任何标记。此方法会返回一个应用程序需要发送给同位体、以便由其 acceptSecContext 方法进行处理的输出标记。应用程序可以调用 isEstablished 来确定在上下文的这一方是否完成了上下文创建阶段。如果从 isEstablished 中返回的值是 false，则指示希望为 initSecContext 提供更多的标记。完成上下文创建后，可通过 get 方法查询可用的上下文选项。

注意，有可能出现这样一种情况：initSecContext 方法为同位体返回一个标记，isEstablished 也返回 true。这表示，需要将标记发送给同位体，但该上下文的本地端现已完全创建。

有些机制提供商可能会要求调用方授予初始化安全上下文的权限。失败的权限检查可以导致从此方法中抛出 SecurityException。

参数：

inputBuf - 由同位体生成的标记。由于尚未从该同位体中接收到标记，因此在初次调用时此参数将被忽略。

offset - inputBuf 中标记开始处的偏移量。

len - 该标记的长度。

返回：

包含发送给同位体标记的 byte[]。null 指示未生成任何标记。

抛出：

GSSException，包含以下主要错误代码：{@link - GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}、GSSException.BAD_MIC、GSSException.NO_CRED、GSSException.CREDENTIALS_EXPIRED、GSSException.BAD_BINDINGS、GSSException.OLD_TOKEN、GSSException.DUPLICATE_TOKEN、GSSException.BAD_NAMETYPE、GSSException.BAD_MECH、GSSException.FAILURE

GSSException

initSecContext

int initSecContext(InputStream inStream,
                   OutputStream outStream)
                   throws GSSException

由上下文初始端调用，以启动上下文的创建阶段，处理由使用流的同位体的 acceptSecContext 方法生成的任何标记。此方法将向 OutpuStream 写入输出标记，应用程序需要将此标记发送到同位体以便通过其 acceptSecContext 调用进行处理。一般情况下，应用程序会通过在 OutputStream 上调用 flush 方法来确保封装这两个同位体之间的连接。应用程序可以通过此方法返回的值确定是否向 OutputStream 写入了标记。如果返回的值是 0，则表示没有写入任何值。应用程序可以调用 isEstablished 来确定在上下文的这一方是否完成了上下文创建阶段。如果从 isEstablished 中返回的值是 false，则指示希望为 initSecContext 提供更多的标记。完成上下文创建后，可通过 get 方法查询可用的上下文选项。

注意，有可能出现这样一种情况：initSecContext 方法为同位体返回一个标记，isEstablished 也返回 true。这表示，需要将标记发送给同位体，但该上下文的本地端现已完全创建。

GSS-API 身份验证标记包括确定的始端和终端。此方法将尝试每次调用时读取其中的一个标记，并且在仅有部分标记可用时阻塞流。在所有其他方面，此方法等同于基于字节数组的 initSecContext。

有些机制提供商可能会要求调用方授予初始化安全上下文的权限。失败的权限检查可能会导致从此方法中抛出 SecurityException。

以下示例代码演示了使用此方法的方式：

     InputStream is ...
     OutputStream os ...
     GSSContext context ...

     // Loop while there is still a token to be processed

     while (!context.isEstablished()) {

         context.initSecContext(is, os);

         // send output token if generated
         os.flush();
     }
 

参数：

inStream - 一个包含由同位体生成的标记的 InputStream。由于尚未（不会）从该同位体的该点接收到标记，因此在初次调用时此参数将被忽略。

outStream - 将向其中写入输出标记的 OutputStream。在上下文创建的最终阶段，可能不需要写入字节。

返回：

将作为标记的一部分发送给同位体、写入到 OutputStream 的字节数。0 值指示不需要发送标记。

抛出：

GSSException，包含以下主要错误代码：{@link - GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}、GSSException.BAD_MIC、GSSException.NO_CRED、GSSException.CREDENTIALS_EXPIRED、GSSException.BAD_BINDINGS、GSSException.OLD_TOKEN、GSSException.DUPLICATE_TOKEN、GSSException.BAD_NAMETYPE、GSSException.BAD_MECH、GSSException.FAILURE

GSSException

acceptSecContext

byte[] acceptSecContext(byte[] inToken,
                        int offset,
                        int len)
                        throws GSSException

由上下文接受端在收到同位体的标记后调用。此方法会返回一个输出标记，应用程序将把该标记发送到同位体、以便通过其 initSecContext 调用进行进一步处理。

应用程序可以通过调用 isEstablished 来确定是否完成了此同位体的上下文创建阶段。如果从 isEstablished 中返回的值是 false，则指示希望为此方法提供更多的标记。完成上下文创建后，可通过 get 方法查询可用的上下文选项。

注意，有可能出现这样一种情况：acceptSecContext 为同位体返回一个标记，isEstablished 也返回 true。这表示，需要将标记发送给同位体，但该上下文的本地端现已完全创建。

有些机制提供商可能会要求调用方授予接受安全上下文的权限。失败的权限检查可能会导致从此方法中抛出 SecurityException。

以下示例代码演示了使用此方法的方式：

     byte[] inToken;
     byte[] outToken;
     GSSContext context ...

     // Loop while there is still a token to be processed

     while (!context.isEstablished()) {
         inToken = readToken();
         outToken = context.acceptSecContext(inToken, 0,
                                             inToken.length);
         // send output token if generated
         if (outToken != null)
             sendToken(outToken);
     }
 

参数：

inToken - 由同位体生成的标记。

offset - inToken 中标记开始处的偏移量。

len - 该标记的长度。

返回：

包含发送给同位体标记的 byte[]。null 指示未生成任何标记。

抛出：

GSSException，包含以下主要错误代码：{@link - GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}、GSSException.BAD_MIC、GSSException.NO_CRED、GSSException.CREDENTIALS_EXPIRED、GSSException.BAD_BINDINGS、GSSException.OLD_TOKEN、GSSException.DUPLICATE_TOKEN、GSSException.BAD_MECH、GSSException.FAILURE

GSSException

acceptSecContext

void acceptSecContext(InputStream inStream,
                      OutputStream outStream)
                      throws GSSException

由上下文接受端调用，以处理来自使用流的同位体的标记。此方法将向 OutputStream 写入输出标记，应用程序需要将此标记发送到同位体以便通过其 initSecContext 方法进行处理。一般情况下，应用程序会通过在 OutputStream 上调用 flush 方法来确保封装这两个同位体之间的连接。应用程序可以调用 isEstablished 来确定在上下文的这一方是否完成了上下文创建阶段。如果从 isEstablished 中返回的值为 false，则指示希望为 acceptSecContext 提供更多的标记。完成上下文创建后，可通过 get 方法查询可用的上下文选项。

注意，有可能出现这样一种情况：acceptSecContext 为同位体返回一个标记，isEstablished 也返回 true。这表示，需要将标记发送给同位体，但该上下文的本地端现已完全创建。

GSS-API 身份验证标记包括确定的起始端和终端。此方法将尝试每调用一次读取其中的一个标记，并且在仅有部分标记可用时阻塞流。在所有其他方面，此方法等同于基于字节数组的 acceptSecContext。

有些机制提供商可能会要求调用方授予接受安全上下文的权限。失败的权限检查可能会导致从此方法中抛出 SecurityException。

以下示例代码演示了使用此方法的方式：

     InputStream is ...
     OutputStream os ...
     GSSContext context ...

     // Loop while there is still a token to be processed

     while (!context.isEstablished()) {

         context.acceptSecContext(is, os);

         // send output token if generated
         os.flush();
     }
 

参数：

inStream - 一个包含由同位体生成的标记的 InputStream。

outStream - 将向其中写入输出标记的 OutputStream。在上下文创建的最终阶段，可能不需要写入字节。

抛出：

GSSException，包含以下主要错误代码：{@link - GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}、GSSException.BAD_MIC、GSSException.NO_CRED、GSSException.CREDENTIALS_EXPIRED、GSSException.BAD_BINDINGS、GSSException.OLD_TOKEN、GSSException.DUPLICATE_TOKEN、GSSException.BAD_MECH、GSSException.FAILURE

GSSException

isEstablished

boolean isEstablished()

用来在上下文创建期间确定上下文的状态。

返回：

如果它是在调用方上完全创建的上下文，并且不再需要来自同位体的标记，则返回 true。

dispose

void dispose()
             throws GSSException

释放存储在上下文对象中并且使上下文无效的系统资源和加密信息。

抛出：

GSSException，包含以下主要错误代码：{@link - GSSException#FAILURE GSSException.FAILURE}

GSSException