HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
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.
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 184.108.40.206, Looking Up DOI and ACME IDs, all use of the Event or Query function codes is
specific to a DOI.
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
of ACME$K_NETWORK, indicating that while they supply
a password, no complex interaction is possible.
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:
Dialogue mode operation applies only to the Authenticate
Principal and Change Password functions. Calls to any other functions
must be in nondialogue mode.
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:
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.
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
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.
So long as there is no targeting by the caller of the SYS$ACM[W] system service (discussed in Section 33.4.5), the decision regarding which ACME agent handles a particular request is governed by the following factors:
If the syntax provided to the SYS$ACM[W] system service can be handled by only one ACME agent, that settles the matter. If it can be handled by more than one ACME agent, then the decision also depends on which ACME agent (in order) is the first to be able to map the particular principal name to a VMS user name.
Whether a particular ACME agent can map a particular principal name also depends on the mapping tables or algorithms specific to that ACME agent, but this is typically more time-consuming than simple decisions made on the basis of the syntax presented in the principal name. Consider the acceptable syntax presented in the following table:
Given those two ACME agents, it is possible to specify a principal name that can only be handled by the Windows NT DOI (by a full specification including the execute (@) command), but it is not possible to specify a principal name that can only be handled by the VMS DOI.
But that table only describes the situation for the combination of
those two ACME agents, the initial ones produced by
Compaq. The VMS ACME is always present on any
OpenVMS system, but on some systems you might omit the NT ACME and/or
include some other ACME agents, one of which might
honor some of the same syntax as the NT ACME agent.
These item codes are used when your program requires that a particular
DOI handle your request.
220.127.116.11 When to Use DOI_NAME vs. DOI_ID
The following item codes affect the SYS$ACM[W] system service operations in the same way:
A similar relationship exists between the following item codes:
The system manager specifies DOI names in configuring the ACME server, although in most cases the system manager uses the registered names specified by a vendor.
DOI IDs are implicitly specified by the system manager by the order in which each is specified for the first time after each boot of the system. That means that a particular DOI ID may have an entirely different meaning on the same machine after the next reboot.
Specifying a DOI_NAME clearly gives better ease-of-use, while
specifying a DOI_ID gives slightly better performance with an overhead
penalty paid up front to look up a DOI_ID based on a DOI_NAME. Some
programs that call the SYS$ACM[W] system service, however, need to perform that
lookup in order to interpret the contents of the ACM communications buffer,
so in those cases the DOI_ID is already available and can be used in
calls to the SYS$ACM[W] system service.
Use the Query function code with a Target DOI ID of 0 (meaning the SYS$ACM[W] system service itself) to determine what DOI_ID corresponds to a given name.
The item list to do this would be as follows:
33.4.6 Determining ACME Information with the Query Function
The general nature of the Query function is that your code supplies the following items:
See the documentation for that ACME agent for more
The general nature of the Event function is that your code supplies the following items:
Your program possibly receives back item ACME$_EVENT_DATA_OUT. Whether ACME$_EVENT_DATA_OUT is supported and the exact nature of what the SYS$ACM[W] system service is supposed to do for an event is up to the ACME agent that you specify as the target of the Event function.
See the documentation for that ACME agent for more
You can use the SYS$ACM[W] system service to accomplish the following functions:
It was possible to perform many of these functions prior to introduction of the SYS$ACM[W] system service by combining the use of the following techniques:
These steps made it difficult to provide a complete and bug-free
implementation. Furthermore, such an approach dealt only with
traditional VMS password-based authentication rather than including
add-on mechanisms. With the introduction of the SYS$ACM[W] system service, those
scenarios can be handled in a uniform, supported manner.
If all information is known in advance, a call to SYS$ACMW is quite simple, as in the following example:
The details of handling the field ACMESB$L_ACME_STATUS depend on
the nature of the ACME agent indicated in field ACMESB$L_ACME_ID.
If that ACME agent is not specifically known to the program that
calls the SYS$ACM[W] system service, there is no way to interpret that field. The
previous example presumes there is special knowledge regarding
at least one ACME agent held in
routine REPORT_ACME_SPECIFIC_ERROR, which is not supplied.
Particularly with the function code ACME$_FC_CHANGE_PASSWORD, you cannot reliably predict all the necessary input at the time of the initial call, because the first password chosen might be found in the password history file or be unacceptable in some other way.
Following is a sample of how you might decode and process a dialogue response:
This example leaves the details of handling an optional confirmation prompt to the routine CONSTRUCT_ITEM_NOECHO_FROM_TERMINAL, which is not supplied. In addition, the code to process and display output items is not shown.
Confirmation prompts are more common in Change Password than in Authenticate Principal, but the program that calls SYS$ACM[W] system service should be prepared to handle them in either situation (that is, any time dialogue mode is used).