Setting up security for web services

BMC 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

Sign the soap:Body element using the chosen algorithm with the private key.
Include the resulting signature data in a ds:Signature element.
Place it in the wsse:Security element in the soap:Header.
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

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)
AES-128	http://www.w3.org/2001/04/xmlenc#kw-aes128 (http://www.w3.org/2001/04/xmlenc#kw\-aes128)

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
RSA-v1.5	http://www.w3.org/2001/04/xmlenc#rsa-1_5 (http://www.w3.org/2001/04/xmlenc#rsa\-1_5)
RSA-OAEP	http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p (http://www.w3.org/2001/04/xmlenc#rsa\-oaep\-mgf1p)

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

Keystore	Description
Filename	`<BMCAtriumCoreInstallationDirectory> /wsc/atriumws91/keystores/bmcatriumwsserver.jks`
Type	Java KeyStore (JKS)
Password	atrium
Server key details within the keystore	Server Key Name — bmcatriumwsserver Server Private Key Password — atrium
Certificate file	BMC provides the server keystore file so that you can import it into your keystore. You can find this file at: `<BMCAtriumCoreInstallationDirectory> /wsc/atriumws91/keystores/bmcatriumwsserver.cer`

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 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

`Keystore`	Description
`Filename`	`<BMCAtriumCoreInstallationDirectory> /wsc/atriumws91/keystores/bmcatriumwsserverssl.jks`
`Type`	Java KeyStore (JKS)
`Password`	atrium
`Key alias`	bmcatriumwsserverssl
`Key password`	atrium

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

`Keystore`	Description
`Filename`	`<BMCAtriumCoreInstallationDirectory> /wsc/atriumws91/keystores/bmcatriuwscacertsssl.jks`
`Type`	Java KeyStore (JKS)
`Password`	atrium

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 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:

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.

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

Option	Description
`-package\|-p`	Creates a new CMDB Web Services archive with all changes in main.xml and with the atriumwsutil utility.
`-deploy\|-d`	Deploys the CMDB Web Services archive into the CMDB web application, replacing the previous archive and its configuration.
`-verbose\|-v`	Displays a detailed file-by-file listing in the output of the archive creation process.
`-restoredefaults\| -rd`	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.
`-listconfig\|-l`	Lists the current security configuration excluding passwords.
`<filename>`	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: Parameters can be separated by white space or by new lines. Parameter values with intervening spaces must be surrounded by quotation marks. Quotation marks contained within parameters already surrounded by quotation marks can be escaped with a back slash. Blank lines are ignored. Lines can be commented out by having the first non-white-space character as a '#'. Any environment variables that are intended to be expanded in the option value must be surrounded by the '%' character.

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

<securityProperty> <value1> . . . <valueN> 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 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

Option syntax	Description
`-resttransport\|-rt [HTTP_ONLY\|HTTP_PRIMARY\|HTTPS_ONLY\|HTTPS_PRIMARY]`	Configures the transports from which the RESTful Web services can be accessed. HTTP_ONLY ensures that the service is only accessible from the http port configured in Tomcat. HTTPS_ONLY (default) ensures that the service is only accessible from the https port configured in Tomcat. HTTP_PRIMARY and HTTPS_PRIMARY make the services accessible from both http and https ports. WSDL files themselves are accessible from both ports regardless of the option chosen here.
`-transport\|-t [HTTP_ONLY\|HTTP_PRIMARY\|HTTPS_ONLY\|HTTPS_PRIMARY]`	Configures the transports from which the SOAP Web services can be accessed. HTTP_ONLY ensures that the service is only accessible from the http port configured in Tomcat. HTTPS_ONLY (default) ensures that the service is only accessible from the https port configured in Tomcat. HTTP_PRIMARY and HTTPS_PRIMARY make the services accessible from both http and https ports, but will cause the WSDL files of the services to report the endpoint with the primary port. WSDL files themselves are accessible from both ports regardless of the option chosen here.
`-noncevalidation\|-nv [ON\|OFF\|REQUIRED\|NONCE_ONLY\|CREATED_ONLY]`	Configures the Web services to validate wsse:Nonce and wssu:Created elements passed in with the wsse:UsernameToken element in the wsse:Security header. ON enables validation of both elements optionally, meaning only if they are present in the header. This is the optimal option for compliance to the WS-Security 1.0 standard when using wsse:UsernameToken with PasswordText encoding. OFF (default) disables all validation, ignoring the presence or absence of these elements. REQUIRED enables validation of both wsse:Nonce and wssu:Created elements. NONCE_ONLY enables validation of only the wsse:Nonceelement. CREATED_ONLY enables validation of only the wssu:Created element.
`-noncethreshold\|-nt [300-86400]`	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.
`-createdthreshold\|-ct [60-86400]`	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.
`-timestampin\|-ti [ON\|OFF]`	Configures the services' requirement for a valid wsu:Timestamp. OFF (default) — wsu:Timestamp is validated if received but is not required. ON — wsu:Timestamp is required and validated in the wsse:Security header of all SOAP requests.
`-timestampout\|-to [ON\|OFF]`	Configures the services to include a valid wsu:Timestamp. OFF (default) — wsu:Timestamp is not included. ON — A valid wsu:Timestamp is included in the wsse:Security header of all SOAP responses with an expiry of five minutes past the creation date.
`-checksignature\|-cs [ON\|OFF]`	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. OFF (default) — Disables the requirement. ON — Enables the requirement.
`-decryptrequest\|-dr [ON\|OFF]`	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. OFF (default) — Disables the server to decrypt requests. ON — Enables the server to decrypt requests. If an incoming message is not encrypted, this option alone does not fail the request. To require encryption, use the -enforceencryption option.
`-signresponse\|-sr [ON\|OFF]`	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. OFF (default) — Disables the requirement. ON — Enables the requirement.
`-encryptresponse\|-er [ON\|OFF]`	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. OFF (default) — Disables encryption. ON — Enables encryption.
`-enforceencryption\|-ee [ON\|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. OFF (default) — Disables the encrypted wsse:UsernameToken and SOAP:Body requirement. ON — Enables the requirement.
`-encryptionalgorithm\|-ea [TRIP_DES\|AES_128\|AES_192\|AES_256]`	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.
`-keytransportalgorithm\|-kta [RSA_15\|RSA_OAEP]`	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.
`-signaturekey\|-sk <keystoreFile> <keystorePassword>[JKS\|JCEKS\|PKCS12] <keyAlias> <keyPassword>`	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: Keystore File Name: `<BMCAtriumCoreInstallationDirectory>/wsc/atriumws91/keystores/bmcatriumwsserver.jks` Keystore Type: Java Keystore (JKS) Keystore Password: atrium Key Alias: bmcatriumwsserver Key Password: atrium Because the client authenticates the signature in the Web Service response, clients connecting with the default configuration must add the following public certificate to its own truststore: `<BMCAtriumCoreInstallationDirectory>/wsc/atriumws91/keystores/bmcatriumwsserver.cer` Note: Replace the default keystore and key with one that meets your company's requirements.
`-decryptionkey\|-dk <keystoreFile> <keystorePassword>[JKS\|JCEKS\|PKCS12] <keyAlias> <keyPassword>`	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: Keystore File Name: `<BMCAtriumCoreInstallationDirectory>/wsc/atriumws91/keystores/bmcatriumwsserver.jks` Keystore Type: Java Keystore (JKS) Keystore Password: atrium Key Alias: bmcatriumwsserver Key Password: atrium To encrypt its requests to the services using the default certificate, a client must add the default public certificate to its own keystore that is found in the following file: `BMCAtriumCoreInstallationDirectory>/wsc/atriumws77/keystores/bmcatriumwsserver.cer` Note: Replace the default decryption key with one that meets your company's requirements.
`-truststore\|-ts <truststoreFile> <password>[JKS\|JCEKS\|PKCS12]`	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: Keystore File Name: `<BMCAtriumCoreInstallationDirectory>/wsc/atriumws91/keystores/bmcatriumwscacerts.jks>` Keystore Type: Java Keystore (JKS) Keystore Password: atrium This default truststore contains all the public certificates of Certificate Authorities in the cacerts file of the Java 1.6 distribution. It also contains a public self-signed certificate with the alias bmcatriumwsclient. This certificate allows clients to sign their requests and decrypt their responses with the following private/public key pair: Keystore File Name: `<BMCAtriumCoreInstallationDirectory>/wsc/atriumws91/keystores/bmcatriumwsclient.jks` Keystore Type: Java Keystore (JKS) Keystore Password: atrium Key Alias: bmcatriumwsclient Key Password: atrium Note: Replace the default truststore and key with one that meets your company's requirements.

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 -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.

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.