tn5250 README
------------------------------------------------------------------------------

This is an implementation of the 5250 telnet protocol.  It was originally an
implementation for Linux, but it has been reportedly compiled on a number
of other platforms.  Contributed keyboard maps and termcap entries for
FreeBSD are in this tarball as well (see freebsd/README for more information).

This, the 0.17.x series, is the development series and may cause severe
headaches and stomach cramps, if only due to the quality of code :)  If you
are looking for a stable emulator, get the latest 0.16.x version.  Even so,
0.17.x is quite stable and in production at several sites.  Furthermore, for
the enhanced 5250 protocol 0.17.x is required.

Building from CVS
=================

Skip to ``Building and Installing'' below if you got these sources from a
.tar.gz release file or a CVS snapshot (as opposed to using `cvs checkout'
or `cvs update' to retreive the sources).

Certain files, such as the libtool support files and some shell scripts
which replace possibly missing commands on the target system are not in
CVS because we don't maintain them.  They can be installed with the
following command:

   ./autogen.sh

This command requires current versions of the following packages, and the
generated files may not work properly.

   automake
   autoconf
   libtool

You may receive an error the first time you run this script.  If so, run
the script a second time to make sure you don't get an error (this is a bug
with automake).


Building and Installing
=======================

To build the emulator simply type the following:

   ./configure
   make
   make install

