HP OpenVMS System Services Reference Manual
Previous Contents Index

$ACM

The $ACM service provides a common interface to all functions supported by the Authentication and Credential Management (ACM) authority.

The caller must specify the function code and any applicable function modifiers and item codes for the requested operation.

The $ACM service completes asynchronously; for synchronous completion, use the $ACMW form of the service.

Format

SYS$ACM [efn], func, [context], itmlst, acmsb, [astadr], [astprm]

C Prototype

int sys$acm (unsigned int efn, unsigned int func, struct _acmecb **context, void *itmlst, struct _acmesb *acmsb, void (*astadr)(__unknown_params), int astprm);

Arguments

efn


OpenVMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value

Number of the event flag that is set when the $ACM request completes. The efn argument is a longword containing this number; however, $ACM uses only the low-order byte.

When the request is queued, $ACM clears the specified event flag. Then, when the request completes, the specified event flag is set.

func


OpenVMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by value

Function code and modifiers specifying the operation that $ACM is to perform. The func argument is a longword containing the function code, logically 'OR'ed together with the modifiers. For some programming languages this may be defined as a record structure.

Function codes have symbolic names of the following format:

ACME$_FC_code

Function modifiers have symbolic names of the following format:

ACME$M_modifier

The language support mechanisms specific to each programming language define the names of each function code and modifier. Only one function code can be specified across a dialogue sequence of related calls to $ACM.

Most function codes require or allow additional information to be passed in the call. This information is passed using the itmlst argument, which specifies a list of one or more item descriptors. Each item descriptor in turn specifies an item code, which either controls the action to be performed, or requests specific information to be returned.

context


OpenVMS usage: context
type: longword pointer (signed)
access: modify
mechanism: by 32- or 64-bit reference

Address of a longword to receive the 32-bit address of an ACM communications buffer.

$ACM uses the ACM communications buffer for dialogue functions (ACME$_FC_AUTHENTICATE_PRINCIPAL and ACME$_FC_CHANGE_PASSWORD) to request that the caller provide additional information in a subsequent call.

The context argument on a continuation call must contain the same ACM communications buffer address returned by $ACM on the previous call. The itmlst provided on a continuation call must contain entries to fulfill each of the input item set entries in the ACM communications buffer returned by $ACM on the previous call.

The longword specified must contain a -1 on the first call in a dialogue sequence of related calls. If additional information is required to complete the request, $ACM returns a pointer in the context argument to an ACM communications buffer that describes the information. To continue with the particular operation call, $ACM again specifying the function argument previously provided.

The ACM communications buffer is user readable, but not user writable. It consists of a structure header, an item set, and a string buffer segment. The item set is an array of item set entries, each describing an item of information that is needed to complete the request or information that can be reported to a human user.

$ACM presents the item set entries in the logical presentation order for a sequential interface, so calling programs that give a sequential view to the user should process the item set entries in that $ACM order. More advanced GUI programs may use simultaneous presentation with distinctive placement for various message types.

The following diagram depicts the overall format of an ACM communications buffer:

ACM Communications Buffer

The following table defines the ACM communications buffer header fields:
Descriptor Field Definition
ACMECB$Q_CONTEXT_ID A quadword containing a value used internally by $ACM to uniquely bind the ACM communications buffer to the associated request across iterative calls.
ACMECB$W_SIZE A word containing the size of the ACM communications structure.
ACMECB$W_REVISION_LEVEL A word containing a value that identifies the revision level of the ACM communications structure.
ACMECB$L_ACME_ID A longword containing the agent ID of the ACME agent that initiated this dialogue sequence.
ACMECB$L_ITEM_SET_COUNT A longword containing the number of item set entries in the item set.
ACMECB$PS_ITEM_SET A longword containing the 32-bit address of the item set. The item set is an array of item set entries that describes the information needed by $ACM to complete the particular request.

The following diagram depicts the format of an item set entry:

The following table defines the item set entry fields:
Descriptor Field Definition
ACMEIS$L_FLAGS A longword containing a mask of flags that indicates the interpretation of the ACMEIS$Q_DATA_1 and ACMEIS$Q_DATA_2 quadword-sized 32-bit descriptors and the method for processing.

