JavaTM Platform
Standard Ed. 6

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,直到创建好该上下文。同时,在此环路中,initSecContextacceptSecContext 方法将产生应用程序发送给同位体的标记。同位体将根据情况将任何这样的标记作为输入传递给它的 acceptSecContextinitSecContext

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

在上下文创建好或 isProtReady 方法返回 true后,可调用查询例程来确定已创建上下文的实际特征和服务。还可以通过使用 wrapgetMIC 的 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

字段摘要
static int DEFAULT_LIFETIME
          一个表示默认的上下文生存期的生存期常量。
static int INDEFINITE_LIFETIME
          一个表示不确定的上下文生存期的生存期常量。
 
方法摘要
 byte[] acceptSecContext(byte[] inToken, int offset, int len)
          由上下文接受端在收到同位体的标记后调用。
 void acceptSecContext(InputStream inStream, OutputStream outStream)
          由上下文接受端调用,以处理来自使用流的同位体的标记。
 void dispose()
          释放存储在上下文对象中并且使上下文无效的系统资源和加密信息。
 byte[] export()
          导出此上下文,以便使其他进程能够导入它。
 boolean getAnonymityState()
          确定是否会向上下文接受端对上下文初始端进行匿名验证。
 boolean getConfState()
          确定数据机密性是否可用于上下文。
 boolean getCredDelegState()
          确定是否在此上下文上启用凭据委托。
 GSSCredential getDelegCred()
          获取上下文初始端委托给上下文接受端的凭据。
 boolean getIntegState()
          确定数据完整性是否可用于上下文。
 int getLifetime()
          确定此上下文剩余的生存期是多长。
 Oid getMech()
          确定什么机制正用于此上下文。
 byte[] getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp)
          返回包含所提供消息的加密消息完整性代码 (MIC) 的标记,以便传输到同位体应用程序。
 void getMIC(InputStream inStream, OutputStream outStream, MessageProp msgProp)
          使用流来产生包含所提供消息的加密 MIC 的标记,以便传输到同位体应用程序。
 boolean getMutualAuthState()
          确定是否在此上下文上启用了相互验证。
 boolean getReplayDetState()
          确定是否针对此上下文中的 per-message 安全服务启用了重放检测。
 boolean getSequenceDetState()
          确定是否针对本上下文中的 per-message 安全服务启用了序列检查。
 GSSName getSrcName()
          返回上下文初始端的名称。
 GSSName getTargName()
          返回上下文接受端的名称。
 int getWrapSizeLimit(int qop, boolean confReq, int maxTokenSize)
          用来确定可以传输给 wrap 的消息的大小限制。
 byte[] initSecContext(byte[] inputBuf, int offset, int len)
          由上下文初始端调用,以启动上下文创建阶段,处理由同位体的 acceptSecContext 方法生成的任何标记。
 int initSecContext(InputStream inStream, OutputStream outStream)
          由上下文初始端调用,以启动上下文的创建阶段,处理由使用流的同位体的 acceptSecContext 方法生成的任何标记。
 boolean isEstablished()
          用来在上下文创建期间确定上下文的状态。
 boolean isInitiator()
          确定它是否为上下文初始端。
 boolean isProtReady()
          确定上下文是否已为要在其上使用的 per message 准备就绪。
 boolean isTransferable()
          确定通过使用 export 方法,该上下文是否可以传输给其他进程。
 void requestAnonymity(boolean state)
          请求不要将初始端的身份泄露给接受端。
 void requestConf(boolean state)
          请求针对 wrap 方法启用数据机密性。
 void requestCredDeleg(boolean state)
          请求在上下文创建期间将初始端的凭据委托给接受端。
 void requestInteg(boolean state)
          请求针对 wrapgetMIC 方法启用数据完整性。
 void requestLifetime(int lifetime)
          请求上下文以秒为单位的生存期。
 void requestMutualAuth(boolean state)
          要求相互验证在上下文创建期间完成。
 void requestReplayDet(boolean state)
          请求在上下文创建之后针对 per-message 安全服务启用重放检测。
 void requestSequenceDet(boolean state)
          请求在上下文创建之后针对 per-message 安全服务启用序列检查。
 void setChannelBinding(ChannelBinding cb)
          设置在上下文创建期间使用的通道绑定。
 byte[] unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp)
          用来处理在上下文的另一方由 wrap 方法生成的标记。
 void unwrap(InputStream inStream, OutputStream outStream, MessageProp msgProp)
          使用流来处理在上下文的另一方由 wrap 方法生成的标记。
 void verifyMIC(byte[] inToken, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp)
          通过提供的消息,检查包含在标记参数中的加密的 MIC。
 void verifyMIC(InputStream tokStream, InputStream msgStream, MessageProp msgProp)
          通过提供的消息,使用流来验证包含在标记参数中的加密的 MIC。
 byte[] wrap(byte[] inBuf, int offset, int len, MessageProp msgProp)
          将 per-message 安全服务应用于已创建的安全上下文。
 void wrap(InputStream inStream, OutputStream outStream, MessageProp msgProp)
          将 per-message 安全服务应用于已创建的使用流的安全上下文。
 

