HP OpenVMS systems documentation

The HP OpenVMS System Services Reference Manual: A--GETUAI provides a comprehensive reference to various values and structures used to call the SYS$ACM[W] system service. This section describes just some of those.

33.3.1 SYS$ACM[W] Function Codes

When your ACM client program calls the SYS$ACM[W] system service, it must specify one of the following function codes to indicate which capability is to be invoked:

• ACME$_FC_AUTHENTICATE_PRINCIPAL
  Determine whether a subject really is a particular individual, typically based on password or some more advanced mechanism. Often this call is also used to return credentials.
• ACME$_FC_CHANGE_PASSWORD
  Modify the password stored on the computer system or network that is used to authenticate a particular individual.
• ACME$_FC_RELEASE_CREDENTIALS
  Relinquish the credentials obtained by calling ACME$_FC_AUTHENTICATE_PRINCIPAL.
• ACME$_FC_QUERY
  Obtain information about a particular ACME agent.
• ACME$_FC_EVENT
  Send information for storage or processing in a manner specific to a particular ACME agent.
• ACME$_FC_FREE_CONTEXT
  Cancel a dialogue mode Authenticate Principal or Change Password request before it is complete.

When your ACM client program calls the SYS$ACM[W] system service, it may specify a combination of the following function codes to request variations in the basic processing.

The first function modifier is equally applicable to all function codes:

• ACME$M_NOAUDIT
  Suppress auditing in the VMS ACME.

The second set of function modifiers consists of those particularly intended for the Authenticate Principal and Change Password function codes:

• ACME$M_UCS2_4
  Indicate that this client program presents information as UCS-2 characters stored in 4-byte cells, rather than the default Latin-1 single-byte cells.
• ACME$M_ACQUIRE_CREDENTIALS
  Supply credentials at the location specified by item code ACME$_PERSONA_HANDLE_OUT.
• ACME$M_MERGE_PERSONA
  Create the ACME$_PERSONA_HANDLE_OUT persona by merging the new credentials into the persona supplied by item code ACME$_PERSONA_HANDLE_IN.
• ACME$M_COPY_PERSONA
  Create the ACME$_PERSONA_HANDLE_OUT persona by merging the new credentials into a copy of the persona supplied by item code ACME$_PERSONA_HANDLE_IN.
• ACME$M_OVERRIDE_MAPPING
  Perform the operation even though the mapping performed by an ACME agent has a VMS user name different from that specified in the ACME$_PERSONA_HANDLE_IN persona.
• ACME$M_NOAUTHORIZATION
  Suppress authorization checks in the VMS ACME.
• ACME$M_FOREIGN_POLICY_HINTS
  Apply the behavior specified by the ACME$M_NOAUDIT and ACME$M_NOAUTHORIZATION modifiers to add-on ACME agents where possible.
• ACME$M_DEFAULT_PRINCIPAL
  Default the ACME$_PRINCIPAL_NAME_IN value to the principal name from the current persona of the calling process.

The SYS$ACM[W] system service follows the standard pattern of returning a 32-bit status value, but that return status indicates only whether the call was accepted for transmission to the ACME server process.

33.3.3.1 When the Return Status Indicates Failure

If the return status is the failure code ACME$_INVALIDCTX and your program was attempting to continue with an ongoing dialogue mode request, the possible causes of this failure are the following:

• The continuation call was made with a different function code from the original call.
• The continuation call was made with a different set of function modifiers from the original call.
• The continuation call was made with an ACM context argument containing a different pointer from that returned by the previous call.

In cases where the return status indicates success, your program can determine the overall resultant effect of a call to the SYS$ACM[W] system service by examining the contents of fields within the ACMESB structure it provided via the ACMSB argument. The following table describes the fields and their contents:

Field Name	Data Type	Contents
ACMESB$L_STATUS	VMS Status Code	The primary status regarding the success of an operation.
ACMESB$L_SECONDARY_STATUS	VMS Status Code	An auxiliary status to further explain the primary status.
ACMESB$L_ACME_ID	ACME ID Type	The identity of the ACME agent that provided information for this status block.
ACMESB$L_ACME_STATUS	ACME-specific	A status using a format specific to the particular ACME agent.

