 |
HP OpenVMS System Services Reference Manual
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.
HP 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.
|
$HIBER
Allows a process to make itself inactive but to remain known to the
system so that it can be interrupted; for example, to receive ASTs.
Format
SYS$HIBER
C Prototype
int sys$hiber (void);
Arguments
None.
Description
The Hibernate service allows a process to make itself inactive but to
remain known to the system so that it can be interrupted; for example,
to receive ASTs. A hibernate request is a wait-for-wake-event request.
When you call the Wake Process from Hibernation ($WAKE) service or when
the time specified with the Schedule Wakeup ($SCHDWK) service occurs,
the process continues execution at the instruction following the
Hibernate call.
In VAX MACRO, you can call the Hibernate service only by using the
$name_S macro.
A hibernating process can be swapped out of the balance set if it is
not locked into the balance set.
An AST can interrupt the wait state caused by $HIBER if the access mode
at which the AST is to execute is equal to or more privileged than the
access mode from which the hibernate request was issued and the process
is enabled for ASTs at that access mode.
When the AST service routine completes execution, the system reexecutes
the $HIBER service on behalf of the process. If a wakeup request has
been issued for the process during the execution of the AST service
routine (either by itself or another process), the process resumes
execution. If a wakeup request has not been issued, it continues to
hibernate.
If one or more wakeup requests are issued for the process while it is
not hibernating, the next hibernate call returns immediately; that is,
the process does not hibernate. No count of outstanding wakeup requests
is maintained.
Although this service has no arguments, a Fortran function reference
must use parentheses to indicate a null argument list, as in the
following example:
Required Access or Privileges
None
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,
$PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
$ICC_ACCEPT
Responds to an incoming connection request. This call is used to
complete an ICC connection from the server side.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$ICC_ACCEPT conn_handle ,[accept_buf] ,[accept_len] ,[user_context]
,[flags]
C Prototype
int sys$icc_accept (unsigned int conn_handle, char * accept_buf,
unsigned int accept_len, unsigned int user_context, unsigned int flags);
Arguments
conn_handle
| OpenVMS usage: |
connection_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The handle of the requested connection.
accept_buf
| OpenVMS usage: |
byte_stream |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
A buffer of up to 1000 bytes of accept data that is sent to the source
of the connection at the completion of the connection process.
accept_len
| OpenVMS usage: |
buffer_length |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The actual number of bytes in accept_buf to be sent.
user_context
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) (VAX); quadword (Alpha and
I64) |
| access: |
read only |
| mechanism: |
by value |
A user-specified value that is subsequently returned on any disconnect
or data events on this connection.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
ICC$M_SYNCH_MODE can be specified to indicate that the data
transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and
$ICC_REPLY are allowed to return the status SS$_SYNCH in the case of
synchronous completion, and that the AST will not be called.
Description
This service is used by a server to respond to an incoming connection
request. The $ICC_ACCEPT service may only be called after receiving a
connection request AST.
At the completion of the service, the connection is open and data can
be exchanged. Once opened, there is no logical distinction between a
connection opened by a client with the Connect service or a server with
the Accept service.
A server can reject a Connection request by calling the $ICC_REJECT
service.
Required Access or Privileges
None.
Required Quota
$ICC_ACCEPT changes the process BYTLM quota for the length of the
accept_buf parameter, as well as a fixed value for
each potential Receive buffer on the connection. The number of
potential Receive buffers is specified by the MAXFLOWBUFCNT parameter
in the $ICC_OPEN_ASSOC service.
Related Services
$ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT,
$ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW,
$ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE,
$ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_ACCVIO
|
Access violation on parameter.
|
|
SS$_BADPARAM
|
Bad parameter value specified.
|
|
SS$_CLEARED
|
Remote association closed the link before it was accepted.
|
|
SS$_EXQUOTA
|
Exceeded BYTCNT/BYTLM.
|
|
SS$_INSFARG
|
Too few arguments supplied.
|
|
SS$_INSFMEM
|
Not enough system resources or process virtual memory available.
|
|
SS$_IVMODE
|
Attempted to accept a connection from a more privileged access mode
than the requested association.
|
|
SS$_IVCHAN
|
Connection not found or Invalid connection handle.
|
|
SS$_LINKDISCON
|
The connection is valid, but the physical link has started to
disconnect.
|
|
SS$_TOO_MANY_ARGS
|
Too many arguments specified.
|
|
SS$_WRONGSTATE
|
Connection is in the wrong state for the request.
|
$ICC_CLOSE_ASSOC
Closes the application's association with ICC.
Format
SYS$ICC_CLOSE_ASSOC assoc_handle
C Prototype
int sys$icc_close_assoc (unsigned int assoc_handle);
Arguments
assoc_handle
| OpenVMS usage: |
association_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The handle of the association to be closed.
Description
This service closes the application's association with ICC. If multiple
associations are open, only the specified association is closed. When
an association is closed, any active connections on that association
are disconnected. If not explicitly closed by the application,
associations opened in user mode will be closed at image exit;
associations opened in inner modes will be closed at process
termination.
All operations on an association must occur in the access mode at which
the association was opened.
When an association is closed, the entry (if any) in the simple
clusterwide association registry is removed.
Required Access or Privileges
None.
Required Quota
None.
Related Services
$ICC_ACCEPT, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT,
$ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW,
$ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE,
$ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_INSFARG
|
The
assoc_handle was not supplied.
|
|
SS$_IVCHAN
|
Invalid association handle.
|
|
SS$_IVMODE
|
Attempted to close an association from a more privileged access mode
than the requested association.
|
|
SS$_TOO_MANY_ARGS
|
Too many arguments specified.
|
$ICC_CONNECT
Establishes a connection to a remote application over an open
association.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$ICC_CONNECT ios_icc ,[astadr] ,[astprm] ,assoc_handle ,conn_handle
,remote_assoc ,[remote_node] ,[user_context] ,[conn_buf]
,[conn_buf_len] ,[return_buf] ,[return_buf_len] ,[retlen_addr] ,[flags]
C Prototype
int sys$icc_connect (struct _ios_icc *ios_icc, void
(*astadr)(__unknown_params), __int64 astprm, unsigned int assoc_handle,
unsigned int *conn_handle, void *remote_assoc, void *remote_node,
unsigned int user_context, char *conn_buf, unsigned int conn_buf_len,
char *return_buf, unsigned int return_buf_len, unsigned int
*retlen_addr, unsigned int flags);
Arguments
ios_icc
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
I/O status block:
Completion status values:
SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM, SS$_IVBUFLEN,
SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM, SS$_NOSUCHOBJ,
SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT, SS$_SSFAIL, SS$_UNREACHABLE,
SS$_WRONGSTATE
The second longword is undefined unless the completion code is
SS$_REJECT. In this case, the application-defined rejection reason code
is supplied by the server when $ICC_REJECT is called.
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure_entry_mask |
| access: |
call without stack unwinding |
| mechanism: |
by 32-bit or 64-bit linkage reference (Alpha and I64); by
32-bit reference (VAX) |
The AST routine to be executed when the operation completes.
astprm
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) (Alpha and I64); longword (unsigned)
(VAX) |
| access: |
read only |
| mechanism: |
by 64-bit value (Alpha and I64); by 32-bit value
(VAX) |
The parameter to be passed to the AST routine.
assoc_handle
| OpenVMS usage: |
association_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The handle of the association on which the connection is to be opened.
The constant ICC$C_DFLT_ASSOC_HANDLE, if used, indicates that the
default association is to be used (and opened if necessary).
conn_handle
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
The 32-bit or 64-bit address (on Alpha and I64 systems) or the 32-bit
address (on VAX systems) of a longword into which $ICC_CONNECT writes
the connection handle of the created connection on a successful call.
remote_assoc
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit descriptor (Alpha and I64); by 32-bit
descriptor (VAX) |
An ASCII character string (31 characters maximum) specifying the name
of the target application to connect to. Association names are case
sensitive.
remote_node
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit descriptor (Alpha and I64); by 32-bit
descriptor (VAX) |
The name of the node where the target association resides. A null or
blank string can be used to indicate the local node. If omitted (by
passing zero by value), the simple clusterwide association registry is
to be used. Each node name is a one-to-six character SCS node name. A
comma-delimited list of nodes may be specified, indicating that one is
to be chosen at random.
user_context
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) (VAX); quadword (Alpha and
I64) |
| access: |
read only |
| mechanism: |
by value |
A user-specified value to be subsequently returned on any disconnect or
data events on this connection.
conn_buf
| OpenVMS usage: |
byte_stream |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
A buffer of up to 1000 bytes of connection data to be sent to the
target of the connection during the connection process.
conn_buf_len
| OpenVMS usage: |
buffer_length |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The number of bytes in conn_buf to be sent.
return_buf
| OpenVMS usage: |
byte_stream |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
A buffer of up to 1000 bytes in length to receive any incoming
connection accept or reject data returned.
return_buf_len
| OpenVMS usage: |
buffer_length |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The length of the supplied return_buf.
retlen_addr
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
The 32-bit or 64-bit address (on Alpha and I64 systems) or the 32-bit
address (on VAX systems) of a longword into which $ICC_CONNECT writes
the actual length (in bytes) of any user accept or reject data returned
in the buffer return_buf.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
ICC$M_SYNCH_MODE can be specified to indicate that the data
transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and
$ICC_REPLY are allowed to return the status SS$_SYNCH in the case of
synchronous completion, indicating that the AST will not be called.
Description
This service establishes a connection to a remote application over an
open association. Connections must be opened in the same mode as their
association. If the user provides the default association constant
ICC$C_DFLT_ASSOC_HANDLE as its association handle, the default
association will be used; it will be opened if it is not already open.
Multiple connections are possible over a single association. When
completion is signaled by the AST routine, the application must check
the completion status field of the IOS_ICC to determine if the server
has accepted or rejected the connection request. The number of
connections is subject to process BYTLM quota.
|
