Setting up security for web services


BMC Helix CMDB requires client authentication with wsse:Username. The wsse:Username authentication is the only default security policy.


Authenticating web services

Use the following procedure to authenticate to the web services and validate that message content has not been altered.

To authenticate web services

  1. Sign the soap:Body element using the chosen algorithm with the private key.
  2. Include the resulting signature data in a ds:Signature element.
  3. Place it in the wsse:Security element in the soap:Header.
  4. Include the public key in the following locations:
    • an X509v3 certificate
    • a wsse:BinarySecurityToken element in Base64 encoding
    • the soap:Header element

Understanding request message confidentiality

The security policy that enables request message confidentiality requires that important message content is obscured in transit and through the lifetime of the message. CMDB Web Services accomplishes message confidentiality by using XML Encryption. CMDB Web Services requires using a combination of symmetric and asymmetric encryption to ensure message confidentiality.

This optional policy does not require encrypted incoming messages by default. When you enable this policy, clients can send encrypted as well as unencrypted messages. However, you can require that clients encrypt the soap:Body and wsse:UsernameToken elements.

The client must generate a synchronous 128-bit key and use that synchronous key to encrypt important parts of the document using one of the following algorithms:

Synchronous 128-bit kit algorithms

The web service's asynchronous public certificate encrypts the corresponding 128-bit synchronous key (depending on the algorithm that you used to generate the key) using one of the following algorithms:

Asynchronous 128-bit kit algorithms

Include the wsse:EncryptedKey and wsse:BinarySecurityToken elements (representing the result of encryption in the wsse:Security element) in your soap:Header element.

CMDB Web Services includes a keystore and corresponding public and private asynchronous encryption key combination. Clients can use that public key as the asynchronous component in this process.

Important

Replace the default keystore and key with one that meets your company's requirements. For more information about replacing the keystore, see Modifying-the-AR-System-server-used-as-a-web-services-userstore.


Server keystore details

Supported security policies for SOAP responses

By default, no outgoing WS-Security policies are enabled. Messages are sent out without WS-Security-based message-level security applied. You can apply incoming and outgoing security policies, such as cryptographic policies for XML digital signature and XML encryption.

To consume a Simple Object Access Protocol (SOAP) response from CMDB Web Services, clients can use several security policies.

The following policies comply with WS-Security 1.0 standards:

  • Authenticate that the response came from the correct web service server and verify the integrity of the response content by using XML Digital Signature.
  • Validate that the message is coming from the correct web service server and verify the response content for integrity by using XML Digital Signature.
  • Decrypt the content of the SOAP response by using XML Encryption.

Authenticating to the client and checking response message integrity

The server signs the soap:Body element of the SOAP response by using the corresponding private key of the public key that it exposes for encryption.

The private key is called bmcatriumwsserver and it belongs to the bmcatriumwsserver.jks keystore. XML Digital Signature creates the signature by using the RSAwithSHA1 (PKCS1) algorithm.

The client validates that the signed content of the message (the soap:Body element) has not been modified, and it authenticates the server by verifying that the related public certificate sent in the wsse:BinarySecurityToken element within the wsse:Security element in the soap:Header element matches the public certificate of the server.

For the server's keystore details, see Server keystore details.

Ensure response message confidentiality

The server encrypts the soap:Body element of the SOAP response by using a synchronous key with the AES-128 algorithm. It then encrypts the synchronous key by using the public certificate that the client sends to the server in the wsse:BinarySecurityToken element for its XML Digital Signature in the corresponding SOAP request using the RSA-v1.5 algorithm.

Because the client originally signs the document with the corresponding private key, it is able to decrypt the key by using that private key, and then decrypt the encrypted soap:Body element by using the resulting synchronous certificate and algorithm.

If you use the example client certificate and bmcatriumwsclient private key from the bmcatriumwsclient.jks keystore, that private key decrypts the response. Otherwise, the corresponding private key of any other public certificate in the signature of the request decrypts the response.

Because the server encrypts its responses with the public certificate that the client includes in its request signature, you cannot apply this policy unless you have also applied on the server the policy enforcing XML Digital Signature on requests.

For the client's keystore details, see Client keystore details.


Separating the client implementation and security policy layer

Best practice
We recommend that you keep security policies and client implementation logic separate because security policies can change frequently. Apply and configure policies to an existing client.

Most web service client tools provide the necessary abstraction in their implementations of web service security features and policies. Depending on the tool that you are using, the rules for how to separate the client implementation and the security policy layer might vary.

BMC Helix CMDB allows you to disable, reconfigure, and reapply the available security policies to CMDB Web Services. For example, you can apply conservative measures to implement and enforce all of the available security policies, or liberal measures to enforce only the basic wsse:UsernameToken policy. This flexibility is available because you apply and enforce a policy layer that brokers access to the service implementation.

SSL TLS transport-level security

Apache Tomcat 6 is configured to be ready for both HTTP and HTTPS connections for one-way SSL authentication. CMDB Web Services does not support two-way SSL authentication. The HTTPS connector for CMDB Web Services uses the TLS scheme (TLSv1) rather than SSL/SSLv3.

If you install into an existing Tomcat 6 instance that already has SSL enabled, that SSL configuration is used. If either a new Tomcat 6 instance is installed or your existing Tomcat 6 instance did not have SSL enabled, the installer adds the HTTPS connector and configures it to use the following key and keystore:

Keystore details

 

Because this is only configured for one-way SSL, the server does not authenticate the certificates of any connecting clients. However, the client must authenticate the public certificate that the server uses in its SSL configuration. If the default key pair in Truststore details is used, the client adds the following public certificate to its truststore for SSL: <BMCAtriumCoreInstallationDirectory>/wsc/atriumws91/keystores/bmcatriuwscacertsssl.jks

