This topic describes how to encrypt elements within the WS-Security header in messages sent by InterSystems IRIS web services and web clients. (The tools described here can also be used to encrypt the SOAP body, alone or in combination with security header elements.)
Typically you perform both encryption and signing. This topic describes encryption alone, for simplicity. For information on combining encryption and signing, see Combining Encryption and Signing.
Basic Examples
The following example invokes a web client and sends a <UsernameToken> that is encrypted. In this example, the body is not encrypted.
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)
This client sends messages like the following:
<?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>
As a simple variation, consider the procedure in the preceding section. Suppose that we did the following in step 4 and made no other changes:
set enckey=##class(%XML.Security.EncryptedKey).CreateX509(credset)
In this case, the messages from the client include an encrypted body and an encrypted <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>
In comparison to the previous example, in this case, the <EncryptedKey> element includes references to two <EncryptedData> elements. One is the <EncryptedData> element in the security header, which contains the <UsernameToken>; this reference was created and added manually. The other is the <EncryptedData> element in the SOAP body; this reference was added automatically.