com.tivoli.mts
Class SvrSslCfg

java.lang.Object
  |
  +--com.tivoli.mts.SvrSslCfg

public final class SvrSslCfg
extends java.lang.Object

This program configures a Tivoli Policy Director application server.

The output of a successful run of this program will be a configuration file and a Java Keystore that securely stores a client certificate that allows callers to make authenticated use of Policy Director services.


Field Summary
static java.lang.String CREATE
          The value for the CREATE action
static java.lang.String REPLACE
          The value for the REPLACE action
static java.lang.String UNCONFIG
          The value for the UNCONFIG action
 
Method Summary
static void main(java.lang.String[] argv)
           This function will configure an application for remote usage of Policy Director services.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REPLACE

public static final java.lang.String REPLACE
The value for the REPLACE action

CREATE

public static final java.lang.String CREATE
The value for the CREATE action

UNCONFIG

public static final java.lang.String UNCONFIG
The value for the UNCONFIG action
Method Detail

main

public static void main(java.lang.String[] argv)

This function will configure an application for remote usage of Policy Director services.

As of Policy Director 3.9, this function can be used in one of two ways. If the first positional parameter is a simple name (i.e., is not a distinguished name like cn=x,ou=whatever...) then this function will handle all the chores necessary to configure as a remote Policy Director application, including setting up an account, registering this account in the necessary groups, and also generating and registering a certificate to use client-side authentication over SSL to the PD servers. If the first positional parameter is a distinguished name, then the usage is assumed to be the same as it was in PD 3.7 and 3.8, which means the caller would have to do much more work to complete the configuration successfully. This latter mode is left for compatibility reasons only, so the simple-name usage would be highly recommended.

New in PD 3.9 is the ability to specify a URL for the configuration file and a URL for the keystore file (where the certificate and private key will be stored). Prior to PD 3.9, the location of the configuration file was hardwired to be in the current JRE's home directory, and the location of the keystore file was hardwired to be two directory levels below the config file, in the lib/security directory. Now the invoker can specify where these two files should go. If the invoker chooses to specify a location for the config file that is different from the default location, and they wish to make use of PDPermission checks, then they must also change to use the PDPrincipal constructor that accepts a config URL parameter and/or modify the PDLoginModule configuration to specify the correct config URL (see the documentation for those classes for more information).

Also new in PD 3.9 is the ability to specify an action at the end of the parameter string. If using the old, distinguished-name invocation, no action options are supported. However, if using the new simple-name invocation, the possible action set includes

"unconfig" means that the account that was set up on the server for this application will be deleted, the keystore will be deleted, and portions of the config file that are no longer relevant will be deleted, but the config file itself will still exist. "create" means that if the current configuration seems to indicate that an account has already been set up and a keystore file already exists, an IllegalStateException will be thrown and nothing further will happen. "replace" means that if the current configuration seems to indicate that an account has already been set up and a keystore file already exists, an "unconfig" operation will be attempted before deleting the keystore and starting over to set up an account.

To illustrate the difference in the support now provided with what previously existed, here's all that needs to be done to configure using a simple name:

 java com.tivoli.mts.SvrSslCfg perm17 xxxpassword timon.i.com rafiki.i.com 7135 7136 file:/d:/java13/jre/PdPerm.properties file:/d:/keys/perm17.ks
 

To unconfigure with a simple name, all that needs to be done is:

 java com.tivoli.mts.SvrSslCfg perm17 xxxpassword ignored ignored ignored ignored file:/d:/java13/jre/PdPerm.properties ignored unconfig
 

To contrast with this, here are the things that must be done to use the old distinguished-name support: First, accounts need to be set up on the server, so some admin commands must be run on the pdmgrd server (assume it's timon.i.com):

 pdadmin -a sec_master -p xxxpassword
 user create PdPermission9993 cn=PdPermission/gordo,o=myCompany PdPermission/gordo PdPermission somePW9993
 user modify PdPermission9993 account-valid yes
 group modify remote-acl-users add PdPermission9993
 
(This example assumes that the LDAP root for the users is anchored at o=myCompany, and uses the convention that the "distinguishing" part of the distinguished name will in fact be the hostname of the machine, which in this example is "gordo".)

The command that could be issued now on gordo is:

 java com.tivoli.mts.SvrSslCfg cn=PdPermission/gordo,o=myCompany xxxpassword timon.i.com rafiki.i.com
 
(which is taking the default SSL port numbers for pdacld and pdmgrd, and configuring gordo to use the pdacld on rafiki.i.com).

To unconfigure a setup that used a distinguished name, the invoker is responsible for undoing whatever was done on the server to set up accounts, and then delete the config file and keystore file by hand (i.e., no support is directly provided by this class).

Parameters:
argv[0] - The name of the account that this application will use. This could either be a simple name, which will work with any of the directories used by the PD servers, or a distinguished name, which is only supported if the PD servers are using an LDAP directory
argv[1] - The password for sec_master.
argv[2] - The name of the machine that is running pdmgrd.
argv[3] - The name of the machine that is running the instance of pdacld that this machine is to communicate with.
argv[4] - The SSL port number for pdmgrd, if other than the default (7135).
argv[5] - The SSL port number for pdacld, if other than the default (7136).
argv[6] - The URL of the configuration file, if other than the default file:${jre.home}/PdPerm.properties. The only URL protocol that is currently supported by SvrSslCfg is file:. The invoker is strongly encouraged to supply a URL for this parameter rather than taking the default, but the default location will still be supported for compatibility.
argv[7] - The URL of the keystore to use, if other than the default file:${jre.home}/lib/security/pdperm.ks The only URL protocol that is currently supported by SvrSslCfg is file:. The invoker is strongly encouraged to supply a URL for this parameter rather than taking the default, but the default location will still be supported for compatibility.
argv[8] - Specifies an action. The default is "replace", but could also be "create", or "unconfig". Only valid if a simple name is used for argv[0].
Throws:
java.lang.IllegalArgumentException - if it seems like bad data was passed in.
java.lang.IllegalStateException - if an error occurred processing this request.