Parameters

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1.

rule_array

Direction:	Input
Type:	String array

The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords are described in Table 1.

Table 1. Keywords for Access Control Maintenance control information

Keywords for Access Control Maintenance control information

Keyword	Description
Service to perform (one required)
LSTROLES	Retrieves a list of the roles installed in the coprocessor.
GET-ROLE	Retrieves the non-secret part of a role definition from the coprocessor.

name

Direction:	Input
Type:	String

The name parameter is a pointer to a string variable containing the name of a role or user profile which is the target of the request.

The manner in which this variable is used depends on the service being performed.

Table 2. Meaning of the name parameter

Meaning of the name parameter

Rule-array keyword	Contents of name parameter
LSTROLES	The name parameter is unused.
GET-ROLE	The name parameter contains the 8-character role ID for the role definition that is to be retrieved or deleted. A role ID cannot start with a space character.

output_data_length

Direction:	Input/Output
Type:	Integer

The output_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the output_data variable. The value must be a multiple of four bytes.

On input, the output_data_length parameter must be set to the total size of the variable pointed to by the output_data parameter. On output, this variable contains the number of bytes of data returned by the verb in the output_data variable.

output_data

Direction:	Output
Type:	String

The output_data parameter is a pointer to a string variable containing data returned by the verb. Any integer value returned in the output_data variable is in big-endian format; the high-order byte of the value is in the lowest-numbered address in storage. Authentication data structures are described in Access control data structures.

The manner in which this variable is used depends on the function being performed.

Table 3. Meaning of the output_data parameter

Meaning of the output_data parameter

Rule-array keyword	Contents of output_data parameter
LSTROLES	Contains a list of the role IDs for all the roles stored in the coprocessor.
GET-ROLE	The variable contains the non-secret portion of the selected role. This includes the following data, in the order listed. Role version Two bytes containing 2 one-byte integer values, where the first byte contains the major version number and the second byte contains the minor version number. Comment A 20-character variable padded on the right with spaces, containing a comment which describes the role. This variable is not X'00' terminated. Required authentication-strength level A 2-byte integer defining how secure the user authentication must be in order to authorize this role. Lower time-limit The earliest time of day that this role can be used. The time limit consists of two 1-byte integer values, a 1-byte hour, followed by a 1-byte minute. The hour can range from 0 - 23, and the minute can range from 0 - 59. Upper time-limit The latest time of day that this role can be used. The format is the same as the Lower time-limit. Valid days of the week A 1-byte variable defining which days of the week this role can be used. Seven bits of the byte are used to represent Sunday through Saturday, where a 1 bit means that the day is allowed, while a 0 bit means it is not. The first bit (most significant bit, MSB) is for Sunday, and the last significant bit (LSB) is unused and is set to B'0'. Access-control-point list The access-control-point bit map defines which functions a user with this role is permitted to run.