If no special value is appropriate for the ACMESB$L_SECONDARY_STATUS field, it contains the same value as the ACMESB$L_STATUS. Thus, your program should check to see if the two are equal rather than reporting them both as separate status values.

The values in fields ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS, along with the value in ACMESB$L_ACME_STATUS if provided, all indicate the same success. For ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS, that means that the low-order bits will either both be set (success) or both be cleared (failure). Because ACMESB$L_ACME_STATUS syntax is determined on an ACME-specific basis, the success or failure semantics of that value provided in that longword will match that for the other two fields.

33.3.3.2.1 When the Primary Status Indicates an Item Code Failure

There is a special case when an error with an item code causes the SYS$ACM[W] system service to return one of the following values in the ACMESB$L_STATUS field:

• SS$_BADITMCOD---An ACME-specific item code is undefined or is inappropriate in the circumstance (for example, incompatible with the function code or another item). Alternatively, a required item code is not provided.
• SS$_BADBUFLEN---An item length is wrong for the item code used.
• SS$_BADPARAM---The contents of an item are incorrect for the circumstance.

In those cases, the field ACMESB$L_ACME_STATUS contains the item code for the item on which the problem was encountered.

33.3.3.2.2 When the Primary Status is ACME$_OPINCOMPL

When the primary status contains ACME$_OPINCOMPL, your program must make at least one more call to the SYS$ACM[W] system service, based on the data in the ACM communications buffer, as discussed in Section 33.3.6.

33.3.4 Item Codes

Item codes provided to the SYS$ACM[W] system service can be characterized by particular bit patterns that indicate their type and purpose.

33.3.4.1 Common vs. ACME-Specific Item Codes

Item codes provided to the SYS$ACM[W] system service have a theoretical range from 1 to 65535 and are divided into the following groups:

• The first half, from 1 to 32767, are called common item codes, because they can be used for the same meaning by all ACME agents.
• The second half, from 32768 to 65535, are called ACME-specific item codes, because they carry information only to a single ACME agent.

Another way of making that distinction is to say that bit 15 of the item code indicates whether the item code is ACME-specific.

While the common item codes are defined once for all ACME agents, the ACME-specific item codes are defined separately by each ACME agent, as shown in Figure 33-2, Item List Chain. When the SYS$ACM[W] system service encounters an ACME-specific item code, it attributes it to whichever ACME agent was most recently mentioned with one of the following item codes:

• ACME$_CONTEXT_ACME_ID
• ACME$_CONTEXT_ACME_NAME
• ACME$_TARGET_DOI_ID
• ACME$_TARGET_DOI_NAME

If none of those item codes have been specified before the first ACME-specific item code, the SYS$ACM[W] system service returns a primary status of ACME$_NOACMECTX.

33.3.4.2 Distinguishing Between Input and Output Item Codes

Bit 14 of the item code indicates whether the item code is for an output item. If the bit is clear, it is for an input item.

The SYS$ACM[W] system service does not return data for output items until the final successful completion of an operation. For Authenticate Principal and Change Password operations, that could be after many intervening dialogue mode calls to the SYS$ACM[W] system service.

33.3.4.3 Text vs. Nontext Items

Bit 13 of the item code indicates whether the item code is a text item, and thus susceptible to Unicode translation. Your program can call the SYS$ACM[W] system service either with or without the ACME$M_UCS2_4 function modifier. If that function modifier is present, it means your program is supplying unicode character set (UCS) data for item codes that have bit 13 set. If the function modifier is missing, your program is supplying Latin-1 (similar to ASCII) characters for those item codes. The SYS$ACM[W] system service uses the encoding of the function code to determine which input items it should translate from Latin-1 to UCS for input items, and in the reverse direction for output items.

The setting of bit 13 in an item code gives another important indication for dialogue mode operations. For an ACME agent to ask for input from an arbitrary ACM client program, it must be clear that the ACM client program is capable of handling the data format to be used for input. At the present time, character-string data is the only such input that is understood by all ACM client programs. An ACME agent can only ask for dialogue items that have bit 13 set.