字段详细信息

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_MICGSSException.NO_CREDGSSException.CREDENTIALS_EXPIREDGSSException.BAD_BINDINGSGSSException.OLD_TOKENGSSException.DUPLICATE_TOKENGSSException.BAD_NAMETYPEGSSException.BAD_MECHGSSException.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_MICGSSException.NO_CREDGSSException.CREDENTIALS_EXPIREDGSSException.BAD_BINDINGSGSSException.OLD_TOKENGSSException.DUPLICATE_TOKENGSSException.BAD_NAMETYPEGSSException.BAD_MECHGSSException.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_MICGSSException.NO_CREDGSSException.CREDENTIALS_EXPIREDGSSException.BAD_BINDINGSGSSException.OLD_TOKENGSSException.DUPLICATE_TOKENGSSException.BAD_MECHGSSException.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_MICGSSException.NO_CREDGSSException.CREDENTIALS_EXPIREDGSSException.BAD_BINDINGSGSSException.OLD_TOKENGSSException.DUPLICATE_TOKENGSSException.BAD_MECHGSSException.FAILURE
GSSException

isEstablished

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

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

dispose

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

抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

getWrapSizeLimit

int getWrapSizeLimit(int qop,
                     boolean confReq,
                     int maxTokenSize)
                     throws GSSException
用来确定可以传输给 wrap 的消息的大小限制。如果以相同的 confReqqop 参数呈现给 wrap 方法,则将返回最大的消息大小,这会导致输出标记只包含 maxTokenSize 个字节。

此调用主要供那些通过影响最大消息大小的协议进行通信的应用程序使用。它使应用程序能够在实施保护之前将消息进行分段。

在调用 getWrapSizeLimit 时,推荐实现 GSS-API,但不要求检测无效的 QOP 值。此例程可保证只有最大消息大小,而不是针对消息保护的特定 QOP 值的可用性。

参数:
qop - 将要求 wrap 提供的保护级别。
confReq - 如果要求 wrap 提供保密性,则为 true,否则为 false
maxTokenSize - 由 wrap 发出的标记所需的最大大小。
返回:
针对给定的输出标记大小的输入标记的最大大小
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}、GSSException.BAD_QOPGSSException.FAILURE
GSSException

wrap

byte[] wrap(byte[] inBuf,
            int offset,
            int len,
            MessageProp msgProp)
            throws GSSException
将 per-message 安全服务应用于已创建的安全上下文。该方法将通过它返回一个带有应用程序提供的数据和加密的 MIC 的标记。如果需要机密性(保密性),则可以对数据进行加密。

MessageProp 对象可以通过应用程序进行实例化,并可用来指定一个选择加密算法的 QOP 值,和可选地对消息进行加密的私密服务。在调用中使用的基础机制可能无法提供私密服务。但它将设置在此 MessageProp 对象中提供的实际私密服务,调用者会在该调用返回后对其进行查询。如果机制不能提供请求的 QOP,则它将抛出带有 BAD_QOP 代码的 GSSException。

