$ACM

$ACM, or Authentication and Credential Management, is a system service that provides an interface to all functions supported by the Authentication and Credential Management Authority. The $ACM service completes asynchronously; for synchronous completion, use the $ACMW form of the service.

Syntax

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);

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:

$ACM Set Entry Fields

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.
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:

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 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:

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.

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:

ACME$M_MERGE_PERSONA---Requests that additional credentials you acquire be added into the existing persona ACME$M_COPY_PERSONA---Requests that additional credentials you acquire be added into a copy of the existing persona

In either case, a handle to the resulting persona will be returned as specified by item code ACME$_PERSONA_HANDLE_OUT.

When a new persona is created, the ISS$_PRIMARY_EXTENSION designator indicates which persona extension representing the domain of interpretation was responsible for authenticating the user.

On a subsequent call $ACM will use that designator to guide processing of the ACME$M_DEFAULT_PRINCIPAL function modifier, for instance when there is an ACME$_FC_CHANGE_PASSWORD request.

ACME$_FC_CHANGE_PASSWORD The ACME$_FC_CHANGE_PASSWORD function performs a password change operation. All aspects of the ACME$FC_CHANGE_PASSWORD function can also be performed as part of the ACME$_FC_AUTHENTICATE_PRINCIPAL function. Some degree of the ACME$_FC_AUTHENTICATE_PRINCIPAL function is also performed as part of ACME$_FC_CHANGE_PASSWORD to ensure the identity of the user changing the password. The primary and secondary passwords can be changed independently. This function requires the ACME$_NEW_PASSWORD_FLAGS item code.

ACME$_FC_EVENT The ACME$_FC_EVENT function provides a simple logging feature that can be used to generate certain events related to the policy of a domain of interpretation. To log an event, supply the desired "event type" item code followed by the appropriate "data" item codes pertaining to the "target" domain of interpretation. To determine what event processing might be available, see the documentation provided by the vendors of the supporting ACME agents.

ACME$_FC_FREE_CONTEXT The ACME$_FC_FREE_CONTEXT function is used to terminate iterative processing of a request. The address of the ACM communications buffer associated with the request must be specified using the context argument.

ACME$_FC_QUERY The ACME$_FC_QUERY function provides a simple key-based query feature that can be used to obtain certain information related to the policy of a domain of interpretation. To look up an item of information, supply the desired "key" item code followed by the appropriate "data" item code. To determine what query processing might be available, see the documentation provided by the vendors of the supporting ACME agents.

ACME$_FC_RELEASE_CREDENTIALS The ACME$_FC_RELEASE_CREDENTIALS function removes credentials for a particular domain of interpretation from the specified persona. When the domain of interpretation is specified as "VMS", all non-native credentials are released and the persona is deleted. The "VMS" credentials cannot be removed from either the currently active or the process' natural persona. Thus, you cannot use the $ACM service to delete these personae. Function Modifiers This section describes the various function modifiers for the function codes supported by the $ACM service.

The following table indicates which Function Modifiers are applicable to the various Function Codes:

colspan="col"	Function Codes
Function Modifiers	Authenticate Principal	Change Password	Event	Free Context	Query	Release Credentials
ACME$M_ACQUIRE_CREDENTIALS	IMPERSONATE required
ACME$M_COPY_PERSONA	Permitted
ACME$M_DEFAULT_PRINCIPAL	Permitted	Permitted
ACME$M_FOREIGN_POLICY_HINTS	SECURITY required
ACME$M_MERGE_PERSONA	Permitted
ACME$M_NOAUDIT	SECURITY required
ACME$M_NOAUTHORIZATION	SECURITY required
ACME$M_OVERRIDE_MAPPING	IMPERSONATE required
ACME$M_TIMEOUT
ACME$M_UCS2_4	Permitted	Permitted	Permitted		Permitted	Permitted

ACME$M_ACQUIRE_CREDENTIALS The ACME$M_ACQUIRE_CREDENTIALS function modifier requests credentials be acquired during a successful authentication. ACME$M_COPY_PERSONA The ACME$M_COPY_PERSONA function modifier requests acquired credentials be attached to a copy of the persona specified with item code ACME$_PERSONA_HANDLE_IN. ACME$M_DEFAULT_PRINCIPAL The ACME$M_DEFAULT_PRINCIPAL specifies that the principal name and target domain of interpretation should be taken from the input persona, such as for changing the password of the logged-in user or reauthenticating the logged-in user. ACME$M_FOREIGN_POLICY_HINTS The ACME$M_FOREIGN_POLICY_HINTS function modifier indicates ACME agents should honor the ACME$M_NOAUDIT and ACME$M_NOAUTHORIZATION function modifiers for non-VMS domains of interpretation. ACME$M_MERGE_PERSONA The ACME$M_MERGE_PERSONA function modifier requests acquired credentials be attached to the persona specified with item code ACME$_PERSONA_HANDLE_IN. ACME$M_NOAUDIT The ACME$M_NOAUDIT function modifier indicates that auditing actions should not be performed. Unless the ACME$M_FOREIGN_POLICY_HINTS function modifier is also specified, this modifier applies only to the VMS domain of interpretation. ACME$M_NOAUTHORIZATION The ACME$M_NOAUTHORIZATION function modifier indicates authorization restrictions, such as the enforcement of modal constraints, should not apply. This provides a mechanism for performing pure authentication operations. Unless the ACME$M_FOREIGN_POLICY_HINTS function modifier is also specified, this modifier applies only to the VMS domain of interpretation. ACME$M_OVERRIDE_MAPPING The ACME$M_OVERRIDE_MAPPING function modifier allows for the acquisition of non-VMS credentials during a persona merge or copy operation. This occurs when an externally authorized principal name maps to an OpenVMS user name that differs from the user name associated with the native (VMS) credentials. By default, mixing credentials is prohibited. ACME$M_TIMEOUT The ACME$M_TIMEOUT modifier indicates that the caller requests timeout processing. The timeout interval is specified by the ACME$_TIMEOUT_INTERVAL item code. Timeout processing is always enforced for non-privileged callers. Privileged callers (those running in exec mode or kernel mode or possessing SECURITY privilege) must explicitly specify ACME$M_TIMEOUT for timeout processing to be enforced.

ACME$M_UCS2_4 The ACME$M_UCS2_4 function modifier indicates item codes that specify string values use a 4-byte UCS-2 (Unicode) representation rather than 8-bit ASCII.