Sun Mainframe Security Facility Software, Release 1.0.0
Updated User Documentation

This file contains updates to the user documentation
released with MSF 1.0.0. If there are no documentation
updates for a patch release, it is so noted.

--------------------------------
MSF 1.0.0p2    -  113889-02
--------------------------------

1. Because of some architectural changes made to Sun MSF in this release,
you must run the ConvertDBP1toP2 utility if you are using Sun MSF 1.0.0 
or 1.0.0 patch 1. Running this utility enables you to use the existing
repository database in the new release.

The syntax of the command is:

   ConvertDBP1toP2 {oracle|sybase}  <schema-pw> <admin-pw> <user-pw>
   
where:

   <schema-pw> is your MSF repository schema user's password
   <admin-pw> is your MSF repository administrator's password
   <user-pw> is your MSF repository normal user's password

To Run the Conversion Utility:

   Note: Make sure your environment is set correctly and the EMPSECURITY
   environment variable is set to the new patch version of the software.

   1. Gather the following information:
      - Database type (Sybase or Oracle)
      - Schema password
      - Administrator password
      - User password
      
      For example, your repository is an Oracle database, and the
      schema password is spw, the administrator password is apw, and 
      the user password is upw.
      
   2. Using the example database and passwords, type the following
      command at a UNIX prompt:
      
      $ ConvertDBP1toP2 oracle spw apw upw
      
   The following output will be displayed to indicate a successful migration:
   
      (SecSvc_WARN) Updating the repository from P1 to P2
      (SecSvc_WARN) Completed Updating the repository from P1 to P2

   If any errors are reported, contact your authorized Sun service
   provider.
   

2. In the Sun Mainframe Transaction Processing Software Administrator's Guide, 
in Chapter 9, the section "To Set Up the Sybase Database" contains an error 
in the computer-user dialog in Step 3. (BugId 4797160)

   The line:
     
     isql> sp_changedowner superadmin
     
   should be:
     
     isql> sp_changedbowner superadmin
     

3. The Sun Mainframe Security Facility has been enhanced with a new snapshot
utility that collects the Sun MSF configuration and log files into a 
compressed file that can be transmitted via ftp or email to another location
for analysis. The utility is named msfsnap and is located in the
$EMPSECURITY/bin directory of the Sun MSF installation.

   Format:

     msfsnap [-d <directory>] [-u <userid>]

   where:
   
     <directory>  The directory path where the snapshot is to be written. 
                  If a directory is not specified, the snapshot is written
                  to the directory path specified in the MSFSNAPDIR 
                  environment value. If the environment variable is not set,
                  the tool terminates without taking a snapshot.
     
     <userid>     The user ID needed for the tool to gather SecurityServer
                  statistics into the snapshot. When this option is used, a
                  SecurityServer -p request is executed and the msfsnap 
                  utility prompts for the password as follows:

                     MSF Login password:

                  If an incorrect password is provided, or if the -u option is
                  not specified, SecurityServer statistics are not included.

   The snapshot is packaged as a compressed file in the specified directory 
   in the following format:

      MSFsnapshot.<date_time>.zip

   This file can be uncompressed into its component files for analysis.
   
   Example 1: Write the snapshot to the /tmp directory without SecurityServer
              statistics
              
              msfsnap -d /tmp
              
              
   Example 2: Write the snapshot to the /tmp directory with SecurityServer
              statistics
              
              msfsnap -d /tmp -u <your MSF administrator user ID>
              MSF Login Password: <your MSF administrator password>
              
              
   Example 3: Write the snapshot to the $MSFSNAPDIR directory without
              SecurityServer statistics
              
              export MSFSNAPDIR=/snaps
              msfsnap
              
              
   Example 4: Write the snapshot to the $MSFSNAPDIR directory with
              SecurityServer statistics
              
              export MSFSNAPDIR=/snaps
              msfsnap -u <your MSF administrator user ID>
              MSF Login Password: <your MSF administrator password>
              
   
4. A VERSION file has been added to the Sun MSF package. It will be installed
in the $EMPSECURITY directory. (BugId 4791355)


5. As a result of some internal changes to Sun MSF, the property:

     com.sun.emp.security.adapterBrand
   
in the MSFConfig.properties file is no longer used. If it is configured,
it will be treated as a comment.


6. The IBM Universal Database (UDB) 8.1.0 has been qualified with Sun MSF. 
(BugId 4819788). UDB is the UNIX version of the mainframe DB2 database.

Caution: The UDB JDBC driver is sensitive to the setting of the LANG
environment variable, and might not work correctly with certain locale
settings. The Sun MSF product qualification was done with the LANG variable 
set to C. Check the IBM documentation for additional information.

The following information describes how to set up UDB as the security
repository for Sun MSF.

Using an IBM Universal Database (UDB)

This section provides an example of how to create the table space and user IDs 
for a UDB database that will be used as the security repository. The tools or 
utilities used to perform these tasks can be different based on the UDB 
release you are using.

A. Create Three UNIX Logins

Contact your UNIX system administrator to create three UNIX logins on your
host system for the UDB database. The logins should belong to a single group,
for example, "dbtwo". Consult your UDB administrator for information about 
the UDB group on your host system. The three UNIX logins could be, for example:

  udbsec
  udbadmin
  udbuser

These login names must match the corresponding values in the 
MSFConfig.properties file for the following items:

  com.sun.emp.security.adapterSchema
  com.sun.emp.security.adapterAdmin
  com.sun.emp.security.adapterUser