由于某些应用程序级的协议希望使用 wrap 发出的标记来提供 "secure framing"(安全分帧),所以实现应该支持包装零长度的消息。

应用程序将负责将标记发送到同位体。

参数:
inBuf - 要保护的应用程序数据。
offset - inBuf 中数据开始处的偏移量。
len - 数据的长度
msgProp - MessageProp 的实例,应用程序使用它来设置需要的 QOP 和私密状态。将需要的 QOP 设置为 0,以便请求默认的 QOP。从此方法返回后,此对象将包含基础机制应用于消息的实际私密状态。
返回:
包含将发送给同位体的标记的 byte[]。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}、GSSException.BAD_QOPGSSException.FAILURE
GSSException

wrap

void wrap(InputStream inStream,
          OutputStream outStream,
          MessageProp msgProp)
          throws GSSException
将 per-message 安全服务应用于已创建的使用流的安全上下文。该方法将通过它返回一个带有应用程序提供的数据和加密的 MIC 的标记。如果需要机密性(保密性),则可以对数据进行加密。此方法等同于基于字节数组的 wrap 方法。

应用程序将负责将标记发送到同位体。一般情况下,应用程序会通过在 OutputStream 上调用 flush 方法来确保封装这两个同位体之间的连接。

MessageProp 对象可以通过应用程序进行实例化,并可用来指定一个选择加密算法的 QOP 值,和可选地对消息进行加密的私密服务。在调用中使用的基础机制可能无法提供私密服务。但它将设置在此 MessageProp 对象中提供的实际私密服务,调用者会在该调用返回后对其进行查询。如果机制不能提供请求的 QOP,则它将抛出带有 BAD_QOP 代码的 GSSException。

由于某些应用程序级的协议希望使用 wrap 发出的标记来提供 "secure framing"(安全分帧),所以实现应该支持包装零长度的消息。

参数:
inStream - 一个包含受保护的应用程序数据的 InputStream。将使用 inStream 中提供的所有数据。
outStream - 向其写入受保护消息的 OutputStream。
msgProp - MessageProp 的实例,应用程序使用它来设置需要的 QOP 和保密状态。将需要的 QOP 设置为 0,以便请求默认的 QOP。从此方法返回后,此对象将包含基础机制应用于消息的实际私密状态。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}、GSSException.BAD_QOPGSSException.FAILURE
GSSException

unwrap

byte[] unwrap(byte[] inBuf,
              int offset,
              int len,
              MessageProp msgProp)
              throws GSSException
用来处理在上下文的另一方由 wrap 方法生成的标记。该方法将由同位体应用程序提供的消息返回到其 wrap 调用,同时验证为该消息嵌入的 MIC。

MessageProp 对象将由应用程序实例化,并由基础机制使用,以便返回给调用者一些信息,如 QOP、是否对消息应用了机密性,以及其他一些增补消息状态信息。

由于某些应用程序级的协议希望使用 wrap 发出的标记来提供 "secure framing"(安全分帧),所以实现必须支持包装和不包装零长度的消息。

参数:
inBuf - 包含从同位体接收的包装标记的字节数组。
offset - 标记开始处的偏移量。
len - 标记的长度
msgProp - 从此方法返回后,此对象将包括所应用的 QOP、消息的保密状态、和说明该标记是否为复制的、旧的、超出序列的或在 gap 后进入的标记的增补信息。
返回:
包含从输入标记中展开的消息的 byte[]。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}、GSSException.BAD_MICGSSException.CONTEXT_EXPIREDGSSException.FAILURE
GSSException

unwrap

void unwrap(InputStream inStream,
            OutputStream outStream,
            MessageProp msgProp)
            throws GSSException
使用流来处理在上下文的另一方由 wrap 方法生成的标记。该方法将由同位体应用程序提供的消息返回到其 wrap 调用,同时验证为该消息嵌入的 MIC。

