安全な通信の作成

Caché は、WS-SecureConversation 1.3 仕様に従って、安全な通信をサポートします。これを行う最も簡単な方法は、セキュリティ・ポリシーを作成し、Web サービス/クライアント構成ウィザードの [保護セッション (安全な通信) を確立する] オプションを使用することです。別のオプションは、この章で説明するように、手動で安全な通信を作成することです。この章では、以下のトピックについて説明します。

概要

安全な通信では、Web クライアントは、最初の要求を Web サービスに対して行い、<SecurityContextToken> を含むメッセージを受信します。この要素には、両者が使用できる対称鍵に関する情報が含まれています。この情報は、この両者のみが知っている共有秘密鍵を参照します。両者は、トークンが無効になるまで、またはクライアントがトークンをキャンセルするまで、この対称鍵をその後のメッセージ交換に使用できます。

これらのタスクに <SecurityContextToken> を直接使用する (これはお勧めしません) のではなく、両者は、このトークンから <DerivedKeyToken> を生成し、これを暗号化、署名、解読、およびシグニチャ検証に使用する必要があります。

共有秘密鍵は、以下のいずれかの方法で指定できます。

両者がランダム・エントロピー値を指定する場合、両者が共同で指定。これは、一般的なシナリオです。
クライアントがランダム・クライアント・エントロピー値を指定する場合、クライアントが指定。
サービスがランダム・サービス・エントロピー値を指定する場合、サービスが指定。

安全な通信の開始

Web クライアントは、安全な通信を開始します。Caché でこれを行うには、Web クライアント内で以下の手順を実行します。

このドキュメントで前述したように、SOAP 本文を暗号化します。クライアントが送信した要求には、保護する必要がある情報が含まれています。この情報は、SOAP 本文内に保持されます。
必要に応じて、別の方法で要求メッセージを保護します。このドキュメントの前の各章を参照してください。
%SOAP.WST.EntropyOpens in a new tab の CreateBinarySecret() メソッドを呼び出します。このメソッドは、ランダム・クライアント・エントロピーを表すクラスのインスタンスを返します。このメソッドは、1 つの引数 (バイト単位のエントロピーのサイズ) を取ります。
以下はその例です。
```
 set clientEntropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)
```
このインスタンスは、<Entropy> 要素およびこれに含まれる <BinarySecret> を表します。
%SOAP.WST.RequestSecurityTokenOpens in a new tab の CreateIssueRequest() クラス・メソッドを呼び出します。このメソッドは、安全な通信を要求するためにクライアントが使用する、このクラスのインスタンスを返します。このメソッドには、以下の引数があります。
1. Interval。要求されたトークンの存続期間。既定は 300 秒です。存続期間を指定しない場合、空の文字列を使用します。
2. clientEntropy。前の手順で作成したクライアント・エントロピー・オブジェクト (該当する場合)。
3. requireServerEntropy。サーバが <SecurityContextToken> を作成するときにサーバ・エントロピーを使用する必要があるかどうかを指定するブーリアン値。既定値は False です。
```
 set RST=##class(%SOAP.WST.RequestSecurityToken).CreateIssueRequest(300,clientEntropy,1)
```
オプションで、%SOAP.WST.RequestSecurityTokenOpens in a new tab インスタンスの ComputedKeySize プロパティを指定します。
Web クライアントの StartSecureConversation() メソッドを呼び出します。このメソッドは、両者が使用できる <SecurityContextToken> を要求する Web サービスにメッセージを送信します。このメソッドは、1 つの引数 (前の手順の %SOAP.WST.RequestSecurityTokenOpens in a new tab のインスタンス) を取ります。
このメソッドは、ステータス・コードを返すので、コードでこのステータス・コードを確認する必要があります。応答が成功を示す場合、クライアントの SecurityContextToken プロパティには、クライアントから返された <SecurityContextToken> を表す %SOAP.WSSC.SecurityContextTokenOpens in a new tab のインスタンスが含まれます。この要素には、両者が暗号化、署名、解読、およびシグニチャ検証に使用できる対称鍵に関する情報が含まれています。
<SecurityContextToken> を使用して、必要に応じてセキュリティ・ヘッダを再指定します。この章で後述の “<SecurityContextToken> の使用” を参照してください。

