idnits 2.17.1 draft-ietf-cat-gss-conv-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 0 form feeds but 5 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There is 1 instance of too long lines in the document, the longest one being 4 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document doesn't use any RFC 2119 keywords, yet has text resembling RFC 2119 boilerplate text. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 21, 1999) is 8952 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 7 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft T. Ts'o 2 Common Authentication Technology Working Group MIT 3 draft-ietf-cat-gss-conv-00.txt October 21, 1999 5 GSS Conversation C-bindings Interface 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with 10 all provisions of Section 10 of RFC2026. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet-Drafts as reference 18 material or to cite them other than as "work in progress." 20 The list of current Internet-Drafts can be accessed at 21 http://www.ietf.org/ietf/1id-abstracts.txt 23 The list of Internet-Draft Shadow Directories can be accessed at 24 http://www.ietf.org/shadow.html. 26 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 27 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 28 document are to be interpreted as described in RFC 2119.T 30 Comments on this document should be sent to ``cat-ietf@mit.edu'', the 31 IETF Common Authentication Technology WG discussion list. 33 1. Abstract 35 Traditionally, the GSSAPI specification has not included in its scope 36 the acquisition of initial credentials, or mechanisms which have 37 required interaction with the user in the course of the security 38 context. This has limited the applicability of the GSSAPI 39 specification. 41 This specification allows an application program to register a 42 callback function so that a GSSAPI mechanism can request conversation 43 services from the application program. The application program is 44 responsible for displaying messages to the user and requesting input 45 from the user via the callback function. 47 The goal of this specification is to allow certain low- 48 infrastructure-requiring mechanisms to prompt the user for a 49 username, password, SecureID response, etc. It might also be used by 50 mechanisms such as Kerberos when the GSSAPI library wishes to obtain 51 initial credentials itself, instead of assuming that they are already 52 present in the process. 54 2. GSSAPI Conversation API 56 2.1 The gss_acquire_cred_conv function 58 OM_uint32 gss_acquire_cred_conv ( 59 OM_uint32 *minor_status, 60 const gss_name_t desired_name, 61 OM_uint32 time_req, 62 const gss_OID_set desired_mechs, 63 gss_cred_usage_t cred_usage, 64 gss_cred_conv_t conversation_info, 65 gss_cred_id_t *output_cred_handle, 66 gss_OID_set *actual_mechs, 67 OM_uint32 *time_rec) 69 This function is an extended version of the gss_acquire_cred function 70 defined in the GSSAPI C-bindings specification, with the addition of a 71 new parameter, conversation_info. If the conversation_info parameter is 72 NULL, then the behavior of gss_acquire_cred_conv will be identical to 73 gss_acquire_cred. 75 If a conversation function is registered via the conversation_info 76 parameter, then the GSSAPI mechanism may call the conversation function 77 during the execution of the gss_acquire_cred_conv() function, and the 78 returned GSSAPI credentials will have a reference to the conversation 79 function. If GSSAPI credential containing a conversation function is 80 passed to gss_init_sec_context(), gss_accept_sec_context(), or 81 gss_add_cred(), the GSSAPI mechanism may also call the conversation 82 function during the course of execution of those GSSAPI functions. 84 2.2 The gss_copy_buffer function 86 OM_uint32 gss_display_name ( 87 OM_uint32 *minor_status, 88 gss_buffer_t input_buffer, 89 gss_buffer_t output_buffer) 91 This function is used to copy a buffer into dynamically allocated memory 92 which can be freed by the gss_release_buffer() call. 94 The conversation function must use this function when filling in buffers 95 in the gss_resp array, since the GSSAPI library will free the buffer 96 after it is done using it. (Otherwise, there is no good way to make 97 sure the buffers containing the user's responses get freed.) 99 3 Data Types and Structures 101 3.1 The gss_cred_conv_t data structure 103 The gss_cred_conv_t data type contains a pointer to the conversation 104 function and private data pointer which is passed to the conversation 105 function. It shall have the following C definition: 107 typedef struct gss_conv { 108 int (*conv)(OM_uint32 gss_num_msg, 109 const gss_conv_message_t *gss_msg, 110 gss_conv_message_t *gss_resp, 111 void *gss_appdata_ptr); 112 void *gss_appdata_ptr; 113 } *gss_cred_conv_t; 115 The first parameter to the conversation function, gss_num_msg, specifies 116 the number of messages to be processed by the conversation function. 117 The second and third parameters are two arrays which have gss_num_msg 118 entries. The first array, gss_msg, contains a list of text messages 119 which can be prompts or informational text to be displayed to the user. 120 The second array, gss_resp, is to be filled in by the conversation func- 121 tion as defined below. The final parameter is a private data pointer 122 which was supplied by the calling application in the gss_cred_conv_t 123 structure. 125 The conversation function returns the following integer codes to its 126 caller (the GSSAPI library): 128 #define GSS_CONV_SUCCESS 0 129 /* The user filled in the requested fields and all is well 130 */ 132 #define GSS_CONV_ABORT 1 133 /* The user requested an abort */ 135 3.2 The gss_conv_message_t structure 137 The gss_conv_message_t structure is the data element which is used to 138 pass prompts and informational messages to the conversation function, as 139 well as passing the user's responses back to the GSSAPI library. It has 140 the following C type definition: 142 typedef struct gss_conv_message { 143 OMuint32 gss_msg_code; 144 gss_buffer_desc gss_msg; 145 } gss_conv_message_t; 147 In the gss_msg array, the gss_msg_code field specifies whether each item 148 in the gss_msg array is a prompt for user response, or informative text 149 to be displayed to the user. If the entry in the gss_msg array is a 150 prompt, the gss_msg_code further specifies whether the user response 151 should be echoed or not. If the entry in the gss_msg array is an infor- 152 mative text, the gss_msg_code also specifies whether it should be dis- 153 played as an error or as normal informative text. 155 The following numbers are defined for the gss_msg_code field: 157 #define GSS_CONV_ECHO_OFF 1 158 /* Obtain a string without echoing any text */ 160 #define GSS_CONV_ECHO_ON 2 161 /* Obtain a string with echoing enabled */ 163 #define GSS_CONV_ERROR_MSG 3 164 /* Display an error */ 166 #define GSS_CONV_TEXT_INFO 4 167 /* Display some informational text. */ 169 In the gss_resp array, the gss_msg_code field is reserved, and should be 170 set to zero by the conversation function. 172 4. Operation of the conversation function 174 If a conversation function has been registered with a GSSAPI credential, 175 it may be called during the original call to gss_acquire_cred_conv, or 176 when one of the following functions is called with the GSSAPI credential 177 with the conversation function: gss_init_sec_context(), 178 gss_accept_sec_context(), or gss_acquire_cred(). 180 The conversation function supplied by the application shall process each 181 entry in the gss_msg array in order. If the entry in the gss_msg array 182 is an informational or error text, the conversation function must 183 arrange to have the string displayed to the user. If the entry in the 184 gss_msg array is a prompt, the conversation function is responsible for 185 displaying the prompt and requesting input from the user, with echoing 186 enabled or disabled as appropriate. 188 The response from the user should be placed in the corresponding entry 189 in the gss_resp array, in a dynamically allocated gss_buffer_t. The 190 conversation function should not modify entries in the gss_resp array 191 which correspond to informative texts or error messages in the gss_msg 192 array. The GSSAPI library is responsible for freeing the dynamically 193 allocated buffers placed in the gss_resp array by the conversation func- 194 tion. These buffers should be freed before the GSSAPI function which 195 called the conversation function returns to the application program. 197 5. Security Considerations 199 This interfaces allows a GSSAPI library to ask the user for passwords 200 and other authentication information. It is the responsibility of 201 the calling application to zero any memory that might contain user 202 responses to prevent them from being exposed in case of a program 203 crash. 205 6. Author's Address 207 Theodore Ts'o 208 VA Linux Systems 209 43 Pleasant St. 210 Medford, MA 02155 212 Phone: (781) 391-3464 214 EMail: tytso@valinux.com