Encrypting SOAP messages

You can add encrypt the header and body of a SOAP messages if you want web services security by using encryption.

Before you begin

Go to the Physical View and add identity stores for HCL DevOps Test Integrations and APIs (Test Integrations and APIs). For information on how to define and configure identity stores, see Identity stores and SSL.

About this task

Encrypt the header and body of an outgoing SOAP message.
Note: The ability to encrypt headers of SOAP messages is available in Test Integrations and APIs 8.5.0 or later.

Procedure

  1. In the Logical View of the Architecture School perspective, import and synchronize a WSDL document.
  2. Create a test or a stub.
  3. Open the outgoing SOAP message for editing:
    • In case of a test, double-click a message action.
    • In case of a stub, open the Activity tab and double-click a message action.
  4. In the Config tab, right-click the SOAP message node and select Properties.
    The following example image is from a test.
    Encrypt option
  5. Open the WS-Security tab. Select the Enable check box, if not done already.
  6. Select Encrypt from the drop-down list.
    Encrypt option
    The Encrypt dialog is displayed.
  7. In the Encrypt dialog, configure the encryption for the SOAP message.
    Image of the Encrypt window.

    The following table outlines the parameters and options that are used for encrypting a SOAP message:

    Field/Check box Description
    Transformation Name (Required) A unique name for the encryption action. This helps you identify it in the main list.
    Keystore The HCL DevOps Test Integrations and APIs (Test Integrations and APIs) identity store that you created and configured. Select the appropriate one from the drop-down list.
    Note: A JKS keystore is required to encrypt a message.
    Certificate Alias The alias of the certificate to be used from the keystore to encrypt the messages symmetric key. For example, ca.
    Key identifier type The method by which the certificate is identified at the receiver's end. This element can have one of the following values:
    • Issue serial: Only the issuer name and the serial number of the signing certificate are placed in the security header as opposed to the entire signing certificate. This reduces the amount of data being sent. The encryption method uses the public key associated with this certificate to encrypt the symmetric key used to encrypt data.
    • Binary security token direct reference: The signing certificate is converted to a BinarySecurityToken and inserted into the security header. A reference to the binary security token is also inserted into the wsse:SecurityReferenceToken. This means that the entire signing certificate is transferred to the receiver. The X509 profile recommends using the Issue serial instead of sending the whole certificate.
    • X509 key identifier: The encryption method uses the public key associated with this certificate to encrypt the symmetric key used to encrypt data. The certificate is converted into a KeyIdentfier token and sent to the receiver. Thus the complete certificate data is transferred to the receiver. The X509 profile recommends using Issue serial instead of sending the whole certificate.
    Choose a value depending on who the receiver of the SOAP message is and what the receiver needs to decrypt the message at the receiving end.
    Key Encryption Algorithm The algorithm used to transport the messages symmetric key. The choices available in the list are controlled by the WS-Security Framework.

    The key encryption algorithms specify the Key Transport and KeyWrap algorithms to be used to encrypt and decrypt a secret key (the key used to encrypt the data) respectively. They also specify the algorithm uniform resource identifier (URI) of the key encryption method.

    The following pre-configured key encryption algorithms are supported:http://www.w3.org/2001/04/xmlenc#rsa-1_5http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

    Signature Algorithm The algorithm used to encrypt the payload using the messages symmetric key. Select any of the following values:
    • AES128 in CBC: http://www.w3.org/2001/04/xmlenc#aes128-cbc
    • AES192 in CBC: http://www.w3.org/2001/04/xmlenc#aes192-cbc
    • AES256 in CBC: http://www.w3.org/2001/04/xmlenc#aes256-cbc
    • Triple DES in CBC: http://www.w3.org/2001/04/xmlenc#tripledes-cbc

    This algorithm is used to encrypt the data. The receiver must use the same algorithm to decrypt the data.
    Actor Indicates a specific receiver (either the ultimate receiver or an intermediary) to whom the contents of the message should be typically directed.

    A SOAP message can have multiple WS-Security headers. Each WS-Security header must have a unique actor defined if there is more than one. If a SOAP message is passed between intermediary steps (receivers), each step will use its unique actor value to determine which WS-Security header it needs to process the message as it needs to.
    Must understand?

    Indicates whether or not the receiver (indicated by the Actor attribute) is required to process a header entry. When you set this attribute to true, the actor must understand the semantics of the header entry and must process it correctly to those semantics. If the value is false, processing the header entry becomes optional.The Must understand attribute indicates that the semantics in an element are different from the semantics in its parent or peer elements. This facilitates robust evolution ensuring that a change in semantics does not get ignored by those who may not fully understand it.
    SOAP Body Indicates whether to encrypt the body of a SOAP message.
    WS-Security Tokens WS-Security Tokens are what you have defined on the WS-Security tab such as Binary token, User token, Timestamp token, and so forth (shown below) and become XML elements in the generated security header. You can encrypt any token defined before the Encrypt token individually by the Encrypt token, just as you can encrypt the SOAP header elements and WS-Addressing elements.

    In the Encrypt dialog, for each token displayed under the WS-Security Tokenscheck box, you must select the check box next to it if you want to encrypt it.
    WS-Addressing Indicates whether to encrypt the WS-Addressing fields of a SOAP message. For each field that is displayed under this check box, you must select the check box next to it if you want to encrypt it.
    SOAP Headers Indicates whether to encrypt individual header elements in the SOAP envelope. You must select the header element that you want to encrypt.
    Body Fields Indicates whether to encrypt individual body elements in the SOAP envelope. You must add the qualified name of each field that you want to encrypt.
    Note: In the Encrypt dialog, only message elements that are explicitly selected are encrypted.
  8. Click OK to complete the action.