Using the DomainZipFile file

Use cases of the DomainZipFile file for different levels of security in patterns.

The DomainZipFile.zip file can be used in the Basic Runtime, Basic Runtime Sample, and Advanced Runtime patterns.

SSL is not required to connect the pattern script packages to the DataPower® appliance. If you do not use SSL, you do not have to create a DomainZipFile.zip file, unless you require a cli script to customize the DataPower domain created by the pattern. In this case, if you do not use server authentication as a minimum, the data will not be encrypted. This is a security risk because user and password information is passed to DataPower during the scripting client over a http connection, and this is protected by the certificates in the DomainZipFile.zip file.

If the DataPower host is not configured to validate the client certificate, you do not have to use Mutual Authentication between the script client and the DataPower appliance. It is recommended that you use Server Authentication at a minimum.

The case scenarios in this topic describe different levels of security.

The product supports the following case scenarios:

Case 1: No SSL is required

It is recommended for the security reasons outlined that this option only be used for development scenarios. If you do not wish to use any SSL:

  1. Set the parameters for SCP_host to Unset. If you are using the Basic Runtime or Advanced Runtime Patterns, SCP_host is in the SOA Policy Gateway 2.0.0.0 - Security Package Script. If you are using the Basic Runtime Sample pattern, SCP_host is in the SOA Policy Gateway 2.0.0.0 script. This sets the script in the pattern so that it does not retrieve the DomainZipFile.zip file using SCP.

  2. Set the following parameters to Unset in the same script packages from step 1:
    • CLIENT_PUBLIC_KEY_file
    • CLIENT_PUBLIC_KEY_password
    • Verify password
    • CLIENT_PRIVATE_KEY_file
    • CLIENT_PRIVATE_KEY_password
    • Verify password

Case 2: No SSL is required but a cli script is needed to customize the domain

It is recommended for the security reasons outlined that this option only be used for development scenarios. If you do not want to use SSL but require a cli script:

  1. Set the parameters for SCP_host to Unset. If you are using the Basic or Advanced Runtime Patterns, SCP_host is in the SOA Policy Gateway 2.0.0.0 - Security Package Script. If you are using the Basic Runtime Sample pattern, SCP_host is in the SOA Policy Gateway 2.0.0.0 script. This sets the script in the pattern so that it does not retrieve the DomainZipFile.zip file using SCP.

  2. Set the following parameters to Unset in the same script packages from step 1:
    • CLIENT_PUBLIC_KEY_file
    • CLIENT_PUBLIC_KEY_password
    • Verify password
    • CLIENT_PRIVATE_KEY_file
    • CLIENT_PRIVATE_KEY_password
    • Verify password
    Note: If SCP_host is Unset you do not require a DomainZipFile.zip file, unless you have a cli script you which want to run in the Basic Runtime and Advanced Runtime patterns.
  3. Put the cli script file you want to use in the root of the DomainZipFile.zip file. An example structure of the DomainZipFile.zip file is as follows:

    /cli.cli

    This file is run at the end of the DataPower Domain script package. cli.cli is an example file name. The file name must not contain any spaces.

Case 3: Server authentication of the DataPower Certificate by the Script client is required

