powersc tools for ibm i · the 2fa tool will not operate without the master key. ... press . ... to...

Version 2016.07.27© Copyright 2015, 2016 IBM Corporation

Licensed Materials - Property of IBMPrivate & Confidential - For IBM and customer use only

PowerSC Tools for IBM iTwo Factor Authentication (2FA)

User’s Guide

Terry FordRobert Andrews

© Copyright 2015, 2016 IBM Corporation All Rights Reserved 2

Two Factor Authentication (2FA)

Overview/Disclaimer................................................................................................................................ 3Implementation Overview ........................................................................................................................ 5

Initial Setup............................................................................................................................................... 7Download the Tool from IBM.............................................................................................................. 7Installing (Restoring) the Tool ............................................................................................................. 9Enter the Application Access Code .................................................................................................... 10Master Keys and the 2FA Keystore.................................................................................................... 11Authorization Lists ............................................................................................................................. 11

End User Enrollment and Update ........................................................................................................... 12Authorities required to run the 2FA Tool ........................................................................................... 12Generate 2FA Registration Key (GENGAUTH)................................................................................ 13Set up Registration Key on RFC6238 TOTP Application ................................................................. 14

Administrative User Enrollment and Update and Validation................................................................. 19Generate 2FA Registration for Users (GENUSR2FA)....................................................................... 20Test User Authentication Code (TSTAUTH)..................................................................................... 22Verify a User 2FA Keystore Entry (VFYUSRKSE) .......................................................................... 24Remove a User from 2FA Authentication (RMVUSR2FA) .............................................................. 25Set the User Registration Key manually (SETREGKEY).................................................................. 26Validate User Registration Key (TSTREGK) .................................................................................... 27

User Verification .................................................................................................................................... 28Check User Authentication Code (CHKAUTH) ................................................................................ 29Initial Program.................................................................................................................................... 31Password Reset ................................................................................................................................... 32

Other Uses and Considerations with Two Factor Authentication .......................................................... 33Example of how to use the CHKAUTH in a CL Program ................................................................. 33CLLE example of how to use the 2FA Service Program (RFC6238) ................................................ 33RPGLE example of how to use the 2FA Service Program (RFC6238) ............................................. 34

Troubleshooting 2FA.............................................................................................................................. 35Issue 1: Incorrect secret value ............................................................................................................ 35Issue 2: Time skew ............................................................................................................................. 35

Time-based One-time Password (TOTP) Algorithm Devices/Applications .......................................... 36Objects Shipped with the Two Factor Authentication (2FA) Tool ........................................................ 37Removing the Two Factor Authentication (2FA) Tool .......................................................................... 38Additional Resources.............................................................................................................................. 39IBM Systems Lab Services and Training Security................................................................................. 43


Overview/Disclaimer

The goal of the PowerSC Tools for IBM i Two Factor Authentication (2FA) software is to authenticate a user viatwo different factors before an operation takes place. This operation could be something such as signing on to aTelnet session or something more administrative such as issuing a Power Down System command or running a FireCall type tool. This will require the user to pre-register their profile and receive a time based one-time passwordkey. This time based one-time password key is a sixteen (16) character long code using a reduced alphabet basedon RFC 6238 (based on RFC 4226 for HMAC one-time passwords). Because of this standard, the key can be usedin a wide variety of software and hardware tools to generate a new, pseudo-random six (6) digit code every 30seconds. Since the code is based on time, there is no need for any communications between the server and the usersuch as emailing a reset code or validation link. The system can be completely air gapped from any public networkor system.

To store the time based one-time password key safely, a keystore file will be used. Keystore files are provided bythe operating system specifically to store cryptographic key values for use with the cryptographic services set ofAPIs. This keystore requires a master key is properly set on the system. If the master key value is changed, thekeystore file needs to be translated from the old to the new key. When the time occurs for validation, the user will


be prompted to enter the changing 6 digit code. The current user’s stored key value will be retrieved. The currentas well as plus and minus one interval codes will be generated and checked against the value entered by the user. Ifit is correct, the program completes successfully. If not, they loop until a correct code is entered or the maximumnumber of allowed attempts is exceeded and the job is terminated.

The authors of the contents of this tool have done extensive testing to ensure a safe implementation of its contents.However not every customer environment can be anticipated. This tool is provided AS IS. Neither IBM, IBM LabServices & Training, nor its employees or its representatives are responsible for the contents of this tool or theoperations of its contents.

Statement of Good Security Practices: IT system security involves protecting systems and informationthrough prevention, detection and response to improper access from within and outside your enterprise.Improper access can result in information being altered, destroyed, misappropriated or misused or canresult in damage to or misuse of your systems, including for use in attacks on others. No IT system orproduct should be considered completely secure and no single product, service or security measure canbe completely effective in preventing improper use or access. IBM systems, products and services aredesigned to be part of a lawful, comprehensive security approach, which will necessarily involveadditional operational procedures, and may require other systems, products or services to be mosteffective. IBM DOES NOT WARRANT THAT ANY SYSTEMS, PRODUCTS OR SERVICES AREIMMUNE FROM, OR WILL MAKE YOUR ENTERPRISE IMMUNE FROM, THE MALICIOUS ORILLEGAL CONDUCT OF ANY PARTY.


Implementation Overview

1. Initial Setup

o Restore the 2FA software on each participating systemo Register the 2FA Tool access code on each of the participating systemso The existence of the master key is required and its presence is checked when the access code is

registered. The 2FA tool will not operate without the master key.o If needs be create the keystore file using:

o CLRMSTKEY MSTKEY(1) VERSION(*PENDING)o ADDMSTPART MSTKEY(1) PASSPHRASE(xxx)o SETMSTKEY MSTKEY(1)

