 |
HP OpenVMS System Services Reference Manual
If CHP$V_AUDIT is specified, any error from the $AUDIT_EVENT system
service can also be returned.
$CHECK_FEN (Alpha and I64)
On Alpha and I64 systems, indicates whether floating point is enabled
for the current image.
Format
SYS$CHECK_FEN [flags]
C Prototype
int sys$check_fen (unsigned int *flags);
Arguments
flags
| OpenVMS usage: |
mask longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
For architectures that have multiple floating-point resources that can
be enabled separately, this longword is returned with a bitmask
indicating which resources are enabled. On Alpha systems, no separate
resources exist; nothing is returned. On I64 systems, the bitmask has
two bits: bit 0 for the low floating-point bank and bit 1 for the high
floating-point bank.
Description
The Check Floating Point service returns a Boolean value in R0
indicating whether any floating point resources are 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.
An optional longword, passed by reference, can be specified to receive
architecture-dependent information about the floating-point resources
in use.
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, privileges, or identifier that the calling process must
possess.
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 HP.
|
|
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 HP.
|
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.
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 HP. 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 argument list contains too few arguments for the service.
|
|
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.
|
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 HP.
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 the 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 HP.
|
|
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:
|
