HP OpenVMS System Services Reference Manual
$ACM
The $ACM service provides a common interface to all functions supported
by the Authentication and Credential Management (ACM) authority.
The caller must specify the function code and any applicable function
modifiers and item codes for the requested operation.
The $ACM service completes asynchronously; for synchronous completion,
use the $ACMW form of the service.
Format
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);
Arguments
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:
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:
- 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 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.
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.
|
|
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:
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 HP 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:
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.
|
See the Description section for information relating to the modes of
operation and privilege requirements.
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
| 
