Author: Sami Lehtinen <sjl@ssh.com>

Copyright (C) 2002 SSH Communications Security Corp, Helsinki, Finland
All rights reserved.

Created: Mon Apr 22 06:10:16 2002

Line-based Protocol for Keyboard-interactive Plugin Program
==========================================================

The protocol is line based, i.e. all messages are terminated by a
linefeed character ("\n" in ANSI C, 0x0A in hex).

The messages in this protocol MUST NOT include a linefeed or carriage
return character, and SHOULD be printable ASCII characters.

Either side must be able to handle messages or descriptors in either, or
mixed, case (ie. "user_name:joe" should be handled equally as
"UsEr_NAME:joe").

Maximum line length is defined as 1024 characters (including the
newline). Messages longer than this MUST NOT be sent. This document does
not define how to send messages longer than 1024.

The protocol starts when sshd2 executes the plugin.
sshd2 then sends parameters to the program.

A parameter message takes the following form:

  <param-descriptor>:<value>

<param-descriptor> is a string decribing the following parameter,
e.g. "user_name", "remote_host_name", "remote_host_ip". The parameter
name SHOULD NOT include white space (tab- or space-characters). <value>
can be anything. A parameter name MUST NOT exceed 64 characters in
length, and MUST NOT include a colon (':'). <value> is case-sensitive,
so it MUST always be sent in the approriate case, i.e. "user_name:joe"
is NOT equal to "user_name:JOE".

Any number (including 0 (zero)) of these parameter messages may be sent
by the server.

The server terminates the parameter list by sending the following
message

  end_of_params

The plugin MUST be able to handle at least 128 parameters. The plugin
MUST be able to handle an empty parameter list, i.e. the server starts
directly with "end_of_params".  A plugin MUST silently ignore parameters
it doesn't recognize. If the server terminates the pipe before the
"end_of_params" message is sent, the plugin should gracefully exit
without authorization.

After the server has sent its parameter list, the plugin can send either
a list of requests, or either

  success

or

  failure

which mean either success or failure in the authentication, respectively.

The requests are formatted like parameter messages, above. A request is
of type "req" or "req_echo". "req_echo" specifies, that the user's answer
the request should be echoed to the user's screen. The plugin may also
specify an instruction by sending an "instruction" message. The "req"
and "req_echo" messages MUST NOT be empty, as that would be a protocol
error in keyboard-interactive.

The plugin terminates the request list by sending

  end_of_requests

The server then performs a round in keyboard-interactive, and passes the
replies to the plugin with "reply" messages. This list is terminated by

  end_of_replies

This message passing goes on until the plugin sends either "success" or
"failure".

Example of a typical transaction between sshd2 (in the following, "S")
and the plugin (in the following, "P"):

Note that "S: " or "P: " are not sent in the actual protocol
transaction, and <EOF> means that a side terminates the protocol
transaction, by closing the pipes (sshd2) or exiting (plugin).

S: remote_host_ip:192.6.281.3\n
S: remote_host_name:foo.bar.com\n
S: user_name:joe\n
S: dummy_var_1:dummy_val_1\n
S: dummy_var_2:dummy_val_2\n
S: end_of_params\n
P: instruction:Answer the following questions to get access\n
P: req:s/key: \n
P: req:securid: \n
P: end_of_requests\n
S: reply:2356\n
S: reply:5673\n
S: end_of_replies\n
P: success\n
P: <EOF>
S: <EOF>

Another example where the authentication is denied:

S: remote_host_ip:192.6.281.3\n
S: remote_host_name:foo.bar.com\n
S: user_name:joe\n
S: end_of_params\n
P: failure\n
P: <EOF>
S: <EOF>

Currently defined are the following parameters:

  user_name		The user that has been authenticated
  remote_host_ip	The IP-address of the remote host (IPv4 or IPv6
                        numerical notation)
  remote_host_name	The fully qualified domain name of the client
                        host

/end of file/
