HP OpenVMS Systems Documentation

HP OpenVMS System Services Reference Manual

On a given OpenVMS system, multiple authentication policies may be applicable. The system may be configured to augment the native (local OpenVMS) policy with alternatives pertaining to external environments, such as LAN Manager. Each policy, together with the operating environment to which it pertains, constitutes a domain of interpretation. Within a given domain, any entity, such as a user, that is subject to the applicable authentication policy, is referred to as a principal.

The $ACM service can be used to authenticate a principal, initiate a password change request on behalf of a principal, query information about a particular domain, or report event data within a particular domain.

The $ACM service completes asynchronously; that is, it returns to the caller after queuing the request, without waiting for the operation to complete.

To synchronize completion of an operation, use the Authentication and Credential Management and Wait ($ACMW) service. The $ACMW service is identical to $ACM in every way except that $ACMW returns to the caller after the operation has completed.

Modes of Operation

The typical authentication policy employs the traditional reusable password; however, various alternative mechanisms exist for forming stronger policies. Some of these mechanisms, such as challenge-response, require interaction. The $ACM service is designed to accommodate these mechanisms.

The authentication and change_password functions are capable of operating in a dialogue (iterative) mode to support different types of interactive authentication mechanisms. The query, event, and free_context functions only support the nondialogue (noniterative) mode of operation.

Nondialogue (Noniterative) Mode

The default nature of the $ACM service is to operate in a noniterative mode. All information needed to complete the request must be provided in a single call; otherwise, the request ultimately fails. This requires the caller to know beforehand what information is required to complete the request.

The following list summarizes the control flow for a typical nondialogue mode authentication request. For simplicity, the scenario assumes a single domain of interpretation with a traditional user name and password policy. Also, error processing is ignored.

1. The caller of $ACM prompts the user for the principal name and password, builds an item list specifying the principal name and password, and then calls $ACM specifying the authenticate principal function, the item list with the principal name and password, and a zero address for the context argument.
2. $ACM processes the request and ultimately returns control to the caller with the final status for the operation.

Dialogue (Iterative) Mode

The caller can use the interactive capabilities of the $ACM service for authentication and password change operations by specifying the ACME$_DIALOGUE_SUPPORT item code and a valid context argument. In this mode, ACME agents can request additional information from the caller to complete the request. In effect, the $ACM service is called in an iterative fashion until all information required to complete the request has been provided. The sequence of calls are linked together by passing the context argument returned in one call back in the next call.

In this scenario, when an ACME agent requires additional information, it builds an item set that describes the nature of the information. The item set is passed back to the caller in the communications buffer (see the description for the context argument regarding the format of the communications buffer) and the service returns with the ACME$_OPINCOMPL status. The caller processes each item set entry, gathers the requested information, and then passes it back to the ACME agent using the itmlst argument in the next call. The sequence continues until the call returns with a status code other than ACME$_OPINCOMPL.

The following list summarizes the control flow for a typical dialogue-mode authentication sequence. For simplicity, the scenario assumes a single domain of interpretation with a traditional user name and password policy. Also, error processing is ignored.

1. Make an initial call to $ACM specifying the authenticate principal function code, an item list that merely contains the ACME$_DIALOGUE_SUPPORT item code, and a context argument that has been initialized to -1.
2. $ACM builds a communications buffer containing an item set in the buffer requesting the principal name (user name), sets the context argument to reference the buffer, and returns control to the caller with a status code of ACME$_OPINCOMPL.
3. The caller processes the item set, prompts for the principal name, builds an item list specifying the principal name, and then calls $ACM again specifying the authenticate principal function as before, the item list with the principal name, and a context argument that contains the buffer address returned in the previous call.
4. $ACM validates the context argument, processes the username then builds another communications buffer to contain an item set list requesting the password, sets the context argument to reference the buffer, and returns control to the caller again with a status code of ACME$_OPINCOMPL.
5. The caller processes the item set, prompts for the password, builds an item list specifying the password, and then calls $ACM again specifying the authenticate principal functions as before, the item list with the password, and a context argument that contains the buffer address returned in the previous call.
6. $ACM validates the context argument again, clears it, and then completes the processing of the request, now that it has all the necessary information, and ultimately returns control to the caller with the final status for the operation.

