Skip to main content
Previous section

Details of the Security Elements

This topic discusses the more common security elements in SOAP messages, in particular the variations that can be sent by InterSystems IRIS 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.

<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>
Copy code to clipboard

Details

The parts of this element are as follows:

  • Id is the unique identifier for this token, included so that other elements in this message can refer to this token. InterSystems IRIS generates this automatically if necessary.

  • EncodingType indicates the type of encoding that was used to generate the value in the <BinarySecurityToken>. In InterSystems IRIS, the only encoding used in a <BinarySecurityToken> is base-64 encoding.

  • ValueType indicates the type of value that is contained in the token. In InterSystems IRIS, the only supported value type is an X.509 certificate.

  • The value contained within the <BinarySecurityToken> element is the serialized, encoded certificate. In this example, the value MIICnDCCAYQ[parts omitted]ngHKNhh is the security credentials.

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>
Copy code to clipboard

Details

The parts of this element are as follows:

  • <EncryptionMethod> indicates the algorithms that were used to encrypt the symmetric key.

    In InterSystems IRIS, you can specify the key transport algorithm (shown by the Algorithm attribute of <EncryptionMethod>). See “Specifying the Key Transport Algorithm.”

  • <KeyInfo> identifies the key that was used to encrypt this symmetric key. In InterSystems IRIS, <KeyInfo> includes a <SecurityTokenReference>, which has one of the following forms:

    • A reference to a <BinarySecurityToken> earlier in the WS-Security header, as shown in the preceding example.

    • Information to uniquely identify the certificate, which presumably the message recipient owns. For example, the <SecurityTokenReference> could include the SHA1 thumbprint of the certificate, as follows:

      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                        ValueType="[parts omitted]#ThumbprintSHA1">
            maedm8CNoh4zH8SMoF+3xV1MYtc=
         </KeyIdentifier>
      </SecurityTokenReference>
      
      Copy code to clipboard

    In both cases, the corresponding public key was used to encrypt the symmetric key that is carried in this <EncryptedKey> element.

    This element is omitted if the encryption uses a top-level <ReferenceList> element; see “<ReferenceList>.”

  • <CipherData> carries the encrypted symmetric key, as the value in the <CipherValue> element. In this example, the value WtE[parts omitted]bSyvg== is the encrypted symmetric key.

  • <ReferenceList> indicates the part or parts of this message that were encrypted with the symmetric key carried in this <EncryptedKey> element. Specifically, the URI attribute of a <DataReference> points to the Id attribute of an <EncryptedData> element elsewhere in the message.

    Depending on the technique that you use, this element might not be included. It is possible to instead link a <EncryptedData> and the corresponding <EncryptedKey> via a top-level <ReferenceList> element; see “<ReferenceList>.”

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>
Copy code to clipboard

Details

The parts of this element are as follows:

  • Id is the unique identifier for the element. InterSystems IRIS generates this automatically.

  • <EncryptionMethod> indicates the algorithm that was used to encrypt this data.

    In InterSystems IRIS, you can specify this algorithm. See “Specifying the Block Encryption Algorithm.”

  • <CipherData> carries the encrypted data, as the value in the <CipherValue> element. In this example, the value MLwR6hvKE0gon[parts omitted]8njiQ== is the encrypted data.

  • (Not included in the example) <KeyInfo> identifies the symmetric key. In this case, <KeyInfo> includes a <SecurityTokenReference> element, which includes a reference to a symmetric key in one of the following forms:

    • A reference to a <DerivedKeyToken> earlier in the WS-Security header.

    • A reference to an implied <DerivedKeyToken>. For example:

      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
         <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                       s01:Nonce="mMDk0zn8V7WTsFaIjUJ7zg==" 
                       xmlns:s01="http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512">
            <Reference URI="#Id-93F97220-568E-47FC-B3E1-A2CF3F70B29B"></Reference>
         </SecurityTokenReference>
      </KeyInfo>
      Copy code to clipboard

      In this case, the URI attribute in <Reference> points to the <EncryptedKey> element used to generate the <DerivedKeyToken>, and the Nonce attribute indicates the nonce value that was used.

    In both cases, this derived key was used to encrypt the data that is carried in this <EncryptedData> element.

    The <KeyInfo> element is included if the encryption uses a top-level <ReferenceList> element; see “<ReferenceList>.”

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>
Copy code to clipboard