Review topic on Master Keys and the 2FA Keystore.

o The keystore file used by the 2FA was created as follows assuming master key 1. It may be necessary torecreate the keystore file if the master key did not exist during the restore. Your Lab Services consultantwill advise you if this is necessary:

o CRTCKMKSF KEYSTORE(QZRDSEC2FA/QZRDSEC2FA) MSTKEY(1)TEXT('RFC6238 Validation Store')

o CHGOBJD QZRDSEC2FA/QZRDSEC2FA OBJTYPE(*FILE)TEXT('RFC6238 Validation Store')

o CHGOBJOWN OBJ(QZRDSEC2FA/QZRDSEC2FA) OBJTYPE(*FILE)NEWOWN(QSECOFR)

Determine users of the 2FA Tool that require modifying their initial program:

o Limited capability set to *PARTIALo Initial Program to GAUTHIP in library QZRDSEC2FAo Attention Program to *NONEo Optional Exit Programs to prevent use of SYSREQ

Create Authorization Lists (*AUTL) to define users of 2FA

o Administrative userso Application users

Modify applications for use of 2FA

2. End User Enrollment and Update

Using the TWOFA menu supplied with the 2FA tool, each user to be provisioned for 2FA would need toenroll in the 2FA system once.

The menu option automatically uses the current user profile as input for generating the random time basedone-time password key which is displayed to the user.

If the user was already enrolled the password key will be replaced. Choose RFC6238 TOTP tool and register the password key


3. Administrative User Enrollment and Update

Optionally, an administrator can enroll users. The command will take in a user profile as input for generating the random time based one-time password

key which is displayed to the administrator. If the user was already enrolled the password key will be replaced.

4. User Verification

From any place desired, the TWOFA menu, or including the initial program, the authentication challengecan be called.

The challenge screen will automatically identify the logged in user and prompt for their 6 digit changingcode.

The program will verify the 6 digit code provided. If correct, the program will return true. Otherwise, theprogram will return false.

5. Other Uses and Considerations with Two Factor Authentication

TBD TBD


Initial Setup

Download the Tool from IBM

If not sent via email, IBM may have you download the tool from their secure FTP site. To do so…

From your PC’s Internet browser, go to https://testcase.boulder.ibm.com

You should see a login window with information similar to the following example:

Use the following information to log into the secure file transfer server.

Name: anonymous

Password: your e-mail address ([email protected])

https://testcase.boulder.ibm.com/

mailto:[email protected]


Navigate to the systems/fromibm/systemi directory.

The screen contents should look similar to the following:

Click on the QZRDSEC2FA file and then choose to save the file when the popup window appears. Select alocation on your PC where you can easily navigate to from your PC. Then press OK


Installing (Restoring) the Tool

On your IBM i server, sign in with a user that has all special authorities, QSECOFR for example. On a commandline type

CRTSAVF QGPL/QZRDSEC2FA <ENTER>

to create the save file.

Back on your PC, open up a command prompt and navigate to the directory where you previously saved theQZRDSEC2FA save file to.

Type ftp yoursystem to connect to your IBM i server.

Login as a user with enough authority to transfer the QZRDSEC2FA save file on your PC to the QZRDSEC2FAsave file on the IBM i.

Type bin to put your session into binary mode.

Type put QZRDSEC2FA qgpl/QZRDSEC2FA.savf

Type quit.

Back on the IBM i command line, type

RSTLIB SAVLIB(QZRDSEC2FA) DEV(*SAVF) SAVF(QGPL/QZRDSEC2FA) MBROPT(*ALL)ALWOBJDIF(*ALL)


Enter the Application Access Code

After restoring the QZRDSEC2FA library the first task to complete is to register the IBM supplied access code tothe system. You will need to contact you IBM STG Lab Services representative for this code. The code is basedon your system serial number, so you will need to provide the serial number to your representative.

o CHGCURLIB QZRDSEC2FA <ENTER>o REG2FAAC <ENTER>

Once you have typed in your access code, press <ENTER>. This sets the 2FA application ownership andauthorities. Additionally, it creates the proxy CHKAUTH command in the QSYS library for easy access to 2FAverification usage.

When setup is completed you should notice the following confirmation message at the bottom of the screen if theaccess code was registered correctly.


Master Keys and the 2FA Keystore

During installation of the 2FA program, a keystore file is created. This is a special type of file on the IBM i that isdesigned to hold cryptographic key values. This allows the system to generate them and store them in a protectedmanner such that a user cannot read the key values after the fact. They can only be used within the cryptographicfunctions of the system, providing indirect but not intelligible access to the values.

To create a keystore file, the system must have a master key stored. The IBM i provides for up to eight differentmaster keys to be stored for different applications. Our application will always use master key 1. If master key 1is not set, the keystore file cannot be created and no users may be registered. If prompted during the installationthat master key 1 is not set, it must be set to continue. You can manually check for the existence of master key 1with the following CL command: CHKMSTKVV MSTKEY(1) VERSION(*CURRENT)

A master key is made of up one or more passphrases all put together. This is done so that a company can makesure no one person knows the enter passphrase. First, clean up any pending partial keys that may exist on thesystem. We do this with the Clear Master Key command, CLRMSTKEY. For example, three differentadministrators could each know only their own part of the passphrase. The order that the values are entered doesnot matter. First, clear any pending master key parts using CLRMSTKEY MSTKEY(1) VERISON(*PENDING).Then each administrator adds their passphrase own part using ADDMSTPART MSTKEY(1) PASSPHRASE(mypart of the passphrase), each time adding one part of the overall passphrase. After all parts are entered, then oneadministrator runs SETMSTKEY MSTKEY(1). This takes all the parts, orders them, and generates the master keybased on all parts of the key entered. Users must have BOTH *ALLOBJ and *SECADM special authorities to runeither of these commands.

