Setting up security for web services
BMC CMDB requires client authentication with
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
- Sign the
soap:Bodyelement using the chosen algorithm with the private key.
- Include the resulting signature data in a
- Place it in the
wsse:Securityelement in the
- Include the public key in the following locations:
- an X509v3 certificate
wsse:BinarySecurityTokenelement in Base64 encoding
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
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
|Algorithm||Location of detailed description|
|Triple DES||http://www.w3.org/2001/04/xmlenc#kw-tripledes (http://www.w3.org/2001/04/xmlenc#kw\-tripledes)|
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
|Algorithm||Location of detailed description|
wsse:BinarySecurityToken elements (representing the result of encryption in the
wsse:Security element) in your
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.
Server keystore details
|Type||Java KeyStore (JKS)|
|Server key details within the keystore|
BMC provides the server keystore file so that you can import it into your keystore. You can find this file at:
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
BMC 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:
Java KeyStore (JKS)
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
Java KeyStore (JKS)
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 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:
The WSDL can be accessed at the following address:
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:
- Modify the security property values with the atriumwsutil utility.
- Repackage the service archive with the changes.
- Deploy the repackaged service archive into the BMC CMDB web application running on Tomcat.
To modify, package, and deploy configuration changes, you must use the
- Windows (batch file):
- UNIX (shell script):
Execute the utility from the command-line as follows:
atriumwsutil -package -deploy [HTMLUATAtriumCoreWSH:-verbose]
atriumwsutil -<securityProperty> <value>
You can combine as many of these options on the command line as you need, except for the
<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
-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.
Creates a new CMDB Web Services archive with all changes in main.xml and with the atriumwsutil utility.
Deploys the CMDB Web Services archive into the CMDB web application, replacing the previous archive and its configuration.
|Displays a detailed file-by-file listing in the output of the archive creation process.|
|Restores defaults and list the values so that you can verify that the defaults were restored. This option only restores these values in the atriumwsutil utility's configuration. After restoring the defaults, you must package and deploy the restored archive.|
|Lists the current security configuration excluding passwords.|
|Uses the specified text file to define options. If the only specified parameter is an existing filename that does not begin with a hyphen (-) to signal an option, the atriumwsutil utility reads the file and parses the options in the file. Using a file follows its own parameter format rather than the command-line format. The following rules apply to the format of the file:|
Other than those rules, parameter files operate exactly the same as when passing options through the command-line. |
|Specifies the security parameter to modify and the values to specify for the modification. For more information, see Security policies for BMC Atrium Web Services.|
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 ).
- To view the current security configuration excluding passwords, use the
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.
|Configures the transports from which the RESTful Web services can be accessed.|
|Configures the transports from which the SOAP Web services can be accessed.|
|Configures the Web services to validate wsse:Nonce and wssu:Created elements passed in with the wsse:UsernameToken element in the wsse:Security header.|
|Configures the threshold for wsse:Nonce validation in seconds. This determines how long the Web Services holds the value in the element and prevent its reuse. The value can be 300 (five minutes) to 86400 (24 hours). The default value is 300.|
|Configures the threshold for wsu:Created validation in seconds. This determines how long that the Web Services allow submission of the element after its creation date. The value can be 60 (one minute) to 86400 (24 hours). For best defense against replay attacks, set this to either the same or lesser value as the noncethreshold. The default value is 300.|
|Configures the services' requirement for a valid wsu:Timestamp.|
|Configures the services to include a valid wsu:Timestamp.|
|Configures the services to require that the SOAP request's body is signed, that the signature is valid, and that the client's public certificate is trusted.|
|Configures the services to decrypt the SOAP request using the server's private key. Clients must therefore use the server's public certificate as the key transport encryption key in the encryption of the request.|
|Configures the services to sign the SOAP response's body and, if included, wsu:Timestamp using the private key of the server, and include the server's public certificate is included in the SOAP response as well. The algorithm used to sign the response (RSA-SHA1 or DSA-SHA1) depends on the type of key set in the -signaturekey option. If an RSA key is used, RSA-SHA1 is the algorithm. If a DSA key is used, DSA-SHA1 is the algorithm.|
|Configures the services to encrypt the SOAP response's body and, if included, wsu:Timestamp using the public certificate that the client passes through the SOAP request as the key transport encryption key. Because this outgoing encryption depends on the signing certificate passed to the SOAP request, this option cannot be turned ON while the -checksignature option is turned OFF.|
|Configures the services to reject any SOAP request that does not have the wsse:UsernameToken encrypted at the element level and SOAP:Body encrypted at the content level. Because this option depends on incoming decryption being active, this option cannot be turned ON while the -decryptrequest option is turned OFF.|
|Specifies the symmetric cryptographic algorithm used to encrypt the SOAP requests. TRIP_DES stands for Triple DES, AES_128 for AES 128, AES_192 for AES 192, and AES_256 for AES 256. |
Note: The AES_192 and AES_256 options only operate properly if unlimited encryption has been enabled in the JRE and JDK of the Tomcat instance on which these services are executing.
The default value is TRIP_DES.
|Specifies the asymmetric algorithm to be used for encrypting the symmetric key used to encrypt SOAP responses. The available options are RSA_15 (RSA 1.5) and RSA_OAEP (RSA with Optimal Asymmetric Encryption Padding). The default value is RSA_15.|
|Specifies the asymmetric key used to sign outgoing messages. It requires the path and file name of the keystore containing the key, the password used to access the keystore, the type of keystore (JKS, JCEKS, and PKCS12), the alias of the key, and the password for the private key. The specified signing key can be an RSA or DSA type. The key used determines the algorithm of the outgoing signature. If an RSA key is used, RSA-SHA1 is the algorithm. If a DSA key is used, DSA-SHA1 is the algorithm. The default keystore and decryption key are the following values:|
|Specifies the asymmetric key used to decrypt incoming messages. It requires the path and file name of the keystore containing the key, the password used to access the keystore, the type of keystore (JKS, JCEKS, and PKCS12), the alias of the key, and the password for the private key. |
Note: The specified decryption key must be an RSA type.
The default keystore and decryption key are the following values:
|Specifies the truststore containing all the trusted public CA certificates and all the directly trusted public certificates used to validate signatures on incoming requests. It requires the path and file name of the truststore, the password used to access the truststore, and the type of keystore (JKS, JCEKS, and PKCS12). The truststore has the following defaults:|
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 CMDB web application hosted on Tomcat 6.
To package and deploy the modified service archive
To apply the modified security properties, use the
atriumwsutil -<option>command to package and deploy the CMDB Web Services archive.
You can use the
-deployoptions together, or you can run them separately.
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.
NoteYou 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.
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.