idnits 2.17.1 draft-ietf-kitten-gssapi-store-cred-03.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? -- It seems you're using the 'non-IETF stream' Licence Notice instead 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 : ---------------------------------------------------------------------------- ** 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.) 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 (December 30, 2008) is 5594 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: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 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 December 30, 2008 5 Expires: July 3, 2009 7 GSS-API Extension for Storing Delegated Credentials 8 draft-ietf-kitten-gssapi-store-cred-03.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 July 3, 2009. 33 Copyright Notice 35 Copyright (c) 2008 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 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. 45 Abstract 47 This document defines a new function for the GSS-API which allows 48 applications to store delegated (and other) credentials in the 49 implicit GSS-API credential store. This is needed for GSS-API 50 applications to use delegated credentials as they would use other 51 credentials. 53 Table of Contents 55 1. Intended Status (To Be Removed Upon Publication) . . . . . . . 3 56 2. Conventions used in this document . . . . . . . . . . . . . . 4 57 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 4. GSS_Store_cred() . . . . . . . . . . . . . . . . . . . . . . . 6 59 5. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . 8 60 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 61 7. Security considerations . . . . . . . . . . . . . . . . . . . 10 62 8. Normative References . . . . . . . . . . . . . . . . . . . . . 11 63 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 12 65 1. Intended Status (To Be Removed Upon Publication) 67 The intended status of this document is BCP. 69 2. Conventions used in this document 71 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 72 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 73 document are to be interpreted as described in [RFC2119]. 75 3. Introduction 77 The GSS-API [RFC2743] clearly assumes that credentials exist in an 78 implicit store whence they can be acquired using GSS_Acquire_cred() 79 and GSS_Add_cred() or through use of the default credential. 80 Multiple credential stores may exist on a given host, but only one 81 store may be accessed by GSS_Acquire_cred() and GSS_Add_cred() at any 82 given time. 84 This assumption can be seen in sections 1.1.1.2 and 1.1.1.3 of 85 [RFC2743] as well as in section 3.5 of [RFC2744]. 87 Applications may be able to change the credential store from which 88 credentials can be acquired, either by changing user contexts (where 89 the applications have the privilege to do so) or by other means 90 (where a user may have multiple credential stores). 92 Some GSS-API acceptor applications always change user contexts, after 93 accepting a GSS-API security context and making appropriate 94 authorization checks, to the user context corresponding to the 95 initiator principal name or to a context requested by the initiator. 96 The means by which credential stores are managed are generally beyond 97 the scope of the GSS-API. 99 In the case of delegated credential handles however, such credentials 100 do not exist in the acceptor's credential store or in the credential 101 stores of the user contexts to which the acceptor application might 102 change. The GSS-API provides no mechanism by which delegated 103 credential handles can be made available for acquisition through 104 GSS_Acquire_cred()/GSS_Add_cred(). The GSS-API also does not provide 105 any credential import/export interfaces like the GSS-API context 106 import/export interfaces. 108 Thus acceptors are limited to making only direct use of delegated 109 credential handles and only with GSS_Init_sec_context(), 110 GSS_Inquire_cred*() and GSS_Release_cred(). This limitation is 111 particularly onerous on Unix systems where a call to exec() to 112 replace the process image obliterates any delegated credentials 113 handle that may exist in that process. 115 In order to make delegated credentials generally as useful as 116 credentials that can be acquired with GSS_Acquire_cred() and 117 GSS_Add_cred() a primitive is needed which allows storing of 118 credentials in the implicit credential store. This primitive we call 119 "GSS_Store_cred()." 121 4. GSS_Store_cred() 123 Inputs: 125 o input_cred_handle CREDENTIAL HANDLE, -- credential to store; MUST 126 NOT be GSS_C_NO_CREDENTIAL 128 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 129 2=ACCEPT-ONLY 131 o desired_mech_element OBJECT IDENTIFIER, -- if GSS_C_NULL_OID then 132 store all the elements of the input_cred_handle, otherwise store 133 only the element of the corresponding mechanism 135 o overwrite_cred BOOLEAN, -- if TRUE replace any credential for the 136 same principal in the credential store 138 o default_cred BOOLEAN -- if TRUE make the stored credential 139 available as the default credential (for acquisition with 140 GSS_C_NO_NAME as the desired name or for use as 141 GSS_C_NO_CREDENTIAL) 143 Outputs: 145 o major_status INTEGER, 147 o minor_status INTEGER, 149 o mech_elements_stored SET OF OBJECT IDENTIFIER, -- the set of 150 mechanism OIDs for which credential elements were successfully 151 stored 153 o cred_usage_stored INTEGER -- like cred_usage, but indicates what 154 kind of credential was stored (useful when the cred_usage input 155 parameter is set to INITIATE-AND-ACCEPT) 157 Return major_status codes: 159 o GSS_S_COMPLETE indicates that the credentials were successfully 160 stored. 162 o GSS_S_CREDENTIALS_EXPIRED indicates that the input credentials had 163 expired or expired before they could be stored. 165 o GSS_S_NO_CRED indicates that no input credentials were given. 167 o GSS_S_UNAVAILABLE indicates that the credential store is not 168 available. 170 o GSS_S_DUPLICATE_ELEMENT indicates that an element of the input 171 credential could not be stored because a credential for the same 172 principal exists in the current credential store and the 173 overwrite_cred input argument was FALSE. 175 o GSS_S_FAILURE indicates that the credential could not be stored 176 for some other reason. The minor status code may provide more 177 information if a non-GSS_C_NULL_OID desired_mech_element was 178 given. 180 GSS_Store_cred() is used to store, in the current credential store, a 181 given credential that has either been acquired from a different 182 credential store or been accepted as a delegated credential. 184 Specific mechanism elements of a credential can be stored one at a 185 time by specifying a non-GSS_C_NULL_OID mechanism OID as the 186 desired_mech_element input argument, in which case the minor status 187 output SHOULD have a mechanism-specific value when the major status 188 is not GSS_S_COMPLETE. 190 The initiator, acceptor or both usages of the input credential may be 191 stored as per the cred_usage input argument. 193 The credential elements that were actually stored, when the major 194 status is GSS_S_COMPLETE, are indicated through the cred_usage_stored 195 and mech_elements_stored function outputs. 197 If credentials already exist in the current store for the principal 198 of the input_cred_handle, then those credentials are not replaced 199 with the input credentials unless the overwrite_cred input argument 200 is TRUE. 202 Finally, if the current credential store has no default credential 203 (that is, no credential that could be acquired for GSS_C_NO_NAME) or 204 if the default_cred input argument is TRUE, and the input credential 205 can be successfully stored, then the input credential will be 206 available for acquisition with GSS_C_NO_NAME as the desired name 207 input to GSS_Acquire_cred() or GSS_Add_cred() as well as for use as 208 GSS_C_NO_CREDENTIAL for the cred_handle inputs to GSS_Inquire_cred(), 209 GSS_Inquire_cred_by_mech(), GSS_Init_sec_context() and 210 GSS_Accept_sec_context(). 212 5. C-Bindings 214 The C-bindings for GSS_Store_cred() make use of types from and are 215 designed based on the style of the GSS-APIv2 C-Bindings [RFC2744]. 217 OM_uint32 gss_store_cred( 218 OM_uint32 *minor_status, 219 gss_cred_id_t input_cred_handle, 220 gss_cred_usage_t cred_usage, 221 const gss_OID desired_mech, 222 OM_uint32 overwrite_cred, 223 OM_uint32 default_cred, 224 gss_OID_set *elements_stored, 225 gss_cred_usage_t *cred_usage_stored) 227 Figure 1 229 The two boolean arguments, 'overwrite_cred' and 'default_cred' are 230 typed as OM_uint32; 0 corresponds to FALSE, non-zero values 231 correspond to TRUE. 233 6. Examples 235 The intended usage of GSS_Store_cred() is to make delegated 236 credentials available to child processes of GSS-API acceptor 237 applications. Example pseudo-code: 239 /* 240 * 243 * 244 * <"requested_username" is a username derived from the 245 * initiator name or explicitly requested by the initiator 246 * application.> 247 */ 248 ... 250 if (authorize_gss_client(src_name, requested_username)) { 251 /* 252 * For Unix-type platforms this may mean calling setuid() and 253 * it may or may not also mean setting/unsetting such 254 * environment variables as KRB5CCNAME and what not -- all 255 * OS-specific details. 256 */ 257 if (change_user_context(requested_username)) 258 (void) gss_store_creds(&minor_status, deleg_cred, 259 GSS_C_INITIATE, actual_mech, 260 0, 1, NULL, NULL); 261 } 262 else ... 263 } 264 else ... 266 7. Security considerations 268 Acceptor applications MUST only store delegated credentials into 269 appropriate credential stores and only after proper authorization of 270 the authenticated initiator principal to the requested service(s). 272 Acceptor applications that have no use for delegated credentials MUST 273 release them (such acceptor applications that use the GSS-API 274 C-Bindings may simply provide a NULL value for the 275 delegated_cred_handle argument to gss_accept_sec_context()). 277 8. Normative References 279 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 280 Requirement Levels", BCP 14, RFC 2119, March 1997. 282 [RFC2743] Linn, J., "Generic Security Service Application Program 283 Interface Version 2, Update 1", RFC 2743, January 2000. 285 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 286 C-bindings", RFC 2744, January 2000. 288 Author's Address 290 Nicolas Williams 291 Sun Microsystems 292 5300 Riata Trace Ct 293 Austin, TX 78727 294 US 296 Email: Nicolas.Williams@sun.com