Each flag has a symbolic name that the language support mechanisms specific to each programming language define. The following list describes the flags:

  • ACMEDLOGFLG$V_INPUT
    When clear:
    • ACMEIS$W_MSG_TYPE contains the message type associated with this output data.
    • ACMEIS$Q_DATA_1 and ACMEIS$Q_DATA_2 are 32-bit descriptors that specify text to be displayed to the caller.

      An address of 0 in either descriptor indicates the calling program should ignore that descriptor.

      A length of 0 with a nonzero address in either descriptor indicates the calling program should report a separation indication to the user if that is appropriate for the type of human interface involved. A line mode command interface, for instance, will display a blank line.


    When set:
    • ACMEIS$W_ITEM_CODE defines the item code to use when providing the requested information.
    • ACMEIS$Q_DATA_1 is a 32-bit descriptor that specifies prompt text.

      An address of 0 indicates no prompt text. A length of 0 with a nonzero address is reserved for future definition.

    • Interpretation of ACMEIS$Q_DATA_2 is determined by the state of the ACMEDLOGFLG$V_NOECHO flag.
  • ACMEDLOGFLG$V_NOECHO
    When clear:
    • ACMEIS$Q_DATA_2 is a 32-bit descriptor that specifies the "default" answer that will be assumed by $ACM if the caller responds to this item set entry with an item specifying a length of zero. $ACM provides this "default" answer to the calling program to allow for distinctive display appropriate to the type of interface being supported. For example, traditional line-mode interfaces in VMS will include such a default answer within square brackets when prompting, while a character cell screen interface might pre-fill a field.

    When set:
    • The associated input data is not to be echoed. This is typically used to visually protect sensitive data, such as password information.
    • ACMEIS$Q_DATA_2 is a 32-bit descriptor that specifies secondary prompt text for input verification processing.

      An address of 0 indicates no verification processing. A length of 0 with a nonzero address is reserved for future definition.

    The flag ACMEDLOGFLG$V_NOECHO is ignored when ACMEDLOGFLG$V_INPUT is clear.

ACMEIS$W_ITEM_CODE A word containing the item code that identifies the nature of information associated with the item set. This field defines the item code to use when specifying the requested information in the itmlst argument in the subsequent call to $ACM. A sequence of item set entries containing the same item code reflects a linked list of related information. An item set with the ACMEDLOGFLG$V_INPUT flag set or a different item code indicates the end of the related list.
ACMEIS$W_MAX_LENGTH When ACMEDLOGFLG$V_INPUT is set:

A word containing the maximum length (in bytes) of any input data being requested by this item set. For example, the maximum length of a principal name string. A value of 0 indicates that the only item the calling program can return to satisfy the item set entry is an item specifying zero length. When the calling program returns such a zero length item, it thereby indicates confirmation, as might be indicated by a prompt such as "Indicate when you have read that text".

ACMEIS$W_MSG_TYPE When ACMEDLOGFLG$V_INPUT is clear:

A word containing a value that categorizes the output messages described by 32-bit descriptors ACMEIS$Q_DATA_1 and ACMEIS$Q_DATA_2.

The language support mechanisms specific to each programming language define the following symbols for the standard message categories:

ACMEMC$K_DIALOGUE_ALERT---Text related to the immediately preceding input operation. The calling program should bring this text to the attention of a user prior to handling the renewed input item set entry that typically follows. This message category is used, for example, to indicate that a new password the user has specified does not conform to local security policy.
ACM$K_GENERAL---General text.
ACM$K_HEADER---Text displayed before a succession of Selections.
ACMEMC$K_MAIL_NOTICES---Text related to mail operations, typically an indication that new mail is waiting.
ACMEMC$K_PASSWORD_NOTICES---Text indicating that password expiration is imminent.
ACM$K_TRAILER---Text displayed after a succession of Selections.
ACM$K_SELECTION---Acceptable choices for responding to the subsequent prompt.
ACM$K_SYSTEM_IDENTIFICATION---System identification text.
ACM$K_SYSTEM_NOTICES---Text displayed to a user before authentication.
ACM$K_WELCOME_NOTICES---Text displayed to a user after authentication.
ACM$K_LOGON_NOTICES---Logon and logfail statistics.

In addition to those standard message categories, individual ACME agents may define their own categories, but the meanings of those categories are useful only to callers of $ACM that are specifically recognized by the ACME agent in question, since those are the only callers of $ACM to which the ACME agent will deliver such ACME-specific categories. Documentation of the ACME-specific codes used by the VMS ACME is shown in the VMS ACME-specific Output Message Categories section of this description.

Documentation of ACME-specific codes in general comes in the documentation from the vendor of each ACME agent.

For documentation of ACME-specific codes for the VMS ACME, see the VMS ACME-specific Item Codes section of this description.

ACMEIS$Q_DATA_1 A quadword containing a 32-bit descriptor that describes information (prompt text or other data, as described under the prior entry for ACMEDLOGFLG$V_INPUT) applicable to determining an appropriate response.
ACMEIS$Q_DATA_2 A quadword containing a 32-bit descriptor that describes information (default answer, secondary prompt text or other data described under the prior entries for ACMEDLOGFLG$V_INPUT and ACMEDLOGFLG$V_NOECHO) applicable to determining an appropriate response.

itmlst


OpenVMS usage: 32-bit item_list_3 or 64-bit item_list_64b
type: longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit
access: read only
mechanism: by 32- or 64-bit reference

