Administering Security Data

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus Customer Care if you require further clarification.

The security data used by the VSAM ESM Module is kept in a set of COBOL VSAM (.dat) files, referred to as the VSAM ESM file directory. These files can be created and updated using the mfsecconv utility, which can convert between data specified in a YAML file and the VSAM ESM file directory. YAML is a data serialization language typically used for configuration files which can be created and maintained using a text editor.

The COBOL VSAM files in the VSAM ESM file directory can also be edited using the Data File Editor. See Data File Editor for more information.

An example YAML file is provided with the product, es_default_security.yaml, which is located at %ProgramFiles(x86)%\Micro Focus\Visual COBOL\etc (Windows) or $COBDIR/etc/vsam_esm (UNIX). [4]

The YAML syntax used with mfsecconv is as follows:

Users:
  - User:
    UserId: ""  #Attribute type: String
    AltId: "" #Attribute type: String
    AllowLogon: True #Attribute type: Boolean
    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String
    DefaultGroup: "" #Attribute type: String
    CreateToken: "" #Attribute type: String
    UseToken: "" #Attribute type: String
    LastLoginTime: "" #Attribute type: String, format ISO8601
    ExpirationDate: "" #Attribute type: String, format ISO8601
    LoginAttempts: 0 #Attribute type: Integer
    Audit: True #Attribute type: Boolean
    MTOs:
      Priority: 0 #Attribute type: Integer
      Timeout: 0 #Attribute type: Integer
      OperatorClass: 0 #Attribute type: Integer
      OperatorID: "" #Attribute type: String
      GroupPrefix: "" #Attribute type: String
    Password:
      - Verifier: "" #Attribute type: String in the format "<verifier type>:<verifier>" e.g. "literal:a_strong_password"
      - MustChange: True #Attribute type: Boolean
      - ExpirationDate: "" #Attribute type: String, format ISO8601
      - History: # A sequence of Attribute type: String
        # conforming to the following format "<ISO8601 date/time>:<verifier type>:<verifier> e.g.:"
        - "20220811T164639Z:literal:an_old_password"

UserGroups:
  - UserGroup:
    GroupId: "" #Attribute type: String
    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String
    Member: # A sequence of Attribute type: String, where each entity is a member of this user group
      - "SYSAD" #Meaning the SYSAD user is a member of this user group
      - "#DSAdmin Group" #The " group" suffix indicates "#DSAdmin" is a user group, whose members are also members of this group.
    Audit: True #Attribute type: Boolean

ResourceClass:
  - ResourceClass:
    ResourceClassId: "" #Attribute type: String
    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String

ResourceRules:
  - ResourceRule:
    RuleID : "" #Attribute type: String
    ResourceClassId: "" #Attribute type: String
    ACEs: #A sequence of Attribute type: String representing this rule's Access Control Entries
    # in the format: "<access type>:<actor>:<permission level>" e.g.
      - "allow:ALLUSER group:read" # the " group" suffix indicates ALLUSER is a group and allows all it's members to read.
      - "deny:SYSAD:execute"  #Denies the user SYSAD from executing.
      - "deny:*:write" # denies all actors(both users and groups) from writing.

    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String
    Audit: True #Attribute type: Boolean

You can run mfsecconv as an import or export function and with the flags described below.

Syntax:

mfsecconv import <source yaml file path> <destination vsam esm file directory> [--Flags]

mfsecconv export <source vsam directory> <output yaml directory> [--Flags]

Functions:

import: Imports a file.
export: Exports an existing ESM directory to a YAML file.

Parameters:

-a|-A|--append: Adds new security information.
-h|-H|--help: Displays the command help.
-t|-T|--truncate: Creates the ESM data if it does not exist, this will delete existing ESM data.
-u|-U|--update: Changes existing ESM data.
-l|-L|--loglevel=VALUE: Set custom log level from 0 to 4, where 4 is the greatest severity.

Examples:

The following example adds only new security information specified in the YAML file to the specified VSAM ESM file directory. Existing information in the VSAM ESM file directory is not changed:

mfsecconv import c:\source.yaml c:\destination --append

The following example updates existing security information in the specified VSAM ESM file directory from the specified YAML file. New information in the YAML file is not added to the VSAM ESM file directory:

mfsecconv import c:\source.yaml c:\destination --update

The following example imports a file to the specified VSAM ESM file directory destination while creating the ESM data specified in the YAML file, if it does not exist:

Note: This can potentially delete existing ESM data.

mfsecconv import c:\source.yaml c:\destination -t

The following example exports a file from the specified VSAM ESM file directory using the specified YAML file and sets the custom log level to 3:

mfsecconv export c:\vsam c:\desktop\output_vsam_esm.yaml --loglevel=3

The exported VSAM ESM file directory directory structure will be similar to the following structure:

X:/sample_esm_file_dir
|---Users.dat
|---PasswordHistories.dat
|---Groups.dat
|---Memberships.dat
|---Classes.dat
|---ACICSPCT # A resource class name
|---|---ACEs.dat
|---|---Rules.dat
|---CCICSCMD # Another resource class name
|---|---ACEs.dat
|---|---Rules.dat