33.3.4.4 Single-Valued vs. Multivalued Item Semantics

It is mechanically possible for your program to put the same item code at two different places in a single item list. The following are the possible interpretations of such a circumstance:

• Single-valued input item semantics
  When multiple itemset entries have the same input item code, the last one on the item list takes effect.
• Single-valued output item semantics
  When multiple itemset entries have the same output item code, they all get the same output data.
• Multivalued input item semantics
  When multiple itemset entries have the same input item code, each is taken as a separate instance of that input.
• Multivalued output item semantics
  When multiple itemset entries have the same output item code, each gets a distinct portion of the output data.

The SYS$ACM[W] system service always honors the well-known items with single-valued semantics.

33.3.5 Item Lists

Even in dialogue mode, your first call to the SYS$ACM[W] system service must specify all required input items and desired output items except for those input items that the SYS$ACM[W] system service will specify with a subsequent input itemset entry in the ACM communications buffer.

33.3.5.1 Item List Chains

The item list you pass to the SYS$ACM[W] system service can be built from as many as 32 different item list segments, each of which can be composed of traditional 32-bit ILE3 items or 64-bit ILEB_64 items. All items in a single item list segment must be of the same type. Figure 33-2 illustrates an item list chain.

Figure 33-2 Item List Chain

For dialogue mode calls using Authenticate Principal or Change Password function codes, the SYS$ACM[W] system service may return a primary status of ACME$_OPINCOMPL, indicating more data is needed. In that case, a description of the data needed is provided within the ACM communications buffer pointed to from the ACM context argument longword you supplied.

Field ACMECB$L_ITEM_SET_COUNT indicates how many entries are in the itemset, while field ACMECB$PS_ITEM_SET points to an array of itemset entries, as shown in Figure 33-3.

Figure 33-3 Itemset Layout

Within a single itemset entry, when the flag ACMEDLOGFLG$V_INPUT is set in field ACMEIS$L_FLAGS, the third field is called ACMEIS$W_MAX_LENGTH and indicates the maximum acceptable length in bytes for the input requested.

When the flag ACMEDLOGFLG$V_INPUT is clear, however, the third field is called ACMEIS$W_MSG_TYPE and indicates the message category of the output text. That category can be used to decide placement or presentation of output text for a user. Bit 14 of that code, like bit 13 of an item code, indicates that the data in question (output data in this case) is textual in nature and your program can handle it using methods appropriate for text.

No ACME agent will ever send an ACME-specific message category to an ACM client program without knowing that the ACM client program is familiar with that message category.

Because there is no ACMEIS$W_MSG_TYPE field when flag ACMEDLOGFLG$V_INPUT is set, the SYS$ACM[W] system service performs Unicode conversion of prompting information based on whether or not the resulting input data is eligible for Unicode conversion. Thus, it is not possible to have multiple text formats in prompts with the corresponding input.

33.3.8 Synchronization of Your System Service Calls

As with many other system services, you have your choice of the SYS$ACM or SYS$ACMW interface. Choose one or the other based on whether your program will be doing other work (authentication-related or otherwise) while the authentication operation is underway. This choice has only to do with synchronization within your program; it is unrelated to your choice of dialogue mode or nondialogue mode.

33.4 Authentication Techniques

Your ACM client program can call the SYS$ACM[W] system service to change a password, and the effect is the same as if SET PASSWORD had made the call.

Your ACM client program can call the SYS$ACM[W] system service to authenticate a user. Your authentication is audited and break-in evasion is checked in the ACME server process, just as for LOGINOUT.

Your program can call the SYS$ACM[W] system service to log an event or to query for information specific to a particular domain of interpretation (DOI). With the exception of the general ACM information described in Section 33.4.5.3, Looking Up DOI and ACME IDs, all use of the Event or Query function codes is specific to a DOI.

33.4.1 Nondialogue Mode Operation

The simplest form of call to the SYS$ACM[W] system service is the nondialogue mode call, illustrated in Figure 33-4. It resembles many other system services, except that the item list contains a wider variety of both input and output items.