MessageProp 对象将由应用程序实例化,并由基础机制使用,以便返回给调用者一些信息,如 QOP、是否对消息应用了机密性,以及其他一些增补消息状态信息。

由于某些应用程序级的协议希望使用 wrap 发出的标记来提供 "secure framing"(安全分帧),所以实现必须支持包装和不包装零长度的消息。

此方法读取的输入标记的格式在将要使用的基础机制的规范中定义。此方法将尝试每调用一次读取其中的一个标记。如果机制标记包含确定的始端和终端,则在仅有部分标记可用时,此方法将阻塞 InputStream。如果标记的始端和终端不是确定的,则该方法会尝试将所有的可用字节视为标记的一部分。

与前面介绍的可能出现的阻塞行为不同,此方法等同于基于字节数组的 unwrap 方法。

参数:
inStream - 一个包含由同位体生成的包装标记的 InputStream。
outStream - 向其写入应用程序消息的 OutputStream。
msgProp - 从方法返回后,此对象将包括所用的 QOP、消息的保密状态和说明该标记是否为复制的、旧的、超出序列或在 gap 后进入的标记的增补信息。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}、GSSException.BAD_MICGSSException.CONTEXT_EXPIREDGSSException.FAILURE
GSSException

getMIC

byte[] getMIC(byte[] inMsg,
              int offset,
              int len,
              MessageProp msgProp)
              throws GSSException
返回包含所提供消息的加密消息完整性代码 (MIC) 的标记,以便传输到同位体应用程序。与将用户消息封装在返回的标记中的包装不同,在输出标记中仅返回消息 MIC。

注意,保密性只能应用于 wrap 调用。

由于某些应用程序级的协议希望使用 getMIC 发出的标记来提供 "secure framing"(安全分帧),所以实现必须支持从零长度消息中导出 MIC。

参数:
inMsg - 在其上生成 MIC 的消息。
offset - inMsg 中消息开始处的偏移量。
len - 消息的长度
msgProp - MessageProp 的一个实例,应用程序使用它来设置需要的 QOP。在 msgProp 中将需要的 QOP 设置为 0,以便请求默认的 QOP。还可以通过为 msgProp 传入 null 来请求默认的 QOP。
返回:
包含将发送给同位体标记的 byte[]。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}、GSSException.BAD_QOPGSSException.FAILURE
GSSException

getMIC

void getMIC(InputStream inStream,
            OutputStream outStream,
            MessageProp msgProp)
            throws GSSException
使用流来产生包含所提供消息的加密 MIC 的标记,以便传输到同位体应用程序。与将用户消息封装在返回的标记中的包装不同,在输出标记中仅产生消息 MIC。此方法等同于基于字节数组的 getMIC 方法。 注意,保密性只能应用于 wrap 调用。

由于某些应用程序级的协议希望使用 getMIC 发出的标记来提供 "secure framing"(安全分帧),所以实现必须支持从零长度消息中导出 MIC。

参数:
inStream - 一个 InputStream,它包含在其上生成 MIC 的消息。将使用 inStream 中提供的所有数据。
outStream - 向其写入输出标记的 OutputStream。
msgProp - MessageProp 的一个实例,应用程序使用它来设置需要的 QOP。在 msgProp 中将需要的 QOP 设置为 0,以便请求默认的 QOP。还可以通过为 msgProp 传入 null 来请求默认的 QOP。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}、GSSException.BAD_QOPGSSException.FAILURE
GSSException

verifyMIC

void verifyMIC(byte[] inToken,
               int tokOffset,
               int tokLen,
               byte[] inMsg,
               int msgOffset,
               int msgLen,
               MessageProp msgProp)
               throws GSSException
通过提供的消息,检查包含在标记参数中的加密的 MIC。

MessageProp 对象将由该应用程序实例化,并由基础机制使用,以便返回给调用者诸如 QOP 之类的信息,从而表明应用于消息的保护的长度和其他一些增补消息状态信息。