B. To Create the Table Space/Database

  1. Log in to the host system as udbsec. 
  2. Make sure the db2 command is in your path. Source the db2profile file
     given to you by your UDB admin. 
  3. Type the db2 command. 
     The "db2 =>" prompt should be displayed. 
  4. To create a database called MSFSECUDB, type:

     db2 => CREATE DATABASE MSFSECUDB

     DB20000I  The CREATE DATABASE command completed successfully.

     db2 => connect to MSFSECUDB

     Database Connection Information

      Database server        = DB2/SUN 8.1.0
      SQL authorization ID   = UDBSEC
      Local database alias   = MSFSECUDB

C. Setting up the Configuration Files

You can now set up the configuration files.

  MSFConfig.properties File

  Set the necessary properties in the MSFconfig.properties file. Remember 
  the three UNIX logins and the name of your database (in this case
  MSFSECUDB). For example:

       com.sun.emp.security.adapterType=JDBC
       com.sun.emp.security.adapterKeyFile=/tmp/udbkey.txt
       com.sun.emp.security.adapterURL=jdbc:db2://mach-2:50000/MSFSECUDB
       com.sun.emp.security.adapterDriver=com.ibm.db2.jcc.DB2Driver
       com.sun.emp.security.adapterSchema=udbsec
       com.sun.emp.security.adapterAdmin=udbadmin
       com.sun.emp.security.adapterUser=udbuser
  

  Java Policy File

  Set up your java.policy file so that the UDB Java runtime file (for
  example, db2jcc.jar) has permission to connect and resolve connections. 
  For example:

  /* grant the DB2 classes permissions needed to connect to the database */
  grant codebase "file:/usr/local/pkgs/db2/sqllib/java/db2jcc.jar" {
          permission java.net.SocketPermission "*", "connect,resolve";
  };


  Your directory, host names, and ports may vary. Consult your UDB 
  administrator for the correct URL, environment setups and client
  configurations for JDBC. 
 
D. Ensure your execution environment includes the necessary MSF and UDB
file paths. The proper UDB jar file (for example, db2jcc.jar) must be in 
your CLASSPATH.

E. Run the MakeAnAdministrator utility. Refer to the Sun MTP Administrator's
Guide for detailed information.


--------------------------------
MSF 1.0.0p1    -  113889-01
--------------------------------


------------------------------------------------------------------------------
Important Information

Before attempting to bring up a Sun MTP region with external security enabled,
read the README.doc file located in the $EMPSECURITY/test directory. It 
contains important information about loading security rules for Sun MTP
resources that are supplied with the product (transactions, files, maps).
Steps 1 and 2 in the README.doc file contain instructions for loading the
Sun MTP resources.
-------------------------------------------------------------------------------

1. The SecurityServer command no longer requires the user name and password be 
provided on the command line. It will prompt for the required user name and 
password. (BugId 4761324)

An example of the computer-user dialog is as follows:

        $ SecurityServer -s
        MSF Login username: admin1
        MSF Login password: *******


2. The following are new messages in the secsvc_messages.properties file (BugID 
4751613):

SecSvc_300=(SecSvc_300) Security Repository Error occured: {0}

Description: This message is displayed if there is a problem in the security
repository, for example, the database is not functioning, a table is missing,
or there is a network disconnection to the repository. This message is also 
written to the audit logs.

SecSvc_301=(SecSvc_301) Unknown Security Error occured: {0}

Description: This message is displayed by SecAdmin if any non-repository error 
occurs while operating SecAdmin. This message is also logged to the audit files.

3. This patch release comes with a new file named java.security, which is 
installed in the lib directory of the Sun MSF installation (for example, 
$EMPSECURITY/lib/java.security). It contains values required for Sun MSF and can
reduce the chance of introducing errors when editing the java.policy and 
java.security files. (BugID 4761301)

To Update the java.security File
     
     Append the contents of the new $EMPSECURITY/lib java.security file, 
     which contains values required for Sun MSF, to the java.security file
     located in the <Java-home>/lib/security directory. In addition, to
     ensure that security is enforced by disabling a command-line override 
     of the security policy set in the java.policy file, the following
     option has been set in the $EMPSECURITY/lib/java.security file:
     
        policy.allowSystemProperty=false
     
     If that option is not appropriate in your environment, delete that
     line.

Note that the directions for updating the java.policy file have been changed
as follows:

     Append the contents of the $EMPSECURITY/lib/java.policy file, which
     contains Sun MSF-specific entries, to the java.policy file located in 
     the <Java-home>/lib/security directory.

4. Because the Sun MTP maps for the CEBR and CEDA transactions were
inadvertently omitted from the file that loads the Security Repository 
($EMPSECURITY/test/suppliedLoadFile.txt), you must run the following commands.
You can either add them to the suppliedLoadFile.txt, if you haven't
populated the repository, or you can execute them through SecAdmin. 
(BugID 4778974)

 crs,KIX_PROGRAM,CEBRMAP,MTP-supplied BMS map for CEBR transaction
 crd,MTPdeveloperPrograms,MTP-supplied programs requiring Developer permissions
 ard,KIX_PROGRAM,CEBRMAP,MTPdeveloperPrograms
 arp,MTPdeveloperUsers,MTPdeveloperPrograms,READ,EXECUTE

 crs,KIX_PROGRAM,CEDADISM,MTP-supplied BMS map for CEDA transaction
 crd,MTPadminPrograms,MTP-supplied programs requiring Admin permissions
 ard,KIX_PROGRAM,CEDADISM,MTPadminPrograms
 arp,MTPadminUsers,MTPadminPrograms,READ,EXECUTE