The keystore file used by the 2FA was created as follows assuming master key 1. It may be necessary to recreatethe keystore file if the master key did not exist during the restore. Your Lab Services consultant will advise you ifthis is necessary:

o CRTCKMKSF KEYSTORE(QZRDSEC2FA/QZRDSEC2FA) MSTKEY(1)TEXT('RFC6238 Validation Store')

o CHGOBJD QZRDSEC2FA/QZRDSEC2FA OBJTYPE(*FILE)TEXT('RFC6238 Validation Store')

o CHGOBJOWN OBJ(QZRDSEC2FA/QZRDSEC2FA) OBJTYPE(*FILE)NEWOWN(QSECOFR)

As an additional note, the CLRMSTKEY (Ex: CLRMSTKEY MSTKEY(1) VERSION(*CURRENT)) command can be used toblank out a master key, making the keystore file useless. Because of this danger, it is recommended to highly secure thiscommand with an exit program in addition to it’s built in security measures.

Authorization Lists

Consider the creation of Authorization Lists (*AUTL) to define users of 2FA administration.

o Administrative users. The following objects are shipped *PUBLIC *EXCLUDE.

o GENUSR2FAP, REG2FAACP programso GENUSR2FA, REG2FAAC commands

Application users. By default the 2FA application is shipped *PUBLIC *USE. An application AUTL wouldnot be required necessarily.

© Copyright 2015, 201

End User Enrollment and Update

To launch the tool, at the command line type

- CHGCURLIB QZRDSEC2FA <ENTER>

- GO TWOFA <ENTER> A screen similar to the following should appear

This menu provides the end user with the capability for setting up their TOTP device key and testing that theverification keys are working.

Authorities required to run the 2FA Tool

NOTE: Use of an Au

The user running this tool must be given *USE access to:

The menu TWOFA

The commands GENGAUTH and CHKAUTH

6 IBM Corporation All Rights Reserved 12

thorization List (*AUTL) is suggested. See Security Setup Recommendations

The programs GENAUTHR, CHKAUTHCL


Generate 2FA Registration Key (GENGAUTH)

Using option 1 from the QZRDSEC2FA/TWOFA menu or the GENGAUTH command, each user participating in2FA can generate their own unique TOTP registration key. This key is unique to a specific system for a specificuser. This should only need to be done once unless a users TOTP application or device is lost or stolen. Usersshould protect this key and register it right away to their TOTP device. Do not write it down!

This key will only show on this screen. These values are stored in the encrypted keystore file. Because of thisthere is no way to retrieve the value after this screen disappears. If the value is lost, register again which willreplace the lost value with a new one which will be displayed.

Note: A link to a QR Code that can be generated is provided for those users who desire some automation in settingup their TOTP device. If using the QR Code, it is highly recommended to use Private browsing mode to preventthe registration key from being store in the browser history. Please be sure to clear your browser history of thisentry if it is used.

© Copyright 2015, 2016 IBM Corporation

Set up Registration Key on

RFC6238 TOTP Authenticators vary from cell phones, smart watches, and tablets to laptops, personal computers,and servers. Each is unique in how you apply the registration key.Google Authenticator and is obtained from the

https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2

or from the App Store (for iOS devices)

https://itunes.apple.com/us/app/google

The following describes how you might enter the registration key on an Android phone using the GoogleAuthenticator:

Open the Google Authenticator App on your mobile device.

All Rights Reserved

RFC6238 TOTP Application

RFC6238 TOTP Authenticators vary from cell phones, smart watches, and tablets to laptops, personal computers,servers. Each is unique in how you apply the registration key. One of the more common Authenticators is the

Google Authenticator and is obtained from the Android App Store on Google Play


App Store (for iOS devices) at

unes.apple.com/us/app/google-authenticator/id388497605?mt=8

The following describes how you might enter the registration key on an Android phone using the Google

Open the Google Authenticator App on your mobile device.

14

RFC6238 TOTP Authenticators vary from cell phones, smart watches, and tablets to laptops, personal computers,One of the more common Authenticators is the

The following describes how you might enter the registration key on an Android phone using the Google


https://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8




The app will walk you through the setup. Click

All Rights Reserved

The app will walk you through the setup. Click Begin Setup.

15


On the next screen, you’re given two ways to add a new site to your Google Authenticator app. SelectEntry. . (Note: If you go to http://blog.tinisles.com/2011/10/googlejavascript/, you can copy/paste the 16 character secret code and it will generate the QR code for it that can then beentered using the “Scan Barcode” mode instead.)

All Rights Reserved

On the next screen, you’re given two ways to add a new site to your Google Authenticator app. Select. (Note: If you go to http://blog.tinisles.com/2011/10/google-authenticator-one-time-

javascript/, you can copy/paste the 16 character secret code and it will generate the QR code for it that can then beentered using the “Scan Barcode” mode instead.)

16

On the next screen, you’re given two ways to add a new site to your Google Authenticator app. Select Manual-password-algorithm-in-

javascript/, you can copy/paste the 16 character secret code and it will generate the QR code for it that can then be


For the manual entry method, use the(GENGAUTH) application on the IBM i.

All Rights Reserved

use the registration key provided from the Generate 2FA Registration Keyapplication on the IBM i.

17

Generate 2FA Registration Key


Once Google Authenticator has recognized your

Now you can use the 6-digit code generated by the app to log in tothis code refreshes every 30 seconds).

All Rights Reserved

Once Google Authenticator has recognized your registration key a new site will be added to the app.

