Oracle® Fusion Middleware
Part 20. Integrity filters

With an asymmetric signature, the signatory's private key (from a public-private key pair) is used to sign the message. The corresponding public key is then used to verify the signature. The following fields are available for configuration on this tab:

Private Key in Certificate Store:

To use a signing key from the certificate store, select Key in Store, and click Signing Key. Select a certificate that has the required signing key associated with it. The signing key can also be stored on a Hardware Security Module (HSM). For more details, see Manage certificates and keys. The Distinguished Name of the selected certificate appears in the X509SubjectName element of the XML signature as follows:

<dsig:X509SubjectName>
       CN=Sample,OU=R&D,O=Company Ltd.,L=Dublin 4,ST=Dublin,C=IE
    </dsig:X509SubjectName>

Private Key from Selector Expression:

Alternatively, the signing key might have already have been used by another filter and stored in a message attribute. To reuse this key, select Private Key from Selector Expression, and enter the selector expression (for example, ${asymmetric.key}). Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store (KPS), or environment variable). For more details, see Select configuration values at runtime.

With a symmetric signature, the same key is used to sign and verify the message. Typically the client generates the symmetric key and uses it to sign the message. The key must then be transmitted to the recipient so that they can verify the signature. It would be unsafe to transmit an unprotected key along with the message so it is usually encrypted (or wrapped) with the recipient's public key. The key can then be decrypted with the recipient's private key and can then be used to verify the signature. The following configuration options are available on this window:

Generate Symmetric Key, and Save in Message Attribute:

If you select this option, the API Gateway generates a symmetric key, which is included in the message before it is sent to the client. By default, the key is saved in the symmetric.key message attribute.

Symmetric Key from Selector Expression:

If a previous filter (for example, a Sign Message filter) has already used a symmetric key, you can to reuse this key as proof that the API Gateway is the holder-of-key entity. Enter the name of the selector expression in the field provided, which defaults to ${symmetric.key}. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, a Key Property Store (KPS), or environment variable). For more details, see Select configuration values at runtime.

Include Encrypted Symmetric Key in Message:

As described earlier, the symmetric key is typically encrypted for the recipient and included in the message. However, it is possible that the initiator and recipient of the transaction have agreed on a symmetric key using some out-of-bounds mechanism. In this case, it is not necessary to include the key in the message. However, the default option is to include the encrypted symmetric key in the message. The <KeyInfo> section of the signature points to the <EncryptedKey>.

Encrypt with Key in Store:

Select this option to encrypt the symmetric key with a public key from the certificate store. Click the Signing Key button and then select the certificate that contains the public key of the recipient. By encrypting the symmetric key with this public key, you are ensuring that only the recipient that has access to the corresponding private key will be able to decrypt the encrypted symmetric key.

Encrypt with Key from Selector Expression:

You can also use a key stored in a message attribute to encrypt (or wrap) the symmetric key. Select this radio button and enter the selector expression to obtain the public key you want to use to encrypt the symmetric key with. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, a Key Property Store (KPS), or environment variable). For more details, see Select configuration values at runtime.

Use Derived Key:

A <wssc:DerivedKeyToken> token can be used to derive a symmetric key from the original symmetric key held in and <enc:EncryptedKey>. The derived symmetric key is then used to actually sign the message, as opposed to the original symmetric key. It must be derived again during the verification process using the parameters in the <wssc:DerivedKeyToken>. One of these parameters is the symmetric key held in <enc:EncryptedKey>. The following example shows the use of a derived key:

<enc:EncryptedKey Id="Id-0000010b8b0415dc-0000000000000000">
  <enc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
  <dsig:KeyInfo>
       ...
  </dsig:KeyInfo>
  <enc:CipherData>
</enc:EncryptedKey>