由于某些应用程序级的协议希望使用 getMIC 发出的标记来提供 "secure framing"(安全分帧),所以实现必须支持计算和检查零长度消息的 MIC。

参数:
inToken - 由同位体的 getMIC 方法生成的标记。
tokOffset - inToken 中标记开始处的偏移量。
tokLen - 该标记的长度
inMsg - 通过它来验证加密的 MIC 的应用程序消息。
msgOffset - inMsg 中消息开始处的偏移量。
msgLen - 该消息的长度。
msgProp - 从方法返回后,此对象将包括所用的 QOP 和说明该标记是否为复制的、旧的、超出序列或在 gap 后进入的标记的增补信息。
抛出:
GSSException, - 包含以下主要错误代码:GSSException.DEFECTIVE_TOKENGSSException.BAD_MICGSSException.CONTEXT_EXPIREDGSSException.FAILURE
GSSException

verifyMIC

void verifyMIC(InputStream tokStream,
               InputStream msgStream,
               MessageProp msgProp)
               throws GSSException
通过提供的消息,使用流来验证包含在标记参数中的加密的 MIC。此方法等同于基于字节数组的 verifyMIC 方法。 MessageProp 对象将由该应用程序实例化,并由基础机制使用,以便返回给调用者诸如 QOP 之类的信息,从而表明应用于消息的保护的长度和其他一些增补消息状态信息。

由于某些应用程序级的协议希望使用 getMIC 发出的标记来提供 "secure framing"(安全分帧),所以实现必须支持计算和检查零长度消息的 MIC。

此方法读取的输入标记的格式在将要使用的基础机制的规范中定义。此方法将尝试每调用一次读取其中的一个标记。如果机制标记包含确定的始端和终端,则在仅有部分标记可用时,此方法将阻塞 InputStream。如果标记的始端和终端不是确定的,则该方法会尝试将所有的可用字节视为标记的一部分。

与前面介绍的可能出现的阻塞行为不同,此方法等同于基于字节数组的 verifyMIC 方法。

参数:
tokStream - 一个包含由同位体的 getMIC 方法生成的标记的 InputStream。
msgStream - 一个包含可用来验证加密的 MIC 的应用程序消息的 InputStream。将使用 msgStream 中提供的所有数据。
msgProp - 从方法返回后,此对象将包括所用的 QOP 和说明该标记是否为复制的、旧的、超出序列或在 gap 后进入的标记的增补信息。
抛出:
GSSException, - 包含以下主要错误代码:GSSException.DEFECTIVE_TOKENGSSException.BAD_MICGSSException.CONTEXT_EXPIREDGSSException.FAILURE
GSSException

export

byte[] export()
              throws GSSException
导出此上下文,以便使其他进程能够导入它。假设支持在多个进程间共享工作。此例程通常由应用程序中的上下文接受端使用,在该应用程序中,单一进程接收传入的连接请求,并通过它们获得安全上下文,然后将创建的上下文传递给一个或多个其他的进程,从而进行消息交换。

此方法将取消激活安全上下文,并创建一个进程间标记,当将该标记传递给另一个进程中的 GSSManager.createContext 时,它将在第二个进程中重新激活上下文。只有给定上下文的单一实例化可以在任何时间处于活动状态;上下文导出器对导出的安全上下文的后续访问尝试都不会成功。

该实现可以限制进程的 set,可以通过这些进程导入进程间的标记,要么将其作为本地安全策略的一项功能,要么将其作为实现决策的结果。例如,有些实现会限制上下文仅在在同一帐户下运行的进程间传递,或者上下文是同一进程组的一部分。

进程间的标记可以包含安全性敏感信息(例如,加密密钥)。尽管鼓励机制要么避免将此类敏感性信息放在进程间标记中,要么在将标记返回到应用程序前对其进行加密,但在典型的 GSS-API 实现中,这是不可能的。因此,应用程序必须小心地保护进程间的标记,并确保标记将要向其传输的任何进程都是完全受信任的。

不要求实现支持安全上下文的进程间的传输。调用 isTransferable 方法将指示上下文对象是否可传输。