digit code generated by the app to log in to IBM i application when promptedthis code refreshes every 30 seconds).

18

a new site will be added to the app.

IBM i application when prompted (just note


Administrative User Enrollment and Update and Validation

To launch the tool for administrators, at the command line type


- GO TWOFAA <ENTER> A screen similar to the following should appear

This menu provides administrators with the capability for setting up TOTP device keys for Users and testing thatthe verification keys are working.

Also note two function keys are available for working with the Master Key(s) – F6 and Keystore File(s) – F7.


Generate 2FA Registration for Users (GENUSR2FA)

Each user participating in 2FA can generate their own unique TOTP registration key. Optionally, an administratorcan create the registration key for end users and email or text it to them. Use the GENUSR2FA to createregistration keys for users:

o CHGCURLIB QZRDSEC2FA <ENTER>o GENUSR2FA <F4> or option 1 from the TWOFAA menuo Key in the user to register (or replace if they are already registered) <ENTER>


The Registration Key presented in the following screen is for the RFC6238 TOTP application or device for the userkeyed in the previous screen. Communicate this Registration Key to the user in a secure manner with instructionsfor registering with TOTP applications or device. This key is unique to a specific system for a specific user. Thiskey will only show on this screen. These values are stored in the encrypted keystore file. Because of this there isno way to retrieve the value after this screen disappears. If the value is lost, register the user again which willreplace the lost value with a new one which will be displayed.

Note: A link to a QR Code that can be generated is provided for those users who desire some automation in settingup their TOTP device. If using the QR Code, it is highly recommended to use Private browsing mode to preventthe registration key from being store in the browser history. Please be sure to instruct the user to clear theirbrowser history of this entry if it is used.


Test User Authentication Code (TSTAUTH)

To test that the 2FA authenticator is working for a user use the TSTAUTH command in the QZRDSEC2FA libraryor option 2 from the TWOFAA menu. Provide the user you want to test with and the verification code generatedfrom the 2FA tool used (using the registration key provided via the GENUSR2FA command).

Optionally you can select to keep the results of the test or multiple tests. If you keep the results, they are stored inthe file DBG2FA in library QZRDSEC2FA.

After pressing Enter on the TSTAUTH screen you will be shown a screen similar to the following…


The Code to CK field should be the verification code from the 2FA Tool used. The Epoch Time is the number ofseconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601:1970-01-01T00:00:00Z) for the timestamp retrieved for the check. You can validate that the Epoch time iscalculated correctly at the website

http://www.epochconverter.com/

Notice the - 1 values in the Value CHK fields in the above screen shot. This indicates that the user is not registeredin the keystore to use 2FA. You might also see a message at the bottom of the menu that the selected userkeystore record was not present…

A successful validation of the Code to CK is represented in the following example…

Also note the KVV , which should match the keystore verification value when verifying the same users keystoreentry (option 3 from the TWOFAA menu).

http://www.epochconverter.com/


Verify a User 2FA Keystore Entry (VFYUSRKSE)

To verify that a user is present in the 2FA authenticator tool keystore use the VFYUSRKSE command in theQZRDSEC2FA library or option 3 from the TWOFAA menu. Provide the user you want to verify and press Enter.

If the user is present in the keystore you will see the results of the Display Keystore Entry Attributes(DSPCKMKSFE) for the requested user:

Otherwise, the message “User keystore verification failed.” will be shown at the bottom of the screen.


Remove a User from 2FA Authentication (RMVUSR2FA)

To remove a user from the 2FA authenticator tool use the RMVUSR2FA command in the QZRDSEC2FA library oroption 4 from the TWOFAA menu. Provide the user you want to remove and press Enter.

If the removal was successful you will see a confirmation at the bottom of the screen similar to the following:


Set the User Registration Key manually (SETREGKEY)

To set the registration key for a user manually use the SETREGKEY command in the QZRDSEC2FA library oroption 11 from the TWOFAA menu. Enter the user to set and a 16 character registration key. The registration keymay only contain the uppercase characters A thru Z and the numbers 2 thru 7. Once entered the key is stored as aone way hash in the QZRDSEC2FA library TWO2FA user validation store for verification purposes.

If the User to Set is valid and the Registration Key is valid you will be presented a confirmation screen that includesa QR Code for easy entry within a browser.

Note: If using the QR Code, it is highly recommended to use Private browsing mode to prevent the registrationkey from being store in the browser history. Please be sure to instruct the user to clear their browser history ofthis entry if it is used.


Validate User Registration Key (TSTREGK)

To test the registration key that a user has generated use the TSTREGK command in the QZRDSEC2FA library oroption 12 from the TWOFAA menu. Provide the user you want to test with and the registration key that wasgenerated from either of the GENGAUTH or GENUSR2FA commands.

If the 16 character registration key is valid you will see a visual indication at the bottom of the command line. Thismessage produces no CPF message id and cannot be monitored.

If the 16 character registration key is not valid an error will be displayed at the bottom of the screen. This failuremessage uses the CPF message ID of CPF9898 which can be monitored within an application and appropriateaction taken.


User Verification

To launch the tool, at the command line type


- GO TWOFA <ENTER> A screen similar to the following should appear

This menu provides the end user with the capability for setting up their TOTP device key and testing that theverification keys are working.


Check User Authentication Code (CHKAUTH)

To the check that the 2FA authenticator is working use the CHKAUTH command or option 2 from the TWOFAmenu in QZRDSEC2FA library.

The screen is relatively easy to work with. Enter the 6 digit verification code found in the TOTP application ordevice. If the 6 digit verification key is correct you will see a visual indication at the bottom of the command line.

This message has no CPF message id and cannot be monitored.


