612 West 115th Street, New York NY 10025 USA • kermit@columbia.edu
| …since 1981 |
| Home | Kermit 95 | C-Kermit | Scripts | Current | New | FAQ | Support |
|
|
The Kermit Project |
Columbia
University
612 West 115th Street, New York NY 10025 USA • kermit@columbia.edu
| ||||||||
| |||||||||
[ IBM IE Access Script ] [ Kermit Scripts ] [ FTP Scripts ]
NOTE: IBM's Information Exchange service was acquired 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 the 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.pdfThanks 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 ]
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:
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:
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.
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 pathname. Ditto for the script filename.
Once the script or Dialer entry is launched:
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.
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
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:
[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:
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.
K-95> save command scrollback trouble.log
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:
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
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:
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.
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 unencrypted 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:
Questions? Send them by e-mail to: kermit-support@columbia.eduSET AUTH TLS CERTS-OK ON
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
Insight on how the session works for Passive FTP:
234 AUTH command accepted - proceed with Negotiation.
More Documentation: For a complete manual on Using FTP on the Information Exchange network, please visit http://edi.services.ibm.com/ie/publications.shtml.
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: Mon Mar 14 16:21:01 2011