Accessing IBM Information Exchange with the Kermit FTP Client

[ IBM IE Access Script ] [ Kermit Scripts ] [ FTP Scripts ]

NOTE: IBM's Information Exchange service was aquired by Global eXchange Services (GXS) in October 2004 (read the news release), including the FTP-based service described here (for part of 2005, in some parts of the world, the service was temporarily operated under a third company name, "G International"). The FTP implementation has not changed as of January 2006; for example string "IBM" continues to appear in the CA certificate and in client certificates. The Information Exchange document library has moved from the IBM site to:

https://www.gxsolc.com/public/EDI/us/support/Library/IE_Library.html

... and the IE-FTP manual, with new GXS branding, is now here:

https://www.gxsolc.com/public/EDI/us/support/Library/Publications/IEtcpipFTPGatewayUserGuide_c3423452.pdf

Thanks to John Hartnup of GXS for the updated information.

IBM Information Exchange (IE) is a key component of IBM's Interchange Services for e-business that facilitates secure data transfer among its trading partners. For this, a secure FTP client is required. Several of these are listed on IBM's Information Exchange Support Page. Among them is Columbia University's Kermit software. This document explains how to use Kermit with IBM Information Exchange.

These notes should also apply (perhaps with minor differences) to IBM Internet Data and Document Exchange (IDDX), as well as to AT&T Advantis, which was transferred from IBM several years ago, AT&T WorldNet, and GE Global eXchange. These notes are developed in consultation with IBM and its customers. If you have questions, corrections, or suggestions for improvement, please contact us.

Also see:

[ Kermit Home ] [ Kermit 95 ] [ C-Kermit ] [ Security ]


CONTENTS


Which Kermit Software Should I Use?

The latest Kermit software releases include a new integrated FTP client; CLICK HERE for an overview. The Kermit programs and versions that have this feature are:

If you don't have Kermit software, you can download it from the links above.

From time to time, FTP and other bugs are fixed in these clients. Updates are available here:

Kermit software comes in secure and non-secure versions due to United States export law. A secure version of Kermit 95 or C-Kermit is required to access IBM IE; that is, one that supports SSL/TLS transport with authentication via X.509 certificates. If you already have a copy of Kermit, but you don't know whether it is a secure version, type the following commands at its prompt (sorry; we'll have an easier way to do this in a future release):

define test if avail ssl echo AVAILABLE
test

If the response is:

AVAILABLE

then you have a secure version. If you do not have a secure version, then:


What Do I Do With My Certificate Files?

For a tutorial on X.509 Certificates, CLICK HERE.

\v(appdata), \v(common), and \v(exedir) are Kermit variables denoting Windows directories that can vary from one version of Windows to another: \v(exedir) is Kermit's program directory; \v(common) is Kermit's Application Data directory for all users; \v(appdata) is your personal Kermit Application Data directory. CLICK HERE for a more detailed explanation.

Before you can log in to IBM Info Exchange, you must have two Certificate files provided to you by IBM:

  1. The IBM InfoExchange Root CA Certificate. If you have Kermit 95 2.0, or later this certificate is already installed as part of the Kermit 95 \v(common)ca_certs.pem file.

  2. The Personal File containing the Client Certificate signed by the IBM Root CA and your Private Key. This file is called ibm_ie_personal.pem.

The IBM certificates come in in PKCS#12 format, but OpenSLL (which Kermit uses) requires them to be in PEM format. You can convert them to PEM format with the openssl program, which in Windows is in your Kermit 95 program directory, and in Unix is in /usr/local/ssl/bin/ or whatever other directory OpenSSL was installed in:

openssl pkcs12 -in pkcs12file -out pemfile

More about converting certificates to PEM format HERE.

If you have Kermit 95 2.0 or later, you also already have the IBM IE root certificate, since it is included in the ca_certs.pem file in Kermit 95's All Users Application Data directory.

If you have Kermit 95 1.1.21, note that you can upgrade it to version 2.x HERE.

If you have Kermit 95 1.1.21 or C-Kermit, then you must specify the location (full path) of the IBM IE root certificate with the SET AUTH TLS VERIFY-FILE command. In Windows, this file should go in Kermit 95's All Users Application Data directory:

