HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
1 See the Authentication Glossary at the end of this manual for an explanation of this and other new terminology.
When a user logs in to a system or runs an application that requires authentication, a dialogue takes place between that user and the system (or application). Policies may differ in some respects, but each requires the following basic functions of user identification, authentication, and authorization:
An authentication policy is defined by a particular combination of user identification, authentication, and authorization attributes.
Policy attributes include the following:
Two authentication policies are presently supported: standard OpenVMS
policy and external authentication with Microsoft distributed
33.2 ACME Subsystem Components
The Authentication and Credential Management Extensions (ACME) subsystem provides authentication and persona-based credential services. Applications can use these services to interact with the user to perform one or more of the following functions: user authentication, password change, and persona creation and modification. Both standard OpenVMS authentication and external authentication policies are supported, so applications use the same mechanisms as used by the system's LOGINOUT and SET PASSWORD components.
The ACME subsystem consists of the SYS$ACM system service, the ACME_SERVER process, one or more ACME (policy-provider) agents, and SET [SHOW] SERVER ACME configuration and management commands:
With the introduction of the SYS$ACM[W] system service, operations that were formerly handled entirely within the LOGINOUT and SET PASSWORD programs are now distributed across multiple processes. The user interface activities remain in the original programs, as shown on the left side of Figure 33-1. Actual authentication calculations, however, have been moved to the ACME server process, as shown on the right side of that figure. The VMS ACME supports traditional authentication interactions for the VMS domain of interpretation (DOI). Other ACME agents may support additional DOIs or assist the VMS ACME, for example by providing stronger authentication.
The 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
The first function modifier is equally applicable to all function codes:
The second set of function modifiers consists of those particularly intended for the Authenticate Principal and Change Password function codes:
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.
126.96.36.199 When the Return Status Indicates Failure
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
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
188.8.131.52.1 When the Primary Status Indicates an Item Code Failure
In those cases, the field ACMESB$L_ACME_STATUS contains the item code
for the item
on which the problem was encountered.
184.108.40.206.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.
220.127.116.11 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:
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:
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
18.104.22.168 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
calls to the SYS$ACM[W] system service.
22.214.171.124 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.
126.96.36.199 Single-Valued vs. Multivalued Item Semantics
The SYS$ACM[W] system service always honors the well-known items
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.
188.8.131.52 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.
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.