Figure 33-4 Nondialogue Mode Operation

Use nondialogue mode when only a limited amout of interaction is possible, such as when an existing network protocol like FAL or FTP does not allow an arbitrary authentication exchange. Typically, such programs should specify an ACME$_LOGON_TYPE of ACME$K_NETWORK, indicating that while they supply a password, no complex interaction is possible.

33.4.2 Dialogue Mode Operation

Use dialogue mode when your ACM client program is flexible enough to respond to password change notification, to allow the user to answer arbitrary questions, such as the charge code for a session, and so on.

In dialogue mode, the SYS$ACM[W] system service uses the longword you provide by the ACM context argument parameter to store a pointer to an ACM communications buffer. Figure 33-5 illustrates dialogue mode operation.

Figure 33-5 Dialogue Mode

As with nondialogue mode, your ACM client program must provide on the initial call to the SYS$ACM[W] system service all output items and all input items that are not going to be the subject of an itemset entry.

On intermediate returns, where the SYS$ACM[W] system service provides the primary status ACME$_OPINCOMPL in ACMESB$L_STATUS, it also creates an itemset within the ACM communications buffer indicating what further information exchange is required. The action your program should take depends upon the nature of each itemset entry within the itemset as follows:

• Output itemset entries
  The SYS$ACM[W] system service provides information for display to the user. The exact form of this display is up to your program, as guided by the message category provided in field ACMEIS$W_MSG_TYPE and by the item code provided in field ACMEIS$W_ITEM_CODE. Your program may in fact choose to ignore any or all output itemset entries, except for certain message category values that would not be appropriate, such as suppressing ACMEMC$K_SELECTION information that tells users about possible choices for their next input.
• Input itemset entries
  The SYS$ACM[W] system service provides information regarding input needed on the next call to the SYS$ACM[W] system service. In the simplest case, you can handle this by prompting a character cell terminal, using the prompt text provided in the itemset entry. For a more complex interface, some of the information sought might be provided by the program without user interaction, for instance if authentication were being done with the assistance of a smart card or other personalized hardware device.

If all of the itemset entries within the itemset were output itemset entries, your program should call the SYS$ACM[W] system service with an empty item list (containing just the terminator entry).

Dialogue mode operation applies only to the Authenticate Principal and Change Password functions. Calls to any other functions must be in nondialogue mode.

33.4.3 Login Categories and Classes

The OpenVMS Guide to System Security outlines the following login categories and login classes that are of interest for calling the SYS$ACM[W] system service:

Login Category	Login Class
Interactive	Local, Dialup, Remote
Noninteractive	Batch, Network

Those login classes correspond to the values used in the ACME$_LOGON_TYPE item for the SYS$ACM[W] system service. Each may have specific policy requirements, and may be authenticated differently. Batch jobs, for example, start without specification of a password or other authentication information.

This choice can also influence authorization decisions, such as the VMS day and time restrictions.

Specifying item ACME$_LOGON_TYPE requires the IMPERSONATE privilege. It is defaulted to match the login class of the process that called the SYS$ACM[W] system service.

The login type affects the degree of interaction required to call the SYS$ACM[W] system service, as shown in the following table:

Login Type	Interaction Details
Batch	No authentication is involved. This may mean that credentials are not provided for certain domains of interpretation that base their credential creation on presentation of a password.
Network	Authentication is involved, but it operates in nondialogue mode unless an ACME agent (other than the VMS ACME agent) requires dialogue for authentication.
Local, Dialup, and Remote	Authentication is involved and further dialogue may be encountered to change expiring passwords, and so on. The SYS$ACM[W] system service expects a person to be available to answer questions raised through dialogue.

Thus in the case of the local, dialup, or remote values for ACME$_LOGON_TYPE, you must provide an ACM context argument argument on all calls to the SYS$ACM[W] system service (and you must provide item ACME$_DIALOGUE_SUPPORT on the initial call to indicate support for input dialogue). With the network value for ACME$_LOGON_TYPE, those elements might be required with certain add-on ACME agents.