set auth tls verify-file \v(common)ibm_ie_ca.pem

In Unix, there is no standard place to put certificates, so put them wherever you wish and use the SET AUTH TLS VERIFY-FILE command to let C-Kermit know where it is.

Now you must specify the location of your personal certificate and key files with the following commands:

set auth tls rsa-cert-file filename
set auth tls rsa-key-file filename

Note: the RSA-CERT-FILE and the RSA-KEY-FILE can be the same file, and in the case of IBM IE, they typically are: ibm_ie_personal.pem. In Windows, we recommend you place this file in the CERTS subdirectory of your personal Kermit 95 Application Data directory, \v(appdata):

set auth tls rsa-cert-file \v(appdata)certs/ibm_ie_personal.pem
set auth tls rsa-key-file \v(appdata)certs/ibm_ie_personal.pem

because that is where the IBM Info Exchange entry preloaded in K95 2.x Dialer looks for it. If you put this file in a different location, and still wish to use the Dialer entry, you must edit the SSL/TLS Settings page to show the new location (in the Client Certificate File and Client Private Key file boxes).

In fact the correct location for your personal certificate files is in \v(appdata) and not in its CERTS subdirectory, but the K95 2.x Dialer entry for IBM Info Exchange mistakenly looks for them in the CERTS subdirectory, which is why we recommend you put them there. The ibm_infoexchange sample script finds them in either place. The actual purpose for the CERTS subdirectories is to hold certificate files whose names have a special encoding.

If you need help with setting up your certificates, call IBM at 1-800-655-8865 and ask to speak to an Enabler.


How Do I Access IBM Information Exchange?

If you have Kermit 95 2.0 or later, you can use the Dialer's preloaded IBM Info Exchange entry, which has the connection details and SSL/TLS Settings mostly filled out for you (BUT FIRST CHECK ANY BULLETINS). Before first using this entry, you must edit it to supply your username and password: Right-click on this entry, Choose Edit, then choose Login, fill in the user ID and password for your IBM IE account, and then click OK. When you launch an IBM IE connection from the Dialer, it connects you to IBM IE and logs you in. After that you must use Kermit's command prompt to transfer data, as you would with any command-line FTP client.

NOTE: The FTP User ID for IBM Information Exchange is in the format ACCOUNT.USERID. For example if your IE account is IBM1 and your IE User ID is OLGA, your FTP user ID is IBM1.OLGA. The FTP user ID is not case sensitive.

You only have to edit the Dialer entry once; from then on you can use it simply by double-clicking on it, or by highlighting it and clicking on CONNECT in the Dialer's Toolbar.

In C-Kermit 8.0 or Kermit 95 1.1.21, or (if you wish) K95 2.0 or later, you can use the following Kermit script to make secure connections to IBM Information Exchange:

ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange

You must modify the script to specify the full path for your certificate files if they differ from those used in the script (use a plain-text editor such as Notepad to do this).

Kermit scripts can be executed by any of the methods described HERE. For example, you can store the script file on your Windows desktop with a filetype of .KSC (which is associated with Kermit 95), and then launch the connection by clicking on its icon. From the command line or a batch file, you can use:

k95 ibm_infoexchange.ksc username

This assumes K95.EXE is in your PATH; if not, specify its full pathame. Ditto for the script filename.

