 |
HP OpenVMS System Services Reference Manual
No changes are made to the caller's thread as a result of calling
$PERSONA_CREATE.
The arguments are validated against the caller's mode, so an invalid
argument can cause an access violation to be signaled.
Required Access or Privileges
All calls to $PERSONA_CREATE require IMPERSONATE privilege and read
access to the system authorization database.
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE_EXTENSION,
$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
persona argument cannot be written by the caller.
|
|
SS$_NOPRIV
|
The operation requires IMPERSONATE privilege.
|
|
SS$_INSFMEM
|
Insufficient memory.
|
|
SS$_USERDISABLED
|
User name disabled.
|
|
SS$_IVMODE
|
The caller cannot create a persona that is more privileged than the
caller.
|
|
SS$_INSFARG
|
Certain required arguments were not specified.
|
|
SS$_BADPARAM
|
The value of at least one of the arguments is incorrect.
|
|
SS$_BADCHECKSUM
|
The buffer specified by
usrpro is not valid.
|
|
SS$_BADBUFLEN
|
The buffer length for data within the
usrpro or
itmlst was invalid.
|
|
SS$_BADITMCOD
|
At least one argument in the item code is invalid.
|
|
SS$_INVARG
|
An incorrect combination of arguments was specified.
|
|
SS$_INVSECDOMAIN
|
The buffer specified by
usrpro contains data that originated outside the local
security domain.
|
Any condition value returned by the $LKWSET, $GETUAI, or $FIND_HELD
service can also be returned.
$PERSONA_CREATE_EXTENSION (Alpha and Integrity servers)
On Alpha and Integrity server systems, creates an extension on the
current persona. A persona extension is a mechanism to attach support
for additional security credentials.
Format
SYS$PERSONA_CREATE_EXTENSION persona ,extensionID ,buffer ,length ,flags
C Prototype
int sys$persona_create_extension (unsigned int *persona, unsigned int
*extensionID, void *buffer, unsigned int *length, unsigned int *flags);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the persona identification to which
$PERSONA_CREATE_EXTENSION attaches a new persona extension.
Two special values for persona are also permitted: 0,
which means the current persona, and -1, which means the process'
natural persona is used.
extensionID
| OpenVMS usage: |
extension_ID |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the extension identification (EID) for
which the registered CREATE routine will be called to create a new
persona extension block.
buffer
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a buffer containing data to be used in creating the persona
extension data structure. The interpretation of the data within this
buffer is the responsibility of the extension create routine. For
example, this data could be a Type-Length-Value (TLV) structure
containing fields in the extension data structure. Specifying this
buffer is optional; a caller who does not want to supply a buffer
should specify an address of zero (0).
length
| OpenVMS usage: |
size |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the size, in bytes, of the
buffer argument. Specifying length is
optional; a caller who does not want to supply a length should specify
an address of zero (0). Specifying a buffer without a length is the
same as not specifying a buffer.
flags
| OpenVMS usage: |
flags |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flag mask specifying the options to be employed when the persona
extension is created. Specifying flags is optional; a caller who does
not want to supply flags should specify an address of zero (0).
| Flag |
Description |
|
PXB$V_PRIMARY_EXTENSION
|
This extension is recorded as the persona's primary extension. If a
persona already has a primary extension, the error SS$_UNSUPPORTED is
returned and the extension is not created. The primary extension is
returned when the persona is queried for its "Primary Extension." There
is no other meaning for this value.
|
Description
This service creates an extension by calling the registered Extension
Create routine for the specified extension and by attaching it to the
persona represented by the persona argument.
When a return fails, no persona extension is created.
A VMS extension is already associated with every persona. An attempt to
create a VMS extension using this service returns SS$_DUPLNAM.
Required Access or Privileges
This service requires that the caller have the IMPERSONATE privilege
enabled or be in exec or kernel mode.
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,
$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
A buffer or return address specified in the item list cannot be read.
|
|
SS$_BADITMCOD
|
The item list contains an invalid identifier code.
|
|
SS$_BADPARAM
|
An invalid parameter was specified.
|
|
SS$_DUPLNAM
|
The persona already has an extension of this type.
|
|
SS$_EXQUOTA
|
The caller lacks sufficient quota to allocate a new persona.
|
|
SS$_NOIMPERSONATE
|
The caller does not have the privilege to extend its original
identity/persona.
|
|
SS$_NOSUCHEXT
|
The extension requested does not exist on the system.
|
|
SS$_PERSONANONGRATA
|
The persona ID supplied was invalid.
|
|
SS$_UNSUPPORTED
|
An unsupported request was made; check the PRIMARY_EXTENSION flags bit.
|
$PERSONA_DELEGATE (Alpha and Integrity servers)
On Alpha and Integrity server systems, delegates or assigns the
currently active persona to another process.
Format
SYS$PERSONA_DELEGATE serverPID ,persona ,input
C Prototype
int sys$persona_delegate (unsigned int *serverPID, unsigned int
*persona, unsigned int *input);
Arguments
serverPID
| OpenVMS usage: |
process_ID |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the extended process identification
(PID) of the server process to which $PERSONA_DELEGATE grants the
current persona.
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the identification that the
$PERSONA_RESERVE service reserved in the server's process for this
client's persona.
input
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the persona identification that
describes which persona is delegated to the server. If the
input argument is zero (0) or null, or if the input
value is zero (0), the current persona is delegated. If the input value
is -1, then the natural persona of the process is delegated.
Description
This service delegates or assigns either the specified persona or the
currently active persona to another process. The server process must
have reserved a persona slot for the current process to use by calling
$PERSONA_RESERVE before calling this service.
The delegation of persona is only supported for processes residing on
the same node in the cluster. When a return fails, the persona is not
delegated.
Required Access or Privileges
None
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,
$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The arguments cannot be read by the service.
|
|
SS$_BADPARAM
|
An invalid parameter was specified.
|
|
SS$_EXQUOTA
|
The caller lacks sufficient quota to allocate a new persona.
|
|
SS$_NONEXPR
|
The process specified does not exist.
|
|
SS$_PERSONANONGRATA
|
The persona ID supplied was invalid.
|
$PERSONA_DELETE
Deletes a persona created using the $PERSONA_CREATE, the
$PERSONA_CLONE, or the $PERSONA_RESERVE service.
Format
SYS$PERSONA_DELETE persona
C Prototype
int sys$persona_delete (unsigned int *persona);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword in which the persona identification handle is
expected.
Description
The PERSONA_DELETE service frees the resources used by the persona. No
changes to the caller's process are made as a result of calling
$PERSONA_DELETE.
The persona argument is validated against the caller's
mode, so an invalid argument can cause an access violation to be
signaled.
Required Access or Privileges
None
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,
$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,
$PERSONA_DELEGATE, $PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND,
$PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
Access violation.
|
|
SS$_PERSONADELPEND
|
Persona is in use; delete pending on release.
|
|
SS$_NODELPERMANENT
|
Permanent personae cannot be deleted.
|
$PERSONA_DELETE_EXTENSION (Alpha and Integrity servers)
On Alpha and Integrity server systems, deletes an extension attached to
a persona.
Format
SYS$PERSONA_DELETE_EXTENSION persona ,extensionID
C Prototype
int sys$persona_delete_extension (unsigned int *persona, unsigned int
*extensionID);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the persona identification for which
$PERSONA_DELETE_EXTENSION calls the registered Extension Delete
function.
extensionID
| OpenVMS usage: |
extension_ID |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword containing the extension identification (EID) for
which the registered DELETE routine is called in order to delete a
persona extension block from the specified persona.
Description
This service deletes an extension data structure by calling the
registered Extension Delete routine for the specified extension.
When a return fails, the persona extension is not deleted.
The VMS extension associated with each persona cannot be deleted. An
attempt to delete that extension returns SS$_UNSUPPORTED.
Required Access or Privileges
This service requires that the caller have the IMPERSONATE privilege
enabled or be in exec or kernel mode.
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,
$PERSONA_CREATE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_BADPARAM
|
An invalid parameter was specified.
|
|
SS$_NOIMPERSONATE
|
The caller does not have the privilege to delete pieces of the thread's
original identity/persona.
|
|
SS$_NOSUCHEXT
|
The extension specified does not exist in the persona.
|
|
SS$_PERSONANONGRATA
|
The persona ID supplied was invalid.
|
|
SS$_UNSUPPORTED
|
The specified extension cannot be deleted.
|
$PERSONA_EXTENSION_LOOKUP (Alpha and Integrity servers)
On Alpha and Integrity server systems, translates a text name of an
extension (for example, VMS or NT) into an extension identification
(EID) that can be used in other persona-related system services.
Format
SYS$PERSONA_EXTENSION_LOOKUP extensionName ,extensionID
C Prototype
int sys$persona_extension_lookup (void *extensionName, unsigned int
*extensionID);
Arguments
extensionName
| OpenVMS usage: |
extension_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length descriptor |
Address of a character string descriptor pointing to the name of the
extension being looked up.
extensionID
| OpenVMS usage: |
extension_ID |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the value of the extension
identification (EID) returned by the service is written.
Description
This service translates a text name of an extension into an extension
identification (EID) that can be used in other persona-related system
services.
There are currently two extension names: VMS and NT.
Required Access or Privileges
None
Required Quota
None
Related Services
$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,
$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,
$PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The string descriptor supplied in the
extensionName argument cannot be read by the service.
|
|
SS$_BADPARAM
|
An invalid argument was specified.
|
|
SS$_NOSUCHEXT
|
The supplied
extensionName does not exist on this system.
|
$PERSONA_FIND (Alpha and Integrity servers)
On Alpha and Integrity server systems, enables the caller to find the
personae within a process that have certain attributes or settings.
Format
SYS$PERSONA_FIND persona ,itmlst ,contxt
C Prototype
int sys$persona_find (unsigned int *persona, void *itmlst, unsigned int
*contxt);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the persona identification that
matches all of the items present in the item list is written.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Attributes specifying which information about the persona is to be
compared. The itmlst argument is the address of a list
of item descriptors, each describing an item of information or an item
list processing directive. The list of item descriptors is terminated
by a longword value of 0.
The following diagram shows the format of a single item descriptor:
The following table lists the item descriptor fields and their
definitions:
| Field |
Description |
|
Buffer length
|
A word containing a user-supplied integer specifying the length (in
bytes) of the buffer in which $PERSONA_FIND is to locate the
information. The length of the buffer depends on the item code
specified in the item code field of the item descriptor. If the value
of buffer length is too small, $PERSONA_FIND fails the comparison.
|
|
Item code
|
A word containing a user-supplied symbolic code specifying the item of
information $PERSONA_FIND is to test, or specifying a directive for
processing subsequent items. The $ISSDEF macro defines these codes.
Each item code is described in the Description section.
|
|
Buffer address
|
A longword containing the user-supplied address of the buffer in which
$PERSONA_FIND locates the information used for the comparison.
|
|
Return length address
|
An unused longword containing the user-supplied address of a word into
which the system service writes the length in bytes of the information
it returned. This longword is unused for PERSONA_FIND.
|
contxt
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context value used when repeatedly calling $PERSONA_FIND. The
contxt argument is the address of a longword used
while $PERSONA_FIND searches for all personae that match the criteria.
The context value must be initialized to zero, and the resulting
context of each call to $PERSONA_FIND must be presented to each
subsequent call. After contxt is passed to
$PERSONA_FIND, you must not modify its value.
Description
This service enables the caller to find the personae within a process
that have certain attributes or settings.
A persona identification is returned only if all the items specified in
the item list match those in the persona and its extensions.
The item list cannot be changed between context-saved calls. Results
are unpredictable if the item list is changed between calls.
Repeated calls to $PERSONA_FIND return subsequent matching personae.
When the service returns SS$_NOMOREPROC, there are no more personae to
examine.
OpenVMS Persona Item Codes
The following table contains the item codes specific to the OpenVMS
persona extension data:
| Item Code |
Use+ |
Size (bytes) |
Description |
|
ISS$_USERNAME
|
Q,M,F
|
32
|
OpenVMS user name as text string
|
|
ISS$_ACCOUNT
|
Q,M,F
|
32
|
OpenVMS account name as text string
|
|
ISS$_DOMAIN
|
Q,F
|
32
|
OpenVMS SCSNODE as text string as obtained from $GETJPI's nodename
|
|
ISS$_PRINCIPAL
|
Q,F
|
64
|
OpenVMS user name as text string
|
|
ISS$_EXTENSION
|
Q,F
|
32
|
The text string VMS
|
|
ISS$_WORKPRIV
|
Q,M
|
8
|
Working privilege mask
|
|
ISS$_WORKCLASS
|
Q,M
|
Varying
|
Working classification
|
|
ISS$_RIGHTS
|
Q
|
Varying
|
Enabled list of rights identifiers
|
|
ISS$_NOAUDIT
|
Q,M
|
4
|
No audit counter---0 means audits disabled
|
|
ISS$_UIC
|
Q,M,F
|
4
|
Current UIC
|
|
ISS$_AUTHPRIV
|
Q,M
|
8
|
Authorized privilege mask
|
|
ISS$_PERMPRIV
|
Q,M
|
8
|
Permanent privilege mask
|
|
ISS$_IMAGE_WORKPRIV
|
Q,M
|
8
|
Image working privilege mask
|
|
ISS$_ENABLED
|
Q
|
4
|
Mask of enabled rights chains
|
|
ISS$_AUTHRIGHTS
|
Q
|
Varying
|
Authorized list of rights identifiers
|
|
ISS$_MINCLASS
|
Q
|
Varying
|
Minimum classification
|
|
ISS$_MAXCLASS
|
Q
|
Varying
|
Maximum classification
|
+Use descriptions are: Query, Modify, and Find.
|
