Security policies for BMC Atrium Web Services

You can modify the default security policies. BMC recommends switching out 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.

Modifying security configuration for BMC Atrium 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 BMC Atrium Web Service 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 Atrium 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\atriumws90\atriumwsutil.cmd
UNIX (shell script):<ATRIUMCORE_HOME>/wsc/atriumws90/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 BMC Atrium Web Service 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 BMC Atrium Web Services Archive with all changes in main.xml and with the atriumwsutil utility.
`-deploy\|-d`	Deploys the BMC Atrium Web Services Archive into the Atrium 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.

Modifying security properties for BMC Atrium Web Services

To view and modify the security properties, you must use the atriumwsutil utility, which saves the values to an encrypted file (wsc/atriumws90/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/atriumws90/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/atriumws90/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/atriumws90/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/atriumws90/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/atriumws90/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.

Packaging and deploying the service archive

After making the wanted modifications, you must package and deploy the modified BMC Atrium Web Services Archive for the BMC Atrium 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 BMC Atrium 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 BMC Atrium Web Service Archive is now available for use.