Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $PERSONA_CREATE (VAX Only)

> Creates a persona that can be assumed using the $PERSONA_ASSUME service.

### Format

> SYS$PERSONA_CREATE persona ,usrnam ,flags

### C Prototype

> int sys$persona_create (unsigned int *persona, void *usrnam, unsigned int flags);

### Arguments

> #### persona

> OpenVMS usage: | integer
> type: | longword (unsigned)
> access: | write
> mechanism: | by reference

> Address of a longword into which the persona handle is written.

> #### usrnam

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

> Name of the user to be impersonated. The usrnam argument is the address of a descriptor pointing to a character string containing the user name. The string can contain a maximum of 12 alphanumeric characters.

> #### flags

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Flag mask specifying which Persona services options are to be employed when the persona is created.

> The following table describes each flag:

> Flag | Description
> --- | ---
> IMP$M_ASSUME_DEFPRIV | Create a persona with only default privileges.
> IMP$M_ASSUME_DEFCLASS | Create a persona with default classification.

### Description

> On calling the Create Persona service, the required information concerning the OpenVMS user specified by the usrnam argument is read from the User Authorization File and Rights database and is stored in system memory. A handle to refer to the created persona is returned in the persona argument.

> It is not possible to create a persona for a username which has been disabled.

> No changes are made to the caller's process as a result of calling $PERSONA_CREATE.

> Some of the $PERSONA_CREATE service executes in the caller's access mode (assumed to be user mode). An improper use of the usernam argument can cause an access violation to be signaled.

> Required Access or Privileges

> All calls to $PERSONA_CREATE require DETACH privilege and access to the system authorization database.

> Required Quota

> None

> Related Services

> $PERSONA_ASSUME, $PERSONA_DELETE

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The persona argument cannot be written by the caller.
> SS$_NODETACH | Operation requires DETACH privilege.
> SS$_INSFMEM | Insufficient memory.
> IMP$_USERDISABLED | User name disabled.

Any condition value returned by the $LKWSET, $GETUAI, or, $FIND_HELD can also be returned.

## $PERSONA_CREATE (Alpha Only)

> Creates a persona that can be assumed using the $PERSONA_ASSUME service.

### Format

> SYS$PERSONA_CREATE persona ,[usrnam] ,[flags], [usrpro], [itmlst]

### C Prototype

> int sys$persona_create (unsigned int *persona, void *usrnam, unsigned int flags, unsigned int *usrpro, unsigned int *itmlst);

### Arguments

> #### persona

> OpenVMS usage: | persona
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference

> Address of a longword into which the persona identification handle is written.

> #### usrnam

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

> Name of the user to be impersonated. The usrnam argument is the address of a descriptor pointing to a character string containing the user name. The string can contain a maximum of 32 alphanumeric characters.

> #### flags

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> The $ISSDEF macro defines these codes:
> - ISS$V_CREATE_AUTHPRIV - This bit is used to create a persona with the privilege fields set to the authorized privileges of the specified user.
> - ISS$V_CREATE_DEFPRIV - This bit is used for backward compatibility with the previous implementation of personae. This bit is accepted but not processed, as it describes the default behavior of the service.
> - ISS$V_NOACCESS - Tells $PERSONA_CREATE not to access the SYSUAF file. Only valid in exec or kernel mode.

> #### usrpro

> OpenVMS usage: | char_string
> type: | opaque byte stream
> access: | read only
> mechanism: | by descriptor

> Buffer containing an encoded security profile. The usrpro argument is the address of a descriptor pointing to a buffer that contains encoded security profile data. This profile can be created by calling the SYS$CREATE_USER_PROFILE system service.

> #### itmlst

> OpenVMS usage: | item_list_3
> type: | longword
> access: | read only
> mechanism: | by reference

> Attributes describing modifications to the security profile. The itmlst argument is the address of an item_list defining changes to be made to the specified user profile.

This section lists the ISS$ item codes and definitions.

### Item Codes

> #### ISS$_WORKPRIV

> $PERSONA_CREATE sets the working privileges for the new persona as a quadword value.

