Using the TSSFAR Utility

ctsfz
Use the File Analysis Routine (TSSFAR) to review the permissions and assignments recorded in the Security File. The type of security information displayed by TSSFAR depends upon the control statements selected.
TSSFAR is used to:
  • Provide a cross-reference of ALRB block keys with the ARLBs in the block and verify the count against what is in the header block map
  • Review mismatched ARLB chains
  • Review connections between ACIDs and PROFILEs
  • Review connections between owned and owning ACIDs
  • Review resource ownership between ACIDs and resources
The file TSSFAR executes on is continuously accessed for the duration of the job. Running TSSFAR against the Security File can cause degradation to system performance. We recommend that TSSFAR always run against a Backup File at the direction of Broadcom support staff.
Required Authority
The following users may run TSSFAR:
  • The MSCA
  • A user with no administrative authority may use TSSFAR if given USE access to entity TSSUTILITY.TSSFAR in the CASECAUT resource class.
    This access may be granted by an administrator using the following command:
    TSS PERMIT(user) CASECAUT(TSSUTILITY.TSSFAR) ACCESS(USE)
Set Up MEMLIMIT
The IARV64 macro obtains and releases the 64 bit memory object. For this macro to work:
  • You must have z/OS r1.6 or higher
  • The MEMLIMIT keyword must be increased in either in the SMFPRMxx member during IPL time or on the jobcard of the JCL running TSSFAR
