セキュリティ・ヘッダ要素の暗号化

この章では、Caché Web サービスおよび Web クライアントによって送信されるメッセージの WS-Security ヘッダ内の要素を暗号化する方法について説明します(ここで説明するツールは、単独でまたはセキュリティ・ヘッダ要素と組み合わせて、SOAP 本文の暗号化にも使用できます)。以下の項目について説明します。

通常、暗号化と署名の両方を実行します。この章では、説明を簡単にするために、暗号化のみについて説明します。暗号化と署名の組み合わせに関する詳細は、“暗号化と署名の組み合わせ” の章を参照してください。

“暗号化および署名への派生キー・トークンの使用” の章では、さらに別の方法で SOAP メッセージの部分を暗号化する方法について説明します。

セキュリティ・ヘッダ要素の暗号化

前の章で示した暗号化手法と異なり、WS-Security ヘッダ要素を暗号化するプロセスは、<EncryptedData> 要素を対応する <EncryptedKey> 要素に接続する方法を指定する必要があります。

セキュリティ・ヘッダ要素を暗号化するには、以下の手順を実行します。

必要に応じて、%soap.inc インクルード・ファイルを組み込みます。このファイルには、使用する可能性のあるマクロが定義されています。
ヘッダ要素または暗号化される要素を作成します。以下はその例です。
```
 set userToken=##class(%SOAP.Security.UsernameToken).Create("_SYSTEM","SYS")
```
SOAP メッセージを受信するエンティティの公開鍵を含む資格情報セットを取得します。このドキュメント内で前述の “プログラムによる資格情報セットの取得” を参照してください。
以下はその例です。
```
 set credset=..SecurityIn.Signature.X509Credentials
```
“プログラムによる資格情報セットの取得” の説明に従って、返されたオブジェクトのタイプが %SYS.X509CredentialsOpens in a new tab のインスタンスかどうか確認します。
資格情報セットに基づいて、暗号化キーを作成します。そのためには、%XML.Security.EncryptedKeyOpens in a new tab の CreateX509() クラス・メソッドを呼び出し、オプションで 2 番目の引数を指定します。以下はその例です。
```
 set enckey=##class(%XML.Security.EncryptedKey).CreateX509(credset,$$$SOAPWSEncryptNone)
```
このメソッドは、対称鍵を生成し、<EncryptedKey> ヘッダ要素を表す %XML.Security.EncryptedKeyOpens in a new tab のインスタンスを返します。このヘッダ要素には、指定された資格情報セット内にある公開鍵で暗号化された対称鍵が含まれます。
2 番目の引数は、(鍵のその他の使用に加えて) この鍵が SOAP 本文を暗号化するかどうかを指定します。値 $$$SOAPWSEncryptNone は、この鍵が SOAP 本文の暗号化に使用されないことを意味します。この引数を省略すると、SOAP 本文も暗号化されます。
必要に応じて、別のアルゴリズムを使用するように暗号化キーのインスタンスを変更します。この章で前述の “ブロック暗号化アルゴリズムの指定” および “鍵転送アルゴリズムの指定” を参照してください。
各セキュリティ・ヘッダ要素を暗号化するには、その要素に基づいて <EncryptedData> 要素を作成します。そのためには、%XML.Security.EncryptedDataOpens in a new tab の Create() クラス・メソッドを呼び出します。この手順では、暗号化するセキュリティ・ヘッダ要素である 2 番目の引数のみ指定します。以下はその例です。
```
 set encdata=##class(%XML.Security.EncryptedData).Create(,userToken)
```
<EncryptedKey> の場合、参照を <EncryptedData> 要素に追加します。各 <EncryptedData> 要素に対して、以下の手順を実行します。
1. %XML.Security.DataReferenceOpens in a new tab の Create() クラス・メソッドを呼び出し、暗号化されたデータのインスタンスを引数として指定します。
2. 暗号化キー・インスタンスの AddReference() メソッドを呼び出して、データ参照を引数として指定します。
以下はその例です。
```
 set dataref=##class(%XML.Security.DataReference).Create(encdata)
 do enckey.AddReference(dataref)
```
この手順は、暗号化キー・インスタンスを更新し、暗号化されたデータのインスタンスへのポインタを組み込みます。
この <EncryptedKey> が SOAP 本文も暗号化する場合、<Body> の <EncryptedData> 要素への参照も自動的に組み込まれます。
WS-Security ヘッダ要素に <EncryptedKey> 要素を追加します。そのためには、Web クライアントまたは Web サービスの SecurityOut プロパティの AddSecurityElement() メソッドを呼び出します。追加する要素について、%XML.Security.EncryptedKeyOpens in a new tab のインスタンスを指定します。
以下はその例です。
```
 do ..SecurityOut.AddSecurityElement(enckey)
```
暗号化されたセキュリティ・ヘッダ要素を WS-Security ヘッダ要素に追加します。そのためには、Web クライアントまたは Web サービスの SecurityOut プロパティの AddSecurityElement() メソッドを呼び出します。この場合、以下の 2 つの引数を指定します。
1. 組み込むセキュリティ・ヘッダ要素 (その要素に基づく %XML.Security.EncryptedDataOpens in a new tab のインスタンスではない)。
2. 暗号化キー・インスタンス。2 番目の引数は、最初の引数が指定するアイテムの配置場所を指定します。引数が A、B の場合、Caché は、A が B の後であることを確認します。これを指定して、受信者が暗号化キーを最初に処理し、これに依存する暗号化されたセキュリティ・ヘッダ要素を後で処理するようにします。
以下はその例です。
```
 do ..SecurityOut.AddSecurityElement(userToken,enckey)
```
SOAP メッセージを送信します。このドキュメントで前述の “セキュリティ・ヘッダ要素の追加” の一般的な手順を参照してください。