Item list specifying information to be used in performing the function and requesting information to be returned. The itmlst argument is the 32- or 64-bit address of a list of item descriptors, describing an item of information. An item list in 32-bit format is terminated by a longword of 0; an item list in 64-bit format is terminated by a quadword of 0.

The item list can be composed of up to 32 segments, connected by a chain item (using item code ACME$_CHAIN) at the end of all but the last segment pointing to the start of the next segment. All item descriptors in a single segment must be of the same format (32-bit or 64-bit), but a single item list can contain a mixture of segments composed of 32-bit item descriptors and segments composed of 64-bit item descriptors.

The following diagram depicts the 32-bit format of a single item descriptor:

The following table defines the item descriptor fields for 32-bit item list entries:
Descriptor Field Definition
Buffer length A word specifying the length of the buffer (in bytes); the buffer either supplies information to $ACM or receives information from $ACM. The required length of the buffer varies, depending on the item code specified, and is specified in the description of each item code.
Item code A word containing an item code, which identifies the nature of the information supplied to $ACM or which is received from $ACM. Each item code has a symbolic name; the language support mechanisms specific to each programming language define these symbolic names.
Buffer address A longword containing the 32-bit address of the buffer that specifies or receives the information.
Return length address A longword containing the 32-bit address of a word to receive the length (in bytes) of information returned by $ACM. If specified as 0, no length is returned. For input items the return length address is ignored.

The following diagram depicts the 64-bit format of a single item descriptor:

The following table defines the item descriptor fields for 64-bit item list entries:
Descriptor Field Definition
MBO A word that must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.
Item code A word containing an item code, which identifies the nature of the information supplied to $ACM or that is received from $ACM.

Common item codes have symbolic names (beginning with the characters "ACME$_") defined by the language support mechanisms specific to each programming language. Individual ACME agents may also define additional item codes specific to the functions of those ACME agents.

MBMO A longword that must contain a -1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.
Buffer length A quadword specifying the length of the buffer (in bytes); the buffer either supplies information to $ACM or receives information from $ACM. The required length of the buffer varies, depending on the item code, and is specified in the description of each item code.
Buffer address A quadword containing the 64-bit address of the buffer that specifies or receives the information.
Return length address A quadword containing the 64-bit address of a quadword to receive the length (in bytes) of information returned by $ACM. If specified as 0, no length is returned. For input items the return length address is ignored.

In an item list, no ACME-specific item codes can be included in an item list until the ACME Context has been set with one of the following codes:

ACME$_CONTEXT_ACME_ID
ACME$_CONTEXT_ACME_NAME

You can also implicitly set the ACME Context with one of the following codes:

ACME$_TARGET_DOI_ID
ACME$_TARGET_DOI_NAME

These codes are described in the HP OpenVMS Programming Concepts Manual.

acmsb


OpenVMS usage: acm_status_block
type: octaword array of 4 longwords
access: write only
mechanism: by 32- or 64-bit reference

ACM status block that is to receive the final completion status. The acmsb argument is the 32- or 64-bit address of the ACM status block.

The following diagram depicts the structure of an ACM status block:

The following table defines the ACM status block fields:
Descriptor Field Definition
ACMESB$L_STATUS A longword containing the generalized completion status for the requested operation.
ACMESB$L_SECONDARY_STATUS A longword containing status that may indicate a more detailed description of a failure.
ACMESB$L_ACME_ID A longword containing the agent ID of the ACME agent that reported additional status. An agent ID of 0 indicates that no additional status was reported.
ACMESB$L_ACME_STATUS A longword containing additional status information. Aside from a few cases of item list errors described in the following text, the interpretation of this value is specific to the context of the reporting ACME agent.

Upon request initiation, $ACM sets the value of all fields within the ACM status block to 0. When the requested operation completes. The $ACM service writes condition values into the ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS fields.

If the status in the ACMESB$L_STATUS field is ACME$_AUTHFAILURE, that is the only result that should be displayed or otherwise made known to a user. The status in ACMESB$L_SECONDARY_STATUS (when the caller has the SECURITY privilege, or is calling from kernel or executive mode) contains the detailed reason for the failure, which may be used for purposes that do not disclose the code to the user, such as the process termination code supplied to $DELPRC (but not the image exit code supplied to $EXIT).

Otherwise, the status in ACMESB$L_SECONDARY_STATUS should be considered as subsidiary to that in ACMESB$L_STATUS and used to form a chained message, unless the two cells contain identical values.

In either case, the caller of $ACM[W] can rely on the success bit (bit 0) of the ACMESB$L_STATUS and the ACMESB$L_SECONDARY_STATUS field having the same setting. Either both low-order bits will be set (success) or both will be clear (failure).

