Newsgroups: bit.listserv.ibmtcp-l
Date:         Fri, 2 Oct 1992 08:11:55 EDT
From:         Richard Ryniker <ryniker@WATSON.IBM.COM>
Subject:      MVS FTP exits.

Ref: gettes@PRINCETON.EDU  Thu, 1 Oct 1992 17:55:07 -0400

The exits are documented in the Version 2 Release 2.1 Planning and
Customization manual, SC31-6085-02.  I have included below several
paragraphs from this manual discussing these exits, but please understand
this was extracted from the formatted (LIST3820) file and suffers from
approximations made to force the information into simple text.  Hard copy
publications should be available now, or very shortly; I received them
just a few days ago.

-Richard Ryniker             IBM Research
________________________________________________________________________________

SMF User Exit

The FTP server provides the capability of a user-written exit to be
called when SMF records are being written. This exit, FTPSMFEX, is
dynamically loaded once but called every time an SMF record is about to
be written.

If the FTPSMFEX exit is to be called when writing SMF records, include
the SMFEXIT parameter in the FTP.DATA data set. This causes SRVRFTP to
attempt to load the FTPSMFEX exit during initialization and turn on exit
calling. If FTPSMFEX cannot be loaded, an S806 abend occurs and exit
calling is turned off.

The FTP server passes FTPSMFEX two parameters, a fullword return code and
the SMF record itself. FTPSMFEX can modify the SMF record if desired and
set the return code to either a zero or nonzero value. If the FTP server
receives any nonzero return code from FTPSMFEX, then the SMF record is
not written to SMF.

FTPSMFEX should be the same AMODE/RMODE as FTPSERVE.


FTP Server Security User Exits

Four new user exits have been added to the FTP server to provide
increased security. The user exit load modules can be placed in any
library for which the FTP server has a STEPLIB. They are loaded at FTP
server initialization time. If a user exit is not found, functioning
proceeds as it did before the addition of this FTP User Exit feature.

A user exit gets passed the address of a parameter list in Register 1.
The parameter list is a series of pointers to values. The first word of
the parameter list always points to the Return Code. If the User Exit
sets the Return Code to 0, processing continues as normal. If it is any
other value, a new path is taken.

For example, these four exits are authorization exits, and if the Return
Code is not 0, then authorization is denied, and the user receives a
message indicating this. Upon entry the Return Code is 0, so a correct
return can be indicated by leaving the return code alone.

The second word of the parameter list always points to a word containing
the number of parameters that follow. This helps handle future releases
that may increase the number of parameters in these parameter lists.

The remainder of the parameter list points to values that the User Exit
wants to use in its processing. The following describes the values passed
in the parameter list for each user exit.

Because the user exit is loaded at FTP server initialization time, if you
want the server to use a new version of your exit routine, you need to
recycle the FTP server (stop and start it).  If you are debugging a
user-exit routine, you should have a test version of a server to work
with so that you can stop and start without affecting other users. You
can do that by putting a PORT parameter in the EXEC statement of the FTP
JCL. For example, PARMS='PORT 172'. To connect to this server:

			FTP nodename 172

You can use any non-well-known number as a port number for your test FTP
server.

The following describes the four user exits:

FTCHKIP is called from routine NewConnectionEvent in FTSRVPA at the
initial stage of logon, or whenever the user issues an OPEN command to
open a new connection. The IP and PORT addresses of the local and foreign
hosts determine if the foreign host's control connection should remain or
be canceled. The message

    421 User Exit rejects open for connection

is sent to the user if the resource is denied. The following parameter
list is passed to FTCHKIP.

Offset Value

+0     pointer to word with Return Code

+4     pointer to word containing number 4 (no. of following parms)

+8     pointer to fullword Foreign IP address

+12   pointer to halfword Foreign Port number

+16   pointer to fullword Local IP address

+20   pointer to halfword Local Port number

FTCHKPWD is called from routine DoPass in FTSMVSUB just after the user
enters the password. The exit is passed the user ID and password of the
user that has just logged on. The exit has the option of rejecting the
logon. The message

    530 User Exit rejects logon by 'xxxxx'

is sent to the user if the resource is denied. The following parameter
list is passed to FTCHKPWD.

Offset Value

+0      pointer to word with Return Code

+4      pointer to word containing number 2 (no. of following parms)

+8      pointer to 8 byte user ID that is logging on

+12    pointer to 8 byte Password of user that is logging on

FTCHKCMD is called from routine DoCommand in FTSCMD whenever the user
enters a command to execute (such as GET, PUT, or any other FTP command).
The exit has the option of not permitting the execution of the command,
with the user receiving a message. The message

    500 User Exit denies Userid xxxxx from using Command yyy

is sent to the user if the resource is denied. The following parameter
list is passed to FTCHKCMD.

Offset Value

+0      pointer to word with Return Code

+4      pointer to word containing number 3 (no. of following parms)

+8      pointer to 8 byte Userid that is logged on

+12    pointer to 8 byte command being entered

+16    pointer to string containing arguments after command the first
       halfword of the string contains the number of characters that
       follow.

FTCHKJES is called from routine StorFile in FTSEVEN if the server is in
filetype=jes mode and the client tries to submit a job. The user ID and
the job being submitted are passed to the exit. The exit can allow or
refuse the job to be submitted to the JES internal reader. For example,
the exit can look for a USER= parameter on the JOB card and check it
against the client's user ID. The message

     550 User Exit refuses this job to be submitted by userid

is sent to the user if the remote job submission is denied. The following
parameter list is passed to FTCHKJES.

Offset Value

+0      pointer to word with Return Code

+4      pointer to word containing number 3 (no. of following parms)

+8      pointer to 8 byte user ID that is logged on
+12    pointer to buffer containing JOB being submitted

+16    pointer to word with length of the buffer containing JOB submitted

The Return Code word is initialized to 0, so the user exit can return
without touching it if there is a correct return code. Any other return
code denies access to the resource in question.


 Notes:

  1. FTCHKIP has been placed before the user logs on, and if access is denied,
   the user receives a message and then the control connection is severed.
   This message comes at a point when most clients expect to continue with
   the logon process by sending the user ID and password. Even though it is
   possible that some FTP clients may not expect a 421 message at this point, it
   is the most appropriate place for this exit.

  2. The MVS loader loads the Exit Routines from a library that it normally
 loads
   FTP modules from (one referenced by a Steplib in the FTP Server Proc). If
   you are not using the user-exit facility, put a dummy user-exit load module
 in
   the first library referenced by a Steplib if there is more than one concat-
   enated. This prevents someone from putting in their own module in a library
   later in the concatenation sequence. This also increases the need to have
   that library be SAF protected.
Comments: Gated by NETNEWS@AUVM.AMERICAN.EDU