If the six digit key does not match the verification code on the TOTP application or device an error will be displayedat the bottom of the screen. This failure message uses the CPF message ID of CPF9898 which can be monitoredwithin an application and appropriate action taken.


Initial Program

A common implementation of 2FA is immediately after logon using the administrators or users initial program. The2FA tool comes with an initial program and display file for your use. The program name is GAUTHIP and thedisplay file is GAUTHDS and both are in library QZRDSEC2FA. To use, add to an end users initial program usingthe CHGUSRPRF command:

CHGUSRPRF USRPRF(usertochange) CURLIB(QZRDSEC2FA) INLPGM(QZRDSEC2FA/GAUTHIP)INLMNU(userlib/usermenu) LMTCPB(*PARTIAL) ATNPGM(*NONE)

This program will terminate after 5 minutes of inactivity.The above may work well for some users, but the presence of an initial program may already exist or the currentlibrary may already be set to another. An alternative might be to use a job description similar to the following:

CRTJOBD JOBD(QZRDSEC2FA/TWOFAJD)RQSDTA('CALL QZRDSEC2FA/GAUTHIP')RTGDTA(QCMDI) INLLIBL(QZRDSEC2FA QTEMP QGPL)

CHGUSRPRF USRPRF(usertochange) CURLIB(yourlib) INLPGM(yourlib/yourprogram)JOBD(QZRDSEC2FA/TWOFAJD) INLMNU(yourlib/yourmenu)LMTCPB(*PARTIAL) ATNPGM(*NONE)

NOTE: In this scenario, the end user could still use the SYSREQ menu to cancel the program. You would need torestrict the user from the SYSRQS command by using the Presystem Request Program exit point in conjunctionwith the Set Profile Exit Programs API. Discuss your initial program requirements with your IBM Lab Servicesrepresentatives.


Password Reset

Another common implementation of 2FA is used in password reset applications. A common profile is setup, forexample RESETPWD that users are instructed to use, with an initial program that allows the user to reset theirpassword. The 2FA tool comes with an initial program and display file for your use. The program name isGAPWDRIP and the display file is GAPWDRDS and both are in library QZRDSEC2FA. To use, add to a passwordreset profile initial program using the CHGUSRPRFcommand:

CHGUSRPRF USRPRF(RESETPWD) CURLIB(QZRDSEC2FA) INLPGM(QZRDSEC2FA/GAPWDRIP)INLMNU(*SIGNOFF) DSPSGNINF(*NO) PWDEXPITV(*NOMAX) LMTDEVSSN(*NO)LMTCPB(*YES) ATNPGM(*NONE)

In this scenario, when a user logs on with the profile of RESETPWD they are presented the screen shown above.The user would enter their userid and the verification code from their smart phone or TOTP Application. Ifsuccessful their password is set to PWDR plus the 6 digit verification code (for example, PWDR123456). Theirprofile is also set to enabled and the password set to expired so that when they next logon they can set thepassword properly according to system password rules. When completed, the user is signed off of the RESETPWDprofile.

This program will terminate after 5 minutes of inactivity or after 5 unsuccessful attempts.

NOTE: In this scenario, the end user must be instructed with knowledge of the password of the reset profile.


Other Uses and Considerations with Two Factor Authentication

Example of how to use the CHKAUTH in a CL Program

PGM

CHKAUTH ??AUTHVALUE(*N)MONMSG MSGID(CPF9898 CPF6801) EXEC(GOTO CMDLBL(EXIT))

/* your code to run if it passes */

EXIT: ENDPGM

CLLE example of how to use the 2FA Service Program (RFC6238)

PGM PARM(&CHKVAL)

DCLPRCOPT DFTACTGRP(*NO) ACTGRP(*CALLER) BNDDIR(QZRDSEC2FA/RFC6238)

DCL &CHKVAL *INT 4DCL &USER *CHAR 10DCL &RETVAL *LGLDCL &USERPARM *CHAR 32

RTVJOBA CURUSER(&USER)CHGVAR VAR(&USERPARM) VALUE(&USER)CALLPRC PRC(CHECKAUTHVALUE) PARM((&USERPARM *BYVAL) (&CHKVAL *BYVAL))

RTNVAL(&RETVAL)

IF (&RETVAL = '0') DOSNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) +

MSGDTA('User authentication failed') +MSGTYPE(*ESCAPE)

ENDDOELSE SNDPGMMSG MSG('User authentication passed') +

TOPGMQ(*PRV (* *NONE *NONE))MSGTYPE(*INFO)

ENDDO

ENDPGM


RPGLE example of how to use the 2FA Service Program (RFC6238)

H DFTACTGRP(*NO) BNDDIR('RFC6238') MAIN(MAIN)

D SETAUTHSECRET PR 16

D AUTHLABEL 32 VALUED KEYSTOREPARM 20 VALUE OPTIONS(*NOPASS)

D CHECKAUTHVALUE PR N

D AUTHLABEL 32 VALUED AUTHVALUE 10I 0 VALUED KEYSTOREPARM 20 VALUE OPTIONS(*NOPASS)

D MAIN PR EXTPGM('CHKGAUTH')D LABEL 32D VALUE 6

P MAIN BD MAIN PID LABEL 32D VALUE 6

/FREEIF CHECKAUTHVALUE(LABEL:%INT(VALUE));

DSPLY 'AUTHENTICATED';ELSE;

DSPLY 'FAILURE';ENDIF;RETURN;

/END-FREEP MAIN E


Troubleshooting 2FA

There are two main issues that can cause problems with 2FA authentication:

1. User incorrectly entered the secret code into the authenticator app or tool2. The server or authenticator device time is incorrect.

