Skip to main content

This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Previous section

Details of the Security Elements

This appendix discusses the following items:

<BinarySecurityToken>

<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. Caché generates this automatically if necessary.

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

  • ValueType indicates the type of value that is contained in the token. In Caché, 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>

<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 Caché, 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 Caché, <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>

<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. Caché generates this automatically.

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

    In Caché, 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 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 Caché, 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 Caché, <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 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. Caché generates this automatically.

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

    In Caché, 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>

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