<wssc:DerivedKeyToken wsu:Id="Id-0000010bd2b8eca1-0000000000000017" 
      Algorithm="http://schemas.xmlsoap.org/ws/2005/02/sc/dk/p_sha1">
  <wsse:SecurityTokenReference wsu:Id="Id-0000010bd2b8ed5d-0000000000000018">
    <wsse:Reference URI="#Id Id-0000010b8b0415dc-0000000000000000" 
    ValueType="..../oasis-wss-soap-message-security-1.1#EncryptedKey"/>
  </wsse:SecurityTokenReference>
  <wssc:Generation>0</wssc:Generation>
  <wssc:Length>32</wssc:Length>
  <wssc:Label>WS-SecureConverstaionWS-SecureConverstaion</wssc:Label>
  <wssc:Nonce>h9TTWKRylCOz87+mc1/7Pg==</wssc:Nonce>
</wssc:DerivedKeyToken>
       
<dsig:Signature Id="Id-0000010b8b0415dc-0000000000000004">
  <dsig:SignedInfo>
    <dsig:CanonicalizationMethod 
          Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <dsig:SignatureMethod 
        Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
    <dsig:Reference>...</dsig:Reference>
  </dsig:SignedInfo>
  <dsig:SignatureValue>...dsig:SignatureValue>
  <dsig:KeyInfo>
    <wsse:SecurityTokenReference wsu:Id="Id-0000010b8b0415dc-0000000000000006">
      <wsse:Reference 
          URI="# Id-0000010bd2b8eca1-0000000000000017"
          ValueType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk"/>
    </wsse:SecurityTokenReference>
  </dsig:KeyInfo>
</dsig:Signature>

Symmetric Key Length:

This option enables the user to specify the length of the key to use when performing symmetric key signatures. It is important to realize that the longer the key, the stronger the encryption.

This tab configures how the <KeyInfo> block of the generated XML signature is displayed. Configure the following fields on this tab:

Do Not Include KeyInfo Section:

This option enables you to omit all information about the signatory's certificate from the signature. In other words, the KeyInfo element is omitted from the signature. This is useful where a downstream web service uses an alternative method of authenticating the signatory, uses the signature for the sole purpose of verifying the integrity of the message. In such cases, adding certificate information to the message is an unnecessary overhead.

Include Certificate:

This is the default option which places the signatory's certificate inside the XML signature itself. The following example, shows an example of an XML signature using this option:

<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" id="Sample">
  ...
 <dsig:KeyInfo>
  <dsig:X509Data>
   <dsig:X509SubjectName>CN=Sample...</dsig:X509SubjectName>
   <dsig:X509Certificate>
       MIIEZDCCA0yg
       ....
       RNp9aKD1fEQgJ
   </dsig:X509Certificate>
  </dsig:X509Data>
 </dsig:KeyInfo>
</dsig:Signature>

Expand Public Key:

The details of the signatory's public key are inserted into a KeyValue block. The KeyValue block is only inserted when this option is selected.

<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" id="Sample">
   ...
 <dsig:KeyInfo>
  <dsig:X509Data>
   <dsig:X509SubjectName>CN=Sample...</dsig:X509SubjectName>
   <dsig:X509Certificate>
      MIIE ....... EQgJ
   </dsig:X509Certificate>
  </dsig:X509Data>
  <dsig:KeyValue>
   <dsig:RSAKeyValue>
    <dsig:Modulus>
       AMfb2tT53GmMiD
       ...
       NmrNht7iy18=
    </dsig:Modulus>
    <dsig:Exponent>AQAB</dsig:Exponent>
   </dsig:RSAKeyValue>
  </dsig:KeyValue>
 </dsig:KeyInfo>
</dsig:Signature>

Include Distinguished Name:

If this check box is selected, the Distinguished Name of the signatory's X.509 certificate is inserted in an <X509SubjectName> element as shown in the following example:

<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" id="Sample">
  ...
 <dsig:KeyInfo>
  <dsig:X509Data>
   <dsig:X509SubjectName>CN=Sample,C=IE...</dsig:X509SubjectName>
   <dsig:X509Certificate>
       MIIEZDCCA0yg
       ....
       RNp9aKD1fEQgJ
   </dsig:X509Certificate>
  </dsig:X509Data>
 </dsig:KeyInfo>
</dsig:Signature>