You must provide all the Certificates of the DataPower Certificate chain that protects the XML Management Interface. To locate these, complete the following steps:
  1. Examine the SSL proxy profile for the XML Management Interface, and locate the CryptoProfile. The Crypto Profile will contain the identification credentials that contain the certificates used to protect the XML Management Interface.

  2. Add these certificates to the DomainZipFile.zip file.

    The format is:
    • dataPowerHostName/certificateChainMember1.crt
    • dataPowerHostName/certificateChainMember2.pem
    • dataPowerHostName/certificateChainMember(n).crt
    If you are using the multiple-domain scenario, the file can have two different dataPowerHostName directories, with the following files for each DataPower Certificate Chain:
    • clientCertificate.crt clientKeyFile.key
    • dataPowerHostName/certificateChainMember1.crt
    • dataPowerHostName/certificateChainMember2.pem
    • dataPowerHostName/certificateChainMember(n).crt
    • dataPowerHostName2/certificateChainMember1a.crt
    • dataPowerHostName2/certificateChainMember2a.pem
    • dataPowerHostName2/certificateChainMember2(n).crt
    Note: The DataPower Certificate chain files must be of type .crt or .pem and must only contain the certificate itself. The .crt or .pem file names used here are examples. The file name must not contain any spaces.
  3. If you only require Server Authentication for the SOA Policy Gateway 2.0.0.0 - Security Package Script used by the Basic Runtime and Advanced Runtime Patterns, or the SOA Policy Gateway 2.0.0.0 - Sample script in the Basic Runtime Sample pattern, use Unset as the value for the following parameters in those scripts:
    • CLIENT_PUBLIC_KEY_file
    • CLIENT_PUBLIC_KEY_password
    • Verify password
    • CLIENT_PRIVATE_KEY_file
    • CLIENT_PRIVATE_KEY_password
    • Verify password
  4. Optional: If a cli script is required:

    Put the cli script file you want to use in the root of the DomainZipFile.zip file. An example structure of the DomainZipFile.zip file is as follows:

    /cli.cli

    This file is run at the end of the DataPower Domain script package. cli.cli is an example file name. The file name must not contain any spaces.

Case 4: Mutual Authentication with the DataPower Appliance is Required

In this case, client and DataPower Server require validation of the other's certificates. This is only needed if the DataPower Host is configured in the SSL Proxy Profile for the XML Management Interface to validate the clients' certificates.
  1. Add these certificates to the DomainZipFile.zip file.

    The format is:
    • clientCertificate.crt
    • clientKeyFile.key
    • dataPowerHostName/certificateChainMember1.crt
    • dataPowerHostName/certificateChainMember2.pem
    • dataPowerHostName/certificateChainMember(n).crt
    • dataPowerHostName2/certificateChainMember1a.crt
    • dataPowerHostName2/certificateChainMember2a.pem
    • dataPowerHostName2/certificateChainMember2(n).crt
    Note: The DataPower Certificate chain files must be of type .crt or .pem and must only contain the certificate itself. The .crt or .pem file names used here are examples. The file name must not contain any spaces.

    The client certificate and client key file can contain the data in the certificate or key file before the line in the file that reads: -----BEGIN CERTIFICATE-----.

  2. If you require Mutual Authentication for the SOA Policy Gateway 2.0.0.0 - Security Package Script, used by the Basic and Advanced Runtime Patterns, or in the Basic Runtime Sample pattern SOA Policy Gateway 2.0.0.0 script, you must specify a value for the following parameters in these script packages:
    • CLIENT_PUBLIC_KEY_file
    • CLIENT_PRIVATE_KEY_file
    • CLIENT_PRIVATE_KEY_password
    • Verify password
  3. If there is no password for the Public Key file, the value of the following can be Unset:
    • CLIENT_PUBLIC_KEY_password
    • Verify password
  4. The curl commands used by the script packages assume that the file type is .pem, so that the --key-type and --cert-type are set to PEM by default. The certificate and key files may contain this content before -----BEGIN CERTIFICATE----- in the particular certificate or key file.

  5. Optional: If a cli script is required, using the Basic Runtime or Advanced Runtime patterns:

    Put the cli script file you want to use in the root of the DomainZipFile.zip file. An example structure of the DomainZipFile.zip file is as follows:

    /cli.cli

    This file is run at the end of the DataPower Domain script package. cli.cli is an example file name. The file name must not contain any spaces.

By selecting a case, you have configured the appropriate level of security, with or without using the DomainZipFile.zip file.

Concept Concept

Feedback

Timestamp icon Last updated: Thursday, 3 July 2014
http://publib.boulder.ibm.com/infocenter/prodconn/v1r0m0/topic/com.ibm.scenarios.soawdpwsrr.doc/topics/csoa2_using_domainzip.htm