Securing Caché Web Services
Details of the Security Elements
[Back] 
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Search:    

This appendix discusses the more common security elements in SOAP messages, in particular the variations that can be sent by Caché web services and clients. This information is intended as a refresher for the memory of anyone who does not continually work with SOAP. The details here may also be useful in troubleshooting.

This appendix discusses the following items:
<BinarySecurityToken>
The purpose of <BinarySecurityToken> is to carry security credentials that are used by other elements in the message, for use by the message recipient. The security credentials are carried in serialized, encoded form. The following shows a partial example:
<BinarySecurityToken wsu:Id="SecurityToken-4EC1997A-AD6B-48E3-9E91-8D50C8EA3B53" 
                     EncodingType="[parts omitted]#Base64Binary" 
                     ValueType="[parts omitted]#X509v3">
             MIICnDCCAYQ[parts omitted]ngHKNhh
</BinarySecurityToken>
Details
The parts of this element are as follows:
If this token is associated with an encryption action, then the contained certificate is the certificate of the message recipient. If this token is associated with signing, then the contained certificate is the certificate of the message sender.
Position in Message
A <BinarySecurityToken> should be included within <Security> before any elements that refer to it.
<EncryptedKey>
The purpose of <EncryptedKey> is to carry a symmetric key that is used by other elements in the message. The symmetric key is carried in encrypted form. The following shows a partial example:
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
   <EncryptionMethod Algorithm="[parts omitted]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">
         <Reference URI="#SecurityToken-4EC1997A-AD6B-48E3-9E91-8D50C8EA3B53" 
                    ValueType="[parts omitted]#X509v3">
         </Reference>
      </SecurityTokenReference>
   </KeyInfo>
   <CipherData>
      <CipherValue>WtE[parts omitted]bSyvg==</CipherValue>
   </CipherData>
   <ReferenceList>
      <DataReference URI="#Enc-143BBBAA-B75D-49EB-86AC-B414D818109F"></DataReference>
   </ReferenceList>
</EncryptedKey>
Details
The parts of this element are as follows:
Position in Message
An <EncryptedKey> element should be included within <Security> after any <BinarySecurityToken> that it uses and before all <EncryptedData> and <DerivedKeyToken> elements that refer to it.
<EncryptedData>
The purpose of <EncryptedData> is to carry encrypted data. The following shows a partial example:
<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" 
               Id="Enc-143BBBAA-B75D-49EB-86AC-B414D818109F" 
               Type="http://www.w3.org/2001/04/xmlenc#Content">
   <EncryptionMethod Algorithm="[parts omitted]#aes128-cbc"></EncryptionMethod>
   <CipherData>
      <CipherValue>MLwR6hvKE0gon[parts omitted]8njiQ==</CipherValue>
   </CipherData>
</EncryptedData>
Details
The parts of this element are as follows:
Position in Message
Within <Security>, an <EncryptedData> element should be included after the associated <EncryptedKey>.
An <EncryptedData> element can also be the child of the SOAP body (the <Body> element).
<Signature>
The purpose of <Signature> is to carry a digital signature that can be verified by the recipient of the message. You use digital signatures to detect message alteration or to simply validate that a certain part of a message was really generated by the entity which is listed. As with the traditional manually written signature, a digital signature is an addition to the document that can be created only by the creator of that document and that cannot easily be forged.
The following shows a partial example:
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
   <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
      </CanonicalizationMethod>
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha256"></SignatureMethod>
      <Reference URI="#Timestamp-48CEE53E-E6C3-456C-9214-B7D533B2663F">
         <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></Transform>
         </Transforms>
         <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></DigestMethod>
         <DigestValue>waSMFeYMruQn9XHx85HqunhMGIA=</DigestValue>
      </Reference>
      <Reference URI="#Body-73F08A5C-0FFD-4FE9-AC15-254423DBA6A2">
         <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></Transform>
         </Transforms>
         <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></DigestMethod>
         <DigestValue>wDCqAzy5bLKKF+Rt0+YV/gxTQws=</DigestValue>
      </Reference>
   </SignedInfo>
   <SignatureValue>j6vtht/[parts omitted]trCQ==</SignatureValue>
   <KeyInfo>
      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <Reference URI="#SecurityToken-411A262D-990E-49F3-8D12-7D7E56E15081" 
                    ValueType="[parts omitted]oasis-200401-wss-x509-token-profile-1.0#X509v3">
         </Reference>
      </SecurityTokenReference>
   </KeyInfo>
</Signature>
Details
The parts of this element are as follows:
Position in Message
A <Signature> element should be included within <Security> after the <BinarySecurityToken> or <DerivedKeyToken> that it uses, if any.
<DerivedKeyToken>
The purpose of <DerivedKeyToken> is to carry information that both the sender and the recipient can independently use to generate the same symmetric key. These parties can use that symmetric key for encryption, decryption, signing, and signature validation, for the associated parts of the SOAP message.
The following shows a partial example:
<DerivedKeyToken xmlns="[parts omitted]ws-secureconversation/200512" 
                 xmlns:wsc="[parts omitted]ws-secureconversation/200512" 
                 wsu:Id="Enc-943C6673-E3F3-48E4-AA24-A7F82CCF6511">
   <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <Reference URI="#Id-658202BF-239A-4A8C-A100-BB25579F366B"></Reference>
   </SecurityTokenReference>
   <Nonce>GbjRvVNrPtHs0zo/w9Ne0w==</Nonce>
</DerivedKeyToken>
Details
The parts of this element are as follows:
Computation for the <DerivedKeyToken> element uses a subset of the mechanism defined for TLS in RFC 2246.
The connection between the <DerivedKeyToken> element and the associated <EncryptedData> or <Signature> elements is handled as follows:
Position in Message
A <DerivedKeyToken> should be included within <Security> before any <EncryptedData> and <Signature> elements that refer to it.
<ReferenceList>
This section discusses the <ReferenceList> element, when used as a child of <Security> in the message header. When <ReferenceList> is used in this way, it is possible to perform encryption before signing. The following shows an example of this element:
<ReferenceList xmlns="http://www.w3.org/2001/04/xmlenc#">
   <DataReference URI="#Enc-358FB189-81B3-465D-AFEC-BC28A92B179C"></DataReference>
   <DataReference URI="#Enc-9EF5CCE4-CF43-407F-921D-931B5159672D"></DataReference>
</ReferenceList>
Details
In each <DataReference> element, the URI attribute points to the Id attribute of an <EncryptedData> element elsewhere in the message.
When you use a top-level <ReferenceList> element, the details are different for <EncryptedKey> and <EncryptedData>, as follows:
Scenario <EncryptedKey> <EncryptedData>
<EncryptedKey> contains pointer to <EncryptedData> Includes <KeyInfo> (same for all associated <EncryptedData> elements) Does not include <KeyInfo>
Top-level <ReferenceList> element contains pointer to <EncryptedData> Does not include <KeyInfo> Includes <KeyInfo> (potentially different for each <EncryptedData> element.
Position in Message
Within <Security>, a <ReferenceList> element should be included after the associated <EncryptedKey>.