Document revision date: 15 July 2002

This chapter describes how to write a new Authentication and Credential Management (ACM) client program. An ACM client program uses the SYS$ACM[W] system service to do one or more of the following:

• Determine whether users are actually the individuals they claim to be.
• Acquire credentials¹ for a new user security context (persona).
• Change a user account password.

The Authentication and Credential Management (SYS$ACM[W]) service provides a standard programming interface for authentication, and can return credentials needed to enforce security policies of OpenVMS system logins. The SYS$ACM system service also provides a standard programming interface for user password management.

The SYS$ACM service might require the user, depending on the user name, to furnish two, one, or zero passwords. Other requirements might exist, such as supplying a code number from a "see-through" hardware token, or inserting a smart card into a reader. It is important that the program that calls SYS$ACM be relieved of the need to know all of these requirements, particularly because such a program might be used at multiple sites having different sets of rules.

Along with user authentication, the ACM service provides integrated credentials through normal and extended persona support. Normal persona support allows code to obtain native, that is, OpenVMS, process credentials, which contain username, UIC, and rights identifiers. Extended persona support also enables a process to obtain non-native credentials. As an example, this support would use both Windows NT credentials and OpenVMS credentials.

Use this chapter together with the description of the SYS$ACM[W] system service from the OpenVMS System Services Reference Manual: A--GETUAI. While this chapter presents a conceptual view, that manual contains the detailed formats and rules.

33.1 Identification, Authentication, and Authorization

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:

• Request user's user name.
• Request user's password.
• Verify user name and password.
• Check for expired passwords.
• Apply account restrictions.
• Issue credentials.
• Display system messages (optional).

An authentication policy is defined by a particular combination of user identification, authentication, and authorization attributes.

Policy attributes include the following:

• Identification syntax (simple user name, combination of domain/realm/principal-name)
• Authentication token mechanism (re-useable password, one-time password, system-generated password, single or dual password, challenge-response, hardware)
• Token re-use filters (password dictionary, password history, password legal character set, password minimum/maximum lengths, forced change schedule, expiration)
• Intrusion detection
• Case sensitivity
• Access restrictions (time-of-day, day-of-week, type of access)
• User account controls, such as account lock (disable) and account expiration
• Credential information (user and group identifiers, privileges, and so on)

Two authentication policies are presently supported: standard OpenVMS policy and external authentication with Microsoft distributed authentication policy.

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:

• SYS$ACM is a context-driven system service. The service is designed in such a way so that applications transparently adapt themselves to various authentication dialogues without requiring changes to the application. Applications call SYS$ACM to perform functions such as authenticate principal and change password. The service can return a complete security profile of the user in the form of a persona upon successful authentication.
• The ACME_SERVER process is a multithreaded server supporting one or more authentication policies. Each authentication policy is installed by configuring an ACME agent shareable image that "plugs in" to the ACME_SERVER process using a standard interface. The server manages the authentication sequence in an orderly fashion by calling each ACME agent in turn according to a defined sequence of phases. ACME agents are also responsible for adhering to certain rules regarding how agents can interact during an authentication sequence.
• ACME agents each define a single authentication policy that augments or replaces portions of the standard OpenVMS authentication policy. OpenVMS currently supports two ACME agents: an OpenVMS ACME agent (VMS) that provides the standard OpenVMS authentication policy, and a Microsoft ACME agent (MSV1_0) that provides external authentication using Microsoft distributed authentication protocol (requires installation of Compaq Advanced Server). Compaq plans to publish the ACME agent interface in the future to allow users and ISVs to develop customized ACME agents.
• The ACME subsystem is configured and managed using the DCL commands SET [SHOW] SERVER ACME.

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.

Figure 33-1 SYS$ACM [W] Overview

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

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.

	privacy and legal statement
5841PRO_087.HTML