DataGate SSL Deployment: DataGate for IBM i

---

DataGate for IBM i

SSL support for the IBM i includes facilities for certificate stores and current TLS protocols. Note that there are several operating system software prerequisites for using these facilities. Please consult with your IBM i partner/retailer for more information about what OS/400 options are required for Digital Certificate Manager and SSL facilities.

DataGate for IBM i uses these facilities to functionally provide the same three options for securing connections as DataGate for Windows server:

1. No authentication/encryption
2. TLS authentication/encryption or no authentication/encryption
3. Only TLS authentication/encryption

The option is configured by the value of a *DTAARA object contained in the DataGate/400 installation library. The *DTAARA named "SSLLEVEL", of data type *DEC, can take one of the following values to configure how new connections will be made.

Certificates and DataGate for IBM i

Unlike the Windows platform, the certificate stores on the IBM i are simple stream files which reside in the IFS file system. A single, central certificate store, similar to the Local Machine store on Windows, is available for use by system servers and application servers (like DataGate for IBM i). However, access to this store is available to only a single user profile which the server runs under. DataGate for IBM i provides a run-time environment similar to that of an interactive, green-screen job, which runs under an arbitrary, typically unpriveledged, user profile. Unfortunately, such users cannot access the system certificate store on the IBM i directly.

To preserve the DataGate/400 user experience, DataGate for IBM i can be configured to use a different certificate store than the system store. Other certificate stores can be configured like any other on the IBM i, with the Digital Certificate Manager tool (also known as DCM). The DataGate for IBM i installed default certificate store is contained in the stream files '/ASNA/DataGate/CertStore.kdb' and '/ASNA/DataGate/CertStore.rdb'. Within these files is a certificate labelled "DataGate/400", which is the certificate that DataGate/400 is initially configured to use to create SSL connections. All DataGate for IBM i users must have "read" access to the certificate store files, and the installed default certificate store files are configured this way. Note though, that the certificate store is secured by a password. To preserve the security of the certificate store and the private keys it contains, the password should be secret.

To enable the system administrator to configure these parameters (certificate store file, certificate label, and certificate store file password), DataGate for IBM i provides a set of three more *DTAARA objects of type *CHAR, residing in the installation library. The following table shows the data area names and a description of their contents.

