Document revision date: 30 March 2001

## OpenVMS Programming Concepts Manual

Previous | Contents | Index

## 31.4 Persona (Alpha Only1)

A persona contains a user's security profile. The persona contains all identity and credential information about the process, including the username, UIC, privileges masks, and rights identifiers. Every process in the system has at least one persona, the natural persona of the process. The natural persona is created during process creation. OpenVMS stores a persona in a single data structure, the Persona Security Block (PSB).

The persona block (PSB) contains the following:

- UIC
- Persona and system rights chains
- Permanent, authorized, and working privileges
- Account name
- User name
- Auditing flags and counters

### 31.4.1 Impersonation Services (Alpha Only)

For client/server applications, the server processes requests on behalf of the client. With OpenVMS, the server application developer can use impersonation services for client requests. This mechanism allows the operating system to perform object access checking (and auditing) for the server.

The impersonation system services allow a privileged OpenVMS process to create and use personae. A process, for example a server, can acquire more Persona System Blocks and switch between them using impersonation system services, such as SYS$PERSONA_CREATE, SYS$PERSONA_ASSUME, and SYS$PERSONA_CLONE. Each process has a persona array which is used to store the addresses of all PSBs allocated to the process. Other impersonation services support PSB lookup and attribute retrieval and modification, such as SYS$PERSONA_FIND, SYS$PERSONA_QUERY, and SYS$PERSONA_MODIFY, respectively.

#### 31.4.1.1 Using Impersonation System Services

The following discussion assumes there is a running server that has the ability to impersonate clients and is able to perform work requests for clients. This could be a file server, for example.

When the client connects to the server, the server creates a user profile using the SYS$PERSONA_CREATE service with the username argument. The server can do the following to process a client's requests:

- Switch the server's execution context to the client's profile, which has been previously created, by having the server call SYS$PERSONA_ASSUME, specifying the client's persona.
- Make copies of the created profile and then execute client requests under thread control with a multithreaded server. That is, the server calls the SYS$PERSONA_CLONE service, specifying the client's persona as input, resulting in a copy. The server can now handle multiple requests from the client, using an available copy of the client's persona as input to SYS$PERSONA_ASSUME.
- Check to determine if a given client's profile already exists by calling SYS$PERSONA_FIND. The SYS$PERSONA_FIND service enables the caller to find the personae, within a process, that have certain attributes or settings. For example, the service could specify the USERNAME item as an attribute.
- Check the client's profile, since some client requests may require certain privileges or rights, by calling SYS$PERSONA_QUERY, specifying the persona to check and the items to retrieve. If required and allowable, the server can update the person's working privileges or rights by calling SYS$PERSONA_MODIY, specifying the client's persona and the attributes to change.
- Remove a client's profiles with a client disconnects. The server again could use SYS$PERSONA_FIND to locate personae that match the client's USERNAME attribute. The server invokes SYS$PERSONA_DELETE to remove the specified persona from the server's process.

For more information about the persona system services, see the OpenVMS System Services Reference Manual: GETUTC--Z.

### 31.4.2 Per-Thread Security (Alpha Only)

OpenVMS provides per-thread security capabilities. With per-thread security, a multithreaded process allows each thread of execution to have an individual security profile. That is, a PSB is bound to a thread of execution. Each process has at least one kernel thread. The kernel thread block (KTB) points to the PSB for the currently active thread. Individual user threads can point to different PSBs, which give each user thread a separate identity. Per-thread security profiles are supported by impersonation system services and changes to the underlying system framework.

#### 31.4.2.1 Previous Security Model

Prior to OpenVMS V7.2, the information that constitutes a user's security profile was bound at the process level, common to all threads of execution within a process. Figure 31-7 shows this relationship.

Figure 31-7 Previous Per-Thread Security Model

Modifications that are made to the security profile by one thread are potentially visible to other threads, depending on two key factors:

- Whether multiple threads can truly execute simultaneously
- How the threads perform profile management among themselves

#### 31.4.2.2 Per-Thread Security Model

With OpenVMS Version 7.2, the users' security profile (that is, their privileges, rights, and identifier information) is shifted from the process level to the user thread level. The security information previously stored in several structures, including the Access Rights Block (ARB), the Process Control Block (PCB), the Process Header Descriptor (PHD), the Job Information Block (JIB), and the Control (CTL) region fields, has moved to the new Persona Security Block (PSB) data structure.

Each thread of execution can share a security profile with other threads or have a thread-specific security profile. Figure 31-8 shows these relationships.

