Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $GOTO_UNWIND (Alpha Only)

> On Alpha systems, unwinds the call stack.

### Format

> SYS$GOTO_UNWIND target_invo ,target_pc ,[new_r0] ,[new_r1]

### C Prototype

> int sys$goto_unwind (void *target_invo, void *(*(target_pc)), unsigned __int64 *new_r0, unsigned __int64 *new_r1);

### Arguments

> #### target_invo

> OpenVMS usage: | invo_handle
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> The address of a location that contains a handle for the target invocation.

> If you do not specify the target_invo argument, or if the handle value is 0, an exit unwind is initiated.

> #### target_pc

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

> The address of a location that contains the address at which execution should continue in the target invocation.

> If the target_pc argument is omitted or the value is 0, a system-defined target PC is assumed and execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

> #### new_r0

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by reference

> The address of a location that contains the value to place in the saved R0 location of the mechanism argument vector. The contents of this location are then loaded into the processor R0 register at the time that execution continues in the target invocation.

> If the new_r0 argument is omitted, the contents of the processor R0 register at the time of the call to $GOTO_UNWIND are used.

> #### new_r1

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by reference

> Address of a location that contains the value to place in the saved R1 location of the mechanism argument vector. The contents of the location are then loaded into the processor R1 register at the time that execution continues in the target invocation.

> If the new_r1 argument is omitted, the contents of the processor R1 register at the time of the call to $GOTO_UNWIND are used.

### Description

> The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> $UNWIND

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The specified target_invo, target_pc, new_r0, or new_r1 argument is not accessible.

## $GRANTID

> Adds the specified identifier record to the rights list of the process or the system.

### Format

> SYS$GRANTID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]

### C Prototype

> int sys$grantid (unsigned int *pidadr, void *prcnam, struct _generic_64 *id, void *name, unsigned int *prvatr, unsigned int segment);

### Arguments

> #### pidadr

> OpenVMS usage: | process_id
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> Process identification (PID) number of the process affected when $GRANTID completes execution. The pidadr argument is the address of a longword containing the PID of the process to be affected. You use --1 to indicate the system rights list. When pidadr is passed, it is also returned; therefore, you must pass it as a variable rather than a constant. If you specify neither pidadr nor prcnam, your own process is used.

> #### prcnam

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

> Process name on which $GRANTID operates. The prcnam argument is the address of a character string descriptor containing the process name. The maximum length of the name is 15 characters. Because the UIC group number is interpreted as part of the process name, you must use pidadr to specify the rights list of a process in a different group. If you specify neither pidadr nor prcnam, your own process is used.

> #### id

> OpenVMS usage: | rights_holder
> type: | quadword (unsigned)
> access: | modify
> mechanism: | by reference

> Identifier and attributes to be granted when $GRANTID completes execution. The id argument is the address of a quadword containing the binary identifier code to be granted in the first longword and the attributes in the second longword.

> Use the id argument to modify the attributes of the identifier.

> Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position are defined in the macro library ($KGBDEF):

> Bit Position | Meaning When Set
> --- | ---
> KGB$V_DYNAMIC | Allows holders of the identifier to remove it from or add it to the process rights database using the DCL command SET RIGHTS_LIST.
> KGB$V_NOACCESS | Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
> KGB$V_RESOURCE | Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
> KGB$V_SUBSYSTEM | Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

> You must specify either id or name. Because the id argument is returned as well as passed if you specify name, you must pass it as a variable rather than a constant in this case.

> #### name

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

> Name of the identifier granted when $GRANTID completes execution. The name argument is the address of a descriptor pointing to the name of the identifier. The identifier is granted as it is created. You must specify either id or name.

> #### prvatr

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

> Previous attributes of the identifier. The prvatr argument is the address of a longword used to store the attributes of the identifier if it was previously present in the rights list. If you added rather than modified the identifier, prvatr is ignored.

### Description

> The Grant Identifier to Process service adds the specified identifier to the rights list of the process or the system. If the identifier is already in the rights list, its attributes are modified to those specified. This service is meant to be used by a privileged subsystem to alter the access rights profile of a user, based on installation policy. It is not meant to be used by the general system user.

> The result of passing the pidadr or the prcnam argument, or both, to SYS$GRANTID is summarized in the following table:

> prcnam | pidadr | Result
> --- | --- | ---
> Omitted | Omitted | Current process ID is used; process ID is not returned.
> Omitted | 0 | Current process ID is used; process ID is returned.
> Omitted | Specified | Specified process ID is used.
> Specified | Omitted | Specified process name is used; process ID is not returned.
> Specified | 0 | Specified process name is used; process ID is returned.
> Specified | Specified | Specified process ID is used and process name is ignored.

> The result of passing the name or the id argument, or both, to SYS$GRANTID is summarized in the following table:

> name | id | Result
> --- | --- | ---
> Omitted | Omitted | Illegal. The INSFARG condition value is returned.
> Omitted | Specified | Specified identifier value is used.
> Specified | Omitted | Specified identifier name is used; identifier value is not returned.
> Specified | 0 | Specified identifier name is used; identifier value is returned.
> Specified | Specified | Specified identifier value is used and identifier name is ignored.

> Note that a value of 0 in either of the preceding tables indicates that the contents of the address specified by the argument is the value 0. The word omitted indicates that the argument was not supplied.

> Required Access or Privileges

> You need CMKRNL privilege to invoke this service. In addition, you need GROUP privilege to modify the rights list of a process in the same group as the calling process (unless the process has the same UIC as the calling process). You need WORLD privilege to modify the rights list of a process outside the caller's group. You need SYSNAM privilege to modify the system rights list.