Include Key Name:

This option allows you insert a key identifier, or KeyName, to allow the recipient to identify the signatory. Enter an appropriate value for the KeyName in the Value field. Typical values include Distinguished Names (DName) from X.509 certificates, key IDs, or email addresses. Specify whether the specified value is a Text value of a Distinguished name attribute by checking the appropriate radio button.

<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" id="Sample">
   ...
 <dsig:KeyInfo>
  <dsig:KeyName>test@oracle.com</dsig:KeyName>
 </dsig:KeyInfo>
</dsig:Signature>

Put Certificate in an Attachment:

The API Gateway supports SOAP messages with attachments. By selecting this option, you can save the signatory's certificate to the file specified in the input field. This file can then be sent along with the SOAP message as a SOAP attachment.

From previous examples, it is clear that the user's certificate is usually placed inside a KeyInfo element. However, in this example, the certificate is actually contained within an attachment, and not within the XML signature itself. To reference the certificate from the XML signature, so that validating applications can process the signature correctly, is the role of the SecuriyTokenReference block.

The SecurityTokenReference block provides a generic way for applications to retrieve security tokens in cases where these tokens are not contained within the SOAP message. The name of the security token is specified in the URI attribute of the Reference element.

<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" id="Sample">
   ...
 <dsig:KeyInfo>
  <wsse:SecurityTokenReference xmlns:wsse="http://schemas.xmlsoap.org/ws/...">
   <wsse:Reference URI="c:\myCertificate.txt"/>
  </wsse:SecurityTokenReference>
 </dsig:KeyInfo>
</dsig:Signature>

When the message is actually sent, the certificate attachment will be given a "Content-Id" corresponding to the URI attribute of the Reference element. The following example shows what the complete multipart MIME SOAP message looks like as it is sent over the wire. This illustrates how the Reference element actually refers to the "Content-ID" of the attachment:

POST /adoWebSvc.asmx HTTP/1.0
Content-Length: 3790
User-Agent: API Gateway
Accept-Language: en
Content-Type: multipart/related; type="text/xml";
              boundary="----=Multipart-SOAP-boundary"

------=Multipart-SOAP-boundary
Content-Id: soap-envelope
Content-Type: text/xml; charset="utf-8";
SOAPAction=getQuote

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   ...
 <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" id="Sample">
    ...
  <dsig:KeyInfo>
   <ws:SecurityTokenReference xmlns:ws="http://schemas.xmlsoap.org/ws/...">
    <ws:Reference URI="c:\myCertificate.txt"/>
   </ws:SecurityTokenReference>
  </dsig:KeyInfo>
 </dsig:Signature>
    ...
</s:Envelope>

------=Multipart-SOAP-boundary
Content-Id: c:\myCertificate.txt
Content-Type: text/plain; charset="US-ASCII"

MIIEZDCCA0ygAwIBAgIBAzANBgkqhki
....
7uFveG0eL0zBwZ5qwLRNp9aKD1fEQgJ
------=Multipart-SOAP-boundary-

Security Token Reference:

A <wsse:SecurityTokenReference> element can be used to point to the security token used in the generation of the signature. Select this option to use this element. The type of the reference must be selected from the Reference Type field.

The <wsse:SecurityTokenReference>, (within the <dsig:KeyInfo>), can contain a <wsse:Embedded> security token. Alternatively, the <wsse:SecurityTokenReference>, (within the <dsig:KeyInfo>), can refer to a certificate via a <dsig:X509Data>. Select the appropriate button, Embed or Refer, depending on whether you want to use an embedded security token or a referred one.

You can make sure to include a <BinarySecurityToken> (BST) that contains the certificate used to wrap the symmetric key in the message by selecting the Include BinarySecurityToken option. The BST is inserted into the WS-Security header regardless of the type of Security Token Reference selected.

If the API Gateway is acting as the recipient of a secure transaction, it can also use the Kerberos session keys to sign the message returned to the client. However, in this case, the KeyInfo must be configured to use a Security Token Reference with ValueType of Kerberosv5_APREQSHA1. When this ValueType is selected, the Kerberos token is not contained in the message. The Security Token Reference contains a SHA1 digest of the original Kerberos token received from the client, which identifies the session keys to the client.