CMDB Web Services also includes a truststore that contains all the public certificates of commonly accepted Certificate Authorities as well as the default public certificate used in configuration. The following table describes this truststore.


Public certificate details

Important

Replace the default truststore and key with one that meets your company's requirements.

You can configure the CMDB Web Services Archive to accept both HTTP and HTTPS connections, exposing the web services on both endpoints, or you can restrict to one or the other. The default instance restricts access to HTTPS because the default behavior has no cryptographic WS-Security policies applied.


To enable SSL for transport-level encryption for CMDBWS

Because CMDBWS was never documented to support SSL and contained no out-of-the-box SSL configuration in BMC Helix CMDB, the default configuration in CMDB Web Services does not apply to CMDBWS.

If you configured SSL for CMDBWS or need to enable it after upgrading to CMDB Web Services, use the following procedure to map a configured SSL server, such as the default SSL_Server, to CMDBWS.

In previous versions, you had to configure CMDBWS separately from CMDB Web Services. In the Axis2-implementation, CMDBWS is always exposed through both HTTP and HTTPS without additional steps.

To access CMDBWS, use the following endpoints:

  • http://<hostname>:<httpport>/cmdbws/server/cmdbws
  • https://<hostname>:<sslport>/cmdbws/server/cmdbws

The WSDL can be accessed at the following address: 
http://<hostname>:<httpport>/cmdbws/server/cmdbws.wsdl


Security policies for BMC CMDB web services

You can modify the default security policies. You should change keystores and references to private keys for keystores and keys that fit your security standards.

Also, consider modifying your security policies when your standard client tools and libraries cannot support web services security encryption (for example, gSOAP). In this case, you might want to disable the policy that manages encryption enforcement and the policy that manages incoming and outgoing web services cryptography.

To modify security configuration for CMDB Web Services

Certain configuration settings, all security policies, and settings for WS-Security and transport-enablement cannot be modified during runtime because these properties are defined in the CMDB Web Services archive.

To modify these properties, you must use the following procedure:

  1. Modify the security property values with the atriumwsutil utility.
  2. Repackage the service archive with the changes.
  3. Deploy the repackaged service archive into the BMC Helix CMDB web application running on Tomcat.

 Atriumwsutil command

To modify, package, and deploy configuration changes, you must use the atriumwsutil command:

  • Windows (batch file): <BMCAtriumCoreInstallationDirectory>\wsc\atriumws91\atriumwsutil.cmd
  • UNIX (shell script):<ATRIUMCORE_HOME>/wsc/atriumws91/atriumwsutil

Note

The Axis2 administration console not available by default. For more information, see Apache Axis2 WAR Distribution modifications.

Execute the utility from the command-line as follows:

atriumwsutil -package -deploy [HTMLUATAtriumCoreWSH:-verbose]

atriumwsutil -restoredefaults

atriumwsutil -listconfig

atriumwsutil <filename>

atriumwsutil -<securityProperty> <value>

You can combine as many of these options on the command line as you need, except for the listconfig, restoredefaults, and <filename> options, each of which must be used by itself. The security settings and modifications are processed first. Then, if those changes pass validation, the -package and -deploy options execute in that order.

For example, the following command changes the transport configuration of the utility's configuration files to HTTPS_PRIMARY. Then it packages and deploys the new CMDB Web Services archive with the new transport setting.

atriumwsutil -transport HTTPS_PRIMARY -package -deploy

The following table describes the command options for the atriumwsutil utility.


atriumwsutil options

Other than those rules, parameter files operate exactly the same as when passing options through the command-line. |

To modify security properties for CMDB Web Services

To view and modify the security properties, you must use the atriumwsutil utility, which saves the values to an encrypted file (wsc/atriumws91/conf/crypto.xml ).

  1. To view the current security configuration excluding passwords, use the atriumwsutil -listconfig command.

To modify security properties, use the atriumwsutil -<securityProperty> <value> command. 

The following table describes the security properties that you can define. For more information, see Atriumwsutil command.

 Security properties

To package and deploy the service archive

After making the wanted modifications, you must package and deploy the modified CMDB Web Services archive for the BMC Helix CMDB web application hosted on Tomcat 6.

To package and deploy the modified service archive

  1. To apply the modified security properties, use the atriumwsutil -<option> command to package and deploy the CMDB Web Services archive. 

    You can use the -package and -deploy options together, or you can run them separately. 

    Example: atriumwsutil -package -deploy 

    The previous archive is undeployed and replaced by the new archive. The output appears either in the standard output log file for Tomcat 6 or its console window.

    Note

    You can ignore messages that a service was not found in the WSDL because they refer to the abstract WSDL files that are imported by instance WSDL files that do have the necessary service elements.

  2. In the output, confirm that the previous archive is undeployed and that the new archive is deployed. 

    After deploying a package, you should see a message such as the following:

    Deploying service assembly Inspecting services directory C:/a pache-tomcat-6.0.20/webapps/atriumws80/WEB-INF/services Inspecting services list C:/ apache-tomcat-6.0.20/webapps/atriumws80/WEB-INF/services/services.list Replacing service archive in services directory C:/ apache-tomcat-6.0.20/webapps/atriumws80/WEB-INF/services/atriumws80.aar Service assembly filename is already in the services list Finished deploying service assembly

    When the new deployment is available, you should see a message in the Tomcat log files, such as the following:

    [INFO] Deploying Web service: atriumws80.aar - file:/C:/apache-tomcat-6.0.20/webapps/atriumws80/WEB-INF/services/atriumws80.aar

    The new CMDB Web Services archive is now available for use.



 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*