Updated: 11 December 1998

OpenVMS Programming Concepts Manual

When a process is created, LOGINOUT builds a rights list for the process consisting of the identifiers the user holds and any appropriate environmental identifiers. A system rights list is the default rights list used in addition to any process rights list. Modifications to the system rights list effectively become modifications to the rights of each process.

A privileged user can alter the process or system rights list with the SYS$GRANTID or SYS$REVOKID services. These services are not intended for the general system user. Use of these services requires CMKRNL privilege. The SYS$GRANTID service adds an identifier to a rights list or, if the identifier is already part of the rights list, the SYS$GRANTID service modifies the attributes of the identifier. The SYS$REVOKID service removes an identifier from a rights list.

The SYS$GRANTID and SYS$REVOKID services treat the pidadr and prcnam arguments the same way all other process control services treat these arguments. For more details, see the OpenVMS Guide to System Security.

You can also modify the process or system rights list with the DCL command SET RIGHTS_LIST. Additionally, you can use SET RIGHTS_LIST to modify the attributes of the identifier if the identifier is already part of the rights list. Note that you cannot use the SET RIGHTS_LIST command to modify the rights database from which the rights list was created. For more information about using the SET RIGHTS_LIST command, see the OpenVMS DCL Dictionary.

25.4 Persona (Alpha Only¹)

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

For client-server applications, the server processes requests on behalf of the client. With OpenVMS, the server application developer can utilize 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.

25.4.1.1 Using Impersonation System Services

The following discussion assumes there is a running server, which 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 multi-threaded 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.
• Removes 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: GETQUI--Z.

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

25.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 25-7 shows this relationship.

Figure 25-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 amoung themselves

With OpenVMS Version 7.2, the user's 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 25-8 shows these relationships.

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

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

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

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

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.

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

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

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

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

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

25.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--GETMSG and the OpenVMS System Services Reference Manual: GETQUI--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 25-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 25-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

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5841PRO_066.HTML