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.
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 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.
|Creates a new BMC Atrium Web Services Archive with all changes in main.xml and with the atriumwsutil utility.|
|Deploys the BMC Atrium Web Services Archive into the Atrium 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.|
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
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:|
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
-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 BMC Atrium Web Service Archive is now available for use.