Author: Sami Lehtinen <sjl@ssh.com>

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

Created: Thu Mar 28 15:53:07 2002

Line-based Protocol for Command-line Authorization 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 authorization program.
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 authorization program MUST be able to handle at least 128
parameters. The authorization program MUST be able to handle an empty
parameter list, i.e. the server starts directly with "end_of_params".
An authorization program MUST silently ignore parameters it doesn't
recognize. If the server terminates the pipe before the "end_of_params"
message is sent, the authorization program should gracefully exit
without authorization.

After the server has sent its parameter list, the authorization program
replies with either

  success

or

  failure

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

In case of failure, the authorization program MAY send a reason code and
human readable error message to the server. These are formatted as
parameters above. The parameter names for these are "error_code" and
"error_msg", respectively.

Example of a typical transaction between sshd2 (in the following, "S")
and the authorization program (in the following, "C"):

Note that "S: " or "C: " 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 (authorization
program).

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
C: success\n
C: <EOF>
S: <EOF>

Another example where the authorization 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
C: failure\n
C: error_code:password_too_old\n
C: error_msg:User joe's password has expired.\n
C: <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

Currently defined are the following reason codes for authorization failure:

  password_too_old      The user's password has expired, and needs
                        changing.
  generic_error         Some other error occurred.

/end of file/
