OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

It is possible to call $PERSONA_CREATE in any mode. To call $PERSONA_CREATE in kernel mode, the calling sequence is different. Only the usrpro argument is valid (usrnam cannot be used because kernel mode access to the SYSUAF file is not allowed), and it is necessary to set the PSB$M_NOACESS value in the flags.

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 Only)

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 in order 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.

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 Only)

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 persona identification that this 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 Only)

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 Only)

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$_NOSUCHTEXT The supplied extensionName does not exist on this system.

$PERSONA_FIND (Alpha Only)

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.

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

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.

Contents

Index

privacy and legal statement

4527PRO_070.HTML

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.

OpenVMS usage:	persona
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	extension_ID
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	size
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	flags
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	process_ID
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	extension_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length descriptor

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference