 |
OpenVMS System Services Reference Manual
Object handles vary according to the associated security object class.
Currently, the only supported object handles are for the file and
device class objects where the object handle is a word or longword
channel.
The objpro and objnam arguments are
mutually exclusive unless the objpro argument is a
simple object handle. The objpro and
usrpro arguments are also mutually exclusive unless
the objpro argument is an object handle.
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 $CREATE_USER_PROFILE service can be used to construct a user
security profile. The usrpro and
usrnam arguments are mutually exclusive. The
objpro and usrpro arguments are also
mutually exclusive unless the objpro argument is an
object handle.
The item codes used with $CHECK_ACCESS are described in the following
list and are defined in the $CHPDEF system macro library.
Item Codes
CHP$_ACCESS
A longword bit mask that represents the desired access ($ARMDEF). Only
those bits set in CHP$_ACCESS are checked against the protection of the
object to determine whether access is granted.
The default for CHP$_ACCESS is read. Symbolic representations for the
access types associated with the built-in protected classes are found
in the $ARMDEF macro.
For example, ARM$M_MANAGE specifies Manage access for the queue class
object. Access type names are object class specific and vary from class
to class. Because $CHECK_ACCESS performs only a bitwise comparison of
access desired to object protection, the original Read, Write, Execute,
and Delete names can also be used to specify the first four access
types for any object class.
The following table shows the access types available and lists their
common interpretations. These symbols are defined in the $ARMDEF system
macro library. For more information, refer to the OpenVMS Guide to System Security.
| Access Type |
Access Permitted |
|
ARM$M_READ
|
Allows holders to read an object, perform wildcard directory lookups,
display jobs in a queue, or use an associated vector processor.
|
|
ARM$M_WRITE
|
Allows holders to alter the contents of an object, remove a directory
entry, write or extend existing files on a volume, or submit a job to a
queue.
|
|
ARM$M_EXECUTE
|
Allows holders to run an image or command procedure, perform exact
directory lookups, issue physical I/O requests to a device, create new
files on a volume, or act as operator for a queue.
|
|
ARM$M_DELETE
|
Allows holders to delete an object, perform logical I/O to a device, or
delete a job in a queue.
|
|
ARM$M_CONTROL
|
Allows holders to display or alter the security characteristics of an
object.
|
CHP$_ACMODE
A byte that defines the accessor's processor access mode ($PSLDEF). The
following access modes and their symbols are defined in the system
macro library ($PSLDEF). Objects supported by the operating system do
not consider access mode in determining object access.
| 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$_ALARMNAME
Address of a buffer to receive the alarm name from any Alarm ACE
contained in the object's ACL. Currently, if a matching Alarm ACE
exists, the string SECURITY will be returned. The string returned by
CHP$_ALARMNAME can be used as input to the $AUDIT_EVENT system service,
using the NSA$_ALARM_NAME item code.
CHP$_AUDIT_LIST
A list containing information to be added to 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 $CHECK_ACCESS. 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. Currently, if a matching Audit ACE
exists, the string SECURITY will be returned. The string returned by
CHP$_AUDITNAME can be used as input to the $AUDIT_EVENT system service,
using the NSA$_AUDIT_NAME item code.
CHP$_FLAG
A longword that controls 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. These symbols are
defined 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$V_OBSERVE.
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
A variable-length data structure containing the first Identifier ACE in
the ACL that granted or denied access to the object. The $FORMAT_ACL
system service describes the format of an Identifier ACE.
CHP$_PRIVUSED
A longword mask of flags that represent the privileges used to gain
access.
You can also obtain the values as masks with the appropriate bit set by
using the prefix CHP$M rather than CHP$V. The symbols are defined in
the system macro library ($CHPDEF). The following symbols are offsets
to the bits within the longword:
| Symbol |
Meaning |
|
CHP$V_SYSPRV
|
SYSPRV was used to gain the requested access.
|
|
CHP$V_GRPPRV
|
GRPPRV was used to gain the requested access.
|
|
CHP$V_BYPASS
|
BYPASS was used to gain the requested access.
|
|
CHP$V_READALL
|
READALL was used to gain the requested access.
|
|
CHP$V_OPER
|
OPER was used to gain the requested access.
|
|
CHP$V_GRPNAM
|
GRPNAM was used to gain the requested access.
|
|
CHP$V_SYSNAM
|
SYSNAM was used to gain the requested access.
|
|
CHP$V_GROUP
|
GROUP was used to gain the requested access.
|
|
CHP$V_WORLD
|
WORLD was used to gain the requested access.
|
|
CHP$V_PRMCEB
|
PRMCEB was used to gain the requested access.
|
|
CHP$V_UPGRADE
|
UPGRADE was used to gain the requested access.
|
|
CHP$V_DOWNGRADE
|
DOWNGRADE was used to gain the requested access.
|
Description
The Check Access service invokes the operating system control
protection check mechanism, $CHKPRO, to determine whether a named user
is allowed the described access to the named object. A file server, for
example, might check the access attributes of a user who attempts to
access a file (the object).
If the user can access the object, $CHECK_ACCESS returns the SS$_NORMAL
status code; otherwise, $CHECK_ACCESS returns SS$_NOPRIV.
The arguments accepted by this service specify the name and class of
object being accessed, the name of the user requesting access to the
object, the type of access desired, and the type of information to be
returned.
The caller can also request that an object access audit be performed if
security auditing has been enabled for the object class or if Audit
ACEs are contained in the object's ACL. Auditing ACEs include both
Alarm ACEs and Audit ACEs. The CHP$V_AUDIT flag requests an access
audit. This requires that the caller be in executive or kernel mode or
possess the AUDIT privilege.
Normally, $CHECK_ACCESS generates an object access audit when an audit
is required. The caller can specify the CHP$V_CREATE flag to force an
object creation audit instead of an object access audit. Similarly, the
CHP$V_DELETE flag forces an object deletion audit. The CHP$_AUDIT_LIST
item code can be used to specify additional information to be included
in any resulting audit records.
With certain types of devices, $CHECK_ACCESS can return a false
negative, but never a false positive. This is due to additional LOG_IO
and PHY_IO privilege checking in the $QIO system service that might
override an otherwise unsuccessful access attempt. These privilege
checks are not mirrored by the $CHECK_ACCESS system service. The
affected devices are those that are non-file-structured or mounted
foreign and also either spooled, file-oriented, or shareable. For
example, mailbox devices fall into this category because they are
non-file-structured and shareable. To accurately duplicate the result
that would be obtained if the user had issued a read or write against
these devices, it might be necessary to test for these additional
privileges using the $CHECK_PRIVILEGE system service. Refer to the
OpenVMS I/O User's Reference Manual for further information on access requirements for devices.
Required Access or Privileges
Access to SYSUAF.DAT and RIGHTSLIST.DAT is required. AUDIT privilege is
required when requesting a user mode audit.
Required Quota
None
Related Services
$CHKPRO, $CREATE_USER_PROFILE, $FORMAT_ACL
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the desired access is granted.
|
|
SS$_ACCVIO
|
The item list cannot be read by the caller, one of the buffers
specified in the item list cannot be written by the caller, or one of
the arguments could not be read or written.
|
|
SS$_BADPARAM
|
Invalid or conflicting combination of parameters.
|
|
SS$_INSFARG
|
Insufficient information to identify object or user.
|
|
SS$_INSFMEM
|
Insufficient process memory to execute service.
|
|
SS$_NOAUDIT
|
Caller lacks privilege to request audit.
|
|
SS$_NOCALLPRIV
|
Caller lacks privilege to access authorization database.
|
|
SS$_NOCLASS
|
No matching object class was located.
|
|
SS$_NOPRIV
|
The desired access is not granted.
|
|
SS$_UNSUPPORTED
|
Operations on remote object are not supported.
|
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, 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 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.
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.
|
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.
|
|