以下に例を示します。

  //encrypt the SOAP body because it contains part of the shared secret key
  Set x509alias = "servernopassword" 
  Set cred = ##class(%SYS.X509Credentials).GetByAlias(x509alias)
  set enckey=##class(%XML.Security.EncryptedKey).CreateX509(cred)
  do client.SecurityOut.AddSecurityElement(enckey)
 
  // if client entropy to be passed
  set entropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)
  // request with 300 second lifetime and computed key using both client 
  //and server entropy.
  set RST=##class(%SOAP.WST.RequestSecurityToken).CreateIssueRequest(300,entropy,1)
  set sc=client.StartSecureConversation(RST)  ; sends a SOAP message

Caché Web サービスによる WS-SecureConversation のサポートの有効化

安全な通信は、Web クライアントが Web サービスにメッセージを送信して安全な通信を要求したときに開始されます。応答で、Web サービスは、両者が使用できる <SecurityContextToken> を送信します。

Caché Web サービスがこのトークンを使用して応答できるようにするには、この Web サービスの OnStartSecureConversation() メソッドを上書きします。このメソッドには、以下のシグニチャがあります。

Method OnStartSecureConversation(RST As %SOAP.WST.RequestSecurityToken) As 
                          %SOAP.WST.RequestSecurityTokenResponseCollection

このメソッドは、以下を実行します。

このドキュメントで前述したように、SOAP 本文を暗号化します。OnStartSecureConversation() が送信したメッセージには、保護する必要がある情報が含まれています。この情報は、SOAP 本文内に保持されます。
必要に応じて、別の方法でメッセージを保護します。このドキュメントの前の各章を参照してください。
オプションで、%SOAP.WST.EntropyOpens in a new tab の CreateBinarySecret() メソッドを呼び出します。このメソッドは、ランダム・サーバ・エントロピーを表すクラスのインスタンスを返します。このメソッドは、1 つの引数 (バイト単位のエントロピーのサイズ) を取ります。
以下はその例です。
```
 set serverEntropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)
```
このインスタンスは、<Entropy> 要素およびこれに含まれる <BinarySecret> を表します。
OnStartSecureConversation() が受信する %SOAP.WST.RequestSecurityTokenOpens in a new tab インスタンスの CreateIssueResponse() メソッドを呼び出します。CreateIssueResponse() メソッドは以下の引数を取ります。
1. $THIS。現在の Web サービスのインスタンスを表します。
2. keysize。目的の鍵のサイズ (バイト単位)。この引数は、サーバ・エントロピーとクライアント・エントロピーの両方が指定される場合にのみ使用されます。クライアント・エントロピーの鍵とサーバ・エントロピーの鍵が指定された場合、既定では小さいほうの鍵のサイズになります。
3. requireClientEntropy。要求にクライアント・エントロピーを含めることを Web サービスが要求するかどうかに応じて、True または False のいずれかです。これが False の場合、要求にクライアント・エントロピーを含めないでください。
4. serverEntropy。手順 2 で作成したサーバ・エントロピー・オブジェクト (該当する場合)。
5. error。出力パラメータとして返されるステータス・コード。
6. lifetime。安全な通信の存続時間を指定する秒単位の整数。
以下はその例です。
```
 set responseCollection=RST.CreateIssueResponse($this,,1,serverEntropy,.error)
```
前の手順の error 出力パラメータをチェックします。エラーが発生した場合、コードで Web サーバの SoapFault プロパティを設定し、空の文字列を返す必要があります。
成功の場合、手順 2 で作成された %SOAP.WST.RequestSecurityTokenResponseCollectionOpens in a new tab のインスタンスを返します。
このインスタンスは、<RequestSecurityTokenResponseCollection> 要素を表します。これには、両者が使用できる <SecurityContextToken> が含まれています。

以下に例を示します。

Method OnStartSecureConversation(RST As %SOAP.WST.RequestSecurityToken) 
As %SOAP.WST.RequestSecurityTokenResponseCollection
{
 // encrypt the SOAP body sent by this messsage 
 //because it contains part of the shared secret key
 Set x509alias = "clientnopassword" 
 Set cred = ##class(%SYS.X509Credentials).GetByAlias(x509alias)
 set enckey=##class(%XML.Security.EncryptedKey).CreateX509(cred)
 do ..SecurityOut.AddSecurityElement(enckey)

 //Supply the server entropy
 set serverEntropy=##class(%SOAP.WST.Entropy).CreateBinarySecret(32)
 // Get the response collection for computed key
 set responseCollection=RST.CreateIssueResponse($this,,1,serverEntropy,.error)
 
 If error'="" {
    set ..SoapFault=##class(%SOAP.WST.RequestSecurityTokenResponse).MakeFault("InvalidRequest")
    Quit ""
    }
 
 Quit responseCollection
}

