OpenVMS System Services Reference Manual
Application ACE
The Application ACE contains application-dependent information. Its
format is as follows:
The following table describes the ACE fields and lists the symbol name
for each:
| Field |
Symbol Name |
Description |
|
Length
|
ACE$B_SIZE
|
Byte containing the length in bytes of the ACE buffer.
|
|
Type
|
ACE$B_TYPE
|
Byte containing the type value ACE$C_INFO
|
|
Flags
|
ACE$W_FLAGS
|
Word containing Application ACE information and ACE type-independent
information
|
|
Application mask
|
ACE$L_INFO_FLAGS
|
Longword containing a mask defined and used by the application
|
|
Application information
|
ACE$T_INFO_START
|
Variable-length data structure defined and used by the application. The
length of this data is implied by the length field
|
The flag field contains information specific to Application ACEs and
information applicable to all types of ACEs. The following symbol is a
bit offset to the Application ACE information:
| Bit |
Meaning When Set |
|
ACE$V_INFO_TYPE
|
Four-bit field containing a value indicating whether the application is
a CSS application (ACE$C_CSS) or a customer application (ACE$C_CUST).
|
The following symbols are bit offsets to ACE information that is
independent of ACE type:
| Bit |
Meaning When Set |
|
ACE$V_DEFAULT
|
This ACE is added to the ACL of any file created in the directory whose
ACL contains this ACE. This bit is applicable only for an ACE in a
directory file's ACL.
|
|
ACE$V_HIDDEN
|
This bit is application dependent. You cannot use the DCL ACL commands
and the ACL editor to change the setting; the DCL command DIRECTORY/ACL
does not display it.
|
|
ACE$V_NOPROPAGATE
|
This ACE is not propagated among versions of the same file.
|
|
ACE$V_PROTECTED
|
This ACE is not deleted if the entire ACL is deleted; instead, you must
delete this ACE explicitly.
|
Audit ACE
The Audit ACE sets a security audit. Its format is as follows:
The following table describes the ACE fields and lists the symbol name
for each:
| Field |
Symbol Name |
Description |
|
Length
|
ACE$B_SIZE
|
Byte containing the length in bytes of the ACE buffer
|
|
Type
|
ACE$B_TYPE
|
Byte containing the type value ACE$C_AUDIT
|
|
Flags
|
ACE$W_FLAGS
|
Word containing Audit ACE information and ACE type-independent
information
|
|
Access
|
ACE$L_ACCESS
|
Longword containing a mask indicating the access modes to be watched
|
|
Alarm name
|
ACE$T_AUDITNAME
|
Character string containing the alarm name
|
The following symbols are bit offsets to ACE information that is
independent of ACE type:
| Bit Position |
Meaning When Set |
|
ACE$V_DEFAULT
|
This ACE is added to the ACL of any file created in the directory whose
ACL contains this ACE. This bit is applicable only for an ACE in a
directory file's ACL.
|
|
ACE$V_HIDDEN
|
This ACE is application dependent. You cannot use the DCL ACL commands
and the ACL editor to change the setting; the DCL command DIRECTORY/ACL
does not display it.
|
|
ACE$V_NOPROPAGATE
|
This ACE is not propagated among versions of the same file.
|
|
ACE$V_PROTECTED
|
This ACE is not deleted if the entire ACL is deleted; instead, you must
delete this ACE explicitly.
|
The following symbol values are offsets to bits within the access mask.
You can also obtain the symbol values as masks with the appropriate bit
set using the prefix ACE$M rather than ACE$V.
| Bit |
Meaning When Set |
|
ACE$V_READ
|
Read access is monitored.
|
|
ACE$V_WRITE
|
Write access is monitored.
|
|
ACE$V_EXECUTE
|
Execute access is monitored.
|
|
ACE$V_DELETE
|
Delete access is monitored.
|
|
ACE$V_CONTROL
|
Modification of the access field is monitored.
|
Creator ACE
The Creator ACE controls access to an object based on creators. Its
format is as follows:
The following table describes the ACE fields and lists the symbol name
for each:
| Field |
Symbol Name |
Description |
|
Length
|
ACE$B_SIZE
|
Byte containing the length in bytes of the ACE buffer.
|
|
Type
|
ACE$B_TYPE
|
Byte containing the type value ACE$C_NEW_OWNER.
|
|
Flags
|
ACE$W_FLAGS
|
Word containing Creator ACE information and ACE type-independent
information.
|
|
Access
|
ACE$L_ACCESS
|
Longword containing a mask indicating the access modes to be granted to
the creator of the file.
|
The following symbols are bit offsets to ACE information that is
independent of ACE type:
| Bit |
Meaning When Set |
|
ACE$V_NOPROPAGATE
|
This ACE is not propagated among versions of the same file.
|
|
ACE$V_PROTECTED
|
This ACE is not deleted if the entire ACL is deleted; instead, you must
delete this ACE explicitly.
|
The following symbol values are offsets to bits within the mask
indicating the access mode granted in the system, owner, group, and
world fields:
| Bit Position |
Meaning When Set |
|
ACE$V_READ
|
Read access is granted.
|
|
ACE$V_WRITE
|
Write access is granted.
|
|
ACE$V_EXECUTE
|
Execute access is granted.
|
|
ACE$V_DELETE
|
Delete access is granted.
|
|
ACE$V_CONTROL
|
Modification of the access field is granted.
|
You can also obtain the symbol values as masks with the appropriate bit
set by using the prefix ACE$M rather than ACE$V.
Default Protection ACE
The Default Protection ACE specifies the UIC-based protection for all
files created in the directory. You can use this type of ACE only in
the ACL of a directory file. Its format is as follows:
The following table describes the ACE fields and lists the symbol name
for each:
| Field |
Symbol Name |
Description |
|
Length
|
ACE$B_SIZE
|
Byte containing the length in bytes of the ACE buffer.
|
|
Type
|
ACE$B_TYPE
|
Byte containing the type value ACE$C_DIRDEF.
|
|
Flags
|
ACE$W_FLAGS
|
Word containing ACE type-independent information.
|
|
Spare
|
ACE$L_SPARE1
|
Longword that is reserved for future use and must be 0.
|
|
System
|
ACE$L_SYS_PROT
|
Longword containing a mask indicating the access mode granted to system
users. Each bit represents one type of access.
|
|
Owner
|
ACE$L_OWN_PROT
|
Longword containing a mask indicating the access mode granted to the
owner. Each bit represents one type of access.
|
|
Group
|
ACE$L_GRP_PROT
|
Longword containing a mask indicating the access mode granted to group
users. Each bit represents one type of access.
|
|
World
|
ACE$L_WOR_PROT
|
Longword containing a mask indicating the access mode granted to the
world. Each bit represents one type of access.
|
The flag field contains information applicable to all types of ACEs.
The following symbols are bit offsets to ACE information that is
independent of ACE type:
| Bit Position |
Meaning When Set |
|
ACE$V_HIDDEN
|
This ACE is application dependent. You cannot use the DCL ACL commands
and the ACL editor to change the setting; the DCL command DIRECTORY/ACL
does not display it.
|
|
ACE$V_NOPROPAGATE
|
This ACE is not propagated among versions of the same file.
|
|
ACE$V_PROTECTED
|
This ACE is not deleted if the entire ACL is deleted; instead, you must
delete this ACE explicitly.
|
The system interprets the bits within the access mask as shown in the
following table. The following symbol values are offsets to bits within
the mask indicating the access mode granted in the system, owner,
group, and world fields:
| Bit Position |
Meaning When Bit Is Set |
|
ACE$V_READ
|
Read access is denied.
|
|
ACE$V_WRITE
|
Write access is denied.
|
|
ACE$V_EXECUTE
|
Execute access is denied.
|
|
ACE$V_DELETE
|
Delete access is denied.
|
|
ACE$V_CONTROL
|
Delete access is denied.
|
You can also obtain the symbol values as masks with the appropriate bit
set by using the prefix ACE$M rather than ACE$V.
Identifier ACE
The Identifier ACE controls access to an object based on identifiers.
Its format is as follows:
The following table describes the ACE fields and lists the symbol name
for each:
| Field |
Symbol Name |
Description |
|
Length
|
ACE$B_SIZE
|
Byte containing the length in bytes of the ACE buffer.
|
|
Type
|
ACE$B_TYPE
|
Byte containing the type value ACE$C_KEYID.
|
|
Flags
|
ACE$W_FLAGS
|
Word containing Identifier ACE information and ACE type-independent
information.
|
|
Access
|
ACE$L_ACCESS
|
Longword containing a mask indicating the access mode granted to the
specified identifiers.
|
|
Reserved
|
ACE$V_RESERVED
|
Longwords containing application-specific information. The number of
reserved longwords is specified in the flags field.
|
|
Identifier
|
ACE$L_KEY
|
Longwords containing identifiers. The number of longwords is implied by
ACE$B_SIZE. If an accessor holds all of the listed identifiers, the ACE
is said to match the accessor, and the access specified in ACE$L_ACCESS
is granted.
|
The flags field contains information specific to Identifier ACEs and
information applicable to all types of ACEs. The following symbol is a
bit offset to Identifier ACE information:
| Bit |
Meaning When Set |
|
ACE$V_RESERVED
|
Four-bit field containing the number of longwords to reserve for
application-dependent data. The number must be between 0 and 15. The
reserved longwords, if any, immediately precede the identifiers.
|
The following symbols are bit offsets to ACE information that is
independent of ACE type:
| Bit |
Meaning When Set |
|
ACE$V_DEFAULT
|
This ACE is added to the ACL of any file created in the directory whose
ACL contains this ACE. This bit is applicable only for an ACE in a
directory file's ACL.
|
|
ACE$V_HIDDEN
|
This bit is application dependent. You cannot use the DCL ACL commands
and the ACL editor to change the setting; the DCL command DIRECTORY/ACL
does not display it.
|
|
ACE$V_NOPROPAGATE
|
This ACE is not propagated among versions of the same file.
|
|
ACE$V_PROTECTED
|
This ACE is not deleted if the entire ACL is deleted; instead, you must
delete this ACE explicitly.
|
The following symbol values are offsets to bits within the mask
indicating the access mode granted in the system, owner, group, and
world fields:
| Bit Position |
Meaning When Set |
|
ACE$V_READ
|
Read access is granted.
|
|
ACE$V_WRITE
|
Write access is granted.
|
|
ACE$V_EXECUTE
|
Execute access is granted.
|
|
ACE$V_DELETE
|
Delete access is granted.
|
|
ACE$V_CONTROL
|
Modification of the access field is granted.
|
You can also obtain the symbol values as masks with the appropriate bit
set by using the prefix ACE$M rather than ACE$V.
Subsystem ACE
The Subsystem ACE maintains protected subsystems. Its format is as
follows:
The following table describes the ACE fields and lists the symbol name
for each:
| Field |
Symbol Name |
Description |
|
Length
|
ACE$B_SIZE
|
Byte containing the length in bytes of the ACE buffer.
|
|
Type
|
ACE$B_TYPE
|
Byte containing the type value ACE$C_SUBSYSTEM_IDS.
|
|
Flags
|
ACE$W_FLAGS
|
Word containing Subsystem ACE information and ACE type-independent
information.
|
|
Spare
|
ACE$L_SPARE1
|
Longword that is reserved for future use and must be 0.
|
|
Identifier/Attributes
|
ACE$Q_IMAGE_IDS
|
Longword identifier value and its associated longword attributes.
|
A Subsystem ACE can contain multiple identifier/attribute pairs. In
this case, the Subsystem ACE is an array of identifiers and attributes
starting at ACE$Q_IMAGE_IDS. Beginning at this offset, KGB$L_IDENTIFIER
and KGB$L_ATTRIBUTES are used to address each of the separate longwords.
The number of identifier/attribute pairs is computed by subtracting
ACE$C_LENGTH from ACE$W_SIZE and dividing by KGB$S_IDENTIFIER.
The following symbols are bit offsets to ACE information that is
independent of ACE type:
| Bit |
Meaning When Set |
|
ACE$V_NOPROPAGATE
|
This ACE is not propagated among versions of the same file.
|
|
ACE$V_PROTECTED
|
This ACE is not deleted if the entire ACL is deleted; instead, you must
delete this ACE explicitly.
|
The following symbol values are offsets to bits within the mask
indicating the access mode granted in the system, owner, group, and
world fields:
| Bit Position |
Meaning When Set |
|
ACE$V_READ
|
Read access is granted.
|
|
ACE$V_WRITE
|
Write access is granted.
|
|
ACE$V_EXECUTE
|
Execute access is granted.
|
|
ACE$V_DELETE
|
Delete access is granted.
|
|
ACE$V_CONTROL
|
Modification of the access field is granted.
|
You can also obtain the symbol values as masks with the appropriate bit
set by using the prefix ACE$M rather than ACE$V.
Required Access or Privileges
None
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $CREATE_USER_PROFILE,
$FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_AUDIT, $GET_SECURITY,
$GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT,
$REM_HOLDER, $REM_IDENT, $REVOKID, $SET_RESOURCE_DOMAIN, $SET_SECURITY
Condition Values Returned
|
SS$_BUFFEROVF
|
The service completed successfully. The output string has overflowed
the buffer and has been truncated.
|
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The ACL entry or its descriptor cannot be read by the caller, or the
string descriptor cannot be read by the caller, or the length word or
the string buffer cannot be written by the caller.
|
$FORMAT_AUDIT
Converts a security auditing event message from binary format to ASCII
text.
Format
SYS$FORMAT_AUDIT fmttyp ,audmsg ,[outlen] ,outbuf ,[width] ,[trmdsc]
,[routin] ,[fmtflg]
C Prototype
int sys$format_audit (unsigned int fmttyp, void *audmsg, unsigned short
int *outlen, void *outbuf, unsigned short int *width, void *trmdsc, int
(*routin)(__unknown_params), unsigned int fmtflg);
Arguments
fmttyp
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Format for the message. The fmttyp argument is a value
indicating whether the security audit message should be in brief
format, which is one line of information, or full format. The default
is full format. Refer to the OpenVMS System Manager's Manual for examples of formatted
output.
The following table defines the brief and full formats:
| Value |
Meaning |
|
NSA$C_FORMAT_STYLE_BRIEF
|
Use a brief format for the message.
|
|
NSA$C_FORMAT_STYLE_FULL
|
Use a full format for the message.
|
audmsg
| OpenVMS usage: |
char_string |
| type: |
byte stream (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Security auditing message to format. The audmsg
argument is the address of a buffer containing the message that
requires formatting.
outlen
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the formatted security audit message. The
outlen argument is the address of the word receiving
the final length of the ASCII message.
outbuf
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor |
Buffer holding the formatted message. The outbuf
argument is the address of a descriptor pointing to the buffer
receiving the message.
width
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Maximum width of the formatted message. The width
argument is the address of a word containing the line width value. The
default is 80 columns.
The width argument does not work consistently. In most
cases, if you specify both the width argument and the
full format style (NSA$C_FORMAT_STYLE_FULL), $FORMAT_AUDIT ignores the
width argument. The minimum width is 80 columns; lower
values do not limit the width to less than 80. If you specify a width
greater than 80 columns, most lines are not joined to use the full
width.
In most cases, you should avoid using the width
argument.
trmdsc
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor |
Line termination characters used in a full format message. The
trmdsc argument is the address of a descriptor
pointing to the line termination characters to insert within a line
segment whenever the width is reached.
routin
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by reference |
Routine that writes a formatted line to the output buffer. The
routin argument is the address of a routine called
each time a line segment is formatted. The argument passed to the
routine is the address of a character string descriptor for the line
segment.
When an application wants event messages in the brief format,
$FORMAT_AUDIT calls the routine twice to format the first event
message. The first time it is called, the routine passes a string
containing the column titles for the message. The second and subsequent
calls to the routine pass the formatted event message. By using this
routine argument, a caller can gain control at various points in the
processing of an audit event message.
fmtflg
| OpenVMS usage: |
longword (unsigned) |
| type: |
mask_longword |
| access: |
read only |
| mechanism: |
by value |
Determines the formatting of certain kinds of audit messages. The
fmtflg argument is a mask specifying whether sensitive
information should be displayed or column titles built for messages in
brief format. For example, the operating system uses bit 0 to suppress
plain-text passwords from security alarm messages.
|
