#**********************************************************************#
#*                                                                    *#
#* Copyright (c) 2004 by Sun Microsystems, Inc.                       *#
#* All rights reserved.                                               *#
#*                                                                    *#
#**********************************************************************#


Introduction
------------
This readme file describes how to enable the Sun MTP VSAM Primer application
and the MQ sample applications to use Sun MSF as an external security manager
(ESM). Exercising the applications demonstrates how Sun MTP can provide full
resource-level security (RSL).

Getting Started
---------------
Before performing the procedures in this readme file, you must:
1. Install Sun MTP. Refer to the Sun MTP Installation Guide.
2. Install and configure Sun MSF, including initializing the security
   repository. Refer to the Sun MSF Administrator's Guide.

Note: In this readme file, the environment variable MSF_HOME refers to the
Sun MSF installation directory.

Files in $MSF_HOME/etc
-------------------------------
The following files are used to load and unload resources in the security
repository:

suppliedLoadFile.txt  - Loads Sun MTP resources
suppliedUnload.txt    - Unloads Sun MTP resources

primerLoadFile.txt    - Loads Primer region application resources
primerUnload.txt      - Unloads Primer region application resources

mqsampleLoadFile.txt  - Loads Sun MTP MQ sample application resources
mqsampleUnload.txt    - Unloads Sun MTP MQ sample application resources

Loading the resources into the security repository
---------------------------------------------------------------
1.  Start the security logs server.

2.  Change to the $MSF_HOME/etc directory.

3.  Start the 'SecAdmin' tool at a command prompt.

4.  When the following prompts are displayed, type the user name and password.

    MSF Login username: <your Security Administrator name>
    MSF Login password: <your Security Administrator password>
===============================================================================
| Copyright (c) 2002 by Sun Microsystems, Inc. All rights reserved.           |
|                                                                             |
| Welcome to SecAdmin, the security administration command-line tool          |
|     Enter 'help' to see a list of commands, or 'help,<command>' for         |
|     help on a specific command.                                             |
===============================================================================

5.  Populate your security repository with the rules for the Sun MTP
    resources using the SecAdmin "loadFile" command:

    SecAdmin: lf,suppliedLoadFile.txt

6   Populate your security repository with the rules for the Primer
    application resources:

    SecAdmin: lf,primerLoadFile.txt

7.  If you plan to test the MQ sample application, you can populate your
    security repository with the rules for the MQ application:

    SecAdmin: lf,mqsampleLoadFile.txt

8.  Verify that your security repository has been populated with the rules
    you just loaded. Type the "printDomainTree" (pdt) and
    "printRoleTree" (prt) commands to produce a summary structural report of
    your security repository contents. The output should be similar to the
    following:

    SecAdmin: pdt
    [SecAdmin]: printDomainTree
    AdminResources-->|Principal,*|Group,*|Role,*|ResourceDomain,*|Resource,*
		     |ResourceType,*|PermissionType,*|ObjectReference,*
		     |CalendarRule,*|ApplicationRule,*
    MTP-EPITransactions-->|KIX_ATTACH_TRANS,CTIN
    MTP-ISCTransactions-->|KIX_ATTACH_TRANS,CPMI|KIX_ATTACH_TRANS,
                           CRTE|KIX_ATTACH_TRANS,CVMI
    MTPadminFiles-->|KIX_FILE,CATALOG|KIX_TSQUEUE,MQTEST01|KIX_TSQUEUE,CEBR*
    MTPadminPrograms-->|KIX_PROGRAM,CEDADISM|KIX_PROGRAM,JMQGTAL
    MTPadminTransactions-->|KIX_ATTACH_TRANS,CBCH|KIX_ATTACH_TRANS,
			    CEDA|KIX_ATTACH_TRANS,CEMT|KIX_ATTACH_TRANS,
			    CFMS|KIX_ATTACH_TRANS,CINI|KIX_ATTACH_TRANS,
			    CRED|KIX_ATTACH_TRANS,CTBL|KIX_COMMAND,
			    SHUTDOWN|KIX_ATTACH_TRANS,KMQ1|KIX_ATTACH_TRANS,
			    MQJV|KIX_START_TRANS,KMQ1|KIX_START_TRANS,MQJV
    MTPdefaultPrograms-->|KIX_PROGRAM,SIGNMAP
    MTPdefaultTransactions-->|KIX_ATTACH_TRANS,CCIN|KIX_ATTACH_TRANS,
			      CESF|KIX_ATTACH_TRANS,CESN|KIX_ATTACH_TRANS,
			      CPLT|KIX_ATTACH_TRANS,CRSR|KIX_ATTACH_TRANS,
			      CSMT|KIX_ATTACH_TRANS,CSPG|KIX_ATTACH_TRANS,
			      CSSF|KIX_ATTACH_TRANS,CSSN
    MTPdeveloperPrograms-->|KIX_PROGRAM,CEBRMAP
    MTPdeveloperTransactions-->|KIX_ATTACH_TRANS,CEBR|KIX_ATTACH_TRANS,
			        CECI|KIX_ATTACH_TRANS,CEDF|KIX_ATTACH_TRANS,
			        CMNU|KIX_ATTACH_TRANS,CSGU
    MTPprimerUpdateTransactions-->|KIX_ATTACH_TRANS,AC02
       MTPprimerPrintTransactions-->|KIX_ATTACH_TRANS,AC03|KIX_START_TRANS,AC03
			   	    |KIX_START_TRANS,ACLG
          MTPprimerQueryTransactions-->|KIX_ATTACH_TRANS,AC01|KIX_ATTACH_TRANS,
			           AC05|KIX_ATTACH_TRANS,ACCT|KIX_PROGRAM,ACCT04
    MTPprimerUpdatePrograms-->|KIX_PROGRAM,ACCT02
       MTPprimerPrintPrograms-->|KIX_PROGRAM,ACCT03
          MTPprimerQueryPrograms-->|KIX_PROGRAM,ACCT00|KIX_PROGRAM,ACCT01
				   |KIX_PROGRAM,ACCTSET|KIX_PROGRAM,ACCTSETM
    MTPprimerFiles-->|KIX_FILE,ACCTFIL|KIX_FILE,ACCTIX
    MTPprimerTSQueues-->|KIX_TSQUEUE,AC01*|KIX_TSQUEUE,AC02*|KIX_TSQUEUE,ACCTLOG

    SecAdmin: prt
    [SecAdmin]: printRoleTree
    MTPepiUr-->
    MTPiscUr-->
    adminMTP-->|ADMUSER
        develMTP-->|DEVUSER
            defltMTP-->|unikix
    updatMTP-->|UPDUSER
        printMTP-->|PRTUSER
            queryMTP-->|QRYUSER


