WFTPWD.EXE - Password support for WFTHost
=========================================

Introduction
============

Some packet radio BBS's, when you log on, require you to send a
password to authenticate the log on.  Obviously, this helps in
reducing the incidence of piracy.
WFTPWD.EXE is a small program, intended to be used as an external
script command, which will automate the whole process of sending
your password when you log on to your BBS.  To use it, all you require
is a password file, which contains the password string or matrix.
WFTPWD.EXE supports FBB, NNA and MD2 password formats.
You must of course use a suitable script to connect to your BBS.
Sample scripts are included in this document.
WFTPWD.EXE requires version 1.3 or later of WFTHost.

Supported password formats
==========================

Version 1.2 supports the following password formats:

Mode 0
------

FBB passwords sent in a format similar to this:

Password> 12 35 21 37 44

In this mode each number represents the character position in a
predetermined password string.  WFTPWD will respond with a five
character string.  For example, if your password string was

an4bfhcbdkcmvbnghbj68504kfnc6mdldimbafjmzxbslqpsdnchfdkeuenfk85jfmmcmz

then the response to the password prompt above would be:

v5bfl

Note that in mode 0, the first character in the password string is
numbered 0.  The password string can be organised as a matrix of
rows of ten characters if desired, rather than one long string, e.g.

an4bfhcbdk
cmvbnghbj6
8504kfnc6m
dldimbafjm
zxbslqpsdn
chfdkeuenf
k85jfmmcmz

The prompt received from the BBS may include extra characters after
the five numbers, for example:

GB7LWB> 12 35 21 37 44 [0142536789]

WFTPWD always assumes that the five numbers occur immediately after
the BBS prompt.  This should fix a bug in version 1.1.

Mode 1
------

Exactly as mode 0, except that the first character in the
password string is numbered 1.

The response to the same prompt, and with the same password string
as above would be:

m8mas

Mode 2
------

NNA style passwords, using either an 8 X 8 or 16 X 16 matrix.
In this mode, the password file holds the matrix which would be
like this:

n38x);aF
C4T:lUjz
BG6^t{pI
S1qpD8Ug
ZZdE<nJ&
GvLkrYW[
XcbyaD(p
J76IoGlZ

for an 8 X 8 matrix or a similar structure of 16 lines of 16
characters for a 16 X 16 matrix.  The BBS sends out a set of pairs
of numbers such as:

26 45 62

and these are used to determine which characters to send back as the
response, using the first digit of each pair as the row number, and
the second digit of each pair as the column number (both start at 0).
In the case of a 16 X 16 matrix, hexadecimal characters 0 to F are
used to indicate the row and column numbers.
In the example above, the expected response would be:

pnb

Note that if your NNA BBS sysop sends you a matrix file with spaces
between each character, you *must* remove those spaces before using the
matrix.

Mode 3
------

MD2 passwords.  This is the most secure method and is used by some
BBS's.  A typical prompt would be:

Password > [0826354769]

The number in the square brackets is used in conjunction with a
password string to generate a 32 character hexadecimal response.

Using WFTPWD.EXE
================

1)  Ensure that the following files are installed in your \EXTERNAL
directory:
WFTPWD.EXE
WFTMD2.DLL (if you require MD2 password support)
WFTPWD_n.TXT (see step 2 below)

2)  Construct the password file.  The password file is named
WFTPWD_n.TXT, where n is the mode as discussed above.  For example,
to use MD2 passwords, create a file called WFTPWD_3.TXT.
The password file must contain your password string or matrix and
NOTHING ELSE!  The password file must be located in your \EXTERNAL
directory.

Setting up a script
===================

The WFTPWD program is called from a script running in WFTHost.
When WFTHost calls an external program from a script (by using the
EXEC command), it passes to it as a command-line parameter the stream
number on which the script is being executed (0 to 9), any parameter
that you supply and a line of data received on that stream.  This gives
WFTPWD.EXE the data it needs to work on.
As far as WFTPWD.EXE is concerned, the parameter that you supply is
the mode of password to expect.  Thus, valid parameters are 0 to 3.  If
you don't supply a parameter, the program will assume mode 1.
The second parameter you supply is the line offset, which tells WFTHost
which line of received data to pass to WFTPWD.EXE.  Usually this will
be 0 (for the most recent line), but will be 1 for NNA passwords
(mode 2).  If this is confusing, read the "External script programs"
section in WFTHost's online help.
When WFTPWD.EXE terminates it has returned the required response to the
calling script, which then outputs it to the BBS.  Some sample scripts
follow.  In reading these scripts, refer to the Script Command Reference
in WFTHost online help if you are not familiar with the command syntax.

Sample Mode 0 or 1 script
-------------------------

; ******************** START OF SCRIPT *********************
; Sample FBB type password script
; T. Kearsley, August, 1999
;
; The next line issues a connect command.  You can alter the
; wait time accordingly.  Replace GB9XYZ with a real callsign.
CONNECT 60 Abort GB9XYZ

; Wait for a prompt from the BBS.  This would be typically as
; shown, but can be altered to suit
LINEIN 120 Abort Password >

; Now call WFTPWD.EXE.  The first parameter can be either 0 or 1
; depending on which mode you want to use
EXEC WFTPWD.EXE,0,0

; You can end the script here, or wait for a further prompt
END

; This is the point where processing will branch to if the
; CONNECT or LINEIN commands timeout - don't forget it!
Abort:
; Issue a DISCONNECT and end
CMD D
END

; *********************** END OF SCRIPT **********************

Sample mode 2 script
--------------------

; ******************** START OF SCRIPT *********************
; Sample NNA type password script
; T. Kearsley, August, 1999
;
; The next line issues a connect command.  You can alter the
; wait time accordingly.  Replace GB9XYZ with a real callsign.
CONNECT 60 Abort GB9XYZ

; Wait for a prompt from the BBS.  This should be modified for
; your own situation
LINEIN 120 Abort GB9XYZ BBS >

; Send "@"
OUT @

; Wait for the prompt again
LINEIN 120 Abort GB9XYZ BBS >

; Now call WFTPWD.EXE.  Note the line offset is now 1, because
; we want to supply WFTPWD.EXE with the line of data previous to
; the second prompt
EXEC WFTPWD.EXE,2,1

; You can end the script here, or wait for a further prompt
END

; This is the point where processing will branch to if the
; CONNECT or LINEIN commands timeout - don't forget it!
Abort:
; Issue a DISCONNECT and end
CMD D
END

; *********************** END OF SCRIPT **********************

Sample Mode 3 script
--------------------

; ******************** START OF SCRIPT *********************
; Sample MD2 type password script
; T. Kearsley, August, 1999
;
; The next line issues a connect command.  You can alter the
; wait time accordingly.  Replace GB9XYZ with a real callsign.
CONNECT 60 Abort GB9XYZ

; Wait for a prompt from the BBS.  This would be typically as
; shown, but can be altered to suit
LINEIN 120 Abort Password >

; Now call WFTPWD.EXE.  The first parameter should now be 3
EXEC WFTPWD.EXE,3,0

; You can end the script here, or wait for a further prompt
END

; This is the point where processing will branch to if the
; CONNECT or LINEIN commands timeout - don't forget it!
Abort:
;Issue a DISCONNECT and end
CMD D
END

; *********************** END OF SCRIPT **********************

Troubleshooting
---------------

In the event that you experience difficulties in getting password
support going, first of all make sure that the prompts you are
waiting for in your script are accurate!  If not, the script will
simply time out eventually.
If the script runs OK, but sends a response which doesn't satisfy
the BBS, check that the password string you are using is the same
as what the BBS sysop has for you.
To aid debugging, any errors encountered by WFTPWD.EXE will be
written to a file called WFTPWD_n.ERR, located in the \EXTERNAL
directory, where n is the mode as described above.  If an error
occurs before a mode has been determined by the program (unlikely),
the error file is WFTPWD_X.ERR.  Entries in the error file are date
and time stamped and should be helpful in locating the problem.

Tim Kearsley, G4WFT
August 1999
