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

欄位摘要

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) 請求針對 wrap 和 getMIC 方法啟用資料完整性。
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_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

getWrapSizeLimit

int getWrapSizeLimit(int qop,
                     boolean confReq,
                     int maxTokenSize)
                     throws GSSException

用來確定可以傳輸給 wrap 的訊息的大小限制。如果以相同的 confReq 和 qop 參數呈現給 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_QOP、GSSException.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_QOP、GSSException.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_QOP、GSSException.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_MIC、GSSException.CONTEXT_EXPIRED、GSSException.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_MIC、GSSException.CONTEXT_EXPIRED、GSSException.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_QOP、GSSException.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_QOP、GSSException.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_TOKEN、GSSException.BAD_MIC、GSSException.CONTEXT_EXPIRED、GSSException.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_TOKEN、GSSException.BAD_MIC、GSSException.CONTEXT_EXPIRED、GSSException.FAILURE

GSSException

export

byte[] export()
              throws GSSException

導出此上下文，以便使其他進程能夠導入它。假設支持在多個進程間共享工作。此例程通常由應用程序中的上下文接受端使用，在該應用程序中，單一進程接收傳入的連接請求，並通過它們獲得安全上下文，然後將創建的上下文傳遞給一個或多個其他的進程，從而進行訊息交換。

此方法將取消啟動安全上下文，並創建一個進程間標記，當將該標記傳遞給另一個進程中的 GSSManager.createContext 時，它將在第二個進程中重新啟動上下文。只有給定上下文的單一實例化可以在任何時間處於活動狀態；上下文導出器對導出的安全上下文的後續存取嘗試都不會成功。

該實作可以限制進程的 set，可以通過這些進程導入進程間的標記，要麼將其作為本地安全策略的一項功能，要麼將其作為實作決策的結果。例如，有些實作會限制上下文僅在在同一帳戶下運行的進程間傳遞，或者上下文是同一進程組的一部分。

進程間的標記可以包含安全性敏感資訊（例如，加密密鑰）。儘管鼓勵機制要麼避免將此類別敏感性資訊放在進程間標記中，要麼在將標記返回到應用程序前對其進行加密，但在典型的 GSS-API 實作中，這是不可能的。因此，應用程序必須小心地保護進程間的標記，並確保標記將要向其傳輸的任何進程都是完全受信任的。

不要求實作支持安全上下文的進程間的傳輸。調用 isTransferable 方法將指示上下文物件是否可傳輸。

在不可導出的上下文上調用此方法會導致拋出以下異常，並帶有錯誤程式碼 GSSException.UNAVAILABLE。

返回：

一個套件含導出的上下文的 byte[]

拋出：

GSSException，包含以下主要錯誤程式碼：{@link - GSSException#UNAVAILABLE GSSException.UNAVAILABLE}、GSSException.CONTEXT_EXPIRED、GSSException.NO_CONTEXT、GSSException.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.isDuplicateToken 和 MessageProp.isOldToken 方法將為傳入到 unwrap 方法或 verifyMIC 方法的 MessageProp 物件返回有效結果。

參數：

state - 布林值，指示在創建的上下文上是否應該啟用重放檢測。

拋出：

GSSException，包含以下主要錯誤程式碼： - GSSException.FAILURE

GSSException

另請參見：

getReplayDetState()

requestSequenceDet

void requestSequenceDet(boolean state)
                        throws GSSException

請求在上下文創建之後針對 per-message 安全服務啟用序列檢查。只能在上下文初始端發出此要求，並且必須在初次調用 initSecContext 之前完成。在上下文創建期間，序列檢查不作為選項，而只是基礎機制的一項功能。

並非所有的機制都支持序列檢查，並且某些機制在應用程序不要求序列檢查的情況下也會要求這樣做。因此，應用程序必須進行檢查，看請求是否與 getSequenceDetState 方法有關。如果序列檢查已啟用，則 MessageProp.isDuplicateToken、MessageProp.isOldToken、MessageProp.isUnseqToken 和 MessageProp.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

請求針對 wrap 和 getMIC 方法啟用資料完整性。只能在上下文初始端發出此要求，並且必須在初次調用 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 操作。

返回：

如果諸如 wrap、unwrap、getMIC 和 verifyMIC 之類別的方法可在上下文創建的當前階段用於此上下文，則返回 true，否則，則返回 false。

getConfState

boolean getConfState()

確定資料機密性是否可用於上下文。此方法既可由上下文初始端調用，也可以由上下文接受端調用，但是僅在 isProtReady 或 isEstablished 二者之一返回 true 時調用。如果此方法返回 true，則 getIntegState 也將返回 true

返回：

如果機密性服務可用，則返回 true，否則，則返回 false。

另請參見：

requestConf(boolean)

getIntegState

boolean getIntegState()

確定資料完整性是否可用於上下文。此方法既可由上下文初始端調用，也可以由上下文接受端調用，但是僅在 isProtReady 或 isEstablished 二者之一返回 true 時調用。如果 getConfState 返回 true，則此方法將始終返回 true。

返回：

如果完整性服務可用，則返回 true，否則返回 false。

另請參見：

requestInteg(boolean)

getLifetime

int getLifetime()

確定此上下文剩餘的生存期是多長。它既可以由上下文初始端調用，也可以由上下文接受端調用，但是對於確定的答案，僅在 isEstablished 返回 true 後才調用它。

返回：

剩餘以秒為單位的生存期

另請參見：

requestLifetime(int)

getSrcName

GSSName getSrcName()
                   throws GSSException

返回上下文初始端的名稱。此調用僅在 isProtReady 或 isEstablished 中的二者之一返回 true 時有效。

返回：

一個 GSSName，它是一個套件含上下文初始端名稱的 MN。

拋出：

GSSException，包含以下主要錯誤程式碼：{@link - GSSException#FAILURE GSSException.FAILURE}

GSSException

另請參見：

GSSName

getTargName

GSSName getTargName()
                    throws GSSException

返回上下文接受端的名稱。此調用僅在 isProtReady 或 isEstablished 中的二者之一返回 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