Unprivileged callers (those running in user mode and not possessing SECURITY privilege) are limited by the number of iterative requests they can make in a dialogue sequence of calls. The default is set at 26 dialogue requests. The default can be overridden by defining the exec mode logical name ACME$DIALOGUE_ITERATIVE_LIMIT in the LNM$SYSTEM_TABLE logical name table. Valid values are 1 through 100.

Determining an ACME Name Based on an ACME ID

The identity of the ACME that supplied the ACME$L_ACME_STATUS contents is indicated in the ACMEID$V_ACME_NUM subfield of the ACMESB$L_ACME_ID field. This value is consistent for the duration of one boot of the system, but may have a different value on the next boot. The name of a particular ACME agent can be determined from the ACME ID by calling $ACM with function code ACME$_FC_QUERY and the following item list entries:

• Special ACM Dispatch query---ID value zero:

  ITMCOD = ACME$_TARGET_DOI_ID
  BUFSIZ = 4
  BUFADR = Address of longword containing 0

• Query ACME name based on ACME ID:

  ITMCOD = ACME$_QUERY_KEY_TYPE
  BUFSIZ = 4
  BUFADR = Address of longword containing ACME$K_QUERY_ACME_ID

• Specify ACME ID value:

  ITMCOD = ACME$_QUERY_KEY_VALUE
  BUFSIZ = 4
  BUFADR = Address of longword containing the ACME_ID

• Specify ACME name for the return value:

  ITMCOD = ACME$_QUERY_TYPE
  BUFSIZ = 4
  BUFADR = Address of longword containing ACME$K_QUERY_ACME_NAME

• Specify the output buffer:

  ITMCOD = ACME$_QUERY_DATA
  BUFSIZ = ACME$K_MAXCHAR_DOI_NAME or (ACME$K_MAXCHAR_DOI_NAME*4) depending on whether function modifier ACME$M_UCS2_4 has been specified
  BUFADR = Address of buffer large enough to hold ACME$K_MAXCHAR_DOI_NAME bytes or (ACME$K_MAXCHAR_DOI_NAME*4) depending on whether function modifier ACME$M_UCS2_4 has been specified

Privileges and Restrictions

The $ACM service constitutes a trusted interface. It restricts operations that override the security policy applicable to a given domain of interpretation to those callers who are suitably privileged. The status returned in the ACMESB$L_STATUS field of the ACM Status Block for a failed authentication operation is typically nonspecific, so as not to reveal sensitive information to untrusted callers.

If the caller has the SECURITY privilege, the ACMESB$L_SECONDARY_STATUS field of the ACM Status Block may contain a detailed status that more accurately reflects the actual nature of the failure.

To specify the following function modifiers, the caller must have the SECURITY privilege:

ACME$M_NOAUDIT
ACME$M_NOAUTHORIZATION
ACME$M_FOREIGN_POLICY_HINTS

To specify the following function modifier, the caller must have the IMPERSONATE privilege:

ACME$M_OVERRIDE_MAPPING

To specify the following item code, the caller must have the SECURITY privilege:

ACME$_NEW_PASSWORD_SYSTEM

To specify the following item codes, the caller must have the IMPERSONATE privilege:

ACME$_ACCESS_PORT
ACME$_CHALLENGE_DATA
ACME$_REMOTE_HOST_ADDRESS
ACME$_REMOTE_HOST_ADDRESS_TYPE
ACME$_REMOTE_HOST_FULLNAME
ACME$_REMOTE_HOST_NAME
ACME$_REMOTE_USERNAME
ACME$_SERVICE_NAME

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list or an input buffer cannot be read in the access mode of the caller; or an output buffer, a return length buffer, or the I/O status block cannot be written in the access mode of the caller.
SS$_ARG_GTR_32_BITS	A 64-bit address was passed in a context requiring a 32-bit address.
SS$_BADBUFADR	The buffer address associated with an entry in the item list is inappropriate in the context of the call. The address may be invalid (for example, 0).
SS$_BADBUFLEN	The buffer length associated with an entry in the item list is inappropriate in the context of the call. The length may be invalid (for example, 0) or outside the range of acceptable values.
SS$_BADCHAIN	A chained item list is inaccessible, or the chain is circular.
SS$_BADCONTEXT	The context argument does not specify a valid context buffer.
SS$_BADITMCOD	A specified item code is invalid or out-of-range.
SS$_BADPARAM	The item list contains an invalid item code.
SS$_BADRETLEN	The return length address associated with an entry in the item list is inappropriate in the context of the call. The address may be invalid (for example, 0).
SS$_EXASTLM	The astadr argument was specified and the process has exceeded its ASTLM quota.
SS$_EXQUOTA	A process quota was exceeded.
SS$_ILLEFC	The efn argument specifies an illegal event flag number.
SS$_ILLMODIFIER	The func argument specifies function modifiers that are inappropriate in the context of the call.
SS$_INSFMEM	Insufficient space exists for completing the request.
SS$_IVTIME	An invalid value was specified for the ACME$_TIMEOUT_INTERVAL item code.
SS$_NOEXTAUTH	External authentication is not available.
SS$_NOPRIV	The caller does not have the necessary privileges to complete the requested operation.
SS$_TOOMUCHDATA	The request size exceeds $ACM messaging constraints.
SS$_UNASEFC	The efn argument specifies an unassociated event flag cluster.
SS$_UNSUPPORTED	The func argument specifies an unsupported function.