> #### ISS$_MODE

> $PERSONA_CREATE sets the access mode of the new persona as a longword value. The mode cannot be more privileged than that of the caller.

> #### ISS$_FLAGS

> $PERSONA_CREATE sets the flags field of the new persona as a longword bit mask. The following bits are currently defined for this field:
> - ISS$V_PERMANENT - Mark this persona as permanent. It will survive image activations/deactivations.
> - ISS$V_SECAUDIT - Always audit this persona's operations.
> - ISS$V_DEBIT - Debit and credit the process BYTLM/BYTCNT for this persona. (This flag is always set for user mode persona.)

> #### ISS$_RIGHTS_INDEX

> The index indicates into which rights chain the rights are placed. Values for the index are: ISS$M_ENABLED_PERSONA, ISS$M_ENABLED_SYSTEM, ISS$M_ENABLED_INSTALLED, ISS$M_ENABLED_SUBSYSTEM, and ISS$M_ENABLED_TEMPORARY. All subsequent rights item packets use the index until a new ISS$_RIGHTS_INDEX item changes the index. If a rights index is not specified, the rights item packets will use the PERSONA chain as the default. Rights item packets include: ISS$_AUTHRIGHTS, ISS$_RIGHTS, ISS$_ADD_AUTHRIGHTS, and ISS$_ADD_RIGHTS.

> #### ISS$_AUTHRIGHTS (Reserved for use by Compaq.)

> $PERSONA_CREATE sets the user authorized rights of the new persona as a list of quadword values. Any existing authorized rights will be overwritten. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes.

> #### ISS$_RIGHTS

> $PERSONA_CREATE sets the user rights of the new persona as a list of quadword (paired longword) values. Any existing authorized rights will be overwritten. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes. The format of the list is the same as ISS$_AUTHRIGHTS.

> The format of the list is as follows:

#### ISS$_USERNAME

$PERSONA_CREATE sets the user name of the new persona as a 32-byte character string.

#### ISS$_ACCOUNT

$PERSONA_CREATE sets the account of the new persona as a 32-byte character string.

#### ISS$_NOAUDIT

$PERSONA_CREATE sets the No Audit field of the new persona as a longword value.

#### ISS$_UIC

$PERSONA_CREATE sets the UIC of the new persona as a longword value.

#### ISS$_AUTHPRIV

$PERSONA_CREATE sets the authorized privileges for the new persona as a quadword value.

#### ISS$_PERMPRIV

$PERSONA_CREATE sets the permanent privileges for the new persona as a quadword value.

#### ISS$_IMAGE_WORKPRIV

$PERSONA_CREATE sets the image working privileges for the new persona as a quadword value.

#### ISS$_ENABLED

$PERSONA_CREATE sets the Rights Enable field of the new persona as a longword bit mask. These bits correspond to the indices of the different rights chains. By setting the bit in the ENABLED field, the corresponding rightslist chain will be enabled, and its rights will be included in all rights checks. Valid bits are: ISS$V_ENABLED_PERSONA, ISS$V_ENABLED_SUBSYSTEM, ISS$V_ENABLED_IMAGE, ISS$V_ENABLED_SYSTEM, and ISS$V_ENABLED_TEMPORARY.

#### ISS$_ADD_AUTHRIGHTS

$PERSONA_CREATE adds the rights to the current list of authorized rights. $PERSONA_CREATE expects the same format as that outlined in ISS$_AUTHRIGHTS. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes.

#### ISS$_ADD_RIGHTS

$PERSONA_CREATE adds the rights to the current list of rights. $PERSONA_CREATE expects the same format as that outlined in ISS$_AUTHRIGHTS. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes.

### Description

> When you call this service, you can specify either the usrnam or usrpro argument, but not both. The required information specifying the OpenVMS user is read from either the User Authorization File (UAF) and rights database or the usrpro buffer and is stored in system memory. Any modifications specified in the itmlst are then applied to complete the new persona. A persona identification handle that refers to the created persona is returned in the persona argument. This service creates a default VMS extension for the persona.

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

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_073.HTML