在不可导出的上下文上调用此方法会导致抛出以下异常,并带有错误代码 GSSException.UNAVAILABLE

返回:
一个包含导出的上下文的 byte[]
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#UNAVAILABLE GSSException.UNAVAILABLE}、GSSException.CONTEXT_EXPIREDGSSException.NO_CONTEXTGSSException.FAILURE
GSSException
另请参见:
GSSManager.createContext(byte[])

requestMutualAuth

void requestMutualAuth(boolean state)
                       throws GSSException
要求相互验证在上下文创建期间完成。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。

并非所有的机制都支持相互验证,并且某些机制在应用程序不要求相互验证的情况下也会要求这样做。因此,应用程序必须进行检查,看请求是否与 getMutualAuthState 方法有关。

参数:
state - 布尔值,指示是否应该使用相互验证。
抛出:
GSSException,包含以下主要错误代码: - GSSException.FAILURE
GSSException
另请参见:
getMutualAuthState()

requestReplayDet

void requestReplayDet(boolean state)
                      throws GSSException
请求在上下文创建之后针对 per-message 安全服务启用重放检测。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。在上下文创建期间,重放检测不作为选项,而只是基础机制的一项功能。

并非所有的机制都支持重放检测,并且某些机制在应用程序不要求重放检测的情况下也会要求这样做。因此,应用程序必须进行检查,看请求是否与 getReplayDetState 方法有关。如果重放检测已启用,则 MessageProp.isDuplicateTokenMessageProp.isOldToken 方法将为传入到 unwrap 方法或 verifyMIC 方法的 MessageProp 对象返回有效结果。

参数:
state - 布尔值,指示在创建的上下文上是否应该启用重放检测。
抛出:
GSSException,包含以下主要错误代码: - GSSException.FAILURE
GSSException
另请参见:
getReplayDetState()

requestSequenceDet

void requestSequenceDet(boolean state)
                        throws GSSException
请求在上下文创建之后针对 per-message 安全服务启用序列检查。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。在上下文创建期间,序列检查不作为选项,而只是基础机制的一项功能。

并非所有的机制都支持序列检查,并且某些机制在应用程序不要求序列检查的情况下也会要求这样做。因此,应用程序必须进行检查,看请求是否与 getSequenceDetState 方法有关。如果序列检查已启用,则 MessageProp.isDuplicateTokenMessageProp.isOldTokenMessageProp.isUnseqTokenMessageProp.isGapToken 方法将为传入到 unwrap 方法或 verifyMIC 方法的 MessageProp 对象返回有效结果。

参数:
state - 布尔值,指示在创建的上下文上是否应该启用序列检查。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException
另请参见:
getSequenceDetState()

requestCredDeleg

void requestCredDeleg(boolean state)
                      throws GSSException
请求在上下文创建期间将初始端的凭据委托给接受端。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。 并非所有的机制都支持凭据委托。因此,需要委托的应用程序应该进行检查,看请求是否与 getCredDelegState 方法相关。如果应用程序指示不能使用委托,则机制将认可该请求,不执行委托。对于即使在不请求的情况下机制也会启用服务这项常规规则而言,这是个例外。

参数:
state - 布尔值,指示是否应该委托该凭据。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException
另请参见:
getCredDelegState()

requestAnonymity

void requestAnonymity(boolean state)
                      throws GSSException
请求不要将初始端的身份泄露给接受端。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。 并非所有的机制都支持初始端匿名。因此,应用程序应该进行检查,看请求是否与 getAnonymityState 方法相关。

参数:
state - 布尔值,表示作为匿名主体,是否应该向接受端对初始端进行验证。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException
另请参见:
getAnonymityState()

requestConf

void requestConf(boolean state)
                 throws GSSException
请求针对 wrap 方法启用数据机密性。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。 并非所有的机制都支持机密性,并且有些机制即使在应用程序不请求时也会启用它。应用程序会进行检查,看请求是否与 getConfState 方法相关。如果已经启用了机密性,则机制仅在此时认可传入到 wrap 方法的 MessageProp 对象中的保密请求。

启用机密性还会自动启用完整性。

参数:
state - 布尔值,指示是否应该启用机密性。
抛出:
GSSException,包含以下主要错误代码: - GSSException.FAILURE
GSSException
另请参见:
getConfState(), getIntegState(), requestInteg(boolean), MessageProp

requestInteg

void requestInteg(boolean state)
                  throws GSSException
请求针对 wrapgetMIC 方法启用数据完整性。只能在上下文初始端发出此要求,并且必须在初次调用 initSecContext 之前完成。 并非所有的机制都支持完整性,并且有些机制即使在应用程序不请求时也会启用它。应用程序会进行检查,看请求是否与 getIntegState 方法相关。

禁用完整性也将自动禁用机密性。

参数:
state - 布尔值,指示是否应该启用完整性。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException
另请参见:
getIntegState()

requestLifetime

void requestLifetime(int lifetime)
                     throws GSSException
请求上下文以秒为单位的生存期。只能在上下文初始端调用此方法,并且必须在初次调用 initSecContext 之前完成。

上下文的实际生存期将取决于基础机制的功能,并且应用程序必须通过调用 getLifetime 方法来确定此生存期。

参数:
lifetime - 所需要的以秒为单位的上下文生存期。使用 INDEFINITE_LIFETIME 来请求不确定的生存期,使用 DEFAULT_LIFETIME 来请求默认的生存期。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException
另请参见:
getLifetime()

setChannelBinding

void setChannelBinding(ChannelBinding cb)
                       throws GSSException
设置在上下文创建期间使用的通道绑定。此方法既可以在上下文初始端调用,也可以在上下文接受端调用,但必须是在上下文创建开始前调用。这意味着,初始端必须在初次调用 initSecContext 之前调用它,接受端也必须在初次调用 acceptSecContext 之前调用它。

参数:
cb - 要使用的通道绑定。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

getCredDelegState

boolean getCredDelegState()
确定是否在此上下文上启用凭据委托。上下文初始端和上下文接受端都可以调用它。对于确定的答案,仅在完成上下文创建后才调用此方法。注意,如果初始端请求不允许进行委托,则 requestCredDeleg 方法将认可该请求,并且从该点开始,此方法将在初始端返回 false

返回:
如果启用了委托,则返回 true;否则返回 false。
另请参见:
requestCredDeleg(boolean)

getMutualAuthState

boolean getMutualAuthState()
确定是否在此上下文上启用了相互验证。上下文初始端和上下文接受端都可以调用它。对于确定的答案,仅在完成上下文创建后才调用此方法。请求相互验证的初始端可以在上下文完成后调用此方法,并且可以在请求未得到认可的情况下处置该上下文。

返回:
如果启用相互验证,则返回 true,否则返回 false。
另请参见:
requestMutualAuth(boolean)

getReplayDetState

boolean getReplayDetState()
确定是否针对此上下文中的 per-message 安全服务启用了重放检测。上下文初始端和上下文接受端都可以调用它。对于确定的答案,仅在完成上下文创建后才调用此方法。请求重放检测的初始端可以在上下文完成后调用此方法,并且可以在请求未得到认可的情况下处置该上下文。

返回:
如果启用重新检测,则返回 true,否则返回 false。
另请参见:
requestReplayDet(boolean)

getSequenceDetState

boolean getSequenceDetState()
确定是否针对本上下文中的 per-message 安全服务启用了序列检查。上下文初始端和上下文接受端都可以调用它。对于确定的答案,仅在完成上下文创建后才调用此方法。请求序列检查的初始端可以在上下文完成后调用此方法,并且可以在请求未得到认可的情况下处置该上下文。

返回:
如果启用了序列检查,则返回 true,否则返回 false。
另请参见:
requestSequenceDet(boolean)

getAnonymityState