Condition Values Returned in the ACM Status Block

ACME$_NORMAL	The service completed successfully.
ACME$_ACCOUNTLOCK	The account associated with specified principal name is disabled.
ACME$_AUTHFAILURE	Authorization failed.
ACME$_BUFFEROVF	An output item returned by the service is larger than the user buffer provided to receive the item; the item is truncated.
ACME$_DOIUNAVAILABLE	The specified domain of interpretation is not processing requests.
ACME$_INCONSTATE	The ACME server detected an internal consistency error.
ACME$_INSFDIALSUPPORT	Caller dialogue capabilities specified with the ACME$DIALOGUE_SUPPORT item code are inadequate to meet the needs of one or more ACME agents.
ACME$_INTRUDER	A record matching the request was found in the intrusion database.
ACME$_INVALIDCTX	The context argument is not consistent with the itmlst argument.
ACME$_INVALIDPWD	The specified password is invalid.
ACME$_INVITMSEQ	The service encountered a query type or query key item code without a corresponding query data or query key value item code.
ACME$_INVMAPPING	The OpenVMS user name to which the principal name was mapped is invalid.
ACME$_INVNEWPWD	The new password provided during a change password request does not pass qualification checks.
ACME$_INVPERSONA	The persona handle specified by the itmlst argument is invalid.
ACME$_INVREQUEST	A parameter is invalid in the context of the request. This error code is returned when the caller either defaults or specifies ACME$_BATCH or the value zero (0) for ACME$_LOGON_TYPE.
ACME$_MAPCONFLICT	An attempt was made to merge credentials for a principal name, which maps to an OpenVMS user name that differs from the one associated with existing credentials.
ACME$_NOACMECTX	The service encountered an ACME-specific item code when no ACME context had been established.
ACME$_NOCREDENTIALS	The ACME agent did not issue any credentials.
ACME$_NOEXTAUTH	The specified principal name cannot be authenticated externally.
ACME$_NOPRIV	The caller does not have the necessary privileges to complete the requested operation.
ACME$_NOSUCHDOI	The specified domain of interpretation does not exist.
ACME$_NOSUCHUSER	The specified principal name does not exist.
ACME$_NOTARGETCRED	The persona does not contain credentials for the specified domain of interpretation.
ACME$_NOTAUTHORIZED	Authorization failed due to account restrictions.
ACME$_OPINCOMPL	Interaction is required to complete the request. The context buffer contains information describing how to proceed.
ACME$_PWDEXPIRED	The password provided during an authentication request has expired and a new password is required to complete the request.
ACME$_TIMEOUT	The server did not respond within the designated time-out interval.
ACME$_UNSUPPORTED	The requested operation or an item code is not supported with the selected domain of interpretation.

Table SYS-13 lists status codes and their function codes:

<> ---Permitted

VMS ACME Use of Function Codes The VMS ACME use of the Event function is reserved to HP.

The VMS ACME does not support the Query function. VMS ACME-Specific Item Codes This section describes the $ACM item codes that are ACME-specific for the VMS ACME.

Table SYS-14 indicates which OpenVMS ACME-specific Item Codes are applicable to the various Function Codes:

<> ---Permitted
IR---IMPERSONATE Privilege Required to override default values
SR---SECURITY Privilege Required
O---Output item code
U---Subject to Unicode Conversion
BC---Backward Compatibility---Reserved for HP support of historical interface