To increase MEMLIMIT, add the following line to SYS1.PARMLIB(SMFPRM
xx
):
MEMLIMIT(4G)
Example: Setting up MEMLIMIT
This sample sets MEMLIMIT to 4Gb:
ACTIVE /*ACTIVE SMF RECORDING*/ DSNAME(SYS1.MANx) /* DATA SET */ NOPROMPT /*DO NOT PROMPT OPERATOR FOR OPTIONS*/ REC(PERM) /*TYPE 17 PERM RECORDS ONLY*/ BUFNUM(4,9) /* 4 - 4096 BUFFERS ALWAYS AND ALLOW UP TO 9 BEFORE SUSPENDING A USER FOR BUFFER SHORTAGE*/ MAXDORM(3000) /* WRITE AN IDLE BUFFER AFTER 30 MIN*/ STATUS(010000) /* WRITE SMF STATS AFTER 1 HOUR*/ JWT(0300) /* 522 AFTER 60 MINUTES*/ SID(XExx) /* SYSTEM ID*/ MEMLIMIT(4G) /* 64 BIT STORAGE */ SYS(TYPE(0:255),EXITS(IEFU83,IEFU84,IEFACTRT,IEFUJV, IEFUSI,IEFUJI,IEFUTL,IEFU29),NOINTERVAL,NODETAIL)
TSSFAR JCL
Use the following sample JCL to run TSSFAR:
//TSSFAR JOB USER=msca,CLASS=A //FAR EXEC PGM=TSSFAR //SECFILE DD DSN=top.secret.backup.file,DISP=SHR // //SYSPRINT DD SYSOUT=* //INPUT DD * KEY=ENCRYPTION KEY HEADER ARLBMAP ALLOC ACIDCHAN ACIDLINK RESINDEX ACIDRES RESOURCE SFSTATS WHOHAS (resource owning ACID) /*
TSSFAR Control Statements
The following selection criteria are used in generating TSSFAR reports:
  • KEY
    (Required) Specifies the customer encryption key in 16-byte hexadecimal or 8 EBCDIC characters:
    KEY=hhhhhhhhhhhhhhhh|'cccccccc'
  • ARLBMAP
    (Optional) Prints the ARLB allocation map from the header record.
  • ALLOC
    (Optional) Prints a cross-reference of all mismatches between ARLB block keys and the actual ARLBs in the block. ALLOC also verifies the number of ARLBs against what is in the header block map. Exceptions exist if an ARLB is chained and the first byte was used to add an x'00' to the end of an extension element in the ACID record. This setup makes the key appear to be wrong because the key is allocated but the ARLB is empty. These exceptions are resolved by using the ACIDCHAN function.
  • ACIDCHAN
    (Optional) Analyzes ARLB logical record chains and reports empty chains. ACIDCHAN performs the following activities:
    • Runs the ALLOC function.
    • Reads all ARLB logical records that are connected (chained) to the first ARLB for each ACID.
    • Verifies that the actual number of ARLBs in the chain match what the ACID listed in its File Accessorid Record (FACTREC).
    • Lists any ARLBs that are chained but empty. If this number of empty ALRBs matches the number of ARLBs that the ALLOC function reported as key errors, the allocation maps are correct.
    There is a discrepancy of 12 in the total number of ACIDs reported in your system by TSSFAR compared to a TSS LIST command. This discrepancy is due to TSSFAR having eight user ACIDs that are reserved and four department ACIDs that are dynamically built.
  • ACIDLINK
    (Optional) Reviews all ACIDs for connections to other ACIDs. If a connection exists, ACIDLINK verifies whether the connection should exist. If an ACID shows a profile attached, ACIDLINK verifies that the profile reflects the same information.
  • ACIDSIZE[(
    nnn
    )]
    (Optional) Reviews all ACIDs and reports any ACID whose record size reaches a certain percentage of the maximum allowed size.
    • nnn
      Specifies a percentage of maximum allowed size. When the ACID record size reaches this threshold, notification occurs. If a value is not specified, the default value is 80 (80%).
  • HEADER
    (Optional) Prints the first 256 bytes of the header record.
  • RESINDEX
    (Optional) Verifies that all resource ownership indexes match the owning ACID.
  • ACIDRES
    (Optional) Verifies that all resources claiming to be owned by an ACID have a correct matching owning ACID in the resource index.
  • RESOURCE
    (Optional) Verifies that the following conditions exist:
    • All permits have associated WHOHAS entries on the owning ACID.
    • All WHOHAS information on the owning ACID has a corresponding permit.
    When you run this utility, CA Top Secret might respond with messages identifying permit, owner, or resource issues, because multiple reference pointers might not be up-to-date. These messages include as much information as is available in the security file.
    Example: Reference Pointer Issues
    In this example, you permitted resources to users. Each PERMIT action creates reference pointers that allow the permitted ACID and owning ACID point to each other. However, when you ran the TSSFAR job, the following problems occurred:
    • An owning ACID has “no record of a PERMIT,” meaning the owner is missing the pointer to the permitted ACID.
    • A PERMIT “does not exist” on a permitted ACID, meaning that despite the owning ACID having a pointer to the permitted ACID, the PERMIT is not on the ACID.
    The following message is another type of sample message that might result:
    Permit is not owned ACID holding permit: userid1 Owning ACID: userid2 Resclass: DATASET Resname: USER.DATASET.ONE
    If the list includes discrepancies, you can perform the applicable CA Top Secret administration to correct each instance by revoking and repermitting the authorizations. If the TSSFAR utility flags too many discrepancies to fix through manual CA Top Secret administration, you can run the TSSXTEND utility with the WHOHAS option.
  • SFSTATS
    (Optional) Searches the security file and prints statistics for the following conditions:
    • ACID index entries allocated
    • ACID index entries defined
    • Next available ACID number
    • Last available ACID number
    • ACID blocks allocated
    • ACID blocks used
    • Volume entries allocated
      % Used % Deleted
    • PIE blocks allocated
      % Used % Deleted
    • RES blocks allocated
      % Used % Deleted
    • SDT blocks allocated
      % Used
    • *XREF* ACIDs present/not present
    • Features available on the SECFILE:
      • Large ACID support -- YES/NO
      • Large ORG ACID support -- YES/NO
      • RDT2BYTE support -- YES/NO
      • New password support -- YES/NO
      • SDT in VSAM support -- YES/NO
      • DIGICERTS in VSAM support -- YES/NO
      • AES encryption -- YES/NO
      • Large VSAM records -- YES/NO
    • Version of the SECFILE --
      x.x
    • CA Top Secret version when SECFILE was created --
      xx.x
    • Recommended TSS cache size
    • Recommended XES structure size
    • Active ACID count Average size
      xxxxxxx
      bytes
    • Number of SCAs
    • Number of LSCAs
    • Number of ZONEs
    • Number of ZCAs
    • Number of DIVs
    • Number of VCAs
    • Number of DEPTs
    • Number of DCAs
    • Number of USERs
    • Number of PROFs
    • Number of GROUPs
  • WHOHAS(
    resource-owning ACID
    )
    (Optional) Lists all ACIDs that hold a permit to resources that are owned by the specified ACID. CA Top Secret permits only one WHOHAS control statement per run.
    • resource-owning ACID
      Specifies an ACID that owns resources.