Issue 1: Incorrect secret value

These secret values are stored in the encrypted keystore files. Because of this there is no way to retrieve thevalue after this screen disappears. If the value is known, have the user remove and re-enter it into theirauthenticator tool. If the value is lost, register the user again which will replace the lost value with a new one whichwill be displayed. Have the user enter the new secret value into their authenticator of choice. If they have a hard

time entering the 16 character value, use http://blog.tinisles.com/2011/10/google-authenticator-one-time-password-algorithm-in-javascript/ to generate a scanable QR code of the secret value.

Issue 2: Time skewSince this protocol is based on time, it is important for both the server and client device to have propertimes and time zones set. The protocol handles time zones automatically, so the client and server can bein different time zones, but they must be coded correctly. This also includes correct coding for daylightsaving time. Given the correct time zone for both the server and the device, make sure they sync with aninternet time server using NTP. For IBM i, this can be set in System i Navigator or using CHGNTPA.For most mobile devices, powering off and back on or going into Airplane mode then reconnecting to thecellular network will update the device time, if set to automatic configuration. If set to manual, again,check the time zone and time settings on the device.

Programs such as Emerald Time for Apple iOS devices and ClockSync for Google Android devices cando a NTP time pull and show you your devices skew from the atomic clock servers. Most devices willonly be a few hundredths off. If your device is more than 30 seconds out of sync, please try the methodsabove to resync the time.

http://blog.tinisles.com/2011/10/google-authenticator-one-time-password-algorithm-in-javascript/



Time-based One-time Password (TOTP) Algorithm Devices/Applications

Since this is based on a RFC Standard, there are many choices of tools, software and hardware, that implementthese standards. This is by no means a complete list but provides a sample of the options for generating TOTPverification codes:

Windows:

http://apps.microsoft.com/windows/en-us/app/time-based-password-generator/cabafd39-5d5d-4efe-a4e6-ff2ed563feb5

Web based:

http://gauth.apps.gbraad.nl/


iOS:

http://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8

Android:

http://support.google.com/accounts/bin/answer.py?hl=en&answer=1066447

Windows Phone:

http://www.windowsphone.com/en-us/store/app/authenticator/e7994dbc-2336-4950-91ba-ca22d653759b

Blackberry:

http://www.google.com/support/accounts/bin/answer.py?answer=1066447

Pebble Smart Watch:

http://apps.getpebble.com/en_US/application/52f1a4c3c4117252f9000bb8

Javascript:


Can be used to create QR code off of the secret generated by IBM i to allow scanning into apps instead oftyping. Also can be used as a web based client showing the rolling 30 second value.

For a list of more, see:

https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm#Client_implementations

https://en.wikipedia.org/wiki/Google_Authenticator#Implementations

http://apps.microsoft.com/windows/en-us/app/time-based-password-generator/cabafd39-5d5d-4efe-a4e6-ff2ed563feb5

http://gauth.apps.gbraad.nl/


http://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8

http://support.google.com/accounts/bin/answer.py?hl=en&answer=1066447

http://www.windowsphone.com/en-us/store/app/authenticator/e7994dbc-2336-4950-91ba-ca22d653759b

http://www.google.com/support/accounts/bin/answer.py?answer=1066447

http://apps.getpebble.com/en_US/application/52f1a4c3c4117252f9000bb8


https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm#Client_implementations

https://en.wikipedia.org/wiki/Google_Authenticator#Implementations


Objects Shipped with the Two Factor Authentication (2FA) Tool

Object Type Description

QZRDSEC2FA Library Two Factor Authentication Library

ADDPRDACS Command Add Product Access Code

ADDPRDACS Panel Group Add Product Access Code help panel group

CHKAUTH Command Check User Authentication

CHKAUTHCL Program Check User Authentication processor

DISCLAIMR Display File Disclaimer Screen

DSPPRDACS Command Display Access Code Attributes

DSPPRDACS Panel Group Display Access Code Attributes help panel group

GAUTHDS Display File Authenticator Initial Program Screen

GAUTHIP Program Authenticator Initial Program

GENGAUTH Command Generate 2FA Registration Key

GENGAUTHD Display File Generate 2FA Registration Key - Display

GENGAUTHR Program Generate 2FA Registration Key - Processor

GENUSR2FA Command Generate 2FA Registration Key for Admins

GENUSR2FAP Program Generate 2FA Registration Key for Admins - Process

QZRDACDSP Program DSPPRDACS command processing program

QZRDACDSP Display File Access code attributes display file

QZRDCADD Program ADDPRDACS command processing program

QZRDSEC2FA Keystore File RFC6238 Validation Store

REG2FAAC Command Register PowerSC Tools 2FA Access Code

REG2FAACP Program Register PowerSC Tools 2FA Access Cod

RFC6238 Service Program RFC6238 Processor

RFC6238 Binding Directory Bind directory for Security 2FA

RMVUSR2FA Command Remove User from 2FA

RMVUSR2FAR Program Remove User from 2FA - processor

RTVACDR Program Retrieve Access Code

SETREGKEY Command Set User Registration Key manually

SETREGKEYR Program Set User Registration Key manually - processor

TSTAUTH Command TEST Check User Authentication

TSTCHKAUTH Program TEST Check User Authentication processor

TSTREGK Command TEST Registration Key

TSTREGKEY Program TEST Registration Key processor

TWOFA Menu PowerSC Tools for IBM i - 2FA Menu

TWOFAA Menu PowerSC Tools for IBM i - 2FA Menu for Administrators

TWOFAA Menu PowerSC Tools for IBM i - 2FA Menu for Administrators


Removing the Two Factor Authentication (2FA) Tool

To remove the 2FA Tool from your system…

