HP OpenVMS System Services Reference Manual

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.

Table SYS-11 indicates which Function Modifiers are applicable to the various Function Codes:

Table SYS-11 Function Codes and Function Modifiers
Function Codes

Function Modifiers Authenticate Principal Change Password Event Free Context Query Release Credentials

ACME$M_ACQUIRE_CREDENTIALS IP

ACME$M_COPY_PERSONA <>

ACME$M_DEFAULT_PRINCIPAL <> <>

ACME$M_FOREIGN_POLICY_HINTS SR

ACME$M_MERGE_PERSONA <>

ACME$M_NOAUDIT SR

ACME$M_NOAUTHORIZATION SR

ACME$M_OVERRIDE_MAPPING IR

ACME$M_TIMEOUT

ACME$M_UCS2_4 <> <> <> <> <>

+Required
++Either ID or Name Required

Key to Codes

<> ---Permitted
IP---IMPERSONATE Privilege Required for the MAPPED _VMS _USERNAME to differ from the one current when the initial call to $ACM is made
IR---IMPERSONATE Privilege Required to override default values
SR---SECURITY Privilege Required

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.

Item Code Encoding

Item codes are 16-bit unsigned values and are encoded as follows:

The item codes can be categorized in three different ways and are described as follows:

Common and ACME-specific Item Codes
- Common item codes
  These item codes are defined for the $ACM system service itself and are available to all ACME agents.
- ACME-specific item codes
  These item codes are defined separately for each ACME agent.
Input and Output Item Codes
- Input item code
  Input item codes specify a buffer that contains information provided to $ACM. The buffer length and buffer address fields in the item descriptor must be nonzero; the return length field is ignored.
- Output item code
  Output item codes specify a buffer in which $ACM is to return information. The buffer length and buffer address fields of the item descriptor must be nonzero; the return length field can be zero or nonzero.
Subject and Not Subject to Unicode Conversion
- Subject to Unicode Conversion
  Text strings can be specified as Latin1 or 4-byte UCS-2 characters, depending on the setting of the ACME$M_UCS2_4 function modifier. An item code that is subject to Unicode conversion indicates it is a text item.
- Not subject to Unicode Conversion
  Item codes that are not subject to Unicode conversion have a data format implied by the item code, and the nature of the data format must be explicitly understood by the programmer who calls $ACM.

See the Item Codes section for a description of the common item codes and their data formats.

Documentation of ACME-specific codes in general comes in the documentation from the vendor of each ACME agent.

For documentation of ACME-specific codes for the VMS ACME, see the VMS ACME-specific Item Codes section of this description. Common Item Codes This section describes the common item codes for the function codes supported by the $ACM service.

The item code space is partitioned into common items and ACME-specific items. ACME-specific items are used to request information that is unique to a particular domain of interpretation. The item codes described in this section fall into the common item code space.

Table SYS-12 indicates which Common Item Codes are applicable to the various Function Codes:

Table SYS-12 Function Codes and Common Item Codes
Function Codes

Item Codes Authenticate Principal Change Password Event Free Context Query Release Credentials

ACME$_ACCESS_MODE <>

ACME$_ACCESS_PORT (U) IR IR

ACME$_AUTH_MECHANISM <>

ACME$_AUTHENTICATING_DOI_ID (O) <> <>

ACME$_AUTHENTICATING_DOI_NAME (U,O) <> <>

ACME$_CHAIN <> <> <> <> <>

ACME$_CHALLENGE_DATA IR

ACME$_CONTEXT_ACME_ID (U) <> <>

ACME$_CONTEXT_ACME_NAME <> <>

ACME$_CREDENTIALS_NAME (U) <>++

ACME$_CREDENTIALS_TYPE <>++

ACME$_DIALOGUE_SUPPORT <> <>

ACME$_EVENT_DATA_IN <>

ACME$_EVENT_DATA_OUT (O) <>

ACME$_EVENT_TYPE <>

ACME$_LOCALE (U) <> <>

ACME$_LOGON_INFORMATION (O) <>

ACME$_LOGON_TYPE <>

ACME$_MAPPED_VMS_USERNAME (U,O) <> <>

ACME$_MAPPING_ACME_ID (O) <> <>

ACME$_MAPPING_ACME_NAME (U,O) <> <>

ACME$_NEW_PASSWORD_1 (U) <> <>

ACME$_NEW_PASSWORD_2 (U) <> <>

ACME$_NEW_PASSWORD_FLAGS <> <>

