Subject: GSSAPI Conversation function proposal

From: "Theodore Y. Ts'o" <[email-masked]>
Date: Thu, 27 May 1999 18:44:33 -0400 (EDT)

Hi there,

	I finally had a chance to write up the GSSAPI Conversation
function proposal which I briefly mentioned at the last two IETF
meetings.  

	John, as the working group chair, do you have any objections
with my submitting the following to the I-D directory?

							- Ted

Internet Draft                                                   T. Ts'o
Common Authentication Technology Working Group                       MIT
draft-ietf-cat-gss-conv-00.txt                              May 26, 1999

                 GSS Conversation C-bindings Interface

1.  Status of this Memo

   This document is an Internet Draft.  Internet Drafts are working
   documents of the Internet Engineering Task Force (IETF), its Areas,
   and its Working Groups.  Note that other groups may also distribute
   working documents as Internet Drafts.  Internet Drafts are draft
   documents valid for a maximum of six months. Internet Drafts may be
   updated, replaced, or obsoleted by other documents at any time.  It
   is not appropriate to use Internet Drafts as reference material or to
   cite them other than as a ``working draft'' or ``work in progress.''
   Please check the I-D abstract listing contained in each Internet
   Draft directory to learn the current status of this or any other
   Internet Draft.

   Comments on this document should be sent to [email-masked]'', the
   IETF Common Authentication Technology WG discussion list.

2.  Overview and Rational

   Traditionally, the GSSAPI specification has not included in its scope
   the acquisition of initial credentials, or mechanisms which have
   required interaction with the user in the course of the security
   context.  This has limited the applicability of the GSSAPI
   specification.

   This specification allows an application program to register a
   callback function so that a GSSAPI mechanism can request conversation
   services from the application program. The application program is
   responsible for displaying messages to the user and requesting input
   from the user via the callback function.

   The goal of this specification is to allow certain low-
   infrastructure-requiring mechanisms to prompt the user for a
   username, password, SecureID response, etc.  It might also be used by
   mechanisms such as Kerberos when the GSSAPI library wishes to obtain
   initial credentials itself, instead of assuming that they are already
   present in the process.

3.  GSSAPI Conversation API

 3.1  The gss_acquire_cred_conv function

T. Ts'o                                                        [Page 1]

INTERNET DRAFT    GSS Conversation C-bindings Interface      26 May 1999

          OM_uint32 gss_acquire_cred_conv (
                  OM_uint32         *minor_status,
                  const gss_name_t  desired_name,
                  OM_uint32         time_req,
                  const gss_OID_set desired_mechs,
                  gss_cred_usage_t  cred_usage,
                  gss_cred_conv_t   conversation_info,
                  gss_cred_id_t     *output_cred_handle,
                  gss_OID_set       *actual_mechs,
                  OM_uint32         *time_rec)

This function is an extended version of the gss_acquire_cred function
defined in the GSSAPI C-bindings specification, with the addition of a
new parameter, conversation_info.  If the conversation_info parameter is
NULL, then the behavior of gss_acquire_cred_conv will be identical to
gss_acquire_cred.

If a conversation function is registered via the conversation_info
parameter, then the GSSAPI mechanism may call the conversation function
during the execution of the gss_acquire_cred_conv() function, and the
returned GSSAPI credentials will have a reference to the conversation
function.  If GSSAPI credential containing a conversation function is
passed to gss_init_sec_context(), gss_accept_sec_context(), or
gss_add_cred(), the GSSAPI mechanism may also call the conversation
function during the course of execution of those GSSAPI functions.

 3.2   The gss_copy_buffer function

          OM_uint32 gss_display_name (
                  OM_uint32       *minor_status,
                  gss_buffer_t    input_buffer,
                  gss_buffer_t    output_buffer)

This function is used to copy a buffer into dynamically allocated memory
which can be freed by the gss_release_buffer() call.