> Required Quota

> None

> Related Services

> $ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

### Condition Values Returned

> SS$_WASCLR | The service completed successfully; the rights list did not contain the specified identifier.
> SS$_WASSET | The service completed successfully; the rights list already held the specified identifier.
> SS$_ACCVIO | The pidadr argument cannot be read or written; prcnam cannot be read; id cannot be read or written; the name cannot be read; or prvatr cannot be written.
> SS$_INSFARG | You did not specify either the id or the name argument.
> SS$_INSFMEM | The process dynamic memory is insufficient for opening the rights database.
> SS$_IVIDENT | The specified identifier name is invalid; the identifier name is longer than 31 characters, contains an illegal character, or does not contain at least one nonnumeric character.
> SS$_IVLOGNAM | You specified an invalid process name.
> SS$_NONEXPR | You specified a nonexistent process.
> SS$_NOPRIV | The caller does not have CMKRNL privilege or is not running in executive or kernel mode, or the caller lacks GROUP, WORLD, or SYSNAM privilege as required.
> SS$_NOSUCHID | The specified identifier name does not exist in the rights database. Note that the binary identifier, if given, is not validated against the rights database.
> SS$_NOSYSNAM | The operation requires SYSNAM privilege.
> SS$_RIGHTSFULL | The rights list of the process or system is full.
> RMS$_PRV | The user does not have read access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

## $HASH_PASSWORD

> Applies the hash algorithm you select to an ASCII password string and returns a quadword hash value that represents the encrypted password.

### Format

> SYS$HASH_PASSWORD pwd ,alg ,[salt] ,usrnam ,hash

### C Prototype

> int sys$hash_password (void *pwd, unsigned char alg, unsigned short int salt, void *usrnam, struct _generic_64 *hash);

### Arguments

> #### pwd

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

> ASCII password string to be encrypted. The pwd argument is the address of a character string descriptor pointing to the ASCII password. The password string can contain between 1 and 32 characters and use the uppercase characters A through Z, the numbers 0 through 9, the dollar sign ($), and the underscore (_).

> The caller must validate the password string before calling $HASH_PASSWORD to ensure that only permitted characters are included.

> #### alg

> OpenVMS usage: | byte_unsigned
> type: | byte (unsigned)
> access: | read only
> mechanism: | by value

> Algorithm used to hash the ASCII password string. The alg argument is an unsigned byte specifying the hash algorithm.

> The operating system recognizes the following algorithms:

> Symbolic Name | Description
> --- | ---
> UAI$K_AD_II | Uses a CRC algorithm and returns a longword hash value. This algorithm was used in releases prior to VAX VMS Version 2.0.
> UAI$C_PURDY | Uses a Purdy algorithm over salted input. It expects a blank-padded user name and returns a quadword hash value. This algorithm was used during VAX VMS Version 2.0 field test.
> UAI$C_PURDY_V | Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This algorithm was used in releases prior to VMS Version 5.4.
> UAI$K_PURDY_S | Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This algorithm is used to hash all new passwords in VMS Version 5.4 and later.
> UAI$C_PREFERED_ALGORITHM 1 | Represents the latest encryption algorithm that the operating system uses to encrypt new passwords. Currently, it equates to UAI$C_PURDY_S. Compaq recommends that you use this symbol in source modules because it always equates with the most recent algorithm.

1 The value of this symbol might be changed in future releases if an additional algorithm is introduced.

Values ranging from 128 to 255 are reserved for customer use; the constant UAI$K_CUST_ALGORITHM defines the start of this range.

You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes with the $GETUAI system service to retrieve the primary and secondary password hash algorithms for a user.

#### salt

OpenVMS usage: | word_unsigned
type: | word (unsigned)
access: | read only
mechanism: | by value

Value used to increase the effectiveness of the hash. The salt argument is an unsigned word containing 16 bits of data that is used by the hash algorithms when encrypting a password for the associated user name. The $GETUAI item code UAI$_SALT is used to retrieve the SALT value for a given user. If you do not specify a SALT value, $HASH_PASSWORD uses the value of 0.

#### usrnam

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

Name of the user associated with the password. The usrnam argument is the address of a descriptor pointing to a character text string containing the user name. The current password encryption algorithm (UAI$C_PURDY_S) folds the user name into the ASCII password string to ensure that different users with the same password produce different hash values. This argument must be supplied for all calls to $HASH_PASSWORD but is ignored when using the CRC algorithm (UAI$C_AD_II).

#### hash

OpenVMS usage: | quadword_unsigned
type: | quadword (unsigned)
access: | write only
mechanism: | by reference

Output hash value representing the encrypted password. The hash argument is the address of an unsigned quadword to which $HASH_PASSWORD writes the output of the hash. If you use the UAI$C_AD_II algorithm, the second longword of the hash is always set to 0.

### Description

> The Hash Password service applies the hash algorithm you select to an ASCII password string and returns a quadword hash value that represents the encrypted password.

> Other OpenVMS password services allow spaces, tabs, and other blank characters from the user, but they remove those spaces before passing the string to $HASH_PASSWORD. Before calling $HASH_PASSWORD, all white space must be removed from the password string to ensure proper comparison with passwords created by other services.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> $GETUAI, $SETUAI.

> Use $GETUAI to get the values for the salt and alg arguments. Use $SETUAI to store the resulting hash using the item codes UAI$_PWD and UAI$_PWD2.

> For more information, see the appendix on implementing site-specific security policies in the OpenVMS Programming Concepts Manual.

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The input or output buffer descriptors cannot be read or written to by the caller.
> SS$_BADPARAM | The specified hash algorithm is unknown or invalid.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_059.HTML