The SSLPASSWD data area is particularly sensitive, since it allows access to the security store, and potentially the private key used to encrypt data transmissions. This data area should have *PUBLIC/*EXCLUDE permission, but also note that the logon-disabled DG8SVCPRF user profile must have access to its contents (DG8SVCPRF/*USE). DG8SVCPRF is the user profile installed to run the "listener" service jobs that wait for and authenticate new connections. Since they initialize SSL connections, they must be able to use the secret password to access the certificate assigned to DataGate for IBM i.

Configuring A New Certificate Store and Certificate

The default *DTAARA objects and certificate store files installed with DataGate for IBM i are provided to allow a system administrator an "out of the box" example experience in terms of secure network communication with DataGate. However, since the same objects are provided in all distributions of DataGate for IBM i, it is a fallacy to believe your DataGate configuration is highly secure as-is after an initial install. A thoughtful security plan will include the creation of your own certificate store, password, and server certificate. There are several excellent documents available from IBM for achieving this, but the following walkthrough may be useful for getting started.

First, you should become familiar with the IBM i Digital Certificate Manager ] web browser, as shown. You must consult an IBM reference for the correct URL to use to access DCM on your particular release of OS/400.

To get started, click the 'Create New Certificate Store' link. This will prompt you to decide what kind of certificate store you would like to create. Select 'Other System Certificate Store' and click the continue button, as shown below.

The next page asks if you want to create a certificate in the new store. Select 'Yes' and Continue.

The next page lets you decide how the certificate should be signed. Certificate signing is a topic beyond the scope of this document, but basically it is a way to ensure the authenticity of your certificate. To simplify things in this introductory walkthrough, select 'Local Certificate Authority' and click 'Continue', as below.

The next page lets you choose all the interesting details about your new certificate, the certificate store where it will reside, and a password to access it. In choosing a 'Key Algorithm' and 'Key Size', you should consider whether or not your client Windows machines will be able to use a certificate with those parameters, and how you wish to balance security with data throughput. In most cases, the defaults are fine (RSA, 2048 bits).

On the same page, next decide on a name for your new certificate. This label will be the one you specify in the SSLLABEL *DTAARA in the DataGate/400 configuration. Any arbitrary name will do, but make sure you only use characters available in your local system's default CCSID.

Next you will enter the password that will secure the contents of the certificate store, including the new certificate. The value specified for the password must be placed in the SSLPASSWD *DTAARA object in the DataGate/400 installation library, and should be know only to you. Also, don't worry if you specify invalid characters here; DCM will validate the password and prompt you to pick another password if necessary. Currently the valid characters for certificate store passwords are only upper and lower case alphanumeric characters. The more complex the password, the better security for your certificate store.

Next, scroll down to enter other certificate details as you wish. You may want to consider the value for the 'Common name' field, as it can be used by DataGate client programs to help verify the authenticity of your server with the "Accept certificates with subject name" option (as detailed in the DataGate Client section below). All other fields are arbitrary, as far as DataGate for IBM i is concerned. The 'Subject Alternative Name' fields are not used by DataGate, though other applications that use this certificate may require these.

The next step is to create the certificate store and your certificate. Scroll to the bottom of the page and click the 'Continue' button. If all the entered fields are valid according to DCM, then you should see a page similar to the one below. This page, once again, shows the certificate store path (copy this to the SSLCERTDB *DTAARA) and the certificate label (copy this to the SSLLABEL *DTAARA).

The following are commands you would use to set the data area objects to use the certificate just created above in your DataGate/400 installation (assume it was installed to the DG8 library). Make sure you are running these under a suitably privileged user profile.

CHGDTAARA DTAARA(DG8/SSLCERTDB *ALL) VALUE('/ASNA/DataGate/MySecureCerts.kdb')
CHGDTAARA DTAARA(DG8/SSLLABEL *ALL) VALUE('ASNA DataGate/400 SSL Certificate')
CHGDTAARA DTAARA(DG8/SSLPASSWD *ALL) VALUE('ADz5g3bnkX3YYFmxaN6s')

Please choose a different password; this was given only as an example.

Permissions on Certificate and Configuration Objects

There are still a few critical steps that must be performed for DataGate/400 to use the correct configuration and for your certificate store to be secure.

First, make sure that the certificate store stream file is read-only accessible to all users. There is more than one way to do this (e.g., QSH), but this CL command will set the store file's attributes correctly:

 CHGAUT OBJ('/ASNA/DataGate/MySecureCerts.kdb') USER(*PUBLIC) DTAAUT(*R)

You can verify the *R (read-only) attribute of the file with this command:

DSPAUT OBJ('/ASNA/DataGate/MySecureCerts.kdb') 

This should display a screen similar to the one below, displaying the correct *RW (read/write) permission for QSYS and *R (read-only) for *PUBLIC.

Secondly, make sure that the SSLPASSWD data area is protected from unauthorized access. Recall that this data area should only be accessible by the DataGate/400 user profile, DG8SVCPRF. You should make this change after ha ving set the value of the data area with the certificate store password, as detailed above. Use these commands, running under a user profile with *ALLOBJ authority, to ensure that this is the case:

GRTOBJAUT OBJ(DG8/SSLPASSWD) OBJTYPE(*DTAARA) USER(DG8SVCPRF) AUT(*USE)

RVKOBJAUT OBJ(DG8/SSLPASSWD) OBJTYPE(*DTAARA) USER(*PUBLIC) AUT(*ALL)

After running these commands, you can verify the authorities are correct with this command:

DSPOBJAUT OBJ(DG8/SSLPASSWD) OBJTYPE(*DTAARA)

The display should resemble the screen below, allowing use only by DG8SVCPRF.