The conversation function must use this function when filling in buffers
in the gss_resp array, since the GSSAPI library will free the buffer
after it is done using it.  (Otherwise, there is no good way to make
sure the buffers containing the user's responses get freed.)

4  Data Types and Structures

 4.1  The gss_cred_conv_t data structure

The gss_cred_conv_t data type contains a pointer to the conversation
function and private data pointer which is passed to the conversation

T. Ts'o                                                        [Page 2]

INTERNET DRAFT    GSS Conversation C-bindings Interface      26 May 1999

function.  It shall have the following C definition:

          typedef struct gss_conv {
                  int (*conv)(OM_uint32 gss_num_msg,
                              const gss_conv_message_t *gss_msg,
                              gss_conv_message_t *gss_resp,
                              void *gss_appdata_ptr);
                  void *gss_appdata_ptr;
          } *gss_cred_conv_t;

The first parameter to the conversation function, gss_num_msg, specifies
the number of messages to be processed by the conversation function.
The second and third parameters are two arrays which have gss_num_msg
entries.  The first array, gss_msg, contains a list of text messages
which can be prompts or informational text to be displayed to the user.
The second array, gss_resp, is to be filled in by the conversation func-
tion as defined below.  The final parameter is a private data pointer
which was supplied by the calling application in the gss_cred_conv_t
structure.

The conversation function returns the following integer codes to its
caller (the GSSAPI library):

          #define GSS_CONV_SUCCESS        0
                  /* The user filled in the requested fields and all is well */

          #define GSS_CONV_ABORT          1
                  /* The user requested an abort */

 4.2  The gss_conv_message_t structure

The gss_conv_message_t structure is the data element which is used to
pass prompts and informational messages to the conversation function, as
well as passing the user's responses back to the GSSAPI library.  It has
the following C type definition:

          typedef struct gss_conv_message {
                  OMuint32                gss_msg_code;
                  gss_buffer_desc         gss_msg;
          } gss_conv_message_t;

In the gss_msg array, the gss_msg_code field specifies whether each item
in the gss_msg array is a prompt for user response, or informative text
to be displayed to the user.  If the entry in the gss_msg array is a
prompt, the gss_msg_code further specifies whether the user response
should be echoed or not.  If the entry in the gss_msg array is an infor-
mative text, the gss_msg_code also specifies whether it should be dis-
played as an error or as normal informative text.

T. Ts'o                                                        [Page 3]

INTERNET DRAFT    GSS Conversation C-bindings Interface      26 May 1999

The following numbers are defined for the gss_msg_code field:

          #define GSS_CONV_ECHO_OFF       1
                  /* Obtain a string without echoing any text */

          #define GSS_CONV_ECHO_ON        2
                  /* Obtain a string with echoing enabled */

          #define GSS_CONV_ERROR_MSG      3
                  /* Display an error */

          #define GSS_CONV_TEXT_INFO      4
                  /* Display some informational text. */

In the gss_resp array, the gss_msg_code field is reserved, and should be
set to zero by the conversation function.

5.  Operation of the conversation function

If a conversation function has been registered with a GSSAPI credential,
it may be called during the original call to gss_acquire_cred_conv, or
when one of the following functions is called with the GSSAPI credential
with the conversation function: gss_init_sec_context(),
gss_accept_sec_context(), or gss_acquire_cred().

The conversation function supplied by the application shall process each
entry in the gss_msg array in order.  If the entry in the gss_msg array
is an informational or error text, the conversation function must
arrange to have the string displayed to the user.  If the entry in the
gss_msg array is a prompt, the conversation function is responsible for
displaying the prompt and requesting input from the user, with echoing
enabled or disabled as appropriate.

The response from the user should be placed in the corresponding entry
in the gss_resp array, in a dynamically allocated gss_buffer_t.  The
conversation function should not modify entries in the gss_resp array
which correspond to informative texts or error messages in the gss_msg
array.  The GSSAPI library is responsible for freeing the dynamically
allocated buffers placed in the gss_resp array by the conversation func-
tion.  These buffers should be freed before the GSSAPI function which
called the conversation function returns to the application program.

6.  Security Considerations

   This interfaces allows a GSSAPI library to ask the user for passwords
   and other authentication information.  It is the responsibility of
   the calling application to zero any memory that might contain user
   responses to prevent them from being exposed in case of a program

T. Ts'o                                                        [Page 4]

INTERNET DRAFT    GSS Conversation C-bindings Interface      26 May 1999

   crash.

7.  Author's Address

   Theodore Ts'o
   MIT
   MIT Room E40-343
   1 Amherst St.
   Cambridge, MA 02139

   Phone: (781) 391-3464

   EMail: [email-masked]

T. Ts'o                                                        [Page 5]

==========================================================================
This message was posted through the Stanford campus mailing list
server.  If you wish to unsubscribe from this mailing list, send the
message body of "unsubscribe ietf-cat-wg" to [email-masked]

---

From: "Linn, John" <[email-masked]>
Date: Fri, 28 May 1999 08:28:36 -0400

Ted writes, excerpting:

> -----Original Message-----
> From: Theodore Y. Ts'o [mailto:[email-masked]]
> Sent: Thursday, May 27, 1999 6:45 PM
> To: [email-masked]
> Subject: GSSAPI Conversation function proposal
> 
> 
> Hi there,
> 

This is fine by me as a WG I-D submission.  Also in the "low-infrastructure"
topic area, we've lately received draft-ietf-sskm-00.txt which hasn't yet
been the subject of review discussion on the list.  I'd like to encourage
review and discussion of both drafts. 

More broadly, per the draft WG charter revision as discussed last week (and
now in the hands of the IESG), we've a designated July milestone of
"Determine direction and intent re progressing low-infrastructure mechanism
definitions".  In advance of the Oslo meeting, I'd like to encourage
discussion of this general area to refine the sense of the group about
whether and which draft(s) we'll try to progress, and of whether and what
changes are needed. 

Reviewing the state of bidding from the Minneapolis minutes, the sense then
was as follows: "At the end of the session, a straw poll of attendees was
taken to determine interest in pursuing standardization of various
low-infrastructure GSS-API
alternatives.  Attendees were allowed to express support for multiple
options. Greatest interest was apparent in LIPKEY (19 attendees recorded),
followed by GSS-Easy (12 attendees), and various forms of digest
authentication (10 attendees).  One attendee indicated interest in pursuing
EKE/SPEKE/SRP methods.  No attendees indicated opposition to pursuing
standardization of one or more low-infrastructure mechanism candidates
within the GSS framework."

--jl