Using the WS-Trust for SPENGO standard, the Kerberos session keys are not used directly to sign messages because a security context with an associated symmetric key is negotiated. This symmetric key is shared by both client and service and can be used to sign messages on both sides.

The Additional tab allows you to select additional elements from the message that are to be signed. It is also possible to insert a WS-Security Timestamp into the XML signature, if necessary.

Additional Elements to Sign:

The options here allow you to select other parts of the message to sign.

Transform:

This field is only available when you have selected the Sign Attachments box above. It determines the transform used to reference the signed attachments.

Timestamp Options:

It is possible to insert a timestamp into the message to indicate when exactly the signature was generated. Consumers of the signature can then validate the signature to ensure that it is not of date.

The following options are available:

The Expires In fields enable the user to optionally specify the wsu:Expires for the wsu:Timestamp. If all fields are left at 0, no wsu:Expires element is placed inside the wsu:Timestamp. The following example shows a wsu:Timestamp that has been inserted into a wsse:Security block:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
 <s:Header>
   <wsse:Security>
     <wsu:Timestamp wsu:Id="Id-0000011294a0311e-000000000000003d">
      <wsu:Created>2007-05-16T11:22:45Z</wsu:Created>
      <wsu:Expires>2007-05-23T11:22:45Z</wsu:Expires>
    </wsu:Timestamp>  
    <dsig:Signature ...>
    ...
    </dsig:Signature ...>
   </wsse:Security>
 </s:Header>
 <s:Body>
    ...
 </s:Body>
</s:Envelope>

The fields on this tab determine the combination of cryptographic algorithms and ciphers that are used to sign the message parts.

Algorithm suite:

WS-Security Policy defines a number of algorithm suites that group together a number of cryptographic algorithms. For example, a given algorithm suite will use specific algorithms for asymmetric signing, symmetric signing, asymmetric key wrap, and so on. Therefore, by specifying an algorithm suite, you are effectively selecting a whole suite of cryptographic algorithms to use.

To use a particular WS-Security Policy algorithm suite, you can select it here. The Signature Method, Key Wrap Algorithm, and Digest Method fields will then be automatically populated with the corresponding algorithms for that suite.

Signature Method:

The Signature Method field enables you to configure the method used to generate the signature. Various strengths of the HMAC-SHA1 algorithms are available from the list.

Key Wrap Algorithm:

Select the algorithm to use to wrap (encrypt) the symmetric signing key. This option need only be configured when you are using a symmetric key to sign the message.

Digest Algorithm:

Select the digest algorithm to you to produce a cryptographic hash of the signed data.

This tab enables you to configure various advanced options on the generated XML signature. The following fields can be configured on this tab:

WS-Security Options:

WSSE 1.1 defines a <SignatureConfirmation> element that can be used as proof that a particular XML signature was processed. A recipient and verifier of an XML signature must generate a <SignatureConfirmation> element for each piece of data that was signed (for each <Reference> in the XML signature). A <SignatureConfirmation> element contains the hash of the signed data and must be signed by the recipient before returning it in the response to the initiator (the original signatory of the data).

When the initiator receives the <SignatureConfirmation> elements in the response, it compares the hash with the hash of the data that it produced initially. If the hashes match, the initiator knows that the recipient has processed the same signature. Select the Initiator option if the API Gateway is the initiator as outlined in the scenario above. The API Gateway keeps a record of the signed data and compares it to the contents of the <SignatureConfirmation> elements returned from the recipient in the response message.

Alternatively, if the API Gateway is acting as the recipient in this transaction, you can select the Responder radio button to instruct the API Gateway to generate the <SignatureConfirmation> elements and return them to the initiator. The signature confirmations will be added to the WS-Security header.

Layout Type:

