home *** CD-ROM | disk | FTP | other *** search
/ kermit.columbia.edu / kermit.columbia.edu.tar / kermit.columbia.edu / public_html / ibm_ie.old < prev    next >
Text File  |  2002-07-22  |  32KB  |  1,067 lines
  1. <html><head>
  2. <title>Accessing IBM Information Exchange with Kermit</title>
  3. </head><body bgcolor="#ffffff" text="#000000">
  4.  
  5. <h2><a name="top">Accessing IBM Information Exchange with Kermit</a></h2>
  6.  
  7. [ <a href="index.html">Kermit Home</a> ]
  8. [ <a href="k95.html">Kermit 95</a> ]
  9. [ <a href="ckermit.html">C-Kermit</a> ]
  10. [ <a href="security.html">Security</a> ]
  11. [ <a href="ckscripts.html">Kermit Scripts</a> ]
  12. [ <a href="ftpscripts.html">FTP Scripts</a> ]
  13. <p>
  14.  
  15. <i>Most Recent Update:</i>
  16. Tue Jul 23 10:18:26 2002
  17.  
  18. <p>
  19.  
  20. <a href="http://edi.services.ibm.com/ie/">IBM Information Exchange</a> (IE) is
  21. a key component of IBM's Interchange Services for e-business that facilitates
  22. secure interchange of data among its trading partners.  For this, a <b>secure
  23. FTP client</b> is required.  Several of these are listed on IBM's Information
  24. Exchange
  25. <a href="https://pki.services.ibm.com/ieftp/webdocs.shtml">Support Page</a>.
  26. Among them is Columbia University's <a href="index.html">Kermit software</a>.
  27. This document explains how to use Kermit with IBM Information Exchange.
  28.  
  29. <p>
  30. <blockquote>
  31. <i>
  32.  
  33. These notes should also apply (perhaps with minor differences) to IBM
  34. Advantis, IBM Global Exchange, and IBM Internet Data and Document Exchange
  35. (IDDX).
  36.  
  37. <p>
  38.  
  39. These notes are developed in consultation with IBM and its customers, but
  40. since we do not have access to the IBM services discussed here,
  41. most of the information is second-hand.  If you have questions, corrections,
  42. or suggestions for improvement, please
  43. <a href="mailto:kermit@columbia.edu">contact us</a>.
  44.  
  45. </i>
  46. </blockquote>
  47.  
  48. <h3><hr>CONTENTS</h3>
  49.  
  50. <ul>
  51.  
  52. <li><a href="#alerts">BULLETINS</a>
  53. <li><a href="#software">WHICH KERMIT SOFTWARE SHOULD I USE?</a>
  54. <li><a href="#certs">WHAT DO I DO WITH MY CERTIFICATE FILES?</a>
  55. <li><a href="#access">HOW DO I ACCESS IBM INFORMATION EXCHANGE?</a>
  56. <li><a href="#using">USING THE CONNECTION</a>
  57. <li><a href="#trouble">TROUBLESHOOTING</a>
  58. <li><a href="#automation">HOW DO I AUTOMATE THE CONNECTION?</a>
  59. <li><a href="#ibmhandout">APPENDIX: IBM HANDOUT</a>
  60.  
  61. </ul>
  62.  
  63. <h3><a name="alerts"><hr>BULLETINS</a></h3>
  64.  
  65. <b>If you are using Kermit 95 2.0</b> on Windows and find that your connection
  66. to IBM Info Exchange is closed by the server, this is because of a 
  67. bug in the server (see the
  68. <a href="ftp://kermit.columbia.edu/kermit/k95/newbugs.txt">New Bugs List</a>,
  69. item 680), which was reported to IBM 27 June 2002 and should be fixed soon.
  70. In the meantime, the workaround is to tell Kermit to:
  71.  
  72. <p>
  73. <blockquote>
  74. <pre>
  75. set auth tls cipher-list EXP1024-RC4-SHA
  76. </pre>
  77. </blockquote>
  78. <p>
  79.  
  80. before giving the FTP OPEN command (note: cipher names are case-sensitive).
  81. Version 2.04 (and later) of the <a
  82. href="ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange">sample
  83. script</a> includes this workaround.  If you are using the K95 Dialer's IBM
  84. Info Exchange entry, place the string:
  85.  
  86. <p>
  87. <blockquote>
  88. <pre>
  89. EXP1024-RC4-SHA
  90. </pre>
  91. </blockquote>
  92. <p>
  93.  
  94. (uppercase) into the Cipher List field on the entry's SSL/TLS Settings page.
  95.  
  96. <h3><a name="software"><hr>Which Kermit Software Should I Use?</a></h3>
  97.  
  98. The latest Kermit software releases include a new integrated FTP client;
  99. <a href="ftpclient.html">CLICK HERE</a> for an overview.  The Kermit programs
  100. and versions that have this feature are:
  101.  
  102. <p>
  103. <ul>
  104. <li><a href="k95.html">Kermit 95 2.0</a>
  105. for Windows 95/98/ME/NT/2000/XP; and:
  106. <li><a href="ckermit.html">C-Kermit 8.0</a>
  107. for Unix (Linux, AIX, Solaris, HP-UX, FreeBSD, and all other Unix varieties)
  108. </ul>
  109. <p>
  110.  
  111. If you don't have Kermit software, you can download it from the links above.
  112.  
  113. <p>
  114.  
  115. Kermit software comes in secure and non-secure versions due to United States
  116. export law.  <b>A secure version of Kermit 95 or C-Kermit is required</b> to
  117. access IBM IE; that is, one that supports <b>SSL/TLS</b> transport with
  118. authentication via <b>X.509 certificates</b>.  If you already have a copy of
  119. Kermit, but you don't know whether it is a secure version, type the following
  120. commands at its prompt (sorry; we'll have an easier way to do this in a
  121. future release):
  122.  
  123. <p>
  124. <blockquote>
  125. <pre>
  126. define test if avail ssl echo AVAILABLE
  127. test
  128. </pre>
  129. </blockquote>
  130. <p>
  131.  
  132. If the response is:
  133.  
  134. <p>
  135. <blockquote>
  136. <pre>
  137. AVAILABLE
  138. </pre>
  139. </blockquote>
  140. <p>
  141.  
  142. then you have a secure version.  If you do not have a secure version, then:
  143.  
  144. <p>
  145. <ul>
  146.  
  147. <li>For <a href="k95.html">Kermit 95</a>, you can install the 
  148. <a href="k95upgrade.html">security upgrade</a> if you are in the USA
  149. or Canada (a license for export to other countries is pending).
  150.  
  151. <p>
  152.  
  153. <li>For <a href="ckermit.html">C-Kermit</a>, you can download the source
  154. code and build a secure version on your Unix system (because export of 
  155. certain types of source code is allowed); see the
  156. <a href="security.html">Kermit Security Reference</a> for instructions.
  157.  
  158. </ul>
  159.  
  160. <h3><a name="certs"><hr>What Do I Do With My Certificate Files?</a></h3>
  161.  
  162. <blockquote><i>
  163. For a tutorial on X.509 Certificates,
  164. <a href="http://www.columbia.edu/kermit/security.htm#xa3">CLICK HERE</a>.
  165. </i></blockquote>
  166.  
  167. <p>
  168.  
  169. <tt>\v(appdata)</tt>,
  170. <tt>\v(common)</tt>, and
  171. <tt>\v(exedir)</tt>
  172. are Kermit variables denoting Windows directories that
  173. can vary from one version of Windows to another: <tt>\v(exedir)</tt> is
  174. Kermit's program directory; <tt>\v(common)</tt> is Kermit's Application Data
  175. directory for all users; <tt>\v(appdata)</tt> is your personal Kermit
  176. Application Data directory.  <a href="k95readme.htm#x9">CLICK HERE</a> for a
  177. more detailed explanation.
  178.  
  179. <p>
  180.  
  181. Before you can log in to IBM Info Exchange, you must have two Certificate
  182. files provided to you by IBM:
  183.  
  184. <p>
  185. <ol>
  186.  
  187. <li>The IBM InfoExchange Root CA Certificate.  If you have Kermit 95 2.0, 
  188. this certificate is already installed as part of the Kermit 95
  189. <tt>\v(common)ca_certs.pem</tt> file.
  190.  
  191. <p>
  192.  
  193. <li>The Personal File containing the Client Certificate 
  194. signed by the IBM Root CA and your Private Key.  This file
  195. is called <tt>ibm_ie_personal.pem</tt>.
  196.  
  197. </ol>
  198. <p>
  199.  
  200. The IBM certificates come in in PKCS#12 format, but OpenSLL (which Kermit
  201. uses) requires them to be in PEM format.  You can convert them to PEM format
  202. with the <tt>openssl</tt> program, which in Windows is in your Kermit 95
  203. program directory, and in Unix is in <tt>/usr/local/ssl/bin/</tt> or whatever
  204. other directory OpenSSL was installed in:
  205.  
  206. <p>
  207. <blockquote>
  208. <pre>
  209. openssl pkcs12 -in <i>pkcs12file</i> -out <i>pemfile</i>
  210. </pre>
  211. </blockquote>
  212.  
  213. <p>
  214.  
  215. More about converting certificates to PEM format
  216. <a href="https://pki.services.ibm.com/ieftp/convert2pem.shtml">HERE</a>.
  217.  
  218. <p>
  219.  
  220. <b>If you have Kermit 95 2.0</b>, you also already have the IBM IE root
  221. certificate, since it is included in the <tt>ca_certs.pem</tt> file in Kermit
  222. 95's All Users Application Data directory.
  223.  
  224. <p>
  225.  
  226. <b>If you have Kermit 95 1.1.21</b>, note that you can upgrade it to version
  227. 2.0 <a href="k95upgrade.html">HERE</a>.
  228.  
  229. <p>
  230.  
  231. <b>If you have Kermit 95 1.1.21 or C-Kermit</b>, then you must specify the
  232. location (full path) of the IBM IE root certificate with the SET AUTH TLS
  233. VERIFY-FILE command.  In Windows, this file should go in Kermit 95's
  234. All Users Application Data directory:
  235.  
  236. <p>
  237. <blockquote>
  238. <pre>
  239. set auth tls verify-file \v(common)ibm_ie_ca.pem
  240. </pre>
  241. </blockquote>
  242. <p>
  243.  
  244. In Unix, there is no standard place to put certificates, so put them wherever
  245. you wish and use the SET AUTH TLS VERIFY-FILE command to let C-Kermit know
  246. where it is.
  247.  
  248. <p>
  249.  
  250. Now you must specify the location of your <b>personal certificate and key
  251. files</b> with the following commands:
  252.  
  253. <p>
  254. <blockquote>
  255. <pre>
  256. set auth tls rsa-cert-file <i>filename</i>
  257. set auth tls rsa-key-file <i>filename</i>
  258. </pre>
  259. </blockquote>
  260. <p>
  261.  
  262. Note: the RSA-CERT-FILE and the RSA-KEY-FILE can be the same file, and in the
  263. case of IBM IE, they typically are: <tt>ibm_ie_personal.pem</tt>.
  264. In Windows, we recommend you place this file in the CERTS subdirectory of
  265. your personal Kermit 95 Application Data directory, <tt>\v(appdata)</tt>:
  266.  
  267. <p>
  268. <blockquote>
  269. <pre>
  270. set auth tls rsa-cert-file \v(appdata)certs/ibm_ie_personal.pem
  271. set auth tls rsa-key-file \v(appdata)certs/ibm_ie_personal.pem
  272. </pre>
  273. </blockquote>
  274. <p>
  275.  
  276. because that is where the IBM Info Exchange entry preloaded in K95 2.0 Dialer
  277. looks for it.  If you put this file in a different location, and still wish
  278. to use the Dialer entry, you must edit the SSL/TLS Settings page to show the
  279. new location (in the Client Certificate File and Client Private Key file
  280. boxes).
  281.  
  282. <p>
  283. <blockquote>
  284. <i>
  285.  
  286. In fact the correct location for your personal certificate files is in
  287. <tt>\v(appdata)</tt> and not in its CERTS subdirectory, but the K95 2.0 Dialer
  288. entry for IBM Info Exchange mistakenly looks for them in the CERTS
  289. subdirectory, which is why we recommend you put them there.  The
  290. <tt>ibm_infoexchange</tt> sample script finds them in either place.  The
  291. actual purpose for the CERTS subdirectories is to hold certificate files whose
  292. names have a special encoding.
  293.  
  294. </i>
  295. </blockquote>
  296.  
  297. <h3><a name="access"><hr>How Do I Access IBM Information Exchange?</a></h3>
  298.  
  299. <b>If you have Kermit 95 2.0</b>, you can use the Dialer's
  300. preloaded IBM Info Exchange entry, which has the connection details and
  301. SSL/TLS Settings mostly filled out for you (<a href="#alerts">BUT FIRST CHECK
  302. ANY BULLETINS</a>).  Before first using this entry, you must edit it
  303. to supply your username and password:  Right-click on this entry, Choose Edit,
  304. then choose Login, fill in the user ID and password for your IBM IE
  305. account, and then click OK.
  306.  
  307. <p>
  308. <blockquote>
  309. <i>
  310. NOTE: The FTP User ID for IBM Information Exchange is in the format
  311. ACCOUNT.USERID.  For example if your IE account is IBM1 and your IE User ID
  312. is OLGA, your FTP user ID is IBM1.OLGA.  The FTP user ID is not case sensitive.
  313. </i>
  314. </blockquote>
  315. <p>
  316.  
  317. You only have to edit the Dialer entry once; from now you can use it simply by
  318. double-clicking on it, or by highlighting it and clicking on CONNECT in the
  319. Dialer's Toolbar.
  320.  
  321. <p>
  322.  
  323. <b>In C-Kermit 8.0 or Kermit 95 1.1.21</b>, or (if you wish) K95 2.0,
  324. you can use the following <a href="ckscripts.html">Kermit script</a> to
  325. make secure connections to IBM Information Exchange:
  326.  
  327. <p>
  328. <blockquote>
  329. <pre>
  330. <a href="ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange">ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange</a>
  331. </pre>
  332. </blockquote>
  333. <p>
  334.  
  335. You must modify the script to specify the full path for your certificate files
  336. if they differ from those used in the script (use a plain-text editor such
  337. as Notepad to do this).
  338.  
  339. <p>
  340.  
  341. Kermit scripts can be executed by any of the methods described <a
  342. href="ckscripts.html">HERE</a>.  For example, you can store the script file on
  343. your Windows desktop with a filetype of <tt>.KSC</tt> (which is associated
  344. with Kermit 95), and then launch the connection by clicking on its icon.  From
  345. the command line or a batch file, you can use:
  346.  
  347. <p>
  348. <blockquote>
  349. <pre>
  350. k95 ibm_infoexchange.ksc <i>username</i>
  351. </pre>
  352. </blockquote>
  353. <p>
  354.  
  355. This assumes <tt>K95.EXE</tt> is in your PATH; if not, specify its full
  356. pathame.  Ditto for the script filename.
  357.  
  358. <p>
  359.  
  360. Once the script or Dialer entry is launched:
  361.  
  362. <p>
  363. <ol>
  364.  
  365. <li>If your private key file is encrypted, you are prompted for the decryption
  366. passphrase.
  367.  
  368. <p>
  369.  
  370. <li>If you are using the script, but you did not supply a username on the
  371. command line, you are prompted for a username.  (If you are using the Dialer,
  372. you must supply your username on the IBM Info Exchange entry's Login page.)
  373.  
  374. <p>
  375.  
  376. <li>If you did not supply a host password (on the script command line or
  377. in the Dialer entry), you are prompted for one.  The username and password
  378. are encrypted for transmission to the server.
  379.  
  380. </ol>
  381.  
  382. <p>
  383.  
  384. If the IBM server responds to your connection attempt with:
  385.  
  386. <p>
  387. <blockquote>
  388. <tt>Service not Available, Connection Closed by Server.</tt>
  389. </blockquote>
  390. <p>
  391.  
  392. it probably means that Kermit did not find your certificate file; please
  393. reread previous section.
  394.  
  395. <p>
  396.  
  397. If you see a complaint regarding missing CRL files, you can ignore it.
  398. This means that Kermit looked to see if any Certificate Revocation Lists
  399. are present, which revoke any of the certificates you have.  Normally, there
  400. are no CRLs, thus Kermit does not find any CRL files.
  401.  
  402. <p>
  403.  
  404. Once you are logged in to the Info Exchange server, you can give regular FTP
  405. client commands like DIRECTORY, CD, PUT, GET, and MGET, and when done, you can
  406. give a BYE command to disconnect from the server and EXIT from Kermit.
  407. Throughout your session, all commands and data are encrypted. 
  408.  
  409. <p>
  410.  
  411. For thorough documentation of the Kermit FTP client and its commands and
  412. options, <a href="ckermit80.html#ftp">CLICK HERE</a>.
  413.  
  414. <h3><a name="using"><hr>Using the Connection</a></h3>
  415.  
  416. Once you have a connection to the IBM server, you can use it according to
  417. the instructions you received from IBM.  Please note that the IBM server is
  418. not a normal FTP server.  It implements only the following FTP protocol
  419. commands:
  420.  
  421. <p>
  422. <blockquote>
  423. <pre>
  424. TYPE, MODE, STRU, USER, QUIT, PORT, RETR, STOR, SITE, NOOP, CWD,
  425. ALLO, PASS, PASV and AUTH
  426. </pre>
  427. </blockquote>
  428. <p>
  429.  
  430. Note: No LIST, NLST, MDTM, or SIZE; thus you can't get directory listings
  431. from the server in the normal way (and since there is no NLST command, I don't
  432. see how MGET could work either; thus I think you probably can only GET
  433. single files, one per GET command).  If you give a client command (such as
  434. DIR) that is not supported by the server, the server simply closes the
  435. data connection and you'll see no response.  If you turn on debugging messages
  436. (next section) you'll see something like this:
  437.  
  438. <p>
  439. <blockquote>
  440. <pre>
  441. [c:\] K-95> <u>set ftp debug on</u>
  442. [c:\] K-95> <u>dir</u>
  443. ---> PASV
  444. 227 Entering Secured Passive Mode (32,96,130,20,234,198)
  445. ftp: connect: No error
  446. [c:\] K-95>
  447. </pre>
  448. </blockquote>
  449. <p>
  450.  
  451. Instead of regular FTP commands, you must use FTP SITE commands to send
  452. Info-Exchange-specific commands to the server,
  453. which are documented here:
  454.  
  455. <p>
  456. <blockquote>
  457. <pre>
  458. <a href="http://edi.services.ibm.com/interchange/tb9901.shtml">http://edi.services.ibm.com/interchange/tb9901.shtml</a>
  459. </pre>
  460. </blockquote>
  461. <p>
  462.  
  463. In Kermit, the SITE command is given with "FTP SITE".  Here's a table that
  464. should clarify matters (words in brackets are optional):
  465.  
  466. <p>
  467. <blockquote>
  468. <table border>
  469. <tr>
  470. <th>FTP Protocol Command
  471. <th>FTP Client Command
  472. <th>Kermit Client Command
  473. <th>Description
  474. <tr>
  475. <td>CWD
  476. <td>CD or CWD
  477. <td>[FTP] CD or CWD
  478. <td>Change (Working) Directory on server
  479. <tr>
  480. <td>PASV
  481. <td>PASSIVE
  482. <td>SET FTP PASSIVE
  483. <td>Client chooses TCP port for data connection
  484. <tr>
  485. <td>QUIT
  486. <td>BYE
  487. <td>[FTP] BYE
  488. <td>Break connection with server
  489. <tr>
  490. <td>RETR
  491. <td>GET
  492. <td>[FTP] GET
  493. <td>Get (Retrieve) one file
  494. <tr>
  495. <td>SITE
  496. <td>SITE
  497. <td>FTP SITE
  498. <td>Send a site-specific command to the server
  499. <tr>
  500. <td>STOR
  501. <td>PUT
  502. <td>[FTP] PUT
  503. <td>Put (Send, Store) one file
  504. <tr>
  505. <td>TYPE
  506. <td>TYPE
  507. <td>FTP TYPE
  508. <td>Specify type of next file, "ascii" or binary.
  509. <tr>
  510. <td>USER
  511. <td>USER
  512. <td>[FTP] USER
  513. <td>Specify user name
  514. </table>
  515. </blockquote>
  516. <p>
  517.  
  518. <p>
  519.  
  520. Here the IBM server lists its SITE commands:
  521.  
  522. <p>
  523. <blockquote>
  524. <pre>
  525. [C:\] K-95> <u>ftp site</u>
  526. The following SITE commands are available:-
  527.  HELP, IDLE, EDICHECK, CONFIRM, SYSTEM,
  528.  MSGCHRG, MSGRCPTS, ARCREFID, GETARCHIVE, GETAUDIT,
  529.  PROBE, XLATE, EDICRLF, EDIONLY, MSGRETN,
  530.  SESSKEY, MSGNAME, MSGSEQN, EDIALIASONLY, SHOWOPTS,
  531.  RESETOPTS, LISTSTYLE, RESP226, PASSTHRU, PTRESPNAME,
  532.  LIBREPLACE, EDIREPLYBUF, EDIREPLIES, EDICDHONLY,
  533.  EDICLASS, UNIQUEID, SPACECHR, EDIALIASPROBE, COMPRESS
  534. get site.README from support directory for usage information.
  535. [C:\] K-95>
  536. </pre>
  537. </blockquote>
  538. <p>
  539.  
  540. For further information, see IBM's list of Info Exchange related publications:
  541.  
  542. <p>
  543. <blockquote>
  544. <pre>
  545. <a href="http://edi.services.ibm.com/ie/publications.shtml">http://edi.services.ibm.com/ie/publications.shtml</a>
  546. </pre>
  547. </blockquote>
  548. <p>
  549.  
  550. and in particular, the <cite>Information Exchange via TCP/IP FTP Gateway
  551. User's Guide</cite>:
  552.  
  553. <p>
  554. <blockquote>
  555. <pre>
  556. <a href="http://publib.boulder.ibm.com/edi/pdfs/c3423451.pdf">http://publib.boulder.ibm.com/edi/pdfs/c3423451.pdf</a>
  557. </pre>
  558. </blockquote>
  559. <p>
  560.  
  561. <h3><a name="trouble"><hr>Troubleshooting</a></h3>
  562.  
  563. Secure FTP connections can be complicated and confusing.  If your connection
  564. did not proceed smoothly, first read any <a href="#alerts">BULLETINS</a> at
  565. the top of this page.  Beyond that, the main problem areas tend to be:
  566.  
  567. <p>
  568. <ol>
  569.  
  570. <li>Firewalls that block the connection.  Kermit uses FTP Passive Mode by
  571. default to get around the most common firewall problems, but if your firewall
  572. blocks outbound FTP connections, you might still be able to push through
  573. by using Kermit's support for SOCKS or HTTP Proxy servers
  574. (type "help set tcp" at the K-95> prompt for further info).
  575. <a href="ftp://ftp.isi.edu/in-notes/rfc1579.txt">CLICK HERE</a> to read about
  576. the difficulties of using FTP through firewalls, and
  577. <a href="ftp://kermit.columbia.edu/kermit/k95/draft-fordh-ftp-ssl-firewall-01.txt">HERE</a>
  578. to read more about using secure FTP and firewalls.  IBM says:
  579. <i>"For Information Exchange users, the biggest problem we run
  580. into is with their Firewalls.  The IBM server will dynamically pick any of
  581. the upper ports to ask the client to establish the data connection on
  582. (1025-65,000). This is not the case with the IBM Data and Document Exchange
  583. service. That port range is only 9000 - 9999."</i>
  584.  
  585. <p>
  586.  
  587. <li>Your certificates are in the wrong format.  OpenSSL (which Kermit uses)
  588. requires them to be in PEM format.  IBM gives them to you in PKCS#12
  589. format.  Use the OpenSSL program to convert them as described
  590. <a href="#certs">above</a>.
  591.  
  592. <p>
  593.  
  594. <li>Kermit must be told where to find the certificate and key files if they
  595. are not in the default locations.  If you are using the Dialer's IBM
  596. Info Exchange entry, the locations for these files are given on the
  597. SSL/TLS Settings page.  If you are using the sample script from our FTP site,
  598. the locations are given in the script.  You must make certain the specified
  599. locations agree with the actual locations.
  600.  
  601. <p>
  602.  
  603. <li>You did not decrypt your private key file, or you gave an incorrect
  604. decryption passphrase.
  605.  
  606. </ol>
  607. <p>
  608.  
  609. <b>If you have trouble making the connection:</b>
  610.  
  611. <p>
  612. <ol>
  613. <li>Download the latest copy of the <tt>ibm_infoexchange</tt> sample
  614. script from
  615. <a href="ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange">HERE</a>.
  616.  
  617. <p>
  618.  
  619. <li>At the <tt>K-95></tt> prompt:
  620.  
  621. <blockquote>
  622. <pre>
  623. K-95>  <u>cd <i>xxx</i></u>                    ; CD to directory where script is.
  624. K-95>  <u>clear command scrollback</u>  ; Clear away old messages (optional).
  625. K-95>  <u>define debug 1</u>            ; Enable debugging messages.
  626. K-95>  <u>take ibm_infoexchange</u>     ; Execute the script.
  627. </pre>
  628. </blockquote>
  629.  
  630. <p>
  631.  
  632. <li>When the script has terminated:
  633. <blockquote>
  634. <pre>
  635. K-95>  <u>save command scrollback trouble.log</u>
  636. </pre>
  637. </blockquote>
  638.  
  639. <p>
  640.  
  641. <li>Look through the <tt>trouble.log</tt> file and/or
  642. <a href="mailto:kermit-support@columbia.edu">send it to us</a>
  643. for analysis.
  644.  
  645. </ol>
  646. <p>
  647.  
  648. Note: You can also copy and paste from the K95 Command window.  Just hold
  649. down the left mouse button and drag over the material you want to copy.
  650. If you push the mouse pointer against the top edge of the screen, K95 scrolls
  651. back automatically, so you can copy multiple screensful this way.  The copied
  652. material goes to the Windows Clipboard, from which you can paste it using
  653. Shift-Insert on the keyboard or <i>Edit→Paste</i> in any application's
  654. menu.
  655.  
  656. <p>
  657.  
  658. When debugging, a successful connection looks like this:
  659.  
  660. <p>
  661. <blockquote>
  662. <pre>
  663. [C:\Some Path\] <u>k95 ibm_infoexchange ibm1.xyz123</u>
  664. IBM INFO EXCHANGE ACCESS SCRIPT VERSION 2.05
  665. Connected to ieftpint2.services.ibm.com.
  666. 220 ieftpint2 IE-FTP server (v4r1m0.d) ready on system USA.
  667. ---> AUTH SSL
  668. 234 AUTH command accepted - proceed with Negotiation.
  669. SSL accepted as authentication type
  670. Certificate[1] subject=/C=US/O=IBM/OU=Interchange Services for e-business
  671. /CN=PKI Services Root CA
  672. Certificate[1] issuer =/C=US/O=IBM/OU=Interchange Services for e-business
  673. /CN=PKI Services Root CA
  674. Certificate[0] subject=/C=US/O=IBM/OU=Interchange Services for e-business: 
  675. Server/CN=ieftpint2.services.ibm.com
  676. Certificate[0] issuer =/C=US/O=IBM/OU=Interchange Services for e-business
  677. /CN=PKI Services Root CA
  678. FTP Command channel is Private (encrypted)
  679. ---> PBSZ 0
  680. 200 Protection buffer size successfully set.
  681. ---> PROT P
  682. 200 Data protection level now set to 'P' (Protected).
  683. FTP Data channel is Private (encrypted)
  684. ---> USER ibm1.xyz123
  685. 331 Enter Password.
  686. ---> PASS XXXX
  687. ---> REST 0
  688. 502 Command not supported.
  689. ---> SYST
  690. 502 Command not supported.
  691. Default transfer mode is TEXT ("ASCII")
  692. ---> MODE S
  693. 200 Mode now set to S.
  694. ---> STRU F
  695. 200 Structure now set to F.
  696. ---> PBSZ 0
  697. 200 Protection buffer size successfully set.
  698. ---> PROT P
  699. 200 Data protection level now set to 'P' (Protected).
  700. Connected to IBM InfoExchange
  701. Kermit 95 2.0.1, 7 June 2002, for 32-bit Windows
  702.  Copyright (C) 1985, 2002,
  703.   Trustees of Columbia University in the City of New York.
  704. Type ? or HELP for help.
  705. [C:\Certs\] K-95> _
  706. </pre>
  707. </blockquote>
  708. <p>
  709.  
  710. The lines starting with "<tt>---></tt>" are commands sent by Kermit to
  711. the FTP server; the lines starting with numbers are responses from the server
  712. to Kermit.  Any "Command not supported" messages in response to SYST, REST,
  713. MODE, or STRU are harmless.
  714.  
  715. <p>
  716.  
  717. If you want to log FTP file transfers, use LOG TRANSACTIONS ("help log"
  718. for details).  If you want to log FTP client and server protocol messages,
  719. use "log debug"; this actually logs quite a bit more than that, but you
  720. can extract the desired messages as follows:
  721.  
  722. <p>
  723. <ul>
  724. <li>Messages from the client to the server are in lines that start with
  725. "ftp reply".
  726. <li>Messages from server to client are in lines that start with
  727. "ftpcmd buf2".
  728. </ul>
  729. <p>
  730. Or in Unix notation:
  731. <p>
  732.  
  733. <blockquote>
  734. <pre>
  735. egrep "(ftp reply|ftpcmd buf2)" debug.log
  736. </pre>
  737. </blockquote>
  738.  
  739. <h3><a name="automation"><hr>How Do I Automate the Connection?</a></h3>
  740.  
  741. Kermit's script language lets you elaborate the <a
  742. href="ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange">sample
  743. script</a> (or write your own script) to automate any desired task, as
  744. explained in <a href="ck60manual.html">the manual</a>, and on the <a
  745. href="ckscripts.html">Scripts Library</a> page, and also in the <a
  746. href="ftpscripts.html">Kermit FTP Scripting Tutorial</a>.
  747.  
  748. <p>
  749.  
  750. IMPORTANT: Please don't try to automate your connection until after it is
  751. working interactively.  First make it work, then automate it.
  752.  
  753. <p>
  754. <blockquote>
  755. <i>
  756.  
  757.  
  758. <b>WARNING: There is an intrinsic tradeoff between automation and safety.</b>
  759. The more automated the procedure, the less secure.  To illustrate, the obvious
  760. way to automate access from one computer to another is to script entry of the
  761. authentication information, including the password.  But then anyone who gains
  762. access to your script also gains access to the other computer.  If you change
  763. the script to require manual entry of the password each time you run it, it
  764. becomes more secure but less automatic.
  765. These considerations apply doubly when automating an FTP connection secured
  766. by TLS, since your private key file is protected by a passphrase and
  767. your host account is protected by second passphrase.  That's how FTP-TLS
  768. works.  Automating such a connection introduces new elements of risk.
  769.  
  770. </i>
  771. </blockquote>
  772. <p>
  773.  
  774. When scripting an unattended operation, you must take special measures
  775. to avoid or handle the password prompts:
  776.  
  777. <p>
  778. <ol>
  779.  
  780. <li>If your private key file is encrypted, you are always prompted for the
  781. passphrase when using it.  The only way to avoid this is to create an
  782. unencrypted version of the private key file and then specify the filename of
  783. the unencrypted private key file in the SET AUTH TLS RSA-KEY-FILE command.
  784.  
  785. <p>
  786.  
  787. You can create an unencrypted PEM file from the original PKCS#12-format
  788. key file with the following command:
  789.  
  790. <p>
  791. <blockquote>
  792. <pre>
  793. openssl pksc12 -in <i>encrypted-pkcs12-keyfile</i> -out <i>unencrypted-pem-keyfile</i> -nodes
  794. </pre>
  795. </blockquote>
  796. <p>
  797.  
  798. or you can decrypt a PEM-format key file with:
  799.  
  800. <p>
  801. <blockquote>
  802. <pre>
  803. openssl rsa -in <i>encrypted-pem-keyfile</i> -out <i>unencrypted-pem-keyfile</i>
  804. </pre>
  805. </blockquote>
  806. <p>
  807.  
  808. Now your private key is stored in an unencrypted file, so you must ensure that
  809. the file's permissions allow access only to the person to whom the certificate
  810. was issued (this is possible in Unix, and in Windows NT, 2000, and XP, but
  811. not in Windows 95, 98, or ME).  Check very carefully that your key file is
  812. not accessible from outside, including by disk sharing.
  813.  
  814. <p>
  815.  
  816. <li>You have to supply a password on this type of connection; this is a
  817. limitation of the SSL/TLS / X.509 / FTP protocol combination.
  818. The <a href="ftp://kermit.columbia.edu/kermit/scripts/ckermit/ibm_infoexchange">sample
  819. script</a> accepts your IBM IE username and password on the command line, thus
  820. avoiding the interactive prompts.  These command-line arguments are used in
  821. the FTP OPEN command:
  822.  
  823. <p>
  824. <blockquote>
  825. <pre>
  826. ftp open ieftpint2.services.ibm.com ftp /user:\%1 /password:\%2
  827. </pre>
  828. </blockquote>
  829. <p>
  830.  
  831. (<tt>\%1</tt> and <tt>\%2</tt> are the command line arguments.)
  832.  
  833. <p>
  834.  
  835. You should not put the password in your script, because then anybody who can
  836. access the script file <i>and</i> your unencyrpted private key file can access
  837. your IE account directly (it must be said, however, that even when you omit
  838. the password from you script, the unencrypted key file gives intruders the
  839. bigger piece of the puzzle -- cracking a password is light work for today's
  840. average hacker).  If you don't put the password in your script, however,
  841. you can't run run the script unattended because the FTP OPEN command prompts
  842. you for the password.
  843.  
  844. </ol>
  845. <p>
  846.  
  847. Let's say you agree it is unwise to store a password in your script, but you
  848. still want the script to run unattended.  For example, you want to start the
  849. script before you go home for dinner, but have it run at midnight.  Just have
  850. the script prompt wait until midnight before opening the connection:
  851.  
  852. <p>
  853. <blockquote>
  854. <pre>
  855. sleep 23:59:59            ; wait until just before midnight
  856. ftp open ieftpint2.services.ibm.com ftp /user:\%1 /password:\%2
  857. ...
  858. </pre>
  859. </blockquote>
  860. <p>
  861.  
  862. In case you're worried about spies coming into your office and reading
  863. the password off your screen, also add the following command to your script:
  864.  
  865. <p>
  866. <blockquote>
  867. <pre>
  868. clear command scrollback
  869. </pre>
  870. </blockquote>
  871. <p>
  872.  
  873. This erases the screen and the entire scrollback buffer.  Also note that
  874. if an interloper interrupts the script, the variables containing the username
  875. and password disappear from memory automatically.
  876.  
  877. <p>
  878.  
  879. <b>Questions?</b>  Send them by e-mail to: <a href="mailto:kermit-support@columbia.edu"><tt>kermit-support@columbia.edu</tt></a>
  880.  
  881. <h3><a name="ibmhandout"><hr>APPENDIX: IBM Handout</a></h3>
  882.  
  883. The following message is sent by email from IBM to new FTP users
  884. <i>(the remainder of this section is IBM's message):</i>
  885.  
  886. <p>
  887.  
  888. Hello,
  889.  
  890. <p>
  891.  
  892. Here are some of the guideline for connecting to IBM over the
  893. Internet.
  894.  
  895. <p>
  896. <ul>
  897.  
  898. <li>Must be using an FTP Client that supports SSL ,Passive FTP and conforms
  899. to the RFC 
  900. <a href="http://www.ietf.org/internet-drafts/draft-murray-auth-ssl-08.txt">
  901. <tt>draft-murray-auth-ssl-08.txt</tt></a> standard.
  902. <p>
  903.  
  904. <li>Must have the IBM user number and challenge token to create an IBM
  905. signed certificate from
  906. <a href="https://pki.services.ibm.com/ieftp/webdocs.shtml"><tt>https://pki.services.ibm.com/ieftp/webdocs.shtml</tt></a>.
  907.  
  908. <p>
  909.  
  910. <li>Must have all upper ports enabled for Passive FTP on outgoing messages
  911. to <tt>ieftpint2.services.ibm.com</tt> (32.96.130.20).
  912.  
  913. <p>
  914.  
  915. <li>Must have an account and userid on IBM.
  916. The certificates are userid specific.
  917. IE/FTP access is not required for connecting over the Internet.
  918.  
  919. </ul>
  920. <p>
  921.  
  922. Commands. IBM uses the standard FTP commands on the network:
  923.  
  924. <p>
  925. <blockquote>
  926. <tt>AUTH</tt><br>
  927. <tt>LS -L</tt> = list (only available in home folder)<br>
  928. <tt>GET</tt><br>
  929. <tt>CD</tt> = Change Directories<br>
  930. <tt>PUT</tt>
  931. </blockquote>
  932. <p>
  933.  
  934. <dl>
  935. <dt>To LOGON</dt>
  936. <dd>Your user name should be formatted as Acct.Userid (period in between)
  937. Your password is your Information Exchange password and cannot be the same
  938. as your userid.
  939.  
  940. <p>
  941.  
  942. <dt>Sending and Receiving Files.
  943. <dd>The FTP server is setup similar to a directory tree.  When you are logged
  944. in you are in your home directory and are able to receive any files that
  945. have been sent to you.  This is the only folder that you would be able to
  946. LIST and have read access to. When ever you want to send a file to someone,
  947. you would Change Directories to their home folder and PUT the file.
  948.  
  949. <p>
  950.  
  951. <dt>To Receive Files
  952. <dd>LOG in to the FTP server.<br>
  953. Issue a LS -L to give you a list of all of the file in your mailbox<br>
  954. Issue a GET to receive the first file listed in your mailbox<br>
  955. Issue a MGET to receive all the file in your mailbox.<br>
  956. (*Note - most FTP clients handle most of these commands as background
  957. processes and you are able to just drag and drop your files. Check with
  958. your software supplier on how to do this. Also note, the files hold no
  959. significant name, so you may be asked to supply a name for the file you are
  960. receiving - <tt>GET C:\INCOMING\TEST.TXT</tt>)
  961.  
  962. <p>
  963.  
  964. <dt>To Send a flat file.
  965. <dd>To send a flat file the trading partner must be on the IE network and you
  966. must know their account and userid.
  967. Issue a CD to their Acct.Userid (period between) or set your remote
  968. directory or folder to the Acct.Userid.
  969. Issue a PUT command on the file you want to send - <tt>PUT
  970. C:\OUTGOING\TEST.TXT</tt>
  971. (*Note - most FTP clients handle most of these command as background
  972. processes and you are able to drag and drop your file. Check with your
  973. software supplier on how to do this.)
  974.  
  975. <p>
  976.  
  977. <dt>To Send an EDI file
  978. <dd>When sending EDI files, the network is going to resolve the receiver from
  979. the ISA header and therefore must use an Alias table. To do this use the
  980. command - SITE EDIALIASONLY 1.  Issue this command right after logon.  This
  981. will tell the FTP server to reference the alias tables to find out who the
  982. receiver is.<br>
  983. Issue a CD to the EDI folder or set your remote folder to EDI<br>
  984. Issue a PUT command on the file you want to send - <tt>PUT C:\OUTGOING\TEST.TXT</tt>
  985. or drag your file over.
  986. (*Note - some software packages have a place or field for initializing
  987. commands. The site command will probably be placed there but again you will
  988. want to check with your software vendor for verification. )
  989.  
  990. <p>
  991.  
  992. <dt>TO LOGOFF
  993. <dd>Issue the BYE command or Close your FTP session.  This is important ,
  994. because any files you have received out of your folder, may not be flagged
  995. as received until the session is successfully ended.
  996.  
  997. </dl>
  998. <p>
  999.  
  1000. Insight on how the session works for Passive FTP:
  1001.  
  1002. <p>
  1003. <ul>
  1004.  
  1005. <li>A session is started by an FTP client with IBM by creating a Control Port
  1006. to the IBM Server on port 21.
  1007.  
  1008. <p>
  1009.  
  1010. <li>The Client then issues an Authorization command or AUTH on that Control
  1011. Port.
  1012.  
  1013. <p>
  1014.  
  1015. <li>The IBM Server responds with a ping and then a :
  1016.  
  1017. <p>
  1018. <blockquote>
  1019. <pre>
  1020. 234 AUTH command accepted - proceed with Negotiation.
  1021. </pre>
  1022. </blockquote>
  1023. <p>
  1024.  
  1025. <li>At that point, IBM is waiting for a second port to be created by the FTP
  1026. Client.
  1027.  
  1028. <p>
  1029.  
  1030. <li>The FTP Client will then create a data port on a Dynamically picked port
  1031. from 1025 - 65,000 to negotiate the SSL connection.
  1032.  
  1033. <p>
  1034.  
  1035. <li>Once that has been established, your FTP Session can begin by sending in
  1036. your LOGON information.
  1037.  
  1038. </ul>
  1039. <p>
  1040.  
  1041. More Documentation:
  1042. For a complete manual on Using FTP on the Information Exchange network,
  1043. please visit
  1044. <a href="http://edi.services.ibm.com/ie/publications.shtml"><tt>http://edi.services.ibm.com/ie/publications.shtml</tt></a>.
  1045.  
  1046. <p>
  1047.  
  1048. [ <a href="#top">Top</a> ]
  1049. [ <a href="index.html">Kermit Home</a> ]
  1050. [ <a href="k95.html">Kermit 95</a> ]
  1051. [ <a href="ckermit.html">C-Kermit</a> ]
  1052. [ <a href="security.html">Security</a> ]
  1053. [ <a href="ckscripts.html">Scripts</a> ]
  1054. [ <a href="ftpscripts.html">FTP Scripts</a> ]
  1055.  
  1056. <p>
  1057.  
  1058. <hr>
  1059. <address>
  1060. The Kermit Project /
  1061. Columbia University /
  1062. <a href="mailto:kermit@columbia.edu">kermit@columbia.edu</a> /
  1063. 22 July 2002
  1064. </address>
  1065. </body>
  1066. </html>
  1067.