The ACMESB$L_ACME_STATUS field is valid only when the contents of the ACMESB$L_ACME_ID field are nonzero, indicating which ACME agent supplied the (possibly zero) value in ACMESB$L_ACME_STATUS.

There is one special format for such data in ACMESB$L_ACME_STATUS. If $ACM rejects the request because of a bad entry in the item list, then ACMESB$L_STATUS contains one of the following codes:
SS$_BADPARAM Incorrect contents for the item code
SS$_BADITMCOD Incorrect item code for the function
SS$_BADBUFLEN Incorrect length for the item code

If ACMESB$L_STATUS contains one of the listed returns, then ACME$L_ACME_STATUS contains the item code from the incorrect item, which is an aid to debugging.

In all other cases, the value delivered in ACME$L_ACME_STATUS is specific to the ACME agent that failed the request. An ACME agent can return a longword value that indicates additional information about the operation. $ACM writes this value in the ACMESB$L_ACME_STATUS field of the ACM status block.

In these cases, you can expect the success of a valid value (one where ACMESB$L_ACME_ID is not zero) in field ACMESB$L_ACME_STATUS to match the "success" bits (bit 0) in fields ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS, although what constitutes a "success" value in ACMESB$L_ACME_STATUS is subject to that interpretation specified for the ACME agent that set the value. In particular, the values in the ACMESB$L_ACME_STATUS field from certain ACME Agents might not be a VMS-style message code.

astadr


OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference

AST service routine to be executed when $ACM completes. The astadr argument is the 32- or 64-bit address of this routine. The AST routine executes at the same access mode as the caller of the $ACM service.

astprm


OpenVMS usage: user_arg
type: quadword (unsigned)
access: read only
mechanism: by value

AST parameter to be passed to the AST service routine specified by the astprm argument. The astprm argument is the longword parameter. Function Codes This section describes the various function codes supported by the $ACM service and lists the function modifiers and item codes relevant to each function:
Function Code Purpose
ACME$_FC_AUTHENTICATE_PRINCIPAL Perform authentication and provide credentials.
ACME$_FC_CHANGE_PASSWORD Select a new password.
ACME$_FC_EVENT Log an event to an ACME agent.
ACME$_FC_FREE_CONTEXT Abandon a dialogue mode Authentication or Password Change before it has completed.
ACME$_FC_QUERY Retrieve information from an ACME agent.
ACME$_FC_RELEASE_CREDENTIALS Give up some of the credentials from a persona.

See the Description section for information relating to the modes of operation and privilege requirements.

ACME$_FC_AUTHENTICATE_PRINCIPAL

The ACME$_FC_AUTHENTICATE_PRINCIPAL function requests authentication of a principal based on standard or site-specific authentication criteria and optionally requests credentials authorized for that principal.

You can specify the principal name using the ACME$_PRINCIPAL_NAME item code. If you do not specify it on the initial call to $ACM, the ACME agents supporting $ACM will try to use another method for determining the principal name. For example, traditional VMS autologin processing determines a principal name based on your terminal name. Of if your call to $ACM was in dialogue mode, the ACM communication buffer returned may prompt you to supply a principal name.

You can also guide how your request is to be processed by directing it toward a specific domain of interpretation (DOI) with either the ACME$_TARGET_DOI_NAME or ACME$_TARGET_DOI_ID item code. Using that technique ensures that your request will be handled by the ACME agents that support the specified domain of interpretation. If that domain of interpretation is not configured on the system at the time of your call, however, your request will fail. Leaving the domain of interpretation to be defaulted increases your chance of successful authentication, but does not guarantee any particular set of credentials beyond the normal VMS credentials.

When the domain of interpretation under which your request is handled is anything other than VMS, the ACME agents that support that domain of interpretation will indicate an OpenVMS user name to which the principal name should be mapped. In this case, the OpenVMS user name must correspond to a valid entry in the OpenVMS authorization database (SYSUAF.DAT) that has the UAF$V_EXTAUTH flag set. (When the IGNORE_EXTAUTH flag is set in system parameter SECURITY_POLICY, the UAF$V_EXTAUTH flag requirement does not apply.)

The VMS ACME agent uses that OpenVMS user name to provide supplemental authorization processing (for example, account disabled or expired, or model restrictions) and to provide security profile and quota information applicable after a successful authentication.

You can use the ACME$M_ACQUIRE_CREDENTIALS function modifier to specify that, if your authentication call is successful, you want credentials returned. $ACM will return those credentials via persona extensions attached to a persona whose handle is returned to a location specified by item code ACME$_PERSONA_HANDLE_OUT.

If you want that persona to be based on some persona you already have, specify the existing persona handle with the item code ACME$_PERSONA_HANDLE_IN and, in addition to the function modifier ACME$M_ACQUIRE_CREDENTIALS, specify one of the following two function modifiers:

Previous Next Contents Index