The ADFs are the Agent parameter file with the suffix .gap (commonly referred to as the ``GAP file'') and the properties file with the suffix .properties.
The parameter (.gap) file defines the parameters to be displayed in the administrative interface of the Keon Security Server 5.0, which is called the Keon Security Server Management Console (MC). This file also defines how the parameters are to behave and how the User Access Rights (UARs) are stored in the database.
The properties file defines the names of the fields in the MC. This document primarily discusses the parameter file format but a description of the properties files is also given.
The GAP file consists of three sections, where each section defines a set of parameters. Each section name is specified inside square brackets ([]). For example
[GAP] <parameter1>:"<string>"
[INFO] <parameter2>:"<string>" <parameter3>:"<string>" ...
[EARVAR] <parameter4>:<attribute1>=<value1>,...,<attributeN>=<valueN> <parameter5>:<attribute1>=<value1>,...,<attributeN>=<valueN> ...
For example, ``myagent-1.0'' should have files called ``myagent-1_0.gap'' and ``myagent-1_0.properties''.
parameter:"<string>"
parameter:<attribute1>=<value1>,...,<attributeN>=<valueN>
The parameter formats contain four different delimiters:
.gap
. RSA Security recommends that you name the file <Service>-<Version>.gap, with every dot '.' character in the Version parameter replaced by an
underscore '_' character.
For example, for Service:``oramts'' and Version:``1.0'', the GAP file could
be called oramts-1_0.gap
.
The GAP file is a UTF-8 coded text file. The file should be edited with an editor capable of handling UTF-8 coding, which means that most editors can be used provided US-ASCII is used.
The sequence of parameter lines within a section is not significant.
Each line ends with LF
or CRLF
.
Blank lines are ignored.
Each comment line begins with a hash '#' character in the first character position of the line.
In order to use special characters in text and strings an escape character is used. This character is set to '\'. Escaping of characters can only be done in string values (text enclosed within quotes).
A line can be split into two or more lines. By adding any of the following combinations, the rest of the line can continue on the next row:
'\''LF' '\''CR''LF'
The original line is still interpreted as a single line. The second line can start with 'SPACE' and/or 'TAB'. When concatenating lines into the original line, 'SPACE' and 'TAB' are ignored until another character is found.
Section names, parameter names, and attribute names are case sensitive since UAR data is case sensitive.
[INFO]
section:
Service:"<Agent Service name>" Version:"<Agent Version>" Description:"<Agent Description>"
The Service string should be set to the Agent service name and should consist only of
ASCII values (decimal) 48 - 57 [0-9], 65 - 90 [A-Z], 97 - 122 [a-z] and 95
[_]. If the product is a Beta release, the Service
string should have the format Service:"<service>-Beta"
.
The Version string should be set to the version of the first Agent that uses the
definitions in this file, and should consist of digits separated by dots,
for example, Version:"1.0"
. Subsequent Agent versions should continue to use the same version number
in the GAP file provided the format of the GAP data does not change.
The Description string is used to describe the Agent and should consist only of printable UTF-8 coded characters. The string should also specify the company product version, that is
<product> v <major>.<minor>.<patch> <type>
For example:
Description:"RSA Keon Agent for Oracle/MTS. Oracle/MTS v 1.0.
Each parameter should have seven attributes: SEQ, MAXLEN, MINLEN, CHECK TYPE, VIEW, and DEFVAL. All attributes are mandatory for each parameter.
The sequence of the attributes for a parameter is not significant.
The attributes have the following types and values:
Keyword values are descriptive directives, for example, HIDDEN or ECHO.
The SEQ attribute designates the order in which labels are to be displayed in the generic UAR administration panel of the MC. The SEQ values must range from 1 to N, where N is the number of attribute parameters. If any value in the range is omitted, this is regarded as an error.
The MAXLEN attribute designates the maximum length of the UAR variable. If MAXLEN=0, no length limit exists and no check for length will be performed by the MC.
The MINLEN designates the minimum length of the UAR variable. MINLEN must contain a value less than or equal to MAXLEN except when MAXLEN=0.
The CHECK attribute is used to define if a type check is to be carried out on the value of the UAR variable. When a user enters data in the UAR administration panel of the MC, a check is carried out to determine if the value entered is the correct type. INT, GRAPH, PRINTABLE and NONE are defined as follows:
The DEFVAL attribute contains the default value for each UAR variable. The value can
be an integer or a string within quotes. The specified value of the DEFVAL attribute must match the value of the CHECK attribute, for example, if CHECK=INT
, the DEFVAL value should be an integer.
The VIEW attribute controls how data in the MC should be displayed. If the value is ECHO
, the value should be echoed on the editing panel unchanged. For VIEW=PASSWORD
, the variable should be regarded as a password with asterisks ('*') echoed
for the characters typed. For VIEW=HIDDEN
, the UAR variable should not be displayed in the MC.
When an UAR variable is to be created in the MC, its value should be pre-filled with the value of the DEFVAL attribute.
The file format is one parameter on each line, with the parameter followed by an equals sign ('=') and the string to be displayed. Lines starting with a hash ('#') character are ignored.
The valid parameters are GIVENUSER
, GIVENPSW
, GIVENDBID
,
DBUSER
, DBPSW
, and DBID
# -------------------------------- # # Example GAP file myagent-1_0.gap # # --------------------------------
[GAP]
GAP-Version:"1.0"
[INFO]
Service:"myagent" Version:"1.0" Description:"My first Agent v1.0."
[EARVAR]
GIVENUSER:SEQ=1,MAXLEN=15,MINLEN=1,CHECK=PRINTABLE,TYPE=CLEAR,\ VIEW=ECHO,DEFVAL="*" DBUSER:SEQ=2,MAXLEN=15,MINLEN=1,CHECK=GRAPH,TYPE=CLEAR,\ VIEW=ECHO,DEFVAL="*" DBPSW:SEQ=3,MAXLEN=15,MINLEN=1,CHECK=GRAPH,TYPE=AUTH_DATA,\ VIEW=PASSWORD,DEFVAL="*"
# Needed but not shown (VIEW=HIDDEN) GIVENPSW:SEQ=4,MAXLEN=0,MINLEN=0,CHECK=NONE,TYPE=CLEAR,\ VIEW=HIDDEN,DEFVAL="*" GIVENDBID:SEQ=5,MAXLEN=0,MINLEN=0,CHECK=NONE,TYPE=CLEAR,\ VIEW=HIDDEN,DEFVAL="*" DBID:SEQ=6,MAXLEN=0,MINLEN=0,CHECK=NONE,TYPE=CLEAR,\ VIEW=HIDDEN,DEFVAL="*"
The following is an example of a properties corresponding to the preceding parameter file. Only three fields need to be defined since the parameter file defines three fields to be shown in the MC.
# ---------------------------------------------- # # Example PROPERTIES file myagent-1_0.properties # # ----------------------------------------------
GIVENUSER=Selected Username DBPSW=Application Password DBUSER=Application Username