The Work Validation List Entries tool is a series of commands that
simplify working with validation list entries. After creating a
Validation List, the remaining functions such as adding, changing,
removing, displaying, verifying, retrieving, and converting can be
done with TAA commands rather than system APIs.
Validation lists are typically used with web applications to
authenticate internet users to avoid having to create user profile
objects for them. Password like values may be assigned. Web
configuration tools normally allow authentication using a validation
list.
The system supplied APIs do not provide data translation (CCSIDs),
but the TAA commands do.
A validation list may also be used for any application use where
password type checking or additional password type checking is
required.
A validation list entry contains:
** Entry ID information used to identify the entry. It may be up
to 100 characters and is case sensitive.
** Encryption data (normally used as a password) is encrypted by
the system when an entry is stored. Up to 600 characters may
be entered and is case sensitive.
** Data associated with the entry may be up to 1000 characters
and is case sensitive. This can be just a text description or
it can be a formatted data structure to assist in various
needs.
** Attribute information. The system currently supports a single
attribute which determines whether the encryption data is used
only to verify a user (one-way encryption) or to verify a user
and be retrieved and displayed (two-way encryption).
However, verification can only be done if the QRETSVRSEC
system value is set to '1' to retain the encrypted data. See
the later discussion of the QRETSVRSEC system value.
Commands provided
-----------------
** ADDVLDLE. Adds a validation list entry.
** CHGVLDLE. Changes a validation list entry.
** RMVVLDLE. Removes a validation list entry.
** RTVVLDLE. Retrieves a validation list entry.
** CVTVLDLE. Converts validation list entries to an outfile.
** VFYVLDLE. Verifies a validation list entry.
** WRKVLDLE. Work with validation list entries for a specific
validation list.
** WRKVLDL. Works with validation list objects (a separate tool)
and allows access to WRKVLDLE.
QRETSVRSEC System Value
-----------------------
To understand the system validation list support, you must be aware
of the QRETSVRSEC system value function and the 'method' chosen for
the ENCRYPT parameter on ADD/CHGVLDLE.
** The QRETSVRSEC system value controls whether the security data
needed to authenticate a user can be retained on the host
system. The system uses the word 'retained', but this is not
a good description of how the system operates. Regardless of
the system value setting, the system actually retains the
encrypted data when you add or change an entry. The setting
of the system value determines whether you can actually 'use'
the encrypted data. The words 'using' and 'use' will occur in
this section rather than 'retained'.
The shipped value of QRETSVRSEC by the system is '0' which
prevents any use of the encrypted data such as verification.
For example, the VFYVLDLE command will always return an escape
message.
When QRETSVRSEC is '0', it does not matter what method is
specified for the ENCRYPT parameter. Verification cannot be
performed. The RTVVLDLE command will return *UNAVAILABLE and
the display option will also show *UNAVAILABLE for the
encrypted data.
** If QRETSVRSEC is '1', the system will allow use of the
encrypted data and can authenticate (verify) an entry using
either the *ONEWAY or *TWOWAY method. For example, the entry
can be authenticated by using the VFYVLDLE command and passing
it the value that is specified for 'encrypted data'.
The ENCRYPT method value determines whether the encrypted
value can be displayed or retrieved.
-- If *ONEWAY is specified, the value cannot be displayed
or retrieved. *UNAVAILABLE will be displayed or
retrieved.
-- If *TWOWAY is specified, the encrypted value can be
displayed and retrieved.
** Since regardless of what is specified for QRETSVRSEC, the
system is actually storing the encrypted data, a change to the
system value will change how the system functions. You do not
have to change the way the entries were originally added (or
changed).
For example, if you change the system value from '0' to '1',
an entry can be authenticated and the method of the entry
determines whether you can display or retrieve the data.
Conversely, if you change from '1' to '0', you cannot
authenticate the entry and cannot retrieve or display the
encrypted data. The encrypted data remains stored on the
system and can be used if you change the system value back to
'1'.
To remove all information, the CLRSVRSEC system command exists
which was added in V5R3.
V5R2 users should note that changing from '1' to '0' will
remove all information.
Getting started
---------------
** Review if you have any Validation List (*VLDL) objects on the
user library list with WRKVLDL (a separate tool):
WRKVLDL VLDL(*ALL)
WRKVLDL defaults the qualified name portion to *USRLIBL. The
system ships several validation list objects in QUSRSYS and
QUSRDIRDB, but these should be avoided unless you have a
specific need.
** If you do not have any Validation List objects, use F6 to
prompt for the CRTVLDL command. Enter values to create a
validation list.
When you return to the WRKVLDL display, the new validation
list will be displayed.
** Use Option 6 (Work with Validation List Entries) for the new
Validation List or an existing validation list to prompt for
the WRKVLDLE command. Take the defaults and press Enter.
** The WRKVLDLE display allows you to change, remove, display, or
verify an entry.
** Use F6 to prompt for a new entry. Enter the values (multiple
displays) are used for ENTRYID, ENCRYPT, and DATA.
Each keyword has multiple elements including a CCSID value
which defaults to the current CCSID for the job. You can see
the current CCSID with DSPJOB or CHGJOB.
The ENTRYID value is the ID assigned to the entry. This ID
must be specified when entering a command such as VFYVLDLE
directly (not using an option on WRKVLDLE).
The ENCRYPT keyword allows the entry of data, CCSID, and the
'method' (*ONEWAY or *TWOWAY). The 'data' is the value to
encrypted. A blank value is not valid. *NONE may be used,
but a typical entry would be a string of characters to
simulate a password. The 'method' entry determines whether
you can retrieve or display the encrypted value (if QRETSVRSEC
is '1'). *ONEWAY means the encrypted value can be verified,
but not displayed or retrieved. *TWOWAY means the value can
be verified, displayed, or retrieved.
The DATA keyword may be as simple as a text description
assigned to an entry or as complex as a data structure with a
variety of information.
** When you return to the WRKVLDLE display, the new entry will
appear (rollup or 'position to' may be required).
Help text is supported for the display and all commands.
** If your QRETSVRSEC system value is '1', you can use Option 6
(Verify) to authenticate the entry. A prompt will appear that
allows you to enter a value to match the encrypted value
stored in the system.
** Option 5 (Display) will allow you to display the entry. If
the QRETSVRSEC system value is '0', the encrypted data will
never be displayed. If the QRETSVRSEC system value is '1' and
method *ONEWAY was specified, the encrypted data will not be
displayed. If the system value is '1' and method *TWOWAY was
specified, you will be able to display the encrypted data.
** Option 2 (Change) will allow you to change an entry. If *SAME
appears as the default for ENCRYPT, the current value could
not be retrieved because 1) QRETSVRSEC is set to '0', 2)
*ONEWAY is specified for the 'method', or 3) *NONE was
specified for the encrypted value.
You can change the encrypted value. However, if you take the
default of *SAME, you cannot change the 'method' or the CCSID
value of the encrypted data. A message will appear if you
specify this. The 'method' and CCSID value will only be
changed if you enter a value for the encrypted data.
APIs Used
---------
** QsyAddValidationLstEntry
** QsyFindValidationLstEntry
** QsyChangeValidationLstEntry
** QsyRemoveValidationLstEntry
** QsyFindNextValidationLstEntry
** QsyVerifyValidationLstEntry
Escape messages you can monitor for
-----------------------------------
TAA9871 Error found (text explains specifics)
TAA9872 Verification failed
Escape messages from based on functions will be re-sent.
ADDVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list to add an
entry for. The library value defaults to *LIBL.
*CURLIB or a specific library may also be used.
ENTRYID A two part value for the entry ID.
The first part is the data for the entry ID and
cannot be blank. The value may be up to 100 bytes
of mixed case.
The second part of the parameter is the CCSID
assigned to the entry. The default is *CURUSRDFT.
To see the value, prompt for the CHGJOB command and
review the CCSID parameter. An entry in the range
of 1-65535 may be entered.
ENCRYPT A 3 part parameter that describes the encryption
data and attribute.
The first part is the data to be encrypted which can
be up to 600 bytes of mixed case. A blank entry is
valid if enclosed in apostrophes. *NONE may be
specified for unusual cases.
The second part of the parameter is the CCSID
assigned to the data. The default is *CURUSRDFT.
To see the value, prompt for the CHGJOB command and
review the CCSID parameter. An entry in the range
of 1-65535 may be entered.
The third part of the parameter is the encryption
method.
If the QRETSVRSEC system value is '0', the
entry cannot be verified and the encrypted data
cannot be retrieved or displayed. This occurs
regardless of whether *ONEWAY or *TWOWAY is
specified.
*ONEWAY is the default and means the text is
encrypted and cannot be retrieved or displayed.
It can be verified if the QRETSVRSEC system
value is '1'.
*TWOWAY means the text can be retrieved or
displayed if the QRETSVRSEC system value is
'1'.
DATA A 2 part parameter. The first part describes the
data which may be up to 1000 bytes of mixed case.
This can be as simple as a text description or as
complex as a data structure.
The second part is the CCSID. The default is
*CURUSRDFT. To see the value, prompt for the CHGJOB
command and review the CCSID parameter. An entry in
the range of 1-65535 may be entered.
RTVVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list to
retrieve an entry for. The library value defaults
to *LIBL. *CURLIB or a specific library may also be
used.
ENTRYID A 2 part entry for the entry ID that is requested.
The first part is the entry ID. The second part is
the CCSID of the entry which defaults to *CURUSRDFT.
The parameter's text, length, and CCSID must all
match an existing entry. The entry IDs length is
assumed to be defined by the position of the last
non-blank. If it contains blanks, it must be
enclosed between apostrophes.
DATACCSID The default is *CURUSRDFT. A CCSID may be entered
to specify that translation from the stored entry's
CCSID should be made.
*ENTRY may be specified to retrieve the data without
translation.
RTNENTID The return entry ID. This is an optional return
variable that if used must be specified as *CHAR
LEN(100).
RTNENTCCSI The return entry CCSID. This is an optional return
variable that if used must be specified as *CHAR
LEN(5).
RTNENTLEN The return length of the entry. This is an optional
return variable that if used must be specified as
*CHAR LEN(5).
RTNENCRYPT The return encrypted data. This is an optional
return variable that if used must be specified as
*CHAR LEN(600). If *UNAVAILABLE is returned, see
the METHOD help text.
RTNENCCCSI The return encrypted data CCSID. This is an
optional return variable that if used must be
specified as *CHAR LEN(5).
RTNENCLEN The return length of the encrypted data. This is an
optional return variable that if used must be
specified as *CHAR LEN(5).
RTNENCMTH The method of encryption. *TWOWAY will be returned
if two way encryption is specified and the
QRETSVRSEC system value is set to '1'. If not,
*SEEHLP is returned.
*SEEHLP means the information is not available for
one of the following reasons:
- The QRETSVRSEC system value is '0'.
- The QRETSVRSEC system value is '1' and
*ONEWAY was specified.
- The QRETSVRSEC system value is '1' and *NONE
was specified for the ENCRYPT parameter.
This is an optional return variable that if used
must be specified as *CHAR LEN(7).
RTNENTDATA The return entry data. This is an optional return
variable that if used must be specified as *CHAR
LEN(1000).
RTNDTACCSI The return entry data CCSID. This is an optional
return variable that if used must be specified as
*CHAR LEN(5).
RTNDTALEN The return entry data length. This is an optional
return variable that if used must be specified as
*CHAR LEN(5).
CHGVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list to change
an entry for. The library value defaults to *LIBL.
*CURLIB or a specific library may also be used.
ENTRYID A entry ID to be changed. This is a two part entry.
The first part is the entry which may be a value may
be up to 100 bytes of mixed case and must match an
existing entry ID value.
The second part is the CCSID of the entry which
defaults to*CURUSRDFT. An entry in the range of
1-65535 may be entered.
ENCRYPT A 3 part parameter that describes the encryption
data and attribute.
The first part is the data which can be up to 600
bytes of mixed case. The default is *SAME meaning
no change occurs to the value. If *SAME is
specified, any changes to the METHOD or CCSID parts
are ignored and the completion message will describe
this non-action.
*NONE may be specified which prevents verification.
The second part of the parameter is the CCSID
assigned to the data. The default is *CURUSRDFT.
To see the value, prompt for the CHGJOB command and
review the CCSID parameter. An entry in the range
of 1-65535 may be entered.
The third part of the parameter is the encryption
method.
*ONEWAY means the text is encrypted and cannot
be displayed or retrieved regardless of the
QRETSVRSEC system value setting. The entry can
be verified if the QRETSVRSEC system value is
'1'.
*TWOWAY means the text can be retrieved,
displayed, or verified if the QRETSVRSEC system
value is '1'.
DATA A 2 part parameter. The first part describes the
data which may be up to 1000 bytes of mixed case.
This can be as simple as a text description or as
complex as a data structure.
The second part is the CCSID. The default is
*CURUSRDFT. To see the value, prompt for the CHGJOB
command and review the CCSID parameter. An entry in
the range of 1-65535 may be entered.
RMVVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list to remove
an entry from. The library value defaults to *LIBL.
*CURLIB or a specific library may also be used.
ENTRYID The entry to be removed.
ENTRYID A entry ID to be changed. This is a two part entry.
The first part is the entry which may be a value may
be up to 100 bytes of mixed case and must match an
existing entry ID value.
The second part is the CCSID of the entry which
defaults to*CURUSRDFT. An entry in the range of
1-65535 may be entered.
The value must match what was specified on ADDVLDLE.
CVTVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list to be
converted to an outfile. The library value defaults
to *LIBL. *CURLIB or a specific library may also be
used.
RANGE A two part entry to describe the range of entry IDs
to be converted.
The first part is the starting value. It defaults
to *FIRST.
The second part is the ending value. It defaults to
*LAST.
The entry IDs entered do not have to exist. An
entry ID is converted if the value is *GE the
starting entry ID and *LE the ending ID. See also
the NBRTOCVT parameter.
NBRTOCVT The number of entries to convert.
*RANGE is the default meaning all entries described
by the RANGE parameter.
If a value is entered in the range of 0-999,999,999
the conversion stops when either the NBRTOCVT
entries have been converted or the RANGE parameter
excludes fewer entries than the NBRTOCVT value.
OUTLIB The library for the VLDLEP file to contain the
converted entries.
*LIBL is the default and may be used if the VLDLEP
file already exists.
*CURLIB or a named library may also be specified and
must be used if the VLDLEP file does not exist.
The model file is TAAVLEAP with a format name of
VLDLEPR.
OUTMBR The member of the output file to write records to.
The default is VLDLEP.
REPLACE A *YES/*NO parameter for whether to replace the data
in the outfile. The default is *YES. *NO may be
specified to add to the existing data.
VFYVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list containing
the entry to be verified. The library value
defaults to *LIBL. *CURLIB or a specific library
may also be used.
ENTRYID The entry to be verified.
ENTRYID A entry ID to be changed. This is a two part entry.
The first part is the entry which may be a value may
be up to 100 bytes of mixed case and must match an
existing entry ID value.
The second part is the CCSID of the entry which
defaults to*CURUSRDFT. An entry in the range of
1-65535 may be entered.
The value must match what was specified on ADDVLDLE.
ENCRYPT The data to be compared to the entry's encrypted
data. If the data does not match the encrypted
value stored in the system, TAA9872 is sent as an
escape message. Other reasons exist for the TAA9872
message being sent are:
1) If the QRETSVRSEC system value is set to
'0'.
2) If the ENCRYPT value is currently *NONE.
This is a two part value. The first part is the
text to be verified. The second part is the CCSID
(defaults to CURUSRDFT) to be used when co¢paring to
the entry's encryption data.
WRKVLDLE Command parameters *CMD
---------------------------
VLDL The qualified name of the validation list to be
worked with. The library value defaults to *LIBL.
*CURLIB or a specific library may also be used.
START The starting entry ID. The default is *FIRST.
NBR The number of entries to be made available in the
subfile. The default is 500. The value must be in
a range of 1 16,750.
Restrictions
------------
A limit of 16,750 entries may exist in a single validation list.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKOBJ3 Check object 3
DUPTAADBF Duplicate TAA data base file
EDTVAR Edit variable
RMVLSTMSG Remove last message
RSNLSTMSG Resend last message
RTVSYSVAL3 Retrieve system value 3
SNDCOMPMSG Send completion message
SNDESCINF Send escape information
SNDESCMSG Send escape message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
ADDVLDLE *CMD TAAVLEA QATTCMD
RTVVLDLE *CMD TAAVLEA2 QATTCMD
CHGVLDLE *CMD TAAVLEA3 QATTCMD
RMVVLDLE *CMD TAAVLEA4 QATTCMD
CVTVLDLE *CMD TAAVLEA5 QATTCMD
VFYVLDLE *CMD TAAVLEA6 QATTCMD
WRKVLDLE *CMD TAAVLEA7 QATTCMD
TAAVLEAC *PGM CLP TAAVLEAC QATTCL
TAAVLEAC2 *PGM CLP TAAVLEAC2 QATTCL
TAAVLEAC3 *PGM CLP TAAVLEAC3 QATTCL
TAAVLEAC4 *PGM CLP TAAVLEAC4 QATTCL
TAAVLEAC5 *PGM CLP TAAVLEAC5 QATTCL
TAAVLEAC6 *PGM CLP TAAVLEAC6 QATTCL
TAAVLEAC7 *PGM CLP TAAVLEAC7 QATTCL
TAAVLEAC17 *PGM CLP TAAVLEAC17 QATTCL
TAAVLEAC18 *PGM CLP TAAVLEAC18 QATTCL
TAAVLEAC19 *PGM CLP TAAVLEAC19 QATTCL
TAAVLEAC20 *PGM CLP TAAVLEAC20 QATTCL
TAAVLEAC21 *PGM CLP TAAVLEAC21 QATTCL
TAAVLEAR *PGM RPGLE TAAVLEAR QATTRPG
TAAVLEAR2 *PGM RPGLE TAAVLEAR2 QATTRPG
TAAVLEAR3 *PGM RPGLE TAAVLEAR3 QATTRPG
TAAVLEAR4 *PGM RPGLE TAAVLEAR4 QATTRPG
TAAVLEAR5 *PGM RPGLE TAAVLEAR5 QATTRPG
TAAVLEAR6 *PGM RPGLE TAAVLEAR6 QATTRPG
TAAVLEAR7 *PGM RPGLE TAAVLEAR7 QATTRPG
TAAVLEAD *FILE DSPF TAAVLEAD QATTDDS
TAAVLEAP *FILE PF TAAVLEAP QATTDDS
Structure
---------
ADDVLDLE Cmd
TAAVLEAC CL pgm
TAAVLEAR RPGLE Pgm
RTVVLDLE Cmd
TAAVLEAC2 CL pgm
TAAVLEAR2 RPGLE Pgm
CHGVLDLE Cmd
TAAVLEAC20 CL pgm - Prompt override
TAAVLEAC3 CL pgm
TAAVLEAR3 RPGLE Pgm
RMVVLDLE Cmd
TAAVLEAC4 CL pgm
TAAVLEAR4 RPGLE Pgm
CVTVLDLE Cmd
TAAVLEAC5 CL pgm
TAAVLEAR5 RPGLE Pgm
VFYVLDLE Cmd
TAAVLEAC6 CL pgm
TAAVLEAR6 RPGLE Pgm
WRKVLDLE Cmd
TAAVLEAC7 CL pgm
TAAVLEAR7 RPGLE Pgm
TAAVLEAD DSPF
TAAVLEAC17 CL Pgm Prompt for VFYVLDLE
TAAVLEAC18 CL Pgm Prompt for ADDVLDLE
TAAVLEAC19 CL Pgm Prompt for RMVVLDLE
TAAVLEAC21 CL Pgm Prompt for CHGVLDLE
|