Note:

OnStartSecureConversation() メソッドは最初に定義され、<SecurityContextToken> がポリシーによって指定された場合にのみ、これを返します。“ポリシーの作成と使用” を参照してください。

<SecurityContextToken> の使用

Web サービスが <SecurityContextToken> を使用して応答すると、クライアントのインスタンスおよびサービスのインスタンスは、同じ対称鍵にアクセスできます。この鍵の情報は、両方のインスタンスの SecurityContextToken プロパティに格納されています。推奨される手順は、以下のとおりです。

クライアントで、SecurityOut プロパティを NULL に設定し、要求メッセージで使用されたセキュリティ・ヘッダを削除します。
この手順は、Web サービスでは必要ありません。Web サービスは、各呼び出し後にセキュリティ・ヘッダを自動的にクリアするためです。
必要に応じて、WS-Security ヘッダ要素に <SecurityContextToken> を追加します。そのためには、Web クライアントまたは Web サービスの SecurityOut プロパティの AddSecurityElement() メソッドを呼び出します。以下はその例です。
以下はその例です。
```
 set SCT=..SecurityContextToken
 do ..SecurityOut.AddSecurityElement(SCT)
```
次の手順で派生キー・トークンを作成するときに $$$SOAPWSReferenceSCT 参照オプションを使用する場合、この手順は必須です。それ以外の場合、この手順は必要ありません。
<SecurityContextToken> に基づいて、新しい <DerivedKeyToken> を作成します。そのためには、以下のように %SOAP.WSSC.DerivedKeyTokenOpens in a new tab の Create() メソッドを呼び出します。
```
 set dkenc=##class(%SOAP.WSSC.DerivedKeyToken).Create(SCT,refOpt)
```
このシナリオでは、Create() に最初の引数を指定する必要があり、また、refOpt は以下の参照値のいずれかにする必要があります。
- $$$SOAPWSReferenceSCT (ローカル参照) — 参照の URI 属性は、# で始まり、<SecurityContextToken> 要素の wsu:Id 値を指します。これは、メッセージに含まれている必要があります。
- $$$SOAPWSReferenceSCTIdentifier (リモート参照) — 参照の URI 属性には、<SecurityContextToken> 要素の <Identifier> 値が含まれています。これは、メッセージに含まれている必要はありません。
以下はその例です。
```
 set dkenc=##class(%SOAP.WSSC.DerivedKeyToken).Create(SCT,$$$SOAPWSReferenceSCT)
```
必要に応じて新しい <DerivedKeyToken> を使用し、セキュリティ・ヘッダを指定します。“暗号化および署名への派生キー・トークンの使用” の章を参照してください。
SOAP メッセージを送信します。このドキュメントで前述の “セキュリティ・ヘッダ要素の追加” の一般的な手順を参照してください。

以下に例を示します。

  //initiate conversation -- not shown here
  //clear SecurityOut so that we can respecify the security header elements for
  //the secure conversation
  set client.SecurityOut=""

  //get SecurityContextToken
  set SCT=client.SecurityContextToken
  do client.SecurityOut.AddSecurityElement(SCT) 

  // get derived keys
  set dksig=##class(%SOAP.WSSC.DerivedKeyToken).Create(SCT,$$$SOAPWSReferenceSCT)
  do client.SecurityOut.AddSecurityElement(dksig)

  // create and add signature
  set sig=##class(%XML.Security.Signature).Create(dksig,,$$$SOAPWSReferenceDerivedKey)
  do client.SecurityOut.AddSecurityElement(sig) 

  
  //invoke web methods

安全な通信の終了

安全な通信は、<SecurityContextToken> の有効期限が切れるとすぐに終了しますが、Web クライアントは、有効期限が切れていない <SecurityContextToken> をキャンセルして、通信を終了することも可能です。

安全な通信を終了するには、Web クライアントの CancelSecureConversation() メソッドを呼び出します。以下はその例です。

 set status=client.CancelSecureConversation()

メソッドはステータス値を返します。

このメソッドは、クライアントの SecurityOut プロパティを空の文字列に設定することに注意してください。