基本的な例

以下の例は、Web クライアントを呼び出し、暗号化された <UsernameToken> を送信します。この例では、本文は暗号化されません。

  Set client=##class(XMLEncrSecHeader.Client.XMLEncrSecHeaderSoap).%New()

  // Create UsernameToken
  set user="_SYSTEM"
  set pwd="SYS"
  set userToken=##class(%SOAP.Security.UsernameToken).Create(user,pwd)
 
  //get credentials for encryption
  set cred = ##class(%SYS.X509Credentials).GetByAlias("servernopassword") 

  //get EncryptedKey element and add it
  set encropt=$$$SOAPWSEncryptNone   ; means do not encrypt body
  set enckey=##class(%XML.Security.EncryptedKey).CreateX509(cred,encropt)

  //create EncryptedData and add a reference to it from EncryptedKey
  set encdata=##class(%XML.Security.EncryptedData).Create(,userToken)
  set dataref=##class(%XML.Security.DataReference).Create(encdata)
  do enckey.AddReference(dataref)

  //add EncryptedKey to security header
  do client.SecurityOut.AddSecurityElement(enckey) 
  //add UsernameToken and place it after EncryptedKey
  do client.SecurityOut.AddSecurityElement(userToken,enckey) 

  Quit client.Divide(1,2)

このクライアントは、次のようなメッセージを送信します。

<?xml version="1.0" encoding="UTF-8" ?>
   <SOAP-ENV:Envelope [parts omitted]>  
      <SOAP-ENV:Header>
         <Security xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
               <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
                  <DigestMethod 
                    xmlns="http://www.w3.org/2000/09/xmldsig#"
                    Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
                  </DigestMethod>
               </EncryptionMethod>
               <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                  <SecurityTokenReference 
                       xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
                     <KeyIdentifier EncodingType="[parts omitted]#Base64Binary"    
                            ValueType="[parts omitted]#ThumbprintSHA1">[omitted]</KeyIdentifier>
                  </SecurityTokenReference>
               </KeyInfo>
               <CipherData>
                  <CipherValue>pftET8jFDEjNC2x[parts omitted]xEjNC2==</CipherValue>
               </CipherData>
               <ReferenceList>
                  <DataReference URI="#Enc-61000920-44DE-471E-B39C-6D08CB17FDC2">
                  </DataReference>
               </ReferenceList>
            </EncryptedKey>
            <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" 
                   Id="Enc-61000920-44DE-471E-B39C-6D08CB17FDC2" 
                   Type="http://www.w3.org/2001/04/xmlenc#Element">
               <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
               </EncryptionMethod>
               <CipherData>
                  <CipherValue>wW3ZM5tgPD[parts omitted]tgPD==</CipherValue>
               </CipherData>
            </EncryptedData>
         </Security>  
      </SOAP-ENV:Header>  
      <SOAP-ENV:Body>
         [omitted]
      </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

単純なバリエーションとして、前のセクションの手順を考えてみます。手順 4 で以下を実行し、他には変更しないものとします。

 set enckey=##class(%XML.Security.EncryptedKey).CreateX509(credset)

この場合、クライアントからのメッセージには、暗号化された本文および暗号化された <UsernameToken> が含まれています。

<?xml version="1.0" encoding="UTF-8" ?>
   <SOAP-ENV:Envelope [parts omitted]>  
      <SOAP-ENV:Header>
         <Security xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
               <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
                  <DigestMethod xmlns="http://www.w3.org/2000/09/xmldsig#" 
                        Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
                  </DigestMethod>
               </EncryptionMethod>
               <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                  <SecurityTokenReference 
                     xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
                     <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                         ValueType="[parts omitted]#ThumbprintSHA1">
                               5a[parts omitted]dM1r6cM=
                     </KeyIdentifier>
                  </SecurityTokenReference>
               </KeyInfo>
               <CipherData>
                  <CipherValue>TB8uavpr[parts omitted]nZBiMCcg==</CipherValue>
               </CipherData>
               <ReferenceList>
                  <DataReference URI="#Enc-43FE435F-D1D5-4088-A343-0E76D154615A"></DataReference>
                  <DataReference URI="#Enc-55FE109A-3C14-42EB-822B-539E380EDE48"></DataReference>
               </ReferenceList>
            </EncryptedKey>
            <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" 
                 Id="Enc-43FE435F-D1D5-4088-A343-0E76D154615A" 
                 Type="http://www.w3.org/2001/04/xmlenc#Element">
               <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
               </EncryptionMethod>
               <CipherData>
                  <CipherValue>G+X7dqI[parts omitted]nojroQ==</CipherValue>
               </CipherData>
            </EncryptedData>
         </Security>  
      </SOAP-ENV:Header>  
      <SOAP-ENV:Body>
         <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" 
                  Id="Enc-55FE109A-3C14-42EB-822B-539E380EDE48" 
                  Type="http://www.w3.org/2001/04/xmlenc#Content">
            <EncryptionMethod Algorithm="[parts omitted]aes128-cbc"></EncryptionMethod>
            <CipherData>
               <CipherValue>YJbzyi[parts omitted]NhJoln==</CipherValue>
            </CipherData>
         </EncryptedData>
      </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

前の例と比べると、この場合、<EncryptedKey> 要素には、2 つの <EncryptedData> 要素への参照が含まれています。一方は、セキュリティ・ヘッダの <EncryptedData> 要素で、これには <UsernameToken> が含まれています。この参照は、手動で作成および追加されました。もう一方は、SOAP 本文の <EncryptedData> 要素です。この参照は、自動で追加されました。