Dump all the user profiles to an output file (DSPUSRPRF) Review all usage of the 2FA Tool in initial programs and remove as necessary from affected profiles Review other application usage of the 2FA Tool – JOBD, Programs, etc (DSPPGMREF, etc) and remove as

required. Delete the library from the system (DLTLIB)


AdditionalResources


This section lists some additional sources of information pertaining IBM i security and common security guidelinesand standards that may prove useful to you.

IBM i Information

System i Security reference Version 6 Release 1 SC41-5302-10http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzarl/sc415302.pdf

System i Security reference Version 7 Release 1 SC41-5302-11http://www.ibm.com/support/knowledgecenter/api/content/nl/en-us/ssw_ibm_i_71/rzarl/sc415302.pdf



IBM Redbook:Implementation and Practical Use of LDAP on the IBM eServer iSeries Server, SG24-6193http://www.redbooks.ibm.com/abstracts/sg246193.html?Open

IBM Redbook:IBM eServer iSeries Wired Network Security: OS/400 V5R1 DCM and Cryptographic Enhancements, SG24-6168http://www.redbooks.ibm.com/abstracts/sg246168.html?Open

IBM Redbook:Securing Communications with OpenSSH on IBM i5/OS, REDP-4163http://www.redbooks.ibm.com/abstracts/redp4163.html?Open

IBM Redbook:IBM i5/OS Network Security Scenarios A Practical Approach, SG24-7374http://www.redbooks.ibm.com/abstracts/sg247374.html?Open

IBM Redbook:IBM System i Security Guide for IBM i5/OS Version 5 Release 4, SG24-6668-01http://www.redbooks.ibm.com/abstracts/sg246668.html?Open

IBM Redbook:Security Guide for IBM i V6.1, SG24-7680http://www.redbooks.ibm.com/abstracts/sg247680.html?Open

IBM Redbook:Windows-based Single Signon and the EIM Framework on the IBM eServer iSeries Server, SG24-6975http://www.redbooks.ibm.com/abstracts/sg246975.html?Open

http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/topic/rzarl/sc415302.pdf

http://www.ibm.com/support/knowledgecenter/api/content/nl/en-us/ssw_ibm_i_71/rzarl/sc415302.pdf



http://www.redbooks.ibm.com/abstracts/sg246193.html?Open


http://www.redbooks.ibm.com/abstracts/redp4163.html?Open






IBM Redbook (HTTP server security):IBM HTTP Server (powered by Apache): An Integrated Solution for IBM eServer iSeries Servers, SG24-6716-02http://www.redbooks.ibm.com/abstracts/sg246716.html?Open

IBM Power System Security (HMC)

IBM Redbook:IBM Power Systems HMC Implementation and Usage Guidehttp://www.redbooks.ibm.com/abstracts/sg247491.html?Open

WebSphere MQ SecurityAs a general recommendation regarding WebSphere MQ Security, always encrypt your messages with SSL. Thisensures authentication of the data origin, the confidentiality, and the integrity of messages.

IBM Redbook:WebSphere MQ Security in an Enterprise Environment, SG24-6814http://www.redbooks.ibm.com/abstracts/sg246814.html?Open

WebSphere MQ Information Center → Security http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzas.doc/sy10120_.htm




http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzas.doc/sy10120_.htm


Internet Security Standards and OrganizationsThe standards contain valuable information regarding writing security policies and implementing best practices.

Common CriteriaSecurity Product Certification and Standardshttp://www.commoncriteriaportal.org/

Security Standards download page (i.e. ISO27001, ISO27002)http://www.standards-online.net/InformationSecurityStandard.htm

Control Objectives for Information and related Technology (COBIT)ISACA Sitehttps://www.isaca.org/search/Pages/ResultsAjax.aspx#cobit

SANS InstituteInformation about standards, security vulnerabilities, and policies

Policies:http://www.sans.org/security-resources/policies/Best Practices in Mitigation and Control:http://www.sans.org/top-cyber-security-risks/best-practices.php

CERTInformation about vulnerabilities and fixeshttp://www.cert.org/

Common Vulnerabilities and Exposureshttp://cve.mitre.org/

BSI Security Standards and Best PracticesContains very good information that can be reused to implement proper security policieshttps://www.bsi.bund.de/cln_174/EN/Topics/ITGrundschutz/itgrundschutz_node.html

International Information Systems Security Certification Consortium, Inc., (ISC)²Maintains a critical body of knowledge (CBK) with regard to information security topics. The CBK defines globalindustry standards, serving as a common framework of terms and principles that the CISSP security certification isbased upon.https://www.isc2.org/

http://www.commoncriteriaportal.org/

http://www.standards-online.net/InformationSecurityStandard.htm

https://www.isaca.org/search/Pages/ResultsAjax.aspx#cobit

http://www.sans.org/security-resources/policies/

http://www.sans.org/top-cyber-security-risks/best-practices.php

http://www.cert.org/

http://cve.mitre.org/

https://www.bsi.bund.de/cln_174/EN/Topics/ITGrundschutz/itgrundschutz_node.html

https://www.isc2.org/


IBM Systems Lab Services and Training SecurityPrivacy and data protection are the responsibility of all. In a world where data is easily acquired, shared and stored(and potential data misuse is a concern) everyone must do their part to handle information in compliance with theircompany’s requirements and values. IBM research indicates security expenses are growing three times faster thanIT budgets. Mounting regulatory and compliance mandates carry stiff government penalties and fines if ignored;every-growing volumes of data tax infrastructures and control capabilities; customer records disappear withalarming frequency; and security breaches cost an average of $6.6 million per incident.