Details

The parts of this element are as follows:

  • <SignedInfo> indicates the parts of the message that are signed by this signature and indicates how those parts were processed before signing.

    In InterSystems IRIS, you can specify the digest method (shown by the Algorithm attribute of <DigestMethod>). See “Specifying the Digest Method.”

    You can also specify the algorithm used to compute the signature (shown by the Algorithm attribute of <SignatureMethod>). See “Specifying the Signature Method.”

  • <SignatureValue> holds the actual signature. In this case, the signature is 6vtht/[parts omitted]trCQ==

    This value is computed by encrypting the concatenated digests of the signed parts. The encryption is performed with the private key of the sender.

  • <KeyInfo> identifies the key that was used to create the signature. In InterSystems IRIS, <KeyInfo> includes a <SecurityTokenReference>, which has one of several forms:

    • A reference to a <BinarySecurityToken> earlier in the WS-Security header, as shown in the preceding example. In this case, the corresponding private key was used to create the signature.

    • Information to identify a certificate, which presumably the message recipient has previously received and stored. For example, the <SecurityTokenReference> could include the SHA1 thumbprint of the certificate, as follows:

      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                        ValueType="[parts omitted]#ThumbprintSHA1">
            maedm8CNoh4zH8SMoF+3xV1MYtc=
         </KeyIdentifier>
      </SecurityTokenReference>
      
      Copy code to clipboard

      As with the previous case, the corresponding private key was used to create the signature.

    • A reference to a <DerivedKeyToken> earlier in the WS-Security header. For example:

      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <Reference URI="#Enc-BACCE807-DB34-46AB-A9B8-42D05D0D1FFD"></Reference>
      </SecurityTokenReference>
      
      Copy code to clipboard

      In this case, the signature was created by the symmetric key indicated by that token.

    • A reference to an implied <DerivedKeyToken>. For example:

      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                    s01:Nonce="mMDk0zn8V7WTsFaIjUJ7zg==" 
                    xmlns:s01="http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512">
         <Reference URI="#Id-93F97220-568E-47FC-B3E1-A2CF3F70B29B"></Reference>
      </SecurityTokenReference>
      
      Copy code to clipboard

      In this case, the URI attribute in <Reference> points to the <EncryptedKey> element used to generate the <DerivedKeyToken>, and the Nonce attribute indicates the nonce value that was used.

      As with the previous case, the derived key was used to encrypt the data.

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>
Copy code to clipboard

Details

The parts of this element are as follows:

  • Id is the unique identifier for the element. InterSystems IRIS generates this automatically.

  • <EncryptionMethod> indicates the algorithm that was used to encrypt this data.

    In InterSystems IRIS, you can specify this algorithm. See “Specifying the Block Encryption Algorithm.”

  • <SecurityTokenReference> indicates the symmetric key to use as a basis when computing the derived key. This can contain a <Reference> element whose URI attribute points to either an <EncryptedKey> or another <DerivedKeyToken> in the same message.

    Or <SecurityTokenReference> can contain a <KeyIdentifier> that references the SHA1 hash of the <EncryptedKey> that was used. For example:

    <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                                   s01:TokenType="[parts omitted]#EncryptedKey" 
                                   xmlns:s01="h[parts omitted]oasis-wss-wssecurity-secext-1.1.xsd">
       <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                                  [parts omitted]#EncryptedKeySHA1">
                         U8CEWXdUPsIk/r8JT+2KdwU/gSw=
       </KeyIdentifier>
    </SecurityTokenReference>
    Copy code to clipboard
  • <Nonce> is the base–64–encoded value that was used the seed in the key derivation function for this derived key.

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:

  • Each <DerivedKeyToken> includes an Id attribute with a unique identifier.

  • Within each <EncryptedData> element that has been encrypted by the symmetric key indicated by a given <DerivedKeyToken>, there is a <SecurityTokenReference> element whose URI attribute points to that <DerivedKeyToken>.

  • Within each <Signature> element whose value was computed by the symmetric key indicated by a given <DerivedKeyToken>, there is a <SecurityTokenReference> element whose URI attribute points to that <DerivedKeyToken>.

  • Each <EncryptedData> and <Signature> element also includes the Id attribute with a unique identifier.

  • The WS-Security header includes a <ReferenceList> element that refers to the <EncryptedData> and <Signature> elements.

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>
Copy code to clipboard

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>.