OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

If CHP$V_AUDIT is specified, any error from the $AUDIT_EVENT system service can also be returned.

$CHECK_FEN (Alpha Only)

On Alpha systems, indicates whether floating point is enabled for the current image.

Format

SYS$CHECK_FEN

C Prototype

int sys$check_fen (void);

Arguments

None.

Description

The Check Floating Point service returns a Boolean value in R0 indicating whether floating point is enabled for the current image.
The $CHECK_FEN service returns a value of 1 if the floating point is enabled for the current image. A value of 0 is returned if the floating point is disabled.
Required Access or Privileges

None
Required Quota

None

$CHECK_PRIVILEGE

Determines whether the caller has the specified privileges or identifier. In addition to checking for a privilege or an identifier, $CHECK_PRIVILEGE determines if the caller's use of privilege needs to be audited.

Format

SYS$CHECK_PRIVILEGE [efn] ,prvadr ,[altprv] ,[flags] ,[itmlst] ,[audsts] ,[astadr] ,[astprm]

C Prototype

int sys$check_privilege (unsigned int efn, struct _generic_64 *prvadr, struct _generic_64 *altprv, unsigned int flags, void *itmlst, unsigned int *audsts, 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 to be set when the audit completes. The efn argument is a longword containing the number of the event flag; however, $CHECK_PRIVILEGE uses only the low-order byte. If efn is not specified, event flag 0 is used.
Upon request initiation, $CHECK_PRIVILEGE clears the specified event flag.
prvadr

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by reference

The privilege or identifier to be checked. The prvadr argument is either the address of a quadword bit array, where each bit corresponds to a privilege, or the address of a quadword identifier.
When the array lists privileges, each bit has a symbolic name. The $PRVDEF macro defines these names. You form the bit array by specifying the symbolic name of each desired privilege in a logical OR operation. See the $SETPRV system service for the symbolic name and description of each privilege.
If the caller passes an identifier, the caller must set the NSA$M_IDENTIFIER bit in the flags longword. The identifier structure is defined by the $KGBDEF macro. The identifier attributes (KGB$) are reserved for future use and should be set to 0.
altprv

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by reference

Alternate privilege mask to check against. The altprv argument is the address of a quadword privilege mask, where each bit corresponds to a privilege. This argument and the flags NSA$M_AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually exclusive.
With this argument, $CHECK_PRIVILEGE uses the supplied set of privileges instead of the current, active privileges. Each bit in the mask has a symbolic name, defined by the $PRVDEF macro. You form the bit array by specifying the symbolic name of each desired privilege in a logical OR operation. See the $SETPRV system service for the symbolic name and description of each privilege.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Flags that specify options for the $CHECK_PRIVILEGE operation. The flags argument is a longword bit mask, where each bit corresponds to an option.
Each flag option has a symbolic name. The $NSADEF macro defines the following symbolic names. Be aware that the flags NSA$M_AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually exclusive; therefore, you can specify only one of these flag options.

Symbolic Name Description

NSA$M_AUTHPRIV Checks the authorized privileges of the process instead of the current (active) privileges.

NSA$M_FLUSH Specifies that all messages in the audit server buffer be written to the audit log file.

NSA$M_IDENTIFIER Interprets the prvadr argument as the address of an identifier instead of a privilege mask.

NSA$M_INTERNAL Specifies that the $CHECK_PRIVILEGE call originates in the context of a trusted computing base (TCB) component. The auditing components use this flag to indicate that internal auditing failures should result in a SECAUDTCB bugcheck. This flag is reserved to Compaq.

NSA$M_MANDATORY Specifies that an audit is to be performed, regardless of system alarm and audit settings.

NSA$M_PROCPRIV Checks the permanent privileges of the process, instead of the privileges in the current (active) mask.

NSA$M_SERVER Indicates that the call originates in a TCB server process and that the event should be audited regardless of the state of a process-specific no-audit bit.
Trusted servers use this flag to override the no-audit bit when they want to perform explicit auditing on behalf of a client process. This flag is reserved to Compaq.

itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list specifying additional security auditing information to be included in any security audit that is generated by the service. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a longword of 0.
The item list is a standard format item list. The following diagram depicts the format of a single item descriptor.

Symbolic Name	Description
NSA$M_AUTHPRIV	Checks the authorized privileges of the process instead of the current (active) privileges.
NSA$M_FLUSH	Specifies that all messages in the audit server buffer be written to the audit log file.
NSA$M_IDENTIFIER	Interprets the prvadr argument as the address of an identifier instead of a privilege mask.
NSA$M_INTERNAL	Specifies that the $CHECK_PRIVILEGE call originates in the context of a trusted computing base (TCB) component. The auditing components use this flag to indicate that internal auditing failures should result in a SECAUDTCB bugcheck. This flag is reserved to Compaq.
NSA$M_MANDATORY	Specifies that an audit is to be performed, regardless of system alarm and audit settings.
NSA$M_PROCPRIV	Checks the permanent privileges of the process, instead of the privileges in the current (active) mask.
NSA$M_SERVER	Indicates that the call originates in a TCB server process and that the event should be audited regardless of the state of a process-specific no-audit bit. Trusted servers use this flag to override the no-audit bit when they want to perform explicit auditing on behalf of a client process. This flag is reserved to Compaq.

The following table defines the item descriptor fields.

Descriptor Field Definition

Buffer length A word specifying the length of the buffer in bytes. The buffer supplies information to be used by $CHECK_PRIVILEGE. The required length of the buffer varies, depending on the item code specified; each item code description specifies the required length.

Item code A word containing a symbolic code describing the nature of the information currently in the buffer or to be returned in the buffer. The location of the buffer is pointed to by the buffer address field. Each item code has a symbolic name.

Buffer address A longword containing the address of the buffer that specifies or receives the information.

Return length address Not currently used; this field is reserved to Compaq. You should specify 0.

Descriptor Field	Definition
Buffer length	A word specifying the length of the buffer in bytes. The buffer supplies information to be used by $CHECK_PRIVILEGE. The required length of the buffer varies, depending on the item code specified; each item code description specifies the required length.
Item code	A word containing a symbolic code describing the nature of the information currently in the buffer or to be returned in the buffer. The location of the buffer is pointed to by the buffer address field. Each item code has a symbolic name.
Buffer address	A longword containing the address of the buffer that specifies or receives the information.
Return length address	Not currently used; this field is reserved to Compaq. You should specify 0.

All item codes listed in the Item Codes section of the $AUDIT_EVENT service are valid within the item list used by the $CHECK_PRIVILEGE service except for the NSA$_EVENT_TYPE and NSA$_EVENT_SUBTYPE item codes, which are supplied internally by the $CHECK_PRIVILEGE service.

$CHECK_PRIVILEGE should be called with an item list identifying the alarm and audit journals, and does not need to use the NSA$_PRIVS_USED item code. NSA$_PRIVS_USED is supplied automatically by the $CHECK_PRIVILEGE service. Note that $CHECK_PRIVILEGE returns SS$_BADPARAM if you supply either NSA$_EVENT_TYPE or NSA$_EVENT_SUBTYPE. These items are supplied internally by $CHECK_PRIVILEGE.

audsts

OpenVMS usage:	cond_value_type
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Longword condition value that receives a final completion status from the operation. If a security audit is required, the final completion status represents either the successful completion of the resulting security audit or any failing status that occurred while the security audit was performed within the AUDIT_SERVER process.

The audsts argument is valid only when the service returns success and the status is not SS$_EVTNOTENAB. In addition, the caller must either make use of the astadr argument or use the $CHECK_PRIVILEGEW service before attempting to access audsts.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

Asynchronous system trap (AST) routine to be executed after the audsts argument is written. The astadr argument, which is the address of a longword value, is the procedure value of the AST routine.

The AST routine executes in the access mode of the caller of $CHECK_PRIVILEGE.

astprm

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Asynchronous system trap (AST) parameter passed to the AST service routine. The astprm argument is a longword value containing the AST parameter.

Description

The Check Privilege service determines whether a user has the privileges or identifier that an operation requires. In addition, $CHECK_PRIVILEGE audits the use of privilege if privilege auditing has been enabled by the site security administrator. The caller does not need to determine whether privilege auditing has been enabled.
Required Access or Privileges

AUDIT privilege is required.
Required Quota

None
Related Services

$AUDIT_EVENT, $SETPRV

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The specified parameter of the item list buffer is not accessible.

SS$_BADBUFADR The buffer address is invalid or not readable.

SS$_BADBUFLEN The specified buffer length is invalid or out of range.

SS$_BADCHAIN The address of the next item list to be processed, as identified in the buffer address field, is either not readable or points to itself.

SS$_BADITMCOD The specified item code is invalid or out of range.

SS$_BADPARAM The specified list entry is invalid or out of range.

SS$_EVTNOTENAB No audit required; privilege granted.

SS$_ILLEFC You specified an illegal event flag number.

SS$_INSFARG The required item code is not present.

SS$_INVAJLNAM The alarm or audit journal name is invalid.

SS$_IVSTSFLG The specified system service flags are invalid.

SS$_NOAUDIT The caller does not have the required privilege to perform the audit.

SS$_NOPRIV The subject does not have the required privileges or identifier.

SS$_NO[privilege-name] The subject does not have a specific privilege.

SS$_OVRMAXAUD There is insufficient memory to perform the audit.

SS$_TOOMANYAJL Too many alarm or audit journals were specified.

SS$_UNASEFC An unassociated event flag cluster was specified.

$CHECK_PRIVILEGEW

Determines whether the caller has the specified privileges or identifier. In addition to checking for a privilege or an identifier, the Check Privilege and Wait service determines if the caller's use of privilege needs to be audited.
$CHECK_PRIVILEGEW completes synchronously; that is, it returns the final status to the caller only after receiving an explicit confirmation from the audit server that the associated audit, if enabled, has been performed.

Format

SYS$CHECK_PRIVILEGEW efn ,prvadr ,[altprv] ,[flags] ,[itmlst] ,audsts ,[astadr] ,[astprm]

C Prototype

int sys$check_privilegew (unsigned int efn, struct _generic_64 *prvadr, struct _generic_64 *altprv, unsigned int flags, void *itmlst, unsigned int *audsts, void (*astadr)(__unknown_params), int astprm);

$CHKPRO

Determines whether an accessor with the specified rights and privileges can access an object with the specified attributes.

Format

SYS$CHKPRO itmlst ,[objpro] ,[usrpro]

C Prototype

int sys$chkpro (void *itmlst, void *objpro, void *usrpro);

Argument

itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Protection attributes of the object and the rights and privileges of the accessor. The itmlst argument is the address of an item list of descriptors used to specify the protection attributes of the object and the rights and privileges of the accessor.
The following diagram depicts the format of a single item descriptor.

The following table defines the item descriptor fields.

Descriptor Field Definition

Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the associated buffer. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data.

Item code A word containing a user-supplied symbolic code specifying the item of information in the associated buffer. The item codes are defined in the $ACLDEF system macro library.

Buffer address A longword containing the user-supplied address of the buffer.

Return length address A longword that normally contains the user-supplied address of a word in which the service writes the length in bytes of the information it returned. This is not used by $CHKPRO and should contain a 0.

Descriptor Field	Definition
Buffer length	A word containing a user-supplied integer specifying the length (in bytes) of the associated buffer. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data.
Item code	A word containing a user-supplied symbolic code specifying the item of information in the associated buffer. The item codes are defined in the $ACLDEF system macro library.
Buffer address	A longword containing the user-supplied address of the buffer.
Return length address	A longword that normally contains the user-supplied address of a word in which the service writes the length in bytes of the information it returned. This is not used by $CHKPRO and should contain a 0.

Specifying any specific protection attribute causes that protection check to be made; any protection attribute not specified is not checked. Rights and privileges specified are used as needed. If a protection check requires any right or privilege not specified in the item list, the right or privilege of the caller's process is used.

objpro

OpenVMS usage:	char_string
type:	opaque byte stream
access:	read only
mechanism:	by descriptor

Buffer containing an object security profile. The objpro argument is the address of a descriptor pointing to a buffer that contains an encoded object security profile. The objpro argument eliminates the need to supply all of the component object protection attributes with the $CHKPRO item list. The objpro argument is currently reserved to Compaq.

usrpro

OpenVMS usage:	char_string
type:	opaque byte stream
access:	read only
mechanism:	by descriptor

Buffer containing a user security profile. The usrpro argument is the address of a descriptor pointing to a buffer that contains an encoded user security profile. The usrpro argument eliminates the need to supply all of the component user security attributes with the $CHKPRO item list. The $CREATE_USER_PROFILE service can be used to construct a user security profile. When the usrpro argument is specified, any component user profile attributes specified in the $CHKPRO item list replace those contained in the user security profile.

The item codes used with $CHKPRO are described in following list and are defined in the $CHPDEF system macro library.

Item Codes

CHP$_ACCESS
A longword bit mask representing the type of access desired ($ARMDEF). Be aware that the $CHKPRO service does not interpret the bits in the access mask; instead, it compares them to the object's protection mask (CHP$_PROT). Any bits not specified by CHP$_ACCESS or CHP$_PROT are assumed to be clear, which grants access.
CHP$_ACL
A vector that points to an object's access control list. The buffer address, bufadr, specifies a buffer containing one or more ACEs. The number that specifies the length of the CHP$_ACL buffer, buflen, must be equal to the sum of all ACE lengths. The format of the ACE structure depends on the value of the second byte in the structure, which specifies the ACE type. The $FORMAT_ACL system service description describes each ACE type and its format.
You can specify the CHP$_ACL item multiple times to point to multiple segments of an access control list. You can specify a maximum of 20 segments. The segments are processed in the order specified.
CHP$_ACMODE
A byte that defines the accessor's processor access mode. The following access modes and their symbols are defined in the $PSLDEF macro.

Symbol Access Mode

PSL$C_USER User

PSL$C_SUPER Supervisor

PSL$C_EXEC Executive

PSL$C_KERNEL Kernel

If CHP$_ACMODE is not specified, access mode is not used to determine access.
CHP$_ADDRIGHTS
A vector that points to an additional rights list segment to be appended to the existing rights list. Each entry of the rights list is a quadword data structure consisting of a longword containing the identifier value, followed by a longword containing a mask identifying the attributes of the holder. The $CHKPRO service ignores the attributes.
A maximum of 11 rights descriptors is allowed. If you specify CHP$_ADDRIGHTS without specifying CHP$_RIGHTS, the accessor's rights list consists of the rights list specified by the CHP$_ADDRIGHTS item codes and the rights list of the current process.
If you specify CHP$_RIGHTS and CHP$_ADDRIGHTS, you should be aware of the following:

CHP$_RIGHTS must come first.
The accessor's UIC is the identifier of the first entry in the rights list specified by the CHP$_RIGHTS item code.
The accessor's rights list consists of the rights list specified by the CHP$_RIGHTS item code and the CHP$_ADDRIGHTS item codes.

CHP$_ALARMNAME
Address of a buffer to receive the alarm name from any Alarm ACE contained in the object's ACL. If the object does not have security alarms enabled, $CHKPRO returns retlenadr as 0. If a matching Alarm ACE exists, the string SECURITY will be returned.
CHP$_AUDIT_LIST
A security auditing item list containing additional information to be included in any resulting security audit. The bufadr argument points to the beginning of an $AUDIT_EVENT item list. See the itmlst argument of the $AUDIT_EVENT system service for a list of valid security auditing item codes. Note that the NSA$_EVENT_TYPE and NSA$_EVENT_SUBTYPE items are ignored when auditing with $CHKPRO. The CHP$V_AUDIT flag must be specified.
CHP$_AUDITNAME
Address of a buffer to receive the audit name from any Audit ACE contained in the object's ACL. If the object does not have auditing enabled, $CHKPRO returns retlenadr as 0. If a matching Audit ACE exists, the string SECURITY will be returned.
CHP$_FLAGS
A longword that defines various aspects of the protection check. The symbols in the following table are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set by using the prefix CHP$M rather than CHP$V. The following symbols are defined only in the system macro library ($CHPDEF).

Symbol Access

CHP$V_ALTER Accessor desires write access to object.

CHP$V_AUDIT Access audit requested.

CHP$V_CREATE Perform the audit as an object creation event.

CHP$V_DELETE Perform the audit as an object deletion event.

CHP$V_FLUSH Force audit buffer flush.

CHP$V_INTERNAL Audit on behalf of the Trusted Computing Base (TCB). Reserved to Compaq.

CHP$V_MANDATORY Force the object access event to be audited.

CHP$V_NOFAILAUD Do not perform audits for failed access.

CHP$V_NOSUCCAUD Do not perform audits for successful access.

CHP$V_OBSERVE Accessor desires read access to object.

CHP$V_SERVER Audit on behalf of a TCB server process.

CHP$V_USEREADALL Accessor is eligible for READALL privilege.

The default for CHP$_FLAG is CHP$M_OBSERVE and CHP$M_ALTER.
The primary purpose of the CHP$V_OBSERVE and CHP$V_ALTER flags is as latent support for a mandatory (lattice) security policy, such as that provided by the Security Enhanced VMS (SEVMS) offering.
CHP$_MATCHEDACE
This output item is a variable-length data structure containing the first Identifier ACE in the object's ACL that allowed or denied the accessor to access the object. See the $FORMAT_ACL system service for a description of an Identifier ACE format.
CHP$_MODE
A byte that defines the object's owner access mode. The following access modes of the object's owner and their symbols are defined in the system macro library ($PSLDEF).

Symbol Access Mode

PSL$C_USER User

PSL$C_SUPER Supervisor

PSL$C_EXEC Executive

PSL$C_KERNEL Kernel

CHP$_MODES
A quadword that defines the object's access mode protection. You specify a 2-bit access mode as shown in CHP$_MODE for each possible access type. The following diagram illustrates the format of an access mode vector for bit numbers.

Symbol	Access Mode
PSL$C_USER	User
PSL$C_SUPER	Supervisor
PSL$C_EXEC	Executive
PSL$C_KERNEL	Kernel

Symbol	Access
CHP$V_ALTER	Accessor desires write access to object.
CHP$V_AUDIT	Access audit requested.
CHP$V_CREATE	Perform the audit as an object creation event.
CHP$V_DELETE	Perform the audit as an object deletion event.
CHP$V_FLUSH	Force audit buffer flush.
CHP$V_INTERNAL	Audit on behalf of the Trusted Computing Base (TCB). Reserved to Compaq.
CHP$V_MANDATORY	Force the object access event to be audited.
CHP$V_NOFAILAUD	Do not perform audits for failed access.
CHP$V_NOSUCCAUD	Do not perform audits for successful access.
CHP$V_OBSERVE	Accessor desires read access to object.
CHP$V_SERVER	Audit on behalf of a TCB server process.
CHP$V_USEREADALL	Accessor is eligible for READALL privilege.

Symbol	Access Mode
PSL$C_USER	User
PSL$C_SUPER	Supervisor
PSL$C_EXEC	Executive
PSL$C_KERNEL	Kernel

Each pair of bits in the access mode vector represents the access mode for the specific type of access. For example, bits <6:7> represent the access mode value used to check for delete access.

CHP$_OBJECT_CLASS

A character string containing the protected object class associated with the object. The object class string is used to determine whether any security auditing is enabled for the object access event. This item code is required when the CHP$_AUDIT flag is specified.

CHP$_OBJECT_NAME

A character string containing the object name associated with the protection check. The object name string is included in any resulting security audit. If an object name string is not specified, the string "<not available>" is substituted in any security audit for all protected object classes other than FILE. For FILE class audits, it is assumed that the caller has supplied an object name by using the auditing item list (NSA$_OBJECT_NAME).

CHP$_OWNER

A longword describing the object's owner identifier (UIC or general identifier). This might be either a UIC format identifier or a general identifier.

Contents

Index

Legal

 
4527PRO_008.HTML

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The specified parameter of the item list buffer is not accessible.
SS$_BADBUFADR	The buffer address is invalid or not readable.
SS$_BADBUFLEN	The specified buffer length is invalid or out of range.
SS$_BADCHAIN	The address of the next item list to be processed, as identified in the buffer address field, is either not readable or points to itself.
SS$_BADITMCOD	The specified item code is invalid or out of range.
SS$_BADPARAM	The specified list entry is invalid or out of range.
SS$_EVTNOTENAB	No audit required; privilege granted.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_INSFARG	The required item code is not present.
SS$_INVAJLNAM	The alarm or audit journal name is invalid.
SS$_IVSTSFLG	The specified system service flags are invalid.
SS$_NOAUDIT	The caller does not have the required privilege to perform the audit.
SS$_NOPRIV	The subject does not have the required privileges or identifier.
SS$_NO[privilege-name]	The subject does not have a specific privilege.
SS$_OVRMAXAUD	There is insufficient memory to perform the audit.
SS$_TOOMANYAJL	Too many alarm or audit journals were specified.
SS$_UNASEFC	An unassociated event flag cluster was specified.