boolean getAnonymityState()
确定是否会向上下文接受端对上下文初始端进行匿名验证。上下文初始端和上下文接受端都可以随时调用它。在初始端上,对此方法的调用将确定初始端的身份是否已在到现在为止由 initSecContext 生成的任何上下文创建标记中泄露过。绝对必须进行匿名验证的初始端必须在每次调用 initSecContext 后调用此方法,以确定是否必须将生成的标记发送给同位体或中断的上下文。在接受端上,对此方法的调用可以确定到现在为止,由 acceptSecContext 处理的标记是否已经泄漏了初始端的身份。

返回:
如果上下文初始端仍是匿名,则返回 true,否则返回 false。
另请参见:
requestAnonymity(boolean)

isTransferable

boolean isTransferable()
                       throws GSSException
确定通过使用 export 方法,该上下文是否可以传输给其他进程。此调用仅在完全创建的上下文上有效。

返回:
如果此上下文可以导出,则返回 True;否则返回 false。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

isProtReady

boolean isProtReady()
确定上下文是否已为要在其上使用的 per message 准备就绪。有些机制可能允许在上下文完全创建之前使用 per-message 操作。

返回:
如果诸如 wrapunwrapgetMICverifyMIC 之类的方法可在上下文创建的当前阶段用于此上下文,则返回 true,否则,则返回 false。

getConfState

boolean getConfState()
确定数据机密性是否可用于上下文。此方法既可由上下文初始端调用,也可以由上下文接受端调用,但是仅在 isProtReadyisEstablished 二者之一返回 true 时调用。如果此方法返回 true,则 getIntegState 也将返回 true

返回:
如果机密性服务可用,则返回 true,否则,则返回 false。
另请参见:
requestConf(boolean)

getIntegState

boolean getIntegState()
确定数据完整性是否可用于上下文。此方法既可由上下文初始端调用,也可以由上下文接受端调用,但是仅在 isProtReadyisEstablished 二者之一返回 true 时调用。如果 getConfState 返回 true,则此方法将始终返回 true

返回:
如果完整性服务可用,则返回 true,否则返回 false。
另请参见:
requestInteg(boolean)

getLifetime

int getLifetime()
确定此上下文剩余的生存期是多长。它既可以由上下文初始端调用,也可以由上下文接受端调用,但是对于确定的答案,仅在 isEstablished 返回 true 后才调用它。

返回:
剩余以秒为单位的生存期
另请参见:
requestLifetime(int)

getSrcName

GSSName getSrcName()
                   throws GSSException
返回上下文初始端的名称。此调用仅在 isProtReadyisEstablished 中的二者之一返回 true 时有效。

返回:
一个 GSSName,它是一个包含上下文初始端名称的 MN。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException
另请参见:
GSSName

getTargName

GSSName getTargName()
                    throws GSSException
返回上下文接受端的名称。此调用仅在 isProtReadyisEstablished 中的二者之一返回 true 时有效。

返回:
一个 GSSName,它是一个包含上下文接受端名称的 MN。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

getMech

Oid getMech()
            throws GSSException
确定什么机制正用于此上下文。此方法可在上下文完全创建之前调用,但在已协商的机制中,返回的机制可能会更改后续的调用。

返回:
正在使用的机制的 Oid
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

getDelegCred

GSSCredential getDelegCred()
                           throws GSSException
获取上下文初始端委托给上下文接受端的凭据。必须仅在上下文接受端上调用它,并且仅在完全创建上下文时调用一次。调用者可以使用方法 getCredDelegState 来确定是否存在委托的凭据。

返回:
一个包含初始方委托凭据的 GSSCredential,如果没有委托的凭据,则返回 null
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

isInitiator

boolean isInitiator()
                    throws GSSException
确定它是否为上下文初始端。这既可以在上下文初始端上调用,也可以在上下文接受端上调用。

返回:
如果是上下文初始端,则返回 true,如果上下文接受端,则返回 false。
抛出:
GSSException,包含以下主要错误代码:{@link - GSSException#FAILURE GSSException.FAILURE}
GSSException

JavaTM Platform
Standard Ed. 6

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

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