idnits 2.17.1 draft-ietf-kitten-gssapi-store-cred-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- 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 (March 9, 2009) is 5489 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: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETWORK WORKING GROUP N. Williams 3 Internet-Draft Sun 4 Intended status: Standards Track March 9, 2009 5 Expires: September 10, 2009 7 GSS-API Extension for Storing Delegated Credentials 8 draft-ietf-kitten-gssapi-store-cred-04.txt 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on September 10, 2009. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This document defines a new function for the GSS-API which allows 47 applications to store delegated (and other) credentials in the 48 implicit GSS-API credential store. This is needed for GSS-API 49 applications to use delegated credentials as they would use other 50 credentials. 52 Table of Contents 54 1. Conventions used in this document . . . . . . . . . . . . . . 3 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 3. GSS_Store_cred() . . . . . . . . . . . . . . . . . . . . . . . 5 57 4. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 9 60 7. Security considerations . . . . . . . . . . . . . . . . . . . 10 61 8. Normative References . . . . . . . . . . . . . . . . . . . . . 11 62 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 12 64 1. Conventions used in this document 66 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 67 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 68 document are to be interpreted as described in [RFC2119]. 70 2. Introduction 72 The GSS-API [RFC2743] clearly assumes that credentials exist in an 73 implicit store whence they can be acquired using GSS_Acquire_cred() 74 and GSS_Add_cred() or through use of the default credential. 75 Multiple credential stores may exist on a given host, but only one 76 store may be accessed by GSS_Acquire_cred() and GSS_Add_cred() at any 77 given time. 79 This assumption can be seen in sections 1.1.1.2 and 1.1.1.3 of 80 [RFC2743] as well as in section 3.5 of [RFC2744]. 82 Applications may be able to change the credential store from which 83 credentials can be acquired, either by changing user contexts (where 84 the applications have the privilege to do so) or by other means 85 (where a user may have multiple credential stores). 87 Some GSS-API acceptor applications always change user contexts, after 88 accepting a GSS-API security context and making appropriate 89 authorization checks, to the user context corresponding to the 90 initiator principal name or to a context requested by the initiator. 91 The means by which credential stores are managed are generally beyond 92 the scope of the GSS-API. 94 In the case of delegated credential handles however, such credentials 95 do not exist in the acceptor's credential store or in the credential 96 stores of the user contexts to which the acceptor application might 97 change. The GSS-API provides no mechanism by which delegated 98 credential handles can be made available for acquisition through 99 GSS_Acquire_cred()/GSS_Add_cred(). The GSS-API also does not provide 100 any credential import/export interfaces like the GSS-API context 101 import/export interfaces. 103 Thus acceptors are limited to making only direct use of delegated 104 credential handles and only with GSS_Init_sec_context(), 105 GSS_Inquire_cred*() and GSS_Release_cred(). This limitation is 106 particularly onerous on Unix systems where a call to exec() to 107 replace the process image obliterates any delegated credentials 108 handle that may exist in that process. 110 In order to make delegated credentials generally as useful as 111 credentials that can be acquired with GSS_Acquire_cred() and 112 GSS_Add_cred() a primitive is needed which allows storing of 113 credentials in the implicit credential store. This primitive we call 114 "GSS_Store_cred()." 116 3. GSS_Store_cred() 118 Inputs: 120 o input_cred_handle CREDENTIAL HANDLE, -- credential to store; MUST 121 NOT be GSS_C_NO_CREDENTIAL 123 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 124 2=ACCEPT-ONLY 126 o desired_mech_element OBJECT IDENTIFIER, -- if GSS_C_NULL_OID then 127 store all the elements of the input_cred_handle, otherwise store 128 only the element of the corresponding mechanism 130 o overwrite_cred BOOLEAN, -- if TRUE replace any credential for the 131 same principal in the credential store 133 o default_cred BOOLEAN -- if TRUE make the stored credential 134 available as the default credential (for acquisition with 135 GSS_C_NO_NAME as the desired name or for use as 136 GSS_C_NO_CREDENTIAL) 138 Outputs: 140 o major_status INTEGER, 142 o minor_status INTEGER, 144 o mech_elements_stored SET OF OBJECT IDENTIFIER, -- the set of 145 mechanism OIDs for which credential elements were successfully 146 stored 148 o cred_usage_stored INTEGER -- like cred_usage, but indicates what 149 kind of credential was stored (useful when the cred_usage input 150 parameter is set to INITIATE-AND-ACCEPT) 152 Return major_status codes: 154 o GSS_S_COMPLETE indicates that the credentials were successfully 155 stored. 157 o GSS_S_CREDENTIALS_EXPIRED indicates that the input credentials had 158 expired or expired before they could be stored. 160 o GSS_S_NO_CRED indicates that no input credentials were given. 162 o GSS_S_UNAVAILABLE indicates that the credential store is not 163 available. 165 o GSS_S_DUPLICATE_ELEMENT indicates that an element of the input 166 credential could not be stored because a credential for the same 167 principal exists in the current credential store and the 168 overwrite_cred input argument was FALSE. 170 o GSS_S_FAILURE indicates that the credential could not be stored 171 for some other reason. The minor status code may provide more 172 information if a non-GSS_C_NULL_OID desired_mech_element was 173 given. 175 GSS_Store_cred() is used to store, in the current credential store, a 176 given credential that has either been acquired from a different 177 credential store or been accepted as a delegated credential. 179 Specific mechanism elements of a credential can be stored one at a 180 time by specifying a non-GSS_C_NULL_OID mechanism OID as the 181 desired_mech_element input argument, in which case the minor status 182 output SHOULD have a mechanism-specific value when the major status 183 is not GSS_S_COMPLETE. 185 The initiator, acceptor or both usages of the input credential may be 186 stored as per the cred_usage input argument. 188 The credential elements that were actually stored, when the major 189 status is GSS_S_COMPLETE, are indicated through the cred_usage_stored 190 and mech_elements_stored function outputs. 192 If credentials already exist in the current store for the principal 193 of the input_cred_handle, then those credentials are not replaced 194 with the input credentials unless the overwrite_cred input argument 195 is TRUE. 197 Finally, if the current credential store has no default credential 198 (that is, no credential that could be acquired for GSS_C_NO_NAME) or 199 if the default_cred input argument is TRUE, and the input credential 200 can be successfully stored, then the input credential will be 201 available for acquisition with GSS_C_NO_NAME as the desired name 202 input to GSS_Acquire_cred() or GSS_Add_cred() as well as for use as 203 GSS_C_NO_CREDENTIAL for the cred_handle inputs to GSS_Inquire_cred(), 204 GSS_Inquire_cred_by_mech(), GSS_Init_sec_context() and 205 GSS_Accept_sec_context(). 207 4. C-Bindings 209 The C-bindings for GSS_Store_cred() make use of types from and are 210 designed based on the style of the GSS-APIv2 C-Bindings [RFC2744]. 212 OM_uint32 gss_store_cred( 213 OM_uint32 *minor_status, 214 gss_cred_id_t input_cred_handle, 215 gss_cred_usage_t cred_usage, 216 const gss_OID desired_mech, 217 OM_uint32 overwrite_cred, 218 OM_uint32 default_cred, 219 gss_OID_set *elements_stored, 220 gss_cred_usage_t *cred_usage_stored) 222 Figure 1 224 The two boolean arguments, 'overwrite_cred' and 'default_cred' are 225 typed as OM_uint32; 0 corresponds to FALSE, non-zero values 226 correspond to TRUE. 228 5. Examples 230 The intended usage of GSS_Store_cred() is to make delegated 231 credentials available to child processes of GSS-API acceptor 232 applications. Example pseudo-code: 234 /* 235 * 238 * 239 * <"requested_username" is a username derived from the 240 * initiator name or explicitly requested by the initiator 241 * application.> 242 */ 243 ... 245 if (authorize_gss_client(src_name, requested_username)) { 246 /* 247 * For Unix-type platforms this may mean calling setuid() and 248 * it may or may not also mean setting/unsetting such 249 * environment variables as KRB5CCNAME and what not -- all 250 * OS-specific details. 251 */ 252 if (change_user_context(requested_username)) 253 (void) gss_store_creds(&minor_status, deleg_cred, 254 GSS_C_INITIATE, actual_mech, 255 0, 1, NULL, NULL); 256 } 257 else ... 258 } 259 else ... 261 6. IANA considerations 263 There are no IANA considerations in this document. 265 7. Security considerations 267 Acceptor applications MUST only store delegated credentials into 268 appropriate credential stores and only after proper authorization of 269 the authenticated initiator principal to the requested service(s). 271 Acceptor applications that have no use for delegated credentials MUST 272 release them (such acceptor applications that use the GSS-API 273 C-Bindings may simply provide a NULL value for the 274 delegated_cred_handle argument to gss_accept_sec_context()). 276 8. Normative References 278 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 279 Requirement Levels", BCP 14, RFC 2119, March 1997. 281 [RFC2743] Linn, J., "Generic Security Service Application Program 282 Interface Version 2, Update 1", RFC 2743, January 2000. 284 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 285 C-bindings", RFC 2744, January 2000. 287 Author's Address 289 Nicolas Williams 290 Sun Microsystems 291 5300 Riata Trace Ct 292 Austin, TX 78727 293 US 295 Email: Nicolas.Williams@sun.com