Additional (but decidedly generic) installation instructions are available
in the file `INSTALL' included in this distribution.  Installation
instructions specific to your platform exist if you are using Linux or
FreeBSD -- they are in the linux/ and freebsd/ directories, respectively.
Please read these before telling us that the function keys don't work ;-)

The emulator uses the ncurses library for manipulating the console.  Make
sure you have the ncurses development libraries installed before trying to
compile the source.  There have been both reports of the standard BSD curses
working and not working, so you may have to install GNU curses (ncurses)
under *BSD.

X Windows
=========

To use the emulator under X Windows, use the provided `xt5250' shell script,
which sets up a standard `xterm' (it will *not* work with an `nxterm' or an
`rxvt' terminal).

There is one common problem which would cause xt5250 to flash once on the
screen then disappear.  If the termcap or terminfo entry for the `xterm-5250'
terminal type does not exist, the `xterm' will exit immediately.

x5250 is an X11 front end (which does not use xterm) written by James Rich.
It can be found at http://www.chowhouse.com/~james/x5250.

Other Information
=================

Other information is available on the web.

http://tn5250.sourceforge.net/                       - linux5250 Homepage
http://www.midrange.com/linux5250.shtml              - linux5250 List Info
http://archive.midrange.com/linux5250/index.htm      - linux5250 List Archives
http://sourceforge.net/projects/tn5250/              - linux5250 at Sourceforge
http://perso.libertysurf.fr/plinux/tn5250-faq.html   - linux5250 FAQ
http://www.chowhouse.com/~james/tn5250-HOWTO.pdf     - linux5250 HOWTO

Comments, questions, bug reports and patches are much appreciated - please
subscribe to the list and post them there if at all possible.  If that's too
much trouble, email one of the maintainers below:

Jason M. Felice <jasonf@nacs.net>
Michael Madore <mmadore@blarg.net>

Enjoy!

                    HOW TO SET UP / USE TN5250 WITH SSL

It is possible to configure your AS/400 and tn5250 to encrypt and protect
it's conversation using the SSL/TLS protocol.  This document tells you how.

SETTING UP YOUR SERVER:

   This section assumes that your AS/400 and TELNET server have not yet
   been set up to use SSL, and that you wish you create & sign your own
   SSL certificates (as opposed to buying them from VeriSign on similar
   company)

   If your system is already set up for SSL, please skip to step 7.

   1) You must install the following software on your AS/400:
        -- Digital Certificate Manager, option 34 of OS/400 (5769-SS1)
        -- IBM HTTP Server for AS/400 (5769-DG1)
        -- IBM Cryptographic Access Provider (5769-ACx or 5649-ACx)

      The first two options are included on your OS/400 CDs.  The
      Cryptographic Access Provider must be ordered from IBM, and you
      may get a different option, depending on the laws in your country
      regarding encryption, and the model of AS/400 you have.  At the
      time of this writing, IBM supplies the C.A.P. at no charge.

      If you're given a choice, you'll want to install 5769-AC3, as
      it has the best cryptography.

   2) Start the HTTP *ADMIN server in order to configure your Digital
        Certificate Manager.  From the AS/400, type:
             STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

   3) With a web browser, connect to your AS/400's admin server:
             http://as400.example.com:2001

   4) Click "Digital Certificate Manager", then "Certificate Authority (CA)"
         then "Create a Certificate Authority."  Fill out the forms, etc.

   6) Click "System Certificates".  IF you haven't done so already,
         click "Create new certificate store" and follow the prompts for
         creating the *SYSTEM certificate store.

   7) Select "Work With Secure Applications".  Select
         "QIBM_QTV_TELNET_SERVER", then click the
         "Work with system certificate" button.  It should tell you
         that your telnet server has your system certificate assigned
         to it.  IF not, you can assign it here.

   8) Now you have to start your telnet server on the AS/400.  If it
         is already running, you'll have to end it, and start it again.
         On the AS/400, type:
            ENDTCPSVR SERVER(*TELNET)
            STRTCPSVR SERVER(*TELNET)

   9) Now, verify that your SSL-enabled Telnet server is running.
         on the AS/400, type NETSTAT *CNN.   Press F14 to display
         the port numbers.  Look for a server that's in "Listen"
         state on port 992.  This is the SSL telnet server.

If you have problems, or need more detailed information on how to set
up the TELNET-SSL server on the AS/400, see the TCP/IP configuration area
of the iSeries Information Center.

Here's a link to the TELNET section of the Information Center online:
http://publib.boulder.ibm.com/pubs/html/as400/v4r5/ic2924/info/RZAIWGETSTART.HTM
Click "Telnet server and SSL" to get started.


CONFIGURING TN5250 TO USE SSL:

   1) You must have OpenSSL installed on your Linux/FreeBSD (etc) machine
       before building tn5250 if you want it to use SSL.   If you don't
       already have it, you can get it from http://www.openssl.org

   2) One of the first steps of building TN5250 is to run ./configure.
       To ensure that SSL support is compiled in, type ./configure --with-ssl
       instead of just ./configure.  (If you omit the --with-ssl, the
       script may still use OpenSSL.  The --with-ssl option really just tells it
       to report an error if OpenSSL cannot be found)

   3) Build tn5250 as normal.  (after configure type 'make' then 'make install'
       see the README file for more information)

   4) To tell TN5250 to use SSL when you connect to your AS/400, prefix
       the hostname with ssl: in your configuration.  For example,
       type: tn5250 ssl:as400.example.com

   At this point, your TN5250 session should be encrypted when sent over
   the network.  However, you should also consider telling tn5250 to verify
   the server's certificate when connecting.


VERIFYING YOUR SERVERS CERTIFICATE:

   It is a good idea when using SSL to verify the certificate that your
   telnet-ssl server is sending to tn5250.   This ensures that you are
   communicating with the server that you think you are, and that your
   connection is not being "hijacked" by a 3rd party.

   1) If it's not already running, start the AS/400's HTTP *ADMIN server
        by typing:  STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

   2) Connect to the Admin server with a web browser:
        http://as400.example.com:2001

   3) Click "Digital Certificate Manager", then "Certificate Authority (CA)"
        then "Install CA certificate on your PC", then click
        "Copy and paste certificate"

   4) Highlight the certificate that is displayed with your mouse.  Make
        sure that you include the "----BEGIN CERTIFICATE-----" and the
        "----END CERTIFICATE-----" in the selection.  Copy & paste this
        information into a file on your Linux/FreeBSD machine.  For our
        example, we'll call this file "as400_ca.pem"

   5) Set up tn5250 to verify the server's certificate using the
        +ssl_verify_server keyword and the ssl_ca_file= option.

        for example, type the following (as one line):
           tn5250 +ssl_verify_server ssl_ca_file=/path/to/as400_ca.pem
               ssl:as400.example.com


USING TN5250 WITH SSL CLIENT CERTIFICATES:

Some versions of OS/400 allow you to require client authentication in
the Telnet server.  If your AS/400 is set up this way, here's how you
telnet TN5250 to use certificates & a private key:

   1) If it's not already running, start the AS/400's HTTP *ADMIN server
        by typing:  STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

   2) Connect to the Admin server with a web browser (I used Netscape
        Navigator 4.77 in my tests):
        http://as400.example.com:2001

   3) Click "Digital Certificate Manager", then "Certificate Authority (CA)"
        then "Install CA certificate on your PC", then click
        "Receive certificate"

   4) Netscape brings up the "New Certificate Authority" wizard.  Follow
        the prompts, until you can finally click "Finish".

   5) Click "User Certificates", then "Request a new user certificate",
        Fill out the form and click OK.

   6) Netscape brings up the "Generate A Private Key" wizard.  Follow
        the prompts.  The password you assign it is only temporary,
        but you should assign it one.   Maybe "tn5250" is a good password.

   7) After filling out your password, and waiting a second or two, you
        should come to a screen that says "User Certificate Created
        Successfully".   Click "Receive Certificate".

   8) The certificate should be downloaded into your web browser.  It
        may not tell you that it did anything, so don't be surprised if
        nothing seems to happen.

   9) On the Netscape "Navigation Toolbar" click the "Security" button.
       (This is the button that looks like a padlock).  Then under
       "Certificates", click on "Yours".

  10) The certificate that you just generated should appear, along with
       any other private-key certficates that you have in your browser.
       Highlight the cert that you just generated, and click "Export".

  11) It asks for a password.  Type the password that you used in step 6.

  12) It asks for a new password.   Type the same password again.
        Then type it one more time to verify it. :)

  13) Save the exported certificate to a file called "tn5250.p12"
        It will tell you that the certificate has been successfully
        exported.  Good work!

  14) Unfortunately, Netscape likes to save the certificate in pkcs12
       format, which doesn't do us much good.  We need it in PEM format!
       Back at your *BSD/Linux/Unix/etc prompt type:

            openssl pkcs12 -clcerts -in tn5250.p12 -out tn5250.pem

  15) It asks for the "Import Password".  This is the same password
       that you assigned it in Step 12.

  16) It says "Enter PEM pass phrase".   This is, yet another, password.
       However, this is the important one that you will be using from
       this point on.  You might want to write it down.

  17) Now, finally, to tell tn5250 to use this certificate that you
       just received, use the ssl_cert_file keyword.  Here's an example:

          tn5250 ssl_cert_file=/home/klemscot/tn5250.pem ssl:as400

  18) It should ask you for your PEM pass phrase.  This is the password
        that you typed in Step 16.

  19) If you don't want to type your PEM pass phrase each time, you can
        use the ssl_pem_pass keyword to assign it.  For example, you
        might type the following (as one line):

        tn5250 ssl_cert_file=/home/klemscot/tn5250.pem
            ssl_pem_pass=mmmbeer +ssl_verify_server ssl:as400.example.com


USING SSL IN A CONFIGURATION FILE:

Since these commands are getting sort-of long, you'll probably want to use
a configuration file.

If you want to use a config file  (~/.tn5250rc or /usr/local/etc/tn5250rc)
with tn5250, set it up like this:

   session1 {
      host = ssl:as400.example.com
      +ssl_verify_server
      ssl_ca_file = /path/to/as400_ca.pem
      ssl_cert_file = /path/to/tn5250.pem
      ssl_pem_pass = mmmbeer
      [ .. other options can go here ... ]
   }

And start tn5250 like this:

   tn5250 session1