INGPW

Purpose

The INGPW command initializes the SA z/OS® password encoding feature. The INGPW command processor maintains a VSAM file containing passwords for user IDs, called the password data set. These passwords are used when establishing sessions to external products. The records in the password data set are keyed using a combination of the user ID and owner ID. Each record has these fields:

  • The current-password field
  • The new-password field
  • The password mask
  • The date-password-last-changed field
  • The password change interval
  • Passwords are stored in encoded format

Syntax

Read syntax diagramSkip visual syntax diagramINGPWuser_IDowner_ID ,READ,INIT,MASK= %X%X%X%X%X%X%X%X,MASK= mask,EXPINT= 0,EXPINT= int,INIT= password,MASK= %X%X%X%X%X%X%X%X,MASK= mask,EXPINT= 0,EXPINT= int,DELETE,REGEN,MASK= %X%X%X%X%X%X%X%X,MASK= mask,EXPINT= 0,EXPINT= int,UPDATE

Parameters

user_id
user id (4-32 characters). The parameter is case-sensitive.
owner_id
(1-8 characters) the owning entity for which password maintenance services are required (custom value, policy entry, and so on, depends on consumer service). The parameter is case-sensitive.
READ
Specifies that the appropriate password is retrieved from the data set. This is the default if no request is specified.
INIT
Used to create an entry in the password data set for the specified user_id and owner_id values and to specify an initial or new password value for the entry. Using INGPW with the INIT parameter is required as part of installing the password protection feature. An INIT request without a new password can be used to redefine expiration interval and password mask for the existing password record. If a value is specified for the MASK=mask keyword together with the INIT keyword, then the value of the mask becomes the default mask for the REGEN keyword.
password
Specifies initial/new password for the specified user_id and owner_id. The password value must be between 4 and 32 characters long. The password is case-sensitive.
DELETE
Specifies that the record with the matching user_id and owner_id should be deleted.
REGEN
Causes a new password to be generated (satisfying the requirements of the mask if it is specified). The current and new passwords are shown in response to INGPW REGEN and any subsequent INGPW READ until there is a INGPW UPDATE.
MASK
Describes the format used when generating new passwords for specified user_id and owner_id records. The password generation mask consists of 4 to 32 pairs of characters, each pair defining the attributes of a single password character. The first character of each pair determines how the second character is used.
!
A password character of the value indicated by the following mask character is required.
%
A password character of the type indicated by the following mask character is required.
?
A password character of the type indicated by the following mask character is optional.
The password mask is processed from left to right, and generates a string of characters with a length equal to or greater than the number required. Passwords of at least 4 characters are required. The password character type codes indicate a set of characters to be used when generating a new password. The valid type codes are case-sensitive and are as follows:
  • $ - National only
  • A - Uppercase alphabetic only
  • a - Lowercase alphabetic only
  • B - Uppercase Alphabetic/National
  • b - Lowercase Alphabetic/National
  • C - Uppercase Consonant (Alphabetic, no vowels)
  • c - Lowercase Consonant (Alphabetic, no vowels)
  • E - Even numerics
  • N - Numeric only
  • O - Odd numerics
  • V - Uppercase vowels only
  • v - Lowercase vowels only
  • W - Uppercase alphanumerics (no vowels)
  • w - Lowercase alphanumerics (no vowels)
  • X - Uppercase alphanumerics
  • x - Lowercase alphanumerics
  • Y - Uppercase alphabetical/National
  • y - Lowercase alphabetical/National
  • Z - Uppercase alphanumeric/National (no vowels)
  • z - Lowercase alphanumeric/National (no vowels)
For example, a password mask of !N!N!T%$%C?N%N%E would cause passwords to be generated that begin with 'NNT' followed by a national character, a consonant, and a two or three digit even number. If a value is not specified for mask, then the system-defined default is %X%X%X%X%X%X%X%X.
EXPINT
Defines the expiration interval used when defining or generating new passwords.
int
number of days before current password expiration and next password regeneration. Default is 0 (no password expiration required). The expiration interval can be 0 to 365 days.
UPDATE
Makes the new password generated by REGEN become the current password.

Return Codes

0
Successful completion.
4
No storage obtained.
8
Record not found in VSAM data set.
12
Error Processing VSAM data set.
16
Bad Invocation.
20
Not Authorized.

Security considerations

For security reasons, using command-class checking on INGPW is strongly recommended. Refer to IBM Z System Automation Planning and Installation for more details about command authorization.

Access to the password records can be protected using the ING.PW.user_id.owner_id resource in the SYSAUTO class defined in RACF. The following example shows how to define an INGPW resource in RACF:

RDEFINE SYSAUTO ING.PW.HMCOPER2.CPCLOUD1 UACC(NONE)

The user record for user_id HMCOPER2 and owner_id CPCLOUD1 is defined as a resource in the RACF class SYSAUTO with a universal access attribute of NONE. Note that you can use a wildcard character to specify the resource more generically if that is suitable for your environment.

Level of password access  
READ: read password record (READ request)
UPDATE: update existing password (UPDATE request)
CONTROL: initialize or change existing record (INIT,REGEN requests)
ALTER: delete password record (DELETE request)

Usage

Use a blank instead of a comma to separate the user_id and owner_id values.

If parameter values are required in mixed case (for example, mixed case passwords), you must use the 'NetVasis INGPW' form to make sure that the data is passed without uppercase translation. Failure to do so may result in incorrect data returned or generated by the INGPW command.

Examples

NETVASIS INGPW TestUser TESTSRV,INIT=MYp01WDs,MASK=%A%A%a%N%N%A%A%a
The command initializes a new record for used_id=TestUser and owner_id=TESTSRV with initial mixed case password MYp01WDs and set MASK to generate passwords in mixed case.

INGPW TestUser TESTSRV,INIT=MYp01WDs,MASK=%A%A%a%N%N%A%A%A
The command initializes a new record for used_id=TestUser and owner_id=TESTSRV with initial upper case password MYP01WDS and set MASK to generate passwords in uppercase.