ACME$_NEW_PASSWORD_SYSTEM (U) SR SR

ACME$_NULL <> <> <> <> <>

ACME$_PASSWORD_1 (U) <> <>

ACME$_PASSWORD_2 (U) <> <>

ACME$_PASSWORD_SYSTEM (U) <> <>

ACME$_PERSONA_HANDLE_IN <>

ACME$_PERSONA_HANDLE_OUT (O) <>

ACME$_PHASE_TRANSITION (O)

ACME$_PRINCIPAL_NAME_IN (U) <> <>

ACME$_PRINCIPAL_NAME_OUT (U,O) <> <>

ACME$_QUERY_DATA (O) <>+

ACME$_QUERY_KEY_TYPE <>+

ACME$_QUERY_KEY_VALUE <>+

ACME$_QUERY_TYPE <>+

ACME$_REMOTE_HOST_ADDRESS IR IR

ACME$_REMOTE_HOST_ADDRESS_TYPE IR IR

ACME$_REMOTE_HOST_FULLNAME (U) IR IR

ACME$_REMOTE_HOST_NAME (U) IR IR

ACME$_REMOTE_USERNAME (U) IR IR

ACME$_RESPONSE_DATA <>

ACME$_SERVER_NAME_IN (U) <>

ACME$_SERVER_NAME_OUT (U,O) <>

ACME$_SERVICE_NAME (U) IR IR IR IR IR IR

ACME$_TARGET_DOI_ID <> <> <>++ <>++

ACME$_TARGET_DOI_NAME (U) <> <> <>++ <>++

ACME$_TIMEOUT_INTERVAL

+Required
++Either ID or Name Required

Key to Codes

<> ---Permitted
IR---IMPERSONATE Privilege Required to override default values
SR---SECURITY Privilege Required
O---Output item code
U---Subject to Unicode Conversion

ACME$_ACCESS_MODE
The ACME$_ACCESS_MODE item code is an input item code. It specifies the access mode at which a new persona, resulting from credential acquisition processing, is to be created. The buffer must contain a longword value specifying the access mode.
The $PSLDEF macro defines the following symbols for the four access modes:
PSL$C_KERNEL
PSL$C_EXEC
PSL$C_SUPER
PSL$C_USER

The most privileged access mode used is the access mode of the caller. The specified access mode and the access mode of the caller are compared. The less privileged of the two access modes becomes the access mode at which the persona is created.
ACME$_ACCESS_PORT
The ACME$_ACCESS_PORT item code is an input item code. It specifies the name of local device (for example, a terminal) applicable to an authentication request. The buffer must contain a case-insensitive name string.
If not specified, $ACM passes the name string contained in the PCB$T_TERMINAL field of the process control block for the process, or, if that is empty, for the nearest ancestor process (if any) where the PCB$T_TERMINAL field is not empty.
ACME$_AUTH_MECHANISM
The ACME$_AUTH_MECHANISM item code is an input item code. It specifies the authentication mechanism applicable to an authentication request. The buffer must contain a longword value specifying the desired mechanism code. If not specified, the authenticating domain of interpretation applies its default mechanism.
The $ACMEDEF macro defines the following symbols for the standard mechanism types:
ACMEMECH$K_CHALLENGE_RESPONSE
ACMEMECH$K_PASSWORD

Individual ACME agents may define their own authentication mechanisms specific to their domain of interpretation.
ACME$_AUTHENTICATING_DOI_ID
The ACME$_AUTHENTICATING_DOI_ID item code is an output item code. It specifies the buffer to receive the agent ID of the domain of interpretation that successfully authenticated the principal.
ACME$_AUTHENTICATING_DOI_NAME
The ACME$_AUTHENTICATING_DOI_NAME item code is an output item code. It specifies the buffer to receive the name of the domain of interpretation that successfully authenticated the principal.
The maximum data returned for this item code is the number of characters represented by the symbol, ACME$K_MAXCHAR_DOI_NAME, so a caller's buffer should be at least that long, with the number of bytes allocated dependent on whether the ACME$M_UCS2_4 function code modifier was specified on the call to $ACM[W].
ACME$_CHAIN
The ACME$_CHAIN item code is an input item code. It specifies the address of the next item list segment to process immediately after processing the current list segment.
The buffer address field in the item descriptor specifies the address of the next item list segment to be processed. The ACME$_CHAIN item code must be last in the item list segment; $ACM treats this as the logical end of the current item list segment. Any item list entries following the ACME$_CHAIN item code are ignored.
On Alpha and Integrity servers platforms, both 32- and 64-bit item lists can be chained together.
ACME$_CHALLENGE_DATA
The ACME$_CHALLENGE_DATA item code is an input item code. It specifies the challenge data that was used as the basis for generating the response data specified by the ACME$_RESPONSE_DATA item code. The meaning of this data is specific to the domain of interpretation for which it is used.

