NAME

ADF - Agent Definition Files format

DESCRIPTION

Agent Definition Files (ADFs) are Agent-specific files that must be installed on the Keon Security Server to allow for the administration of the Agent.

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>
    ...

File Naming

The .gap and .properties files should be named with the service name and version of the Agent, with underscore ('_') characters instead of dots ('.').

For example, ``myagent-1.0'' should have files called ``myagent-1_0.gap'' and ``myagent-1_0.properties''.

Parameter Formats

There are two different types of parameters, string parameters and attribute parameters.

    parameter:"<string>"

    parameter:<attribute1>=<value1>,...,<attributeN>=<valueN>

The parameter formats contain four different delimiters:

: (colon)
This follows a parameter name.

, (comma)
This is used to separate attribute values from each other.

= (equals)
This is used to set an attribute value/keyword.

" (quote)
This is used to start and end a string. This delimiter is used only in the string value of string parameters and for the DEFVAL value in attribute parameters. See EXAMPLES.

To make the GAP files more maintainable, you can also add a Newline after the colon (:) that follows the parameter name, as well as after the comma (,) that follows the attribute value. See EXAMPLES.

Miscellaneous

The GAP file should have the extension .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.

The GAP Section

The GAP section contains only one parameter. This parameter is named GAP-Version and the value should be set to the version of the GAP file. The value should consist of digits, separated by dots, for example GAP-Version:``1.0''.

The INFO Section

The following parameters should be defined in the [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.

The EARVAR Section

The parameters corresponding to the UAR variables for the Agent are defined in the EARVAR section. This section contains only attribute parameters.

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:

SEQ
Integer.

MAXLEN
Integer.

MINLEN
Integer.

CHECK
Keyword INT, GRAPH, PRINTABLE, or NONE.

TYPE
Keyword AUTH_DATA or CLEAR.

DEFVAL
Integer or String within quotes.

VIEW
Keyword ECHO, PASSWORD, or HIDDEN.

Integer values are represented by numerics '0' to '9'.

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:

INT
[0-9] (ASCII values 48 - 57)

GRAPH
[!-~] (ASCII values 33 - 126)

PRINTABLE
[all printable characters] (UTF-8)

NONE
No type check.

The TYPE attribute controls whether the value entered is to be protected (encrypted) or sent as clear text in the PAC.

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 Properties File

The properties file is needed only to define the strings shown for the different Agent parameters (as defined by the parameter file) in the MC.

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

EXAMPLES

The following is an example of a parameter file:

  # --------------------------------
  #
  # 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

SEE ALSO

cat