Select the WS-SecurityPolicy layout type that you want the XML signature and any generated tokens to adhere to. This includes elements such as <Signature>, <BinarySecurityToken>, and <EncryptedKey>, which can all be generated as part of the signing process.

Fail if No Nodes to Sign:

Check this option if you want the filter to fail if it cannot find any nodes to sign as configured on the What to Sign tab.

Add Inclusive Namespaces for Exclusive Canonicalization:

You can include information about the namespaces (and their associated prefixes) of signed elements in the signature itself. This ensures that namespaces that are in the same scope as the signed element, but not directly or visibly used by this element, are included in the signature. This ensures that the signature can be validated as a standalone entity outside of the context of the message from which it was extracted.

A PrefixList attribute is used to list the prefixes of in-scope, but not visibly used elements and attributes. The following example shows how the PrefixList attribute is used in practice:

<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope'>
 <soap:Header>
  <wsse:Security xmlns:wsse='http://docs.oasis-open.org/...' 
                 xmlns:wsu='http://docs.oasis-open.org/...'>
   <wsse:BinarySecurityToken wsu:Id='SomeCert' 
                             ValueType="http://docs.oasis-open.org/...">
   lui+Jy4WYKGJW5xM3aHnLxOpGVIpzSg4V486hHFe7sH
   </wsse:BinarySecurityToken>
   <ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
    <ds:SignedInfo>
     <ds:CanonicalizationMethod 
         Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'>
      <c14n:InclusiveNamespaces 
          xmlns:c14n='http://www.w3.org/2001/10/xml-exc-c14n#'
          PrefixList='wsse wsu soap' />
     </ds:CanonicalizationMethod>
     <ds:SignatureMethod 
          Algorithm='http://www.w3.org/2000/09/xmldsig#rsa-sha1'/>
     <ds:Reference URI=''>
      <ds:Transforms>
       <dsig:XPath xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:m='http://example.org/ws'>
       //soap:Body/m:SomeElement
       </dsig:XPath>
       <ds:Transform Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'>
        <c14n:InclusiveNamespaces 
              xmlns:c14n='http://www.w3.org/2001/10/xml-exc-c14n#'
              PrefixList='soap wsu test' />
       </ds:Transform>
      </ds:Transforms>
      <ds:DigestMethod Algorithm='http://www.w3.org/2000/09/xmldsig#sha1' />
      <ds:DigestValue>VEPKwzfPGOxh2OUpoK0bcl58jtU=</ds:DigestValue>
     </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>+diIuEyDpV7qxVoUOkb5rj61+Zs=</ds:SignatureValue>
    <ds:KeyInfo>
     <wsse:SecurityTokenReference>
      <wsse:Reference URI='#SomeCert' />
     </wsse:SecurityTokenReference>
    </ds:KeyInfo>
   </ds:Signature>
  </wsse:Security>
 </soap:Header>
 <soap:Body xmlns:wsu='http://docs.oasis-open.org/...' 
            xmlns:test='http://www.test.com' wsu:Id='TheBody'>
  <m:SomeElement xmlns:m='http://example.org/ws' attr1='test:fdwfde' />
 </soap:Body>
</soap:Envelope>

Indent:

Select this method to ensure that the generated signature is properly indented.

Create Enveloped Signature:

By selecting this option, an enveloped XML signature is generated. The following skeleton signed SOAP message shows the enveloped signature:

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" id="Sample">
 <ds:SignedInfo>
  <ds:Reference URI="">
   <ds:Transforms>
    <ds:Transform 
        Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
   </ds:Transforms>
  </ds:Reference>
 </ds:SignedInfo>
</ds:Signature>

This indicates to the application validating the signature that the signature itself should not be included in the signed data. In other words, to validate the signature, the application must first strip out the signature. This is necessary in cases where the entire SOAP envelope has been signed, and the resulting signature has been inserted into the SOAP header. In this case, the signature is over a nodeset which has been altered (the signature has been inserted), and so the signature will break.

Insert CarriedKeyName for EncryptedKey:

Select this option to include a <CarriedKeyName> element in the <EncryptedKey> block that is generated when using a symmetric signing key.