Previous Next Contents Index

	Function Codes
Function Modifiers	Authenticate Principal	Change Password	Event	Free Context	Query	Release Credentials
ACME$M_ACQUIRE_CREDENTIALS	IP
ACME$M_COPY_PERSONA	<>
ACME$M_DEFAULT_PRINCIPAL	<>	<>
ACME$M_FOREIGN_POLICY_HINTS	SR
ACME$M_MERGE_PERSONA	<>
ACME$M_NOAUDIT	SR
ACME$M_NOAUTHORIZATION	SR
ACME$M_OVERRIDE_MAPPING	IR
ACME$M_TIMEOUT
ACME$M_UCS2_4	<>	<>	<>		<>	<>

	Function Codes
Item Codes	Authenticate Principal	Change Password	Event	Free Context	Query	Release Credentials
ACME$_ACCESS_MODE	<>
ACME$_ACCESS_PORT (U)	IR	IR
ACME$_AUTH_MECHANISM	<>
ACME$_AUTHENTICATING_DOI_ID (O)	<>	<>
ACME$_AUTHENTICATING_DOI_NAME (U,O)	<>	<>
ACME$_CHAIN	<>	<>	<>		<>	<>
ACME$_CHALLENGE_DATA	IR
ACME$_CONTEXT_ACME_ID (U)	<>	<>
ACME$_CONTEXT_ACME_NAME	<>	<>
ACME$_CREDENTIALS_NAME (U)						<>++
ACME$_CREDENTIALS_TYPE						<>++
ACME$_DIALOGUE_SUPPORT	<>	<>
ACME$_EVENT_DATA_IN			<>
ACME$_EVENT_DATA_OUT (O)			<>
ACME$_EVENT_TYPE			<>
ACME$_LOCALE (U)	<>	<>
ACME$_LOGON_INFORMATION (O)	<>
ACME$_LOGON_TYPE	<>
ACME$_MAPPED_VMS_USERNAME (U,O)	<>	<>
ACME$_MAPPING_ACME_ID (O)	<>	<>
ACME$_MAPPING_ACME_NAME (U,O)	<>	<>
ACME$_NEW_PASSWORD_1 (U)	<>	<>
ACME$_NEW_PASSWORD_2 (U)	<>	<>
ACME$_NEW_PASSWORD_FLAGS	<>	<>
ACME$_NEW_PASSWORD_SYSTEM (U)	SR	SR
ACME$_NULL	<>	<>	<>		<>	<>
ACME$_PASSWORD_1 (U)	<>	<>
ACME$_PASSWORD_2 (U)	<>	<>
ACME$_PASSWORD_SYSTEM (U)	<>	<>
ACME$_PERSONA_HANDLE_IN	<>
ACME$_PERSONA_HANDLE_OUT (O)	<>
ACME$_PHASE_TRANSITION (O)
ACME$_PRINCIPAL_NAME_IN (U)	<>	<>
ACME$_PRINCIPAL_NAME_OUT (U,O)	<>	<>
ACME$_QUERY_DATA (O)					<>+
ACME$_QUERY_KEY_TYPE					<>+
ACME$_QUERY_KEY_VALUE					<>+
ACME$_QUERY_TYPE					<>+
ACME$_REMOTE_HOST_ADDRESS	IR	IR
ACME$_REMOTE_HOST_ADDRESS_TYPE	IR	IR
ACME$_REMOTE_HOST_FULLNAME (U)	IR	IR
ACME$_REMOTE_HOST_NAME (U)	IR	IR
ACME$_REMOTE_USERNAME (U)	IR	IR
ACME$_RESPONSE_DATA	<>
ACME$_SERVER_NAME_IN (U)				<>
ACME$_SERVER_NAME_OUT (U,O)				<>
ACME$_SERVICE_NAME (U)	IR	IR	IR	IR	IR	IR
ACME$_TARGET_DOI_ID	<>	<>	<>++		<>++
ACME$_TARGET_DOI_NAME (U)	<>	<>	<>++		<>++
ACME$_TIMEOUT_INTERVAL