Once the script or Dialer entry is launched:

  1. If your private key file is encrypted, you are prompted for the decryption passphrase.

  2. If you are using the script, but you did not supply a username on the command line, you are prompted for a username. (If you are using the Dialer, you must supply your username on the IBM Info Exchange entry's Login page.)

  3. If you did not supply a host password (on the script command line or in the Dialer entry), you are prompted for one. The username and password are encrypted for transmission to the server.

If the IBM server responds to your connection attempt with:

Service not Available, Connection Closed by Server.

it probably means that Kermit did not find your certificate file; please reread previous section.

If you see a complaint regarding missing CRL files, you can ignore it. This means that Kermit looked to see if any Certificate Revocation Lists are present, which revoke any of the certificates you have. Normally, there are no CRLs, thus Kermit does not find any CRL files.

Once you are logged in to the Info Exchange server, you can give regular FTP client commands like DIRECTORY, CD, PUT, GET, and MGET, and when done, you can give a BYE command to disconnect from the server and EXIT from Kermit. Throughout your session, all commands and data are encrypted.

For thorough documentation of the Kermit FTP client and its commands and options, CLICK HERE.


Using the Connection

Once you have a connection to the IBM server, you can use it according to the instructions you received from IBM. Note that the IBM server is not a normal FTP server. Instead of regular FTP commands, you must use FTP SITE commands to send Info-Exchange-specific commands to the server, which are documented here:

http://edi.services.ibm.com/interchange/tb9901.shtml

The GXS FTP server is documented here:

https://www.gxsolc.com/public/EDI/us/support/Library/Publications/IEtcpipFTPGatewayUserGuide_c3423452.pdf

In Kermit, the SITE command is given with "FTP SITE". Here's a table that should clarify matters (words in brackets are optional):

FTP Protocol Command FTP Client Command Kermit Client Command Description
CWD CD or CWD [FTP] CD or CWD Change (Working) Directory on server
PASV PASSIVE SET FTP PASSIVE Client chooses TCP port for data connection
QUIT BYE [FTP] BYE Break connection with server
RETR GET [FTP] GET Get (Retrieve) one file
(none) MGET [FTP] MGET Get multiple files
SITE SITE FTP SITE Send a site-specific command to the server
STOR PUT [FTP] PUT Put (Send, Store) one file
(none) MPUT [FTP] MPUT Put multiple files
TYPE TYPE FTP TYPE Specify type of next file, "ascii" or binary.
USER USER [FTP] USER Specify user name

Here the IBM server lists its SITE commands:

[C:\] K-95> ftp site
The following SITE commands are available:-
 HELP, IDLE, EDICHECK, CONFIRM, SYSTEM,
 MSGCHRG, MSGRCPTS, ARCREFID, GETARCHIVE, GETAUDIT,
 PROBE, XLATE, EDICRLF, EDIONLY, MSGRETN,
 SESSKEY, MSGNAME, MSGSEQN, EDIALIASONLY, SHOWOPTS,
 RESETOPTS, LISTSTYLE, RESP226, PASSTHRU, PTRESPNAME,
 LIBREPLACE, EDIREPLYBUF, EDIREPLIES, EDICDHONLY,
 EDICLASS, UNIQUEID, SPACECHR, EDIALIASPROBE, COMPRESS
get site.README from support directory for usage information.
[C:\] K-95>

For further information, see IBM's list of Info Exchange related publications:

http://edi.services.ibm.com/ie/publications.shtml

and in particular, the Information Exchange via TCP/IP FTP Gateway User's Guide:

http://publib.boulder.ibm.com/edi/pdfs/c3423451.pdf


Troubleshooting

IBM IE Technical Support: 1-800-326-6426 (voice).
Kermit Technical Support: kermit-support@columbia.edu (e-mail)

Secure FTP connections can be complicated and confusing. If your connection did not proceed smoothly, first read any BULLETINS at the top of this page. Beyond that, the main problem areas tend to be:

  1. Your certificates are in the wrong format. OpenSSL (which Kermit uses) requires them to be in PEM format. IBM gives them to you in PKCS#12 format. Use the OpenSSL program to convert them as described above.

  2. Kermit must be told where to find the certificate and key files if they are not in the default locations. If you are using the Dialer's IBM Info Exchange entry, the locations for these files are given on the SSL/TLS Settings page. If you are using the sample script from our FTP site, the locations are given in the script. You must make certain the specified locations agree with the actual locations.

  3. You did not decrypt your private key file, or you gave an incorrect decryption passphrase.

  4. A firewall is blocking the data connection. Kermit uses FTP Passive Mode by default to get around the most common firewall problems, but your firewall might still get in the way. In particular, firewalls that act as FTP proxies can not be use for secure connections because the firewall can't read the encrypted packets. In such cases, you might still be able to push the connection through by using Kermit's support for SOCKS or HTTP Proxy servers (type "help set tcp" at the K-95> prompt for further info). CLICK HERE to read about the difficulties of using FTP through firewalls, and HERE to read more about using secure FTP and firewalls.

  5. A firewall is acting as an FTP proxy. This can't work with secure connections; the firewall can't process messages on the connection after encryption is activated and therefore can't tell which ports are to be opened for FTP data connections. Again, authenticating to the firewall via SOCKS or HTTP proxy server might might get you past the firewall. Or you can try opening an active connection instead of a passive one (SET FTP PASSIVE OFF prior to FTP OPEN). If that doesn't work, the firewall is blocking active connections too; talk to your network administrator.

  6. Firewalls, cont'd... A more insidious case occurs when your session is established successfully and you are logged in, but no data transfer commands work. For example:

    [c:\] K-95> set ftp debug on
    [c:\] K-95> dir
    ---> PASV
    227 Entering Secured Passive Mode (32,96,130,20,234,198)
    ftp: connect: No error
    [c:\] K-95>
    

    In this case your firewall is blocking the response to the DIR command. IBM says: "For Information Exchange users, the biggest problem we run into is with their Firewalls. The IBM server will dynamically pick any of the upper ports to ask the client to establish the data connection on (1025-65,000). This is not the case with the IBM Data and Document Exchange service. That port range is only 9000 - 9999."

If you have trouble making the connection:

  1. Download the latest copy of the ibm_infoexchange sample script from HERE.

  2. At the K-95> prompt:
    K-95>  cd xxx                    ; CD to directory where script is.
    K-95>  clear command scrollback  ; Clear away old messages (optional).
    K-95>  define debug 1            ; Enable debugging messages.
    K-95>  take ibm_infoexchange     ; Execute the script.
    

  3. When the script has terminated:
    K-95>  save command scrollback trouble.log
    

  4. Look through the trouble.log file and/or send it to us for analysis.

Note: You can also copy and paste from the K95 Command window. Just hold down the left mouse button and drag over the material you want to copy. If you push the mouse pointer against the top edge of the screen, K95 scrolls back automatically, so you can copy multiple screensful this way. The copied material goes to the Windows Clipboard, from which you can paste it using Shift-Insert on the keyboard or Edit→Paste in any application's menu.

If you are not using our sample script, then you should be aware of the following Kermit commands that are useful for debugging secure FTP connections:

SET FTP DEBUG ON
Display FTP protocol messages and responses.

SET AUTH SSL VERBOSE ON
Display SSL authentication progress messages.

SET AUTH SSL DEBUG ON
Display SSL authentication debugging messages.

When debugging, a successful connection looks like this:

[C:\Some Path\] k95 ibm_infoexchange ibm1.xyz123
IBM INFO EXCHANGE ACCESS SCRIPT VERSION 2.05
Connected to ieftpint2.services.ibm.com.
220 ieftpint2 IE-FTP server (v4r1m0.d) ready on system USA.
---> AUTH SSL
234 AUTH command accepted - proceed with Negotiation.
SSL accepted as authentication type
Certificate[1] subject=/C=US/O=IBM/OU=Interchange Services for e-business
/CN=PKI Services Root CA
Certificate[1] issuer =/C=US/O=IBM/OU=Interchange Services for e-business
/CN=PKI Services Root CA
Certificate[0] subject=/C=US/O=IBM/OU=Interchange Services for e-business: 
Server/CN=ieftpint2.services.ibm.com
Certificate[0] issuer =/C=US/O=IBM/OU=Interchange Services for e-business
/CN=PKI Services Root CA
FTP Command channel is Private (encrypted)
---> PBSZ 0
200 Protection buffer size successfully set.
---> PROT P
200 Data protection level now set to 'P' (Protected).
FTP Data channel is Private (encrypted)
---> USER ibm1.xyz123
331 Enter Password.
---> PASS XXXX
---> REST 0
502 Command not supported.
---> SYST
502 Command not supported.
Default transfer mode is TEXT ("ASCII")
---> MODE S
200 Mode now set to S.
---> STRU F
200 Structure now set to F.
---> PBSZ 0
200 Protection buffer size successfully set.
---> PROT P
200 Data protection level now set to 'P' (Protected).
Connected to IBM InfoExchange
Kermit 95 2.0.1, 7 June 2002, for 32-bit Windows
 Copyright (C) 1985, 2002,
  Trustees of Columbia University in the City of New York.
Type ? or HELP for help.
[C:\Certs\] K-95> _

The lines starting with "--->" are commands sent by Kermit to the FTP server; the lines starting with numbers are responses from the server to Kermit. Any "Command not supported" messages in response to SYST, REST, MODE, or STRU are harmless.

If you want to log FTP file transfers, use LOG TRANSACTIONS ("help log" for details). If you want to log FTP client and server protocol messages, use "log debug"; this actually logs quite a bit more than that, but you can extract the desired messages as follows. In Kermit 95 2.0 or later, or C-Kermit 8.0.206 or later, the relevant lines start with FTP (upper case). In Unix (or Kermit itself) you can "grep" for them as follows:

grep ^FTP debug.log

In earlier Kermit versions:

Or in Unix notation:

egrep "(ftp reply|ftpcmd buf2)" debug.log


How Do I Automate the Connection?

Kermit's script language lets you elaborate the sample script (or write your own script) to automate any desired task, as explained in the manual, and on the Scripts Library page, and also in the Kermit FTP Scripting Tutorial.

IMPORTANT: Please don't try to automate your connection until after it is working interactively. First make it work, then automate it.

WARNING: There is an intrinsic tradeoff between automation and safety. The more automated the procedure, the less secure. To illustrate, the obvious way to automate access from one computer to another is to script entry of the authentication information, including the password. But then anyone who gains access to your script also gains access to the other computer. If you change the script to require manual entry of the password each time you run it, it becomes more secure but less automatic. These considerations apply doubly when automating an FTP connection secured by TLS, since your private key file is protected by a passphrase and your host account is protected by second passphrase. That's how FTP-TLS works. Automating such a connection introduces new elements of risk.

When scripting an unattended operation, you must take special measures to avoid or handle the password prompts:

  1. If your private key file is encrypted, you are always prompted for the passphrase when using it. The only way to avoid this is to create an unencrypted version of the private key file and then specify the filename of the unencrypted private key file in the SET AUTH TLS RSA-KEY-FILE command.

    You can create an unencrypted PEM file from the original PKCS#12-format key file with the following command:

    openssl pksc12 -in encrypted-pkcs12-keyfile -out unencrypted-pem-keyfile -nodes
    

    or you can decrypt a PEM-format key file with:

    openssl rsa -in encrypted-pem-keyfile -out unencrypted-pem-keyfile
    

    Now your private key is stored in an unencrypted file, so you must ensure that the file's permissions allow access only to the person to whom the certificate was issued (this is possible in Unix, and in Windows NT, 2000, and XP, but not in Windows 95, 98, or ME). Check very carefully that your key file is not accessible from outside, including by disk sharing.

  2. You have to supply a password on this type of connection; this is a limitation of the SSL/TLS / X.509 / FTP protocol combination. The sample script accepts your IBM IE username and password on the command line, thus avoiding the interactive prompts. These command-line arguments are used in the FTP OPEN command:

    ftp open ieftpint2.services.ibm.com ftp /user:\%1 /password:\%2
    

    (\%1 and \%2 are the command line arguments.)

    You should not put the password in your script, because then anybody who can access the script file and your unencyrpted private key file can access your IE account directly (it must be said, however, that even when you omit the password from you script, the unencrypted key file gives intruders the bigger piece of the puzzle -- cracking a password is light work for today's average hacker). If you don't put the password in your script, however, you can't run run the script unattended because the FTP OPEN command prompts you for the password.

Let's say you agree it is unwise to store a password in your script, but you still want the script to run unattended. For example, you want to start the script before you go home for dinner, but have it run at midnight. Just have the script prompt wait until midnight before opening the connection:

sleep 23:59:59            ; wait until just before midnight
ftp open ieftpint2.services.ibm.com ftp /user:\%1 /password:\%2
...

In case you're worried about spies coming into your office and reading the password off your screen, also add the following command to your script:

clear command scrollback

This erases the screen and the entire scrollback buffer. Also note that if an interloper interrupts the script, the variables containing the username and password disappear from memory automatically.

Finally, you might have to cope with various warning-related prompts that interrupt the flow of your script. By default, Kermit operates at the highest level of security consciousness, and therefore warns you about conditions that might indicate a risk, such as self-signed certificates, asking you if it is OK to continue. To suppress such warnings (when you are certain it is safe to do so), include the appropriate SET AUTH command in your script, such as:

SET AUTH TLS CERTS-OK ON
Questions? Send them by e-mail to: kermit-support@columbia.edu


APPENDIX: IBM Handout

The following message is sent by email from IBM to new FTP users (the remainder of this section is IBM's message):

Hello,

Here are some of the guideline for connecting to IBM over the Internet.

Commands. IBM uses the standard FTP commands on the network:

AUTH
LS -L = list (only available in home folder)
GET
CD = Change Directories
PUT

To LOGON
Your user name should be formatted as Acct.Userid (period in between) Your password is your Information Exchange password and cannot be the same as your userid.

Sending and Receiving Files.
The FTP server is setup similar to a directory tree. When you are logged in you are in your home directory and are able to receive any files that have been sent to you. This is the only folder that you would be able to LIST and have read access to. When ever you want to send a file to someone, you would Change Directories to their home folder and PUT the file.

To Receive Files
LOG in to the FTP server.
Issue a LS -L to give you a list of all of the file in your mailbox
Issue a GET to receive the first file listed in your mailbox
Issue a MGET to receive all the file in your mailbox.
(*Note - most FTP clients handle most of these commands as background processes and you are able to just drag and drop your files. Check with your software supplier on how to do this. Also note, the files hold no significant name, so you may be asked to supply a name for the file you are receiving - GET C:\INCOMING\TEST.TXT)

To Send a flat file.
To send a flat file the trading partner must be on the IE network and you must know their account and userid. Issue a CD to their Acct.Userid (period between) or set your remote directory or folder to the Acct.Userid. Issue a PUT command on the file you want to send - PUT C:\OUTGOING\TEST.TXT (*Note - most FTP clients handle most of these command as background processes and you are able to drag and drop your file. Check with your software supplier on how to do this.)

To Send an EDI file
When sending EDI files, the network is going to resolve the receiver from the ISA header and therefore must use an Alias table. To do this use the command - SITE EDIALIASONLY 1. Issue this command right after logon. This will tell the FTP server to reference the alias tables to find out who the receiver is.
Issue a CD to the EDI folder or set your remote folder to EDI
Issue a PUT command on the file you want to send - PUT C:\OUTGOING\TEST.TXT or drag your file over. (*Note - some software packages have a place or field for initializing commands. The site command will probably be placed there but again you will want to check with your software vendor for verification. )

TO LOGOFF
Issue the BYE command or Close your FTP session. This is important , because any files you have received out of your folder, may not be flagged as received until the session is successfully ended.

Insight on how the session works for Passive FTP:

More Documentation: For a complete manual on Using FTP on the Information Exchange network, please visit http://edi.services.ibm.com/ie/publications.shtml.


BULLETINS

IBM reports that as of 15 January 2003, the interoperability bug between the IE-FTP service and OpenSSL is fixed; therefore the workaround described below should no longer be necessary (but it also should do no harm if you continue to use it).

If you are using Kermit 95 2.0 or later on Windows and find that your connection to IBM Info Exchange is closed by the server, this is because of a bug in the server (see the New Bugs List, item 680), which was reported to IBM 27 June 2002 and should be fixed as of 12 January 2003. In any case, the workaround is to tell Kermit to:

set auth tls cipher-list EXP1024-RC4-SHA

before giving the FTP OPEN command (note: cipher names are case-sensitive). Version 2.04 (and later) of the sample script includes this workaround. If you are using the K95 Dialer's IBM Info Exchange entry, place the string:

EXP1024-RC4-SHA

(uppercase) into the Cipher List field on the entry's SSL/TLS Settings page.

[ Top ] [ Kermit Home ] [ Kermit 95 ] [ C-Kermit ] [ Security ] [ Scripts ] [ FTP Scripts ]

Most Recent Update: Fri Jan 6 12:49:48 2006


The Kermit Project / Columbia University / kermit@columbia.edu