9.  Add your Sun MTP administrator's UNIX user ID as a principal to your
    security repository using the following command:

    SecAdmin: cpr,<userid>,,,,,,Sun MTP administrator UNIX user ID

10. Add your Sun MTP administrator's UNIX user ID to the Sun MTP administrator
    role as its primary role using the following command:

    SecAdmin: spr,<userid>,adminMTP

11. If were no error messages from SecAdmin, and you are using an RDBMS as
    your security repository, commit these updates. If you are using an LDAP
    directory, you do not have to perform this step.

    SecAdmin: commit

12. Terminate the SecAdmin tool:

    SecAdmin: quit

13. Start the Sun MSF security server:

    $ msfserver -s
    MSF Login username: <Security Administrator name>
    MSF Login password: <Security Administrator password>


Setting up the Sun MTP application environment to enable Sun MSF as its ESM
---------------------------------------------------------------------------

1.  Ensure the UNIX user ID of your session is the Sun MTP administrator.

2.  Add the following environment variables to the region setup file to enable
    Sun MTP to use the Sun MSF external security manager. You can add these
    variables to the setup file located in the example directory, for
    example, $UNIKIX/examples/primer/cobol_mf/setup.

    KIXSEC=YES
    KIXAPPSEC=NO                 (disable region access checking)
    KIXCMDSEC=NO                 (disable KIX_COMMAND access checking)
    KIXTCTSEC=NO                 (disable terminal access checking)
    KIXSECDFLTUSER=unikix
    KIXSEC_SERVERPORT=<port #>	 (com.sun.emp.security.serverPort value)
    KIXSEC_SERVERHOST=<your host> (com.sun.emp.security.serverHost value)
    KIXSEC_LOGGING=ALL           (logs access affirmations/denials to MTP log)

    Note: By default, setting KIXSEC=YES, enables security checking on all
    other non-specified Sun MTP resource types in your environment. In this
    case, this is equivalent to explicitly specifying:

    KIXDCTSEC=YES                (transient data queues)
    KIXFCTSEC=YES                (VSAM files)
    KIXJCTSEC=YES                (journals)
    KIXPCTSEC=YES                (attached transactions)
    KIXPPTSEC=YES                (programs)
    KIXSTTSEC=YES                (started transactions)
    KIXTSTSEC=YES                (temporary storage queues)


Setting up and running the MQ or MQ-JMS Bridge sample applications
------------------------------------------------------------------

The readme files for the MQ and MQ-JMS Bridge sample applications contain all
the information necessary to set up and run the sample applications with
Sun MSF. When running these applications, use the Sun MTP administrator's
UNIX user ID to bring up the regions and run the applications.


Setting up the Primer application environment
---------------------------------------------

Set up the Primer application environment as described in the readme file
located in the primer directory you are using; for example:

    $UNIKIX/examples/primer/cobol_mf


Running the Primer application
------------------------------

1.  Make sure the user ID of your session is the Sun MTP administrator.

2.  Source the updated setup file for the Primer application.

3.  Start the Primer region with the 'kixstart' command.

4.  Start a local client window, and clear the Sun MTP copyright screen.

    At this point, your client window is connected to the region as your
    Sun MTP administrator's UNIX user ID, which is not authorized to use
    the ACCT transaction..

5.  Sign on to the region as one of the configured principals on the
    security repository.

    Use the CESN transaction to sign on as one of the following users:

    QRYUSER (password PWQ); user authorized to do only ACCT search/query
    PRTUSER (password PWP); user also authorized to do ACCT print request
    UPDUSER (password PWU); user authorized for all ACCT functions

    DEVUSER (password PWD); authorized for Sun MTP Developer transactions
    ADMUSER (password PWA); authorized for Sun MTP Admin transactions

6.  Execute some transactions.

    See the following example.


Example
-------

1.  Sign on as QRYUSER.

2.  Submit the ACCT transaction.

3.  Query for "GREENFIELD".

    A list of records are displayed.

4.  Try to use the P (print) function to select one of those records to print.

    The ACCT transaction will try to start the AC03 transaction, but will
    get a NOTAUTH condition, and will abend with the following message:

     A TRANSACTION ACCESS NOT AUTHORIZED.

    A message similar to the following is written to the Primer application's
    'unikixmain.log' file reporting the access authorization denial.

    09/12/2002 10:49:11 unikixtran0 :KIX4001W External Security: access denied -
    CheckPermission: default,QRYUSER,KIX_START_TRANS,AC03,EXECUTE

    The Sun MSF message log will also contain a message similar to:

    2002-09-12 10:05:53.851 MST FATAL checkPermission (SecSvc_015) Principal
    QRYUSER has been denied access to (com.sun.emp.security.admin.
    CICSResourcePermission "KIX_START_TRANS" AC03 execute).

5.  Log out of the region as QRYUSER by executing the CESF transaction.

    Your client is still connected to region, but as the KIXSECDFLTUSER
    user ID. This "default user" has limited resource access permissions.

6.  Try to submit a transaction not authorized for the default user, such as
    ACCT.

    The request is rejected with the following message:

    KIX0473E   Transaction not authorized by user

7.  Log in to the region as any of the other valid users, and execute
    authorized and non-authorized transactions.

    View the the message log to see the access results.

8.  When you finish testing, log out.

9.  Log in as ADMUSER.

10. Shut down the Primer application region using the following transaction:

    CEMT PERFORM SHUTDOWN

    Alternatively, you can execute the 'kixstop' command at your Sun MTP
    administrator's UNIX command prompt.

11. Shut down the security server using the following command:

    $ msfserver -t
    MSF Login username: <Security Administrator name>
    MSF Login password: <Security Administrator password>

Unloading the Resources
-----------------------

1.  Start the SecAdmin tool.

2.  Uninstall the MQ application security rules (if you loaded them) using
    the following command:

    SecAdmin: lf,mqsampleUnload.txt

3.  Uninstall the Primer application security rules using the following
    command:

    SecAdmin: lf,primerUnload.txt

4.  If you are not going to use Sun MSF, uninstall the Sun MTP transactions
    rule set using the following commands:

    SecAdmin: lf,suppliedUnload.txt
    SecAdmin: dpr,<MTP admin UNIX userid>

5.  Verify that your security repository has been depopulated. Type the
    "printDomainTree" (pdt) and "printRoleTree" (prt) commands to produce a
    summary structural report of your security repository contents. The output
    should be similar to the following:

    SecAdmin:pdt
    [SecAdmin]: printDomainTree
    AdminResources-->|ApplicationRule,*|CalendarRule,*|Group,*|ObjectReference,*
                     |PermissionType,*|Principal,*|Resource,*|ResourceDomain,*
                     |ResourceType,*|Role,*

    SecAdmin:prt
    [SecAdmin]: printRoleTree

6.  If were no error messages from SecAdmin, and you are using an RDBMS as
    your security repository, commit these updates. If you are using an LDAP
    directory, you do not have to perform this step.

    SecAdmin: commit

7.  Terminate the SecAdmin tool:

    SecAdmin: quit