Figure 31-8 Per-Thread Security Profile Model

As is the case with the previous model, modifications to a shared profile are potentially visible to all threads that share the profile. However, modifications made to a thread-specific profile are only applicable to the particular thread.

For more information about per-thread security, see the OpenVMS Guide to System Security.

### 31.4.3 Persona Extensions (Alpha Only)

A persona extension is a mechanism to attach support for additional security credentials into the already existing persona support. This mechanism consists of extension-specific execlet-based code and an extension-specific data structure (PXB) attached to an existing persona block (PSB).

To extend these capabilities, persona extension blocks (PXBs) that represent identity and credential information of a security agent other than OpenVMS can be attached to a PSB. The process can therefore have multiple identities: for example, one for OpenVMS and one for NT.

An extension is more than just a data structure attached to a PSB. Routines provided by the extension are called to process the extension data structure. This leaves the layout of the PXB completely up to the author of the extension support routines. A new credential/security extension can be added to a system by simply creating the new extension routines that describe a PXB. This capability will be added in a future release of OpenVMS.

The new and existing SYS$PERSONA system services invoke extension-specific support routines on behalf of the registered extensions. The services also handle new item codes that describe values stored in the PXB. Besides operating on items for individually named extension-specific data, the services use other item codes to establish a current PXB on which subsequent items operate. Before using an extension-specific item code, that extension must be switched to by using the SWITCH_EXTENSION item code. A generic set of item codes pointing to generally useful PXB values (for example, principal name and domain) can be used to fetch these values without concern for the extension-specific name.

Note ##### 1 Earlier versions of OpenVMS contained base support for the persona. The base support was provided by the SYS$PERSONA_CREATE, SYS$PERSONA_ASSUME, and SYS$PERSON_DELETE system services. VAX support is limited to these base services.

## 31.5 Managing Object Protection

An ACL is a list of entries defining the type of access allowed to an object in the system such as a file, device, or mailbox. An access control entry (ACE) consists of an identifier and one or more access types.

                    (IDENTIFIER=GREEN,ACCESS=WRITE+READ+CONTROL)
                    (IDENTIFIER=YELLOW,ACCESS=READ)
                    (IDENTIFIER=RED,ACCESS=NOACCESS)

Managing object protection involves using system services to manipulate protection codes, UICs, and ACEs; that is, creating, translating, and maintaining ACEs, establishing object ownership, and manipulating the protection codes of protected objects.

### 31.5.1 Protected Objects

A protected object is an entity that can contain or receive information. When such information is not considered shareable, access to those objects can be restricted. The system recognizes eleven classes of protected objects as shown in the following table:

Class Name | Description
--- | ---
Capability 1 | A resource to which the system controls access; currently, the only defined capability is the vector processor.
Common event flag cluster | A set of 32 event flags that enable cooperating processes to post event notifications to each other.
Device | A class of peripherals connected to a processor that are capable of receiving, storing, or transmitting data.
File | Files-11 On-Disk Structure Level 2 (ODS-2) files and directories.
Group global section | A shareable memory section potentially available to all processes in the same group.
Logical name table | A shareable table of logical names and their equivalence names for the system or a particular group.
Queue | A set of jobs to be processed in a batch, terminal, server, or print job queue.
Resource domain | A namespace controlling access to the lock manager's resources.
Security class | A data structure containing the elements and management routines for all members of the security class.
System global section | A shareable memory section potentially available to all processes in the system.
Volume | A mass storage medium, such as a disk or tape, that is in ODS-2 format. Volumes contain files and may be mounted on devices.

1Exists only on systems with vector processors

### 31.5.2 Object Security Profile

The security profile summarizes the various types of protection mechanisms applied to a protected object. The security profile associates a protected object with an owner, a protection code, and optionally an ACL. When a user or process requests access to a protected object, the system compares the user's privileges and identifiers in the system authorization database with appropriate elements in the object's security profile.

#### 31.5.2.1 Displaying the Security Profile

You can display an object's security profile by using the SYS$GET_SECURITY system service. On your first call to SYS$GET_SECURITY, be sure to initialize the context variable to 0. Use the OSS$M_RELCTX flag to release any locks on the context structure when the routine completes execution. The following example illustrates the type of information contained in the security profile of a logical name table:

    LNM$GROUP object of class LOGICAL_NAME_TABLE

            Owner: [ACCOUNTING]
            Protection: (System: RWCD, Owner: RWCD, Group: R, World: R)
            Access Control List:
                    (IDENTIFIER=[USER,CHEHKOV],ACCESS=CONTROL)
                    (IDENTIFIER=[USER,VANNEST],ACCESS=READ+WRITE)

