 |
OpenVMS System Services Reference Manual
$CREATE_USER_PROFILE
Returns an encoded security profile for the specified user.
Format
SYS$CREATE_USER_PROFILE usrnam ,[itmlst] ,[flags] ,usrpro ,usrprolen
,[contxt]
C Prototype
int sys$create_user_profile (void *usrnam, void *itmlst, unsigned int
flags, void *usrpro, unsigned int *usrprolen, unsigned int *contxt);
Arguments
usrnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the user whose security profile is to be returned. The
usrnam argument is the address of a descriptor
pointing to a text string containing the user name. The user name
string can contain a maximum of 12 alphanumeric characters.
For more information about user names, refer to the OpenVMS Guide to System Security.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying the portions of the user's security profile to be
replaced or augmented.
The item list is a standard format item list. The following figure
depicts the general format of an item descriptor. See the Item Codes
section for a list of valid item codes for $CREATE_USER_PROFILE.
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 buffer from which the service is to read the information.
The length of the buffer needed depends on the item code specified in
the item code field of the item descriptor.
|
|
Item code
|
A word containing a user-supplied symbolic code specifying the item of
information.
|
|
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 $CREATE_USER_PROFILE and should contain a
0.
|
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The flags argument is used to control the behavior of
the $CREATE_USER_PROFILE service. This argument does not accept ISS$
mask values; therefore, continue to use the CHP$ mask values for this
argument.
The following table describes each flag:
| Symbol |
Description |
|
CHP$M_DEFCLASS
|
By default, $CREATE_USER_PROFILE initializes the security profile with
the user's maximum authorized classification. When this flag is set,
the service initializes the security profile from the user's default
classification instead. This flag is reserved to Compaq.
|
|
CHP$M_DEFPRIV
|
By default, $CREATE_USER_PROFILE initializes the security profile with
the user's authorized privilege mask. When this flag is set, the
service initializes the security profile from the user's default
privilege mask instead.
|
|
CHP$M_NOACCESS
|
Instructs the service not to access the user authorization file
(SYSUAF.DAT) or rights database (RIGHTSLIST.DAT) to build the security
profile. This flag can be used as an optimization when all the
information necessary to build the security profile is known to the
caller.
|
usrpro
| OpenVMS usage: |
char_string |
| type: |
opaque byte stream |
| access: |
write only |
| mechanism: |
by reference |
Buffer to receive the security profile. The usrpro
argument is the address of a buffer to receive the encoded security
profile. If an address of 0 is specified, $CREATE_USER_PROFILE returns
the size of the buffer needed in the usrprolen
argument.
usrprolen
| OpenVMS usage: |
word |
| type: |
word (unsigned) |
| access: |
read/write |
| mechanism: |
by reference |
Word to receive the full size of the security profile. On input, the
usrprolen argument specifies the length of the buffer
pointed to by the usrpro argument. The
usrprolen argument is the address of a word to which
$CREATE_USER_PROFILE writes the actual length of the security profile.
If the caller specifies a usrpro address of 0,
$CREATE_USER_PROFILE returns the anticipated size, in bytes, of the
buffer needed to hold the user's security profile in the
usrprolen argument.
contxt
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Longword used to maintain authorization file context. The
contxt argument is the address of a longword to
receive a $GETUAI context value. On the initial call, this longword
should contain the value --1. On subsequent calls, the value of the
contxt argument from the previous call should be
passed back in.
Using the contxt argument keeps the UAF open across
all calls, thereby improving the performance of the system on
subsequent calls. To close the UAF, you must run down the image.
The resulting context value from a $CREATE_USER_PROFILE call can also
be used as the input contxt argument to the $GETUAI
system service, and vice versa.
Item Codes
CHP$_ADDRIGHTS
A rights list segment containing additional identifiers to be appended
to the set of identifiers held by the user. A rights list segment is a
list of quadword identifier/attributes pairs, each containing a
longword identifier value, followed by a longword mask identifying the
attributes of the holder. The buflen argument should
be set to the total size, in bytes, of the rights list segment. The
bufadr argument points to a descriptor that points to
the first byte in the rights list segment (that is, the first byte of
the first identifier value).
This item code can be repeated to add up to 256 additional rights list
segments. If more than 256 identifiers are granted to the user,
$CREATE_USER_PROFILE returns SS$_INSFMEM.
CHP$_CLASS
The classification to be associated with the created security profile.
This item code is reserved to Compaq.
CHP$_PRIV
A quadword privilege mask specifying the user's privileges. The $PRVDEF
macro defines the list of available privileges.
CHP$_UIC
A longword describing the user identification code (UIC).
ISS$_ACCOUNT
Variable-length buffer containing the account name. The maximum size of
this buffer is 32 bytes.
ISS$_ADD_RIGHTS
A rights list segment containing additional identifiers to be appended
to the set of identifiers held by the user. A rights list segment is a
list of quadword identifier/attributes pairs, each containing a
longword identifier value, followed by a longword mask identifying the
attributes of the holder. The buflen argument should
be set to the total size, in bytes, of the rights list segment. The
bufadr argument points to a descriptor that points to
the first byte in the rights list segment (that is, the first byte of
the first identifier value).
This item code can be repeated to add up to 256 additional rights list
segments. If more than 256 identifiers are granted to the user,
$CREATE_USER_PROFILE returns SS$_INSFMEM.
ISS$_AUTHPRIV
Quadword containing the authorized privileges. See $PRVDEF macro for
definitions.
ISS$_FLAGS
Longword containing user flags. The following flag is supported:
ISS$M_FLAG_SECAUDIT - Mandatory audit flag.
ISS$_MAXCLASS
Buffer containing the maximum classification. The maximum size of this
buffer is CLS$K_LENGTH. This item code is reserved to Compaq. See the
$CLSDEF macro for definitions.
ISS$_MINCLASS
Buffer containing the minimum classification. The maximum size of this
buffer is CLS$K_LENGTH. This item code is reserved to Compaq. See the
$CLSDEF macro for definitions.
ISS$_MODE
Longword containing the access mode. See $PSLDEF macro for definitions.
ISS$_PERMPRIV
Quadword containing the permanent privileges. See $PRVDEF macro for
definitions.
ISS$_RIGHTS
Descriptor pointing to a vector of quadwords containing
identifier/attribute pairs used to initialize the rights identifier
list. See the $KGBDEF macro for definitions. Any identifiers specified
by the ISS$_ADD_RIGHTS item code will be added to this list.
The format of this vector is as follows:
ISS$_UIC
A longword describing the user identification code (UIC).
ISS$_WORKCLASS
The classification to be associated with the created security profile.
This item code is reserved to Compaq.
ISS$_WORKPRIV
A quadword privilege mask specifying the user's privileges. The $PRVDEF
macro defines the list of available privileges.
Description
The Create User Profile service returns a security profile for a user.
This profile can be generated in two ways:
- If the caller does not specify the CHP$_NOACCESS flag in the
flags argument, $CREATE_USER_PROFILE accesses the
system authorization database (SYSUAF.DAT) or the rights database
(RIGHTSLIST.DAT) for the specified user name and builds a
representation of the privileges and rights granted to that user. The
security profile is returned as an opaque byte stream.
$CREATE_USER_PROFILE returns a representation of the security
profile that the user would have when logged in at the highest
authorized classification with all authorized privileges enabled.
- When the caller specifies the CHP$M_NOACCESS flag in the
flags argument, $CREATE_USER_PROFILE creates a
security profile without accessing the user authorization file
(SYSUAF.DAT) or the rights database (RIGHTSLIST.DAT). When
CHP$M_NOACCESS is specified, all of the information is obtained from
the item list. The caller must supply the CHP$_PRIV and CHP$_UIC items.
In addition, an address of 0 can be specified for the
usrnam argument.
In either case, the newly created security profile can be passed as
input to the $CHKPRO and $CHECK_ACCESS system services using the
usrpro argument.
$CREATE_USER_PROFILE returns the set of identifiers associated with the
user's owner identifier. The CHP$_ADDRIGHTS item code can be used to
add additional identifiers to this set.
Required Access or Privileges
Access to SYSUAF.DAT and RIGHTSLIST.DAT is required unless you are
constructing the security profile for your own user name.
Required Quota
None
Related Services
$CHECK_ACCESS, $CHKPRO, $FIND_HELD, $FINISH_RDB, $GETUAI
Condition Values Returned
|
SS$_NORMAL
|
Profile created successfully.
|
|
SS$_BADITMCOD
|
Item list code is invalid.
|
|
SS$_BADBUFLEN
|
Size specified for item is invalid.
|
|
SS$_ACCVIO
|
Buffer address is invalid or inaccessible.
|
|
SS$_INSFARG
|
Insufficient call arguments.
|
|
SS$_INSFMEM
|
Insufficient memory.
|
|
SS$_IVSTSFLG
|
Invalid system service flags specified.
|
|
SS$_NOPRIV
|
Caller lacks privilege to access UAF.
|
|
RMS$_RNF
|
User name is not in UAF.
|
$CREATE_USER_PROFILE can also return any error returned by the $GETUAI
or $FIND_HELD services.
$CRELNM
Creates a logical name and specifies its equivalence names.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$CRELNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
C Prototype
int sys$crelnm (unsigned int *attr, void *tabnam, void *lognam,
unsigned char *acmode, void *itmlst);
Arguments
attr
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
Attributes to be associated with the logical name. The
attr argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha systems) of a longword bit mask
specifying these attributes.
Each bit in the longword corresponds to an attribute and has a symbolic
name. These symbolic names are defined by the $LNMDEF macro. To specify
an attribute, specify its symbolic name or set its corresponding bit.
The longword bit mask is the logical OR of all desired attributes. All
undefined bits in the longword must be 0.
If you do not specify this argument or specify it as 0 (no bits set),
no attributes are associated with the logical name.
The attributes are as follows:
| Attribute |
Description |
|
LNM$M_CONFINE
|
If set, the logical name is not copied from the process to its spawned
subprocesses. You create a subprocess with the DCL command SPAWN or the
LIB$SPAWN Run-Time Library routine. If the logical name is placed into
a process-private table that has the CONFINE attribute, the CONFINE
attribute is automatically associated with the logical name. This
applies only to process-private logical names.
|
|
LNM$M_NO_ALIAS
|
If set, the logical name cannot be duplicated in this table at an outer
access mode. If another logical name with the same name already exists
in the table at an outer access mode, it is deleted.
|
tabnam
| OpenVMS usage: |
logical_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Name of the table in which to create the logical name. The
tabnam argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha systems) of a descriptor that
points to the name of this table. This argument is required and must be
specified in uppercase.
The name must be entered in uppercase letters. (This requirement
differs from the $CRELNT system service, which automatically changes
tabnam to uppercase.)
If tabnam is not the name of a logical name table, it
is assumed to be a logical name and is translated iteratively until
either the name of a logical name table is found or the number of
translations allowed by the system has been performed. If
tabnam translates to a list of logical name tables,
the logical name is entered into the first table in the list.
lognam
| OpenVMS usage: |
logical_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Name of the logical name to be created. The lognam
argument is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha systems) of a descriptor that points to the logical
name string. Logical name strings of logical names created within
either the system or process directory table must consist of uppercase
alphanumeric characters, dollar signs ($), and underscores (_); the
maximum length is 31 characters. The maximum length of logical name
strings created within other tables is 255 characters with no
restrictions on the types of characters that can be used. This argument
is required.
acmode
| OpenVMS usage: |
access_mode |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
Access mode to be associated with the logical name. The
acmode argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha systems) of a byte that
specifies the access mode.
The access mode associated with the logical name is determined by
maximizing the access mode of the caller with the access mode
specified by the acmode argument, which means that the
less privileged of the two is used. Symbols for the four access modes
are defined by the $PSLDEF macro.
You cannot specify an access mode more privileged than that of the
containing table. However, if the caller has SYSNAM privilege, then the
specified access mode is associated with the logical name regardless of
the access mode of the caller.
If you omit this argument or specify it as 0, the access mode of the
caller is associated with the logical name.
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 (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
Item list describing the equivalence names to be defined for the
logical name and information to be returned to the caller. The
itmlst argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha systems) of a list of item
descriptors, each of which specifies information about an equivalence
name. 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. All
items in an item list must be of the same format---either 32-bit or
64-bit.
Note that it is possible to create a logical that has no equivalence
names. This is done by either omitting the itmlst
argument to $CRELNM, or by not including the LNM$_STRING item code to
the itmlst data structure that is passed into $CRELNM.
It is not possible to create this kind of logical using DCL.
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 number of bytes in the buffer pointed to by the
buffer address field. 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 symbolic code that describes the information in the
buffer or the information to be returned to the buffer, pointed to by
the buffer address field. The item codes are listed in the Item Codes
section.
|
|
Buffer address
|
A longword containing the 32-bit address of the buffer that receives or
passes information.
|
|
Return length address
|
A longword containing the 32-bit address of a word specifying the
actual length in bytes of the information returned by $CRELNM in the
buffer pointed to by the buffer address field. The return length
address field is used only when the item code specified is LNM$_TABLE.
Although this field is ignored for all other item codes, it must
nevertheless be present as a placeholder in each item descriptor.
|
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
|
The field 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 a symbolic code that describes the information in the
buffer or the information to be returned to the buffer, pointed to by
the buffer address field. The item codes are listed in the Item Codes
section.
|
|
MBMO
|
The field 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 number of bytes in the buffer pointed to by
the buffer address field. 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.
|
|
Buffer address
|
A quadword containing the 64-bit address of the buffer that receives or
passes information.
|
|
Return length address
|
A quadword containing the 64-bit address of a word specifying the
actual length in bytes of the information returned by $CRELNM in the
buffer pointed to by the buffer address field. The return length
address field is used only when the item code specified is LNM$_TABLE.
Although this field is ignored for all other item codes, it must
nevertheless be present as a placeholder in each item descriptor.
|
Item Codes
LNM$_ATTRIBUTES
When you specify LNM$_ATTRIBUTES, the buffer address field of the item
descriptor points to a longword bit mask that specifies the current
translation attributes for the logical name. The current translation
attributes are applied to all subsequently specified equivalence
strings until another LNM$_ATTRIBUTES item descriptor is encountered in
the item list. The symbolic names for these attributes are defined by
the $LNMDEF macro. The symbolic name and description of each attribute
are as follows:
| Attribute |
Description |
|
LNM$M_CONCEALED
|
If set, OpenVMS RMS interprets the equivalence name as a device name or
logical name with the LNM$M_CONCEALED attribute.
|
|
LNM$M_TERMINAL
|
If set, further iterative logical name translation on the equivalence
name is not to be performed.
|
LNM$_CHAIN
When you specify LNM$_CHAIN, the buffer address field of the item
descriptor points to another item list that $CRELNM is to process
immediately after it has processed the current item list.
If you specify the LNM$_CHAIN item code, it must be the last item code
in the current item list.
You can chain together 32-bit and 64-bit item lists.
LNM$_STRING
When you specify LNM$_STRING, the buffer address field of the item
descriptor points to a buffer containing a user-specified equivalence
name for the logical name. The maximum length of the equivalence string
is 255 characters.
When $CRELNM encounters an item descriptor with the item code
LNM$_STRING, it creates an equivalence name entry for the logical name
using the most recently specified values for LNM$_ATTRIBUTES. The
equivalence name entry includes the following information:
- Name specified by LNM$_STRING.
- Next available index value. Each equivalence is assigned a unique
value from 0 to 127.
- Attributes specified by the most recently encountered item
descriptor with item code LNM$_ATTRIBUTES (if these are present in the
item list).
Therefore, you should construct the item list so that the
LNM$_ATTRIBUTES item codes immediately precede the LNM$_STRING item
code or codes to which they apply.
Note that it is possible to create a logical that has no equivalence
names. This is done by either omitting the itmlst
argument to $CRELNM, or by not including the LNM$_STRING item code to
the itmlst data structure that is passed into $CRELNM.
It is not possible to create this kind of logical using DCL.
LNM$_TABLE
When you specify LNM$_TABLE, the buffer address field of the item
descriptor points to a buffer in which $CRELNM writes the name of the
logical name table in which it entered the logical name. The return
length address field points to a word that contains a buffer that
specifies the length in bytes of the information returned by $CRELNM.
The maximum length of the name of a logical name table is 31 characters.
|