With the added pressure of a challenging economy, to compete effectively a business cannot tolerate any securityexposures. From a minor breach like exposing one’s password to a peer or major failure like the disclosure of clientdata, neither are unacceptable and can result in new administrative procedures, a failed audit or lost business.Some circumstances could even lead to a lawsuit.

Engage the experts of IBM Systems Lab Services and Training to help uphold your company’s commitment toprivacy and data security. Our team has developed a multitude of offerings to address your specific securityconcerns. From help implementing a security feature to additional resources to supplement your staff, ourConsulting and Implementation Services provide general and custom consulting. Services include passwordelimination and single sign-on, data and tape encryption, system auditing setup and analysis, security assessments,breach analysis and penetration testing and IBM® WebSphere® Application Server health checks.

Security Tools

Complementing our security offerings are a number of tools that we have developed over the years to assist us inthe delivery of our services. These tools have been written with customers in mind to aid them in the tasks ofadministrating security and in response to requirements to fill product gaps. They range from easy–to–install toolsand utilities to more complex solutions; the latter often includes a services component intended to provide technicaltraining and implementation services so clients and business partners can acquire and maintain mission criticalskills. The tools listed below are our most requested. Others exist as well. Perhaps we can build something for you?

Audit Journal Analysis ToolUser activity and system/application auditing is a requirement for most companies. The Audit Journal Analysis Toolsimplifies the task of viewing entries in the IBM i security audit journal. It provides flexibility and a statistical view ofthe number of entries occurring in each journal entry. The security administrator can select an entry by date, timeor type, drill down for details and optionally print or send an output file. The tool includes features for managingjournal receivers, reporting on special authorities, monitoring for the entries defined in the Security Exit Point Tooland a report scheduler.

Quick Security Check for IBM iRegular assessments are key to uncover previously hidden or incorrectly administered security issues. The QuickSecurity Check for IBM i provides information on the security risks of an IBM i system. It quickly collects 500+pieces of operational, administrative and statistical information relative to security including user and group profiles,network configuration, operational configuration, exit points, system settings, user inheritance and more. The toolplaces that data in a single location for viewing. An easy-to-use HTML document provides interpretation of theresults and can be easily converted to other document formats.

IBM i Security Assessment Tool (iSAT)The IBM i Security Assessment Tool (iSAT) is an exhaustive security collection tool that is often used during asecurity assessment to help discover and document security vulnerabilities. More than statistical information foundin the Quick Security Check Tool, the iSAT tool drills deep to analyze object authorities, elevated privileges, etc. toenable a holistic methodical approach towards security hardening. It can also be purchased separately forcustomers wishing to enhance their security reporting capability.


Single Sign On (SSO) / Enterprise Identity Mapping (EIM) Populator Tool (EPT)The need for multiple user registries, an issue most enterprises face, creates a large administrative challenge. EIMfor the IBM i platform offers administrators and application developers an inexpensive solution for easiermanagement of multiple user registries and user identities. EIM creates a system of identity mappings, calledassociations, between various user identities in various user registries. It provides a common interface acrossplatforms to look up relationships between user identities.

One of the most time consuming tasks in implementing a single sign-on solution is registering users to the EIMrepository. The EPT is a Java-based desktop GUI application that allows an administrator to easily importinformation from a comma–separated value text file. With EPT, take a spreadsheet of known user IDs and/ornames and create identifiers and mappings for each user. Java 1.4 or higher is required.

Single Sign On (SSO) / Enterprise Identity Mapping (EIM) Management ToolThe EIM Management Tool is a Java-based desktop GUI application that allows an administrator to easily managethe information within an EIM repository, via a more user-friendly layout than what is provided in iSeries Navigator.Identifiers, aliases, descriptions, associations, and user registries can be created, deleted, and renamed, all fromthe same screen. The tool also includes a tree view of the EIM repository, domain management functions tocreate/delete EIM domains, save/restore of the data in an EIM domain to/from a local XML file, as well as apassword synchronization view to manipulate EIM data that pertains to the network password synchronization tool(NPST). Java 1.4 or higher is required.

Password Validation ToolDespite warnings, one-in-five users choose a non-compliant password to protect their identity. We’ve developed aprogram that validates and ensures passwords meets company and industry recommended rules and guidelines.The tool also allows the security administrator to establish a dictionary of excluded terms, to further tightenpassword security.

Network Password SynchronizationUsers often have different passwords for each system or application they access. To simplify passwordmanagement, the Network Password Synchronization tool allows a user to manage a single password (or many)for multiple systems and applications in one place.

Network Interface Firewall for Exit PointsThe Network Interface Firewall simplifies the managing of Exit Point definitions for users on an IBM i. Currently, thetool includes programs for managing the Exit Points for CLI, DRDA/DDM, FTP, IFS, ODBC, JDBC, File Transfer,REXEC, RMTCMD, Host Server Signon, and others. Additional Exit Point Programs will be added in the future.The tool provides the Security Administrator with an interface to define which users are allowed to use the definedExit Point. An Audit Journal record is created whenever a user accesses the defined Exit Points.

Certificate Expiration Manager (CEM)The Certificate Expiration Manager (CEM) is a Java-based tool for simplifying the management of certificateexpiration (cross-platform). CEM maintains a log of all expiration activities and can send notifications vial email.An easy to use configuration GUI is included for managing the XML settings. The tool only runs on platforms thatsupport Java.

For more information about IBM Systems Lab Services and Training or our Security Offerings . . .

Terry Ford, Team Leader, Security Services [email protected]

Mark Even, Opportunity [email protected]

Or visit our website at: http://www-03.ibm.com/systems/services/labservices/



powersc tools for ibm i · the 2fa tool will not operate without the master key. ... press . ... to...

Documents