After you have returned owner and protection code information, you can call SYS$GET_SECURITY iteratively to return each ACE in the ACL (if it exists) or you can read the entire ACL. In addition, you can perform iterative searches to retrieve objects and their templates.

#### 31.5.2.2 Modifying the Security Profile

You can modify all the security characteristics listed in a protected object's profile by using the SYS$SET_SECURITY system service. You can add or delete ACEs in the ACL selectively or you can delete the entire ACL. You have the option of modifying a local copy of the profile without altering the master copy using the OSS$M_LOCAL flags or you can modify the master copy directly. Also, use the context to release the context structure after the service completes execution.

### 31.5.3 Types of Access Control Entries

There are seven types of security-related ACEs as described in the following table:

ACE | Description
--- | ---
Alarm | Sets an alarm
Application | Contains application-dependent information
Audit | Sets a security audit
Creator | Controls access to an object based on creators
Default Protection | Specifies the default protection for all files and subdirectories created in the directory
Identifier | Controls the type of access allowed based on identifiers
Subsystem | Maintains protected subsystems

For information about the structure of specific types of ACEs, see the SYS$FORMAT_ACL system service in OpenVMS System Services Reference Manual.

You use SYS$FORMAT_ACL and SYS$PARSE_ACL to translate ACEs from one format to another in the same way that SYS$IDTOASC and SYS$ASCTOID translate identifiers from binary to text format and text to binary format.

To create and manipulate ACLs, use the ACL editor, the DCL command SET ACL, or the SYS$GET_SECURITY and SYS$SET_SECURITY system services in a program. The following table lists services that manipulate ACEs:

Service | Description
--- | ---
SYS$FORMAT_ACL | Converts an ACE from binary format to ASCII text
SYS$GET_SECURITY | Retrieves the security characteristics of an object
SYS$PARSE_ACL | Converts an ACE from ASCII text to binary format
SYS$SET_SECURITY | Modifies the security characteristics of a protected object

#### 31.5.3.1 Design Considerations

Before you attempt to manipulate ACLs, you should understand the meaning and relationship among existing identifiers. If you are populating a previously empty ACL, you need to plan the access types and position of each ACE within the ACL.

The position of the ACE within the ACL is an important consideration when creating an ACE. By default, ACEs are added to the top of an ACL. The ACL management services accept options allowing you to control the placement of ACEs. The system compares the identifiers granted to the process requesting access with those associated with the object starting with the top ACE in the object's ACL. Once a matching identifier name is found in the object's ACL, the search stops.

#### 31.5.3.2 Translating ACEs

To translate ACEs from binary format to a text string, use the SYS$FORMAT_ACL service. The aclent argument is the address of a descriptor pointing to a buffer containing the description of the ACE. The first byte of the buffer contains the length of the ACE and the second byte contains the type, which in turn defines the format of the ACE.

The acllen argument specifies the length of the text string written to the buffer pointed to by aclstr. You use the width, trmdsc, and indent arguments to specify a particular width, termination character, and number of blank characters for an ACE. The accnam argument contains the address of an array of 32 quadword descriptors called an access name table. The access name table defines the names of the bits in the access mask of the ACE. The access mask defines the access types associated with a protected object. Use run-time library (RTL) routine LIB$GET_ACCNAM described in the OpenVMS RTL Library (LIB$) Manual to obtain the address of the access name table. If accnam is omitted, the following names are used:

    Bit <0>    READ
    Bit <1>    WRITE
    Bit <2>    EXECUTE
    Bit <3>    DELETE
    Bit <4>    CONTROL
    Bit <5>    BIT_5
    Bit <6>    BIT_6
       .
       .
       .
    Bit <31>   BIT_31

The SYS$PARSE_ACL service translates an ACE from text string format to binary format. The aclstr argument is the address of a string descriptor pointing to the ACE text string. As with SYS$FORMAT_ACL, the aclent argument is the address of a descriptor pointing to a buffer containing the description of the ACE. The first byte of the buffer contains the length of the ACE and the second byte contains the type, which in turn defines the format of the ACE. If SYS$PARSE_ACL fails, the errpos argument points to the failing point in the string. The accnam argument contains the address of an array of 32 quadword descriptors that define the names of the bits in the access mask of the ACE. If accnam is omitted, the names specified in the description of SYS$FORMAT_ACL are used.

#### 31.5.3.3 Creating and Maintaining ACEs

The SYS$GET_SECURITY and SYS$SET_SECURITY system services replace the SYS$CHANGE_ACL system service. The OpenVMS System Services Reference Manual: A--GETUAI and the OpenVMS System Services Reference Manual: GETUTC--Z describe these system services.

To create or modify an ACL associated with a protected object, you use the SYS$SET_SECURITY service. You specify the object whose ACL is to be modified with either the objhan argument, which specifies the I/O channel associated with the object, or the objnam argument, which specifies the object name. If you specify objnam, objhan must be omitted or specified as 0. The clsnam argument specifies the type of object.

Use the acmode argument to specify the access mode used when checking file access protection. By default, kernel mode is used, but the system compares acmode against the caller's access mode and uses the least privileged mode. Compaq recommends that this argument be omitted (passed as zero).

The item code specifies the change to be made to the ACL. Table 31-3 describes the symbols for the item codes that are defined in the system macro library ($ACLDEF). Note that without the itmlst argument, you can manipulate only the security profile locks or release contxt resources.

Table 31-3 Item Code Symbols and Meanings
Item Code | Description
--- | ---
OSS$_ACL_ADD_ENTRY | Adds an access control entry (ACE)
OSS$_ACL_DELETE | Deletes all unprotected ACEs from an ACL
OSS$_ACL_DELETE_ALL | Deletes the ACL, including protected ACEs
OSS$_ACL_DELETE_ENTRY | Deletes an ACE
OSS$_ACL_FIND_ENTRY | Locates an ACE
OSS$_ACL_FIND_NEXT | Moves the current position to the next ACE in the ACL
OSS$_ACL_FIND_TYPE | Locates an ACE of the specified type
OSS$_ACL_MODIFY_ENTRY | Replaces an ACE at the current position
OSS$_ACL_POSITION_BOTTOM | Sets a marker that points to the end of the ACL
OSS$_ACL_POSITION_TOP | Sets a marker that points to the beginning of the ACL
OSS$_OWNER | Sets the UIC or general identifier of the object's owner
OSS$_PROTECTION | Sets the protection code of the object

## 31.6 Protected Subsystems

A protected subsystem is a set of application programs that allows controlled access to objects. It has under its control one or more protected objects and a gatekeeper application. Users cannot access the objects within the subsystem unless they execute the gatekeeper application. Once users have successfully executed the application, their process rights list acquires the identifiers necessary to access objects owned by the subsystem. The identifiers allow processes to use the resources of the subsystem. When the application completes execution or the user exits, the identifiers are removed from the user's process rights list. Protected subsystems are an alternative to creating privileged images and protected shareable images (user-written system services), and help prevent the overuse of privileges.

Roles and Responsibilities

You should think of a protected subsystem as an isolated security domain where the system manager creates and grants SUBSYSTEM identifiers using the Authorize utility as shown in the following example:

    UAF> ADD/IDENTIFIER FOO/ATTRIBUTES=SUBSYSTEM
    UAF> GRANT/IDENTIFIER FOO FRANK /ATTRIBUTES=SUBSYSTEM

The system manager can delegate responsibility for the maintenance of the subsystem to subsystem managers who can associate existing identifiers with the subsystem executable and its data. In the following example, the manager of a protected subsystem creates an ACE in a subsystem's image and data files:

    $ SET SECURITY BLOP.EXE -
    _$ /ACL=(SUBSYSTEM, IDENTIFIER=FOO) -
    $ SET SECURITY BLOP.DAT -
    _$ /ACL=(IDENTIFIER=FOO, ACCESS=READ+WRITE) -
    $ SET SECURITY BLOP.EXE -
    _$ /ACL=(IDENTIFIER=HARRY, ACCESS=EXECUTE) -

Finally, a user uses the protected subsystem to access data available only through the subsystem.

Subsystem Security

During the execution of a protected subsystem, $IMGACT adds subsystem identifiers to the image rights list. What happens if the user presses the Ctrl/Y key sequence during execution? Will the user retain whatever privileges were granted by the subsystem? If the user presses Ctrl/Y, image identifiers are removed from the process. Also, subprocesses do not inherit image identifiers by default. However, SYS$CREPRC and LIB$SPAWN do contain flags PRC$M_SUBSYSTEM and SUBSYSTEM, respectively, that allow subprocesses to inherit image identifiers.

Previous | Next | Contents | Index

| privacy and legal statement |
5841PRO_081.HTML