idnits 2.17.1 draft-ietf-cat-xgssapi-acc-cntrl-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-16) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == There are 6 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 23 longer pages, the longest (page 13) being 61 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 24 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.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 63: '...uthority OCTET STRING OPTIONAL,...' RFC 2119 keyword, line 217: '...3.4.2.4. OPTIONAL RESTRICTIONS...' RFC 2119 keyword, line 643: '... SEQUENCE OF SecAttribute OPTIONAL,...' RFC 2119 keyword, line 644: '... SEQUENCE OF SecAttribute OPTIONAL,...' RFC 2119 keyword, line 645: '... SEQUENCE OF SecAttribute OPTIONAL,...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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 (November 09, 1998) is 9290 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) == Missing Reference: 'RFC-1508' is mentioned on line 876, but not defined ** Obsolete undefined reference: RFC 1508 (Obsoleted by RFC 2078) == Unused Reference: 'RFC 1508' is defined on line 1108, but no explicit reference was found in the text == Unused Reference: 'RFC 1509' is defined on line 1111, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1508 (Obsoleted by RFC 2078) ** Obsolete normative reference: RFC 1509 (Obsoleted by RFC 2744) Summary: 15 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft 2 Tom Parker , ICL 3 Denis Pinkas , Bull 4 IETF Common Authentication Technology WG 5 November 09, 1998 7 Extended Generic Security Service APIs: XGSS-APIs 8 Access control and delegation extensions 10 1. STATUS OF THIS MEMO 12 This document is an Internet Draft. Internet Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its Areas, 14 and its Working Groups. Note that other groups may also distribute 15 working documents as Internet Drafts. Internet Drafts are draft 16 documents valid for a maximum of six months. Internet Drafts may be 17 updated, replaced, or obsoleted by other documents at any time. It 18 is not appropriate to use Internet Drafts as reference material or 19 to cite them other than as a "working draft" or "work in progress." 20 Please check the I-D abstract listing contained in each Internet 21 Draft directory to learn the current status of this or any other 22 Internet Draft. 24 Comments on this document should be sent to "cat-ietf@MIT.EDU", the 25 IETF Common Authentication Technology WG discussion list. 27 2. ABSTRACT 29 The Generic Security Service Application Program Interface (GSS- 30 API), as defined in RFC-1508, provides security services to callers 31 in a generic fashion, supportable with a range of underlying 32 mechanisms and technologies and hence allowing source-level 33 portability of applications to different environments. It defines 34 GSS-API services and primitives at a level independent of underlying 35 mechanism and programming language environment. 37 The GSSAPI allows a caller application to authenticate a principal 38 identity associated with a peer application, to delegate rights to a 39 peer, and to apply security services such as confidentiality and 40 integrity on a per-message basis. 42 The primitives of the GSS-API do not currently allow support of 43 security attributes other than a single identity and do not allow 44 fine control of delegation. 46 The additional primitives described in this document provide support 47 for: 49 * the exchange of a variety of security attributes, and the 50 construction of authorization functions using these attributes, 51 including delegated ones, (attribute handling support functions), 52 * fine control over delegation by allowing specification of the 53 delegation method, the acceptor(s) of a security context, their type 54 and the restrictions that may apply (acceptor control and support 55 functions). 57 3. SECURITY ATTRIBUTES 59 A security attribute is defined as: 61 SecAttribute ::= { 62 attributeType OBJECT IDENTIFIER, 63 definingAuthority OCTET STRING OPTIONAL, 64 securityValue OCTET STRING } 66 attributeType 68 Defines the type of the attribute. Attributes of the same type 69 have the same authorization semantics. 71 definingAuthority 73 It indicates the authority responsible for defining the value 74 within the attribute type. Some policies demand that multiple 75 sources of values for a given attribute type be supported (e.g. a 76 policy accepting attribute values defined outside the security 77 domain), These policies give rise to a risk of value clashes. The 78 definingAuthority field is used to separate these values. When not 79 present, the value defaults to the name of the authority that 80 issued the attribute. 82 securityValue 84 The value of the security attribute. Its syntax is determined by 85 the attribute type. 87 Security attributes are composed of principal attributes and of 88 qualifier attributes. 90 3.1. PRINCIPAL ATTRIBUTES 92 Principal attributes are composed of security privileges and 93 miscellaneous attributes. 95 3.1.1. PRIVILEGES ATTRIBUTES 97 Security privileges are defined as security attributes attached to a 98 principal, and only usable for access control purposes. Ones defined 99 here are: access identity, group memberships, clearance and 100 capability. The use of OBJECT IDENTIFIERS allows for other types to 101 be standardised. 103 3.1.2. MISCELLANEOUS ATTRIBUTES 105 Miscellaneous attributes are defined as security attributes attached 106 to a principal, which are not security privileges. They are used for 107 a variety of purposes. Ones defined here are: the domain name of the 108 issuer of the security attributes, an audit identity, restrictions 109 and validity time periods. 111 3.2. QUALIFIER ATTRIBUTES 113 Qualifier attributes describe the context acceptors for which 114 controls are to apply. Ones defined here are: acceptor name and 115 application trust group. 117 3.3. ATTRIBUTES DEFINITIONS 119 3.3.1. PRIVILEGE ATTRIBUTES 121 A privilege attribute is attached to a principal and is only usable 122 for access control purposes. Privileges are defined under the OID: 124 privilege-attribute OBJECT IDENTIFIER ::= 125 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 126 security-in-open-systems(046) privilege-attribute(4) } 128 3.3.1.1. ROLE ATTRIBUTE 130 The role attribute represents the principal's role. The type of this 131 attribute is: 133 { privilege-attribute 1 } 135 The type and the value of this attribute can be set and returned. 137 3.4.1.2. ACCESS IDENTITY 139 The access identity represents an identity to be used for access 140 control purposes. A security context or a credential may not contain 141 more than a single access identity for a given principal. This attri- 142 bute does not need to be present. The type of this attribute is : 144 { privilege-attribute 2 } 146 The type and the value of this attribute can be set and returned. 148 3.4.1.3. PRIMARY GROUP 150 The primary group represents a uniquely prominent group to which a 151 principal belongs. A security context or a credential may not 152 contain more than one primary group for a given principal. The type 153 of this attribute is : 155 { privilege-attribute 3 } 156 The type and the value of this attribute can be set and returned. 158 3.4.1.4. GROUP 160 A group represents a characteristic common to several principals. 161 A security context or a credential may contain more than one group 162 for a given principal. The type of this attribute is : 164 { privilege-attribute 4 } 166 The type and the value of this attribute can be set and returned. 168 3.4.1.5. CAPABILITY 170 A capability nominates a resource and the operation(s) that can be 171 performed on that resource. The type of this attribute is : 173 { privilege-attribute 5 } 175 The type and the value of this attribute can be set and returned. 177 3.3.2. MISCELLANEOUS ATTRIBUTES 179 Miscellaneous attributes are defined under the OID: 181 misc-attributeOBJECT IDENTIFIER ::= 182 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 183 security-in-open-systems(046) misc-attribute(3) } 185 3.4.2.1. AUDIT IDENTITY 187 The access identity represents the principal's identity to be used 188 for audit purposes. The type of this attribute is : 190 { misc-attribute 2 } 192 Only the type of this attribute can be set and both the type and the 193 value can be returned. 195 3.4.2.2. ISSUER DOMAIN NAME 197 The issuer domain name represents the name of the domain that has 198 issued the security attributes. It cannot be set by a call to 199 GSS_Set_cred_attributes. The type of this attribute is : 201 { misc-attribute 10 } 203 Only the type of this attribute can be set and both the type and the 204 value can be returned. This attribute may always be returned by a 205 call to GSS_Get_cred_attributes. 207 3.4.2.3. VALIDITY PERIODS 209 The validity periods represent a list of the time periods within 210 which the security attributes are valid. The type of this attribute 211 is : 213 { misc-attribute 11 } 215 The type and the values of this attribute can be set and returned. 217 3.4.2.4. OPTIONAL RESTRICTIONS 219 The Optional restrictions represent restrictions that apply to the 220 security context. The context may be accepted, even if the 221 application is unable to understand the optional restrictions. 222 The type of this attribute is : 224 { misc-attribute 12 } 226 The type and the values of this attribute can be set and returned. 228 3.4.2.5. MANDATORY RESTRICTIONS 230 The mandatory restrictions represent restrictions that apply to the 231 security context. The context must not be accepted if the 232 application is unable to understand the mandatory restrictions. The 233 type of this attribute is : 235 { misc-attribute 13 } 237 The type and the values of this attribute can be set and returned. 239 3.3.3. QUALIFIER ATTRIBUTES 241 Qualifier attributes are security attributes which define which 242 applications are authorized to be a security context acceptor. In 243 addition to the qualifier attribute it is possible to specify 244 whether delegation is authorized or not for the context acceptor. 246 Qualifier attributes describe the context acceptors for which 247 controls are to apply. Qualifier attributes are defined under the 248 OID: 250 qualifier-attribute OBJECT IDENTIFIER ::= 251 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 252 security-in-open-systems(046) qualifier-attribute(5) } 254 3.4.3.1. ACCEPTOR NAME 256 An acceptor name represents the name of an application that can 257 potentially accept the security context. The type of this attribute 258 is : 260 { qualifier-attribute 1 } 262 3.4.3.2. APPLICATION TRUST GROUP 264 An application trust group represents a group of acceptors, defined 265 by the security administrator, that mutually trust each other not to 266 spoof each others' identity. The type of this attribute is : 268 { qualifier-attribute 2 } 270 4. ATTRIBUTE SET REFERENCE 272 Attribute set references are defined under the OID: 274 attribute-set-reference OBJECT IDENTIFIER ::= 275 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 276 security-in-open-systems(046) attribute-set-reference (9) 278 An Attribute set reference is used to select a set of security 279 attributes and acceptor controls according to policy. At present 280 only a role name is defined. 282 4.1. ROLE NAME 284 The role name is an attribute set reference used to select a set of 285 security attributes. The type of this attribute is : 287 { attribute-set-reference 1 } 289 The type and the values of this reference can only be set. 291 6. INTERFACE DESCRIPTIONS 293 The interfaces are split between attribute handling support 294 functions and context acceptor control and support functions. 296 6.1. ATTRIBUTE HANDLING SUPPORT FUNCTIONS 298 Three attribute handling support functions are defined : 300 6.1.1. GSS_Set_cred_attributes 302 To enable a GSS-API context initiator to specify security 303 attributes, i.e. security privileges and miscellaneous security 304 attributes to be included in the caller credentials in order to 305 become part of a security context. 307 6.1.2. GSS_Get_sec_attributes 309 To extract security attributes, either from a GSS-API context, or 310 from a credential handle. Both privilege attributes and 311 miscellaneous attributes can be retrieved. The function can be 312 invoked either by a context initiator or by a context acceptor. When 313 applied to a GSS-API context and invoked by a context acceptor, if 314 delegation is being used, the privilege and miscellaneous attributes 315 which are returned and only those of the initiator, i.e. the 316 initiator of the delegation chain. 318 6.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 320 There is a single function. 322 6.2.1. GSS_Get_received_creds 324 To extract credential handles from a GSS-API context (established 325 with GSS_Accept_sec_context function). This is only applicable for 326 some forms of delegation supporting multiple incoming credentials, 327 and can only be invoked by a context acceptor. A call to 328 GSS_Get_received_creds is an intermediary step for an acceptor, 329 before extracting the security attributes of each set of credentials 330 with a call to GSS_Get_sec_attributes. The credential handles are 331 ordered. They start with the credentials of the first initiator and 332 finish with the the credentials of the immediate invoker. 334 6.3. CONTEXT ACCEPTOR CONTROL FUNCTIONS 336 These functions enable a GSS-API context initiator to impose 337 constraints on the security context to be established via 338 GSS_Init_sec_context function, and enable a GSS-API context acceptor 339 to retrieve the control information that applies to a security 340 context established using the GSS_Accept_sec_context function, and 341 to build credentials from others. 343 Three context acceptor control functions are defined: 345 6.3.1. GSS_Set_cred_controls function 347 To enable a GSS-API context initiator to specify acceptor controls 348 to be included in the caller's credentials in order to be part of a 349 security context. The controls determine the context acceptors with 350 which valid security contexts can be established using the 351 associated credentials, and whether they can act only as targets 352 only, delegates only as or as delegate/targets. 354 * an acceptor designated as being a target only may use the 355 privileges attributes in the received credentials when authorising 356 access to its own protected resources and may not forward them. 358 * an acceptor designated as being a delegate only may use the 359 privilege attributes in the received credentials to forward them 360 but should not use them when authorising access to its own 361 protected resources. 363 Note: Only the acceptor system's AEF (Access Enforcement 364 Facility as described in ISO/IEC 10181-3: The Access Control 365 Framework) can prevent an acceptor permitting access based on 366 attributes not intended for it. However it is not in the 367 interests of an acceptor or its AEF to permit access to 368 resources under their control on the basis of attributes that 369 are explicitly stated as not being appropriate. 371 * an acceptor designated as being both a target and a delegate may 372 use the privilege attributes in the received credentials when 373 authorising access to its own protected resources and may also 374 forward them. 376 Restrictions over the operations that are authorised under the 377 context can also be specified. 379 6.3.2. GSS_Get_sec_controls function 381 To enable a GSS-API context initiator or a GSS-API context acceptor 382 to extract acceptor control information either from a credential 383 handle or from a security context. 385 6.3.3. GSS_Compound_creds function 387 To enable a delegate (which is acting as a GSS-API target for a 388 context initiator, and as a GSS-API context initiator for another 389 delegate or target) to build new credentials made from received 390 credentials and its own credentials. 392 7. DETAILED DESCRIPTION OF THE CALLS 394 7.1. ATTRIBUTE HANDLING CALLS 396 7.1.1. GSS_Set_cred_attributes call 398 Input : 400 - cred_handle OCTET STRING, 401 - required_attributes SET OF SecAttribute, 402 - new_cred_req BOOLEAN 403 - commit_cred_req BOOLEAN 405 Output : 407 - output_cred_handle OCTET STRING 409 Return major_status code: 411 - GSS_S_COMPLETE indicates that the nominated 412 attributes are permitted to 413 the caller and have been set. 414 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 415 credentials have expired. 416 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 417 credentials have been detected. 418 - GSS_S_FAILURE indicates a failure,unspecified 419 at the GSS-API level. 421 - GSS_S_UNAUTHORIZED indicates that the function, or 422 an argument of the function was 423 not authorised. 424 - GSS_S_UNAVAILABLE indicates that the operation is 425 not supported. 427 This function enables a caller to request a set of privileges and 428 miscellaneous attributes, optionally replacing existing credentials 429 or creating a new set. The effect of this interface is not 430 cumulative, the requested attributes replace any existing attributes 431 in the credentials claimed. 433 Parameters for GSS_Set_cred_attributes: 435 cred_handle 437 Handle for credentials claimed, cred_handle refers to an 438 authenticated principal. Supply NULL to use default credentials. 440 required_attributes 442 A set of required privilege and miscellaneous attributes. NULL 443 specifies default attributes to be requested. Otherwise, only the 444 privilege and miscellaneous attributes specified will be present. 446 If a specified attribute is provided with a NULL value field, the 447 value allocated to the attribute will be the default for the 448 specified attribute available to the authenticated principal 449 according to the prevailing security policy. Otherwise the value 450 specified will be that present. If a value specified clashes with 451 policy, an error is returned. 453 If an attribute set reference (e.g.a role name) is specified as a 454 single attribute required, and policy permits the principal to use 455 it, it will be used as an attribute set reference to select a set of 456 attributes and acceptor controls according to policy. 458 If an attribute set reference (e.g.a role name) is specified along 459 with other required attributes, and policy permits the principal to 460 use the role name, the attributes potentially available for the 461 authenticated principal are taken from a set compounded of the 462 principal's authorised attributes, and the attributes associated 463 with the role name. 465 new_cred_req 467 TRUE for a new credentials set, FALSE replaces the original. 469 commit_cred_req 471 TRUE for immediate attribute acquisition, FALSE for deferred 472 attribute acquisition. 474 output_cred_handle 476 The credentials handle for the changed or new credentials. 477 GSS_Set_cred_attributes produces a modified version of the input 478 credentials (cred_handle). The original credentials are changed if 479 new_cred_req is FALSE, otherwise the output_cred_handle references a 480 new, and different, copy of the original input credentials (which 481 remain untouched). GSS_Release_cred can be used when the caller is 482 finished with any new credentials created by this function. 484 7.1.2. GSS_Get_sec_attributes call 486 Input : 488 - cred_handle OCTET STRING, 489 - context_handle INTEGER, 490 - attribute_types_required SET OF OBJECT IDENTIFIER 492 Output : 494 - priv_attributes SET OF SecAttribute 495 - misc_attributes SET OF SecAttribute 496 - other_cred_present BOOLEAN 498 Return major_status code : 500 - GSS_S_COMPLETE indicates that retrieval of 501 attributes is supported and 502 that all, some, or none of the 503 requested attribute types have 504 been returned. 505 - GSS_S_CONTEXT_EXPIRED indicates that the specified 506 security 507 context has expired. 508 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 509 credentials have expired. 510 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 511 credentials have been detected. 512 - GSS_S_FAILURE indicates a failure, 513 unspecified at the GSS-API 514 level. 515 - GSS_S_UNAVAILABLE indicates that the operation is 516 not supported. 518 This function can be used by context initiators and context 519 acceptors to query attributes in credentials or security contexts. 520 If the credentials or security context represents a delegation 521 chain, attributes are retrieved only from the initiator of the 522 chain. If the attribute_types_required parameter is not supplied, 523 then all attribute types are returned. This option could allow 524 clients of this interface to query all attributes and pass privilege 525 attributes to a separate authorization service to make a decision. 527 To obtain security attributes from intermediates in a delegation 528 chain, the caller should first call GSS_Get_received_creds (see 529 section 5.2.1 and section 6.2.1). 531 Parameters for GSS_Get_sec_attributes: 533 cred_handle 535 Handle to credentials, cred_handle refers to an authenticated 536 principal. Supply NULL to use default credentials, or a context 537 handle. Note that NULL, without a context handle, is only used for 538 obtaining the caller's own attributes. 540 context_handle 542 GSS-API security context handle, context_handle refers to an 543 established security context. Context_handle is ignored if a non- 544 NULL cred_handle is presented. (Note: it is typically only necessary 545 to use a context_handle parameter rather than cred_handle for the 546 case when a security context is emitted by gss_accept_sec_context, 547 but not with an accompanying set of delegated credentials). 549 attribute_types_required 551 A set of security attribute types. If the default (NULL) is 552 specified, then all miscellaneous and privilege attribute types are 553 returned. 555 This standard does not specify which attributes must be supported, 556 but some common security attributes are defined in section 2. 558 priv_attributes 560 A set of privilege attributes. Response is conditional on the 561 "attribute_types_required" input. 563 misc_attributes 565 A set of miscellaneous attributes. Response is conditional on the 566 "attribute_types_required" input. 568 other_cred_present 570 TRUE when the caller is a context acceptor querying a security 571 context and when more than one set of credentials is present. If 572 interested in the other credential(s), the caller should next call 573 GSS_Get_received_creds, 575 FALSE when either the caller is a context initiator or when the 576 caller is a context acceptor querying a security context and when no 577 other credential is present. 579 7.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 580 7.2.1. GSS_Get_received_creds call 582 Input : 584 - context_handle INTEGER, 586 Output : 588 - received_creds SEQUENCE OF OCTET STRING 590 Return major_status code : 592 - GSS_S_COMPLETE indicates that the requested 593 delegate 594 credentials were retrieved. 595 - GSS_S_CONTEXT_EXPIRED indicates that the specified 596 security 597 context has expired. 598 - GSS_S_FAILURE indicates a failure, 599 unspecified at the GSS-API 600 level. 601 - GSS_S_UNAUTHORIZED indicates that the function, or 602 an argument of the function was 603 not authorised. 604 - GSS_S_UNAVAILABLE indicates that the operation is 605 not supported. 607 This function supports the retrieval of all credentials received by 608 an acceptor. It is intended for context acceptors that require not 609 only the initiator's credentials, but also delegates' credentials, 610 to apply their local security policy. A typical example is the 611 retrieval of delegate credentials to subsequently obtain delegate 612 privilege attributes (using GSS_Get_sec_attributes) for use in 613 authorization decisions. 615 Parameters for GSS_Get_received_creds: 617 context_handle 619 GSS-API security context handle, context_handle refers to a security 620 context that is part of an established association. A default 621 context is assumed if no context_handle is supplied. 623 received_creds 625 Contains an ordered list of credentials for the original initiator 626 and for each of the intermediate delegates (if any) between the 627 original initiator and this context acceptor, the first of these 628 being the credentials of the original initiator, and the last being 629 of the immediately preceding delegate. It is expected that the 630 normal use for such credentials would merely be inspection via 631 GSS_Get_sec_attributes as most known mechanisms would not permit 632 such delegate credentials to be directly used for initiating further 633 security contexts. Note that it is the caller's responsibility to 634 free any received credentials returned from gss_get_received_creds 635 via gss_release_cred. 637 7.3. ACCEPTOR CONTROL HANDLING CALLS 639 The following construct is used in both the GSS_Set_cred_controls 640 and GSS_Get_sec_controls calls: 642 AcceptorControl ::= SEQUENCE { 643 targetOnly SEQUENCE OF SecAttribute OPTIONAL, 644 delegateOnly SEQUENCE OF SecAttribute OPTIONAL, 645 delegateTarget SEQUENCE OF SecAttribute OPTIONAL, 646 delegationMode DelegationMode OPTIONAL,} 648 DelegationMode ::= ENUMERATED { 649 default (0), 650 simple (1), 651 composite (2), 652 traced (3),} 654 The fields targetOnly, delegateOnly and delegateTarget specify one 655 or several qualifier attributes describing the acceptors (as 656 targets, delegates or delegate/targets) for which controls are to 657 apply. 659 * the targetOnly specifies that the qualifier(s) are identifying 660 one or more targets, none of which may use the credentials as a 661 delegate. 663 * the delegateOnly choice specifies that the qualifier(s) are 664 identifying one or more delegates, none of which should use the 665 privilege attributes in the credentials when authorising access to 666 their own protected resources, but which may use the received 667 credentials as a delegate. 669 * the delegateTarget choice specifies that the qualifier is 670 identifying one or more delegate/targets any of which can use the 671 received credentials as a delegate and can also use the privileges 672 attributes in the the credentials when authorising access to its 673 own protected resources. 675 delegationMode 677 Indicates the mode of delegation required. 679 Currently three delegation modes and one default are specified: 681 - default: whatever mode of delegation has been set as default (this 682 may be no delegation). 684 - simple: only the original initiator's credentials have to be 685 forwarded in the security context being established, 687 - composite: the credentials of the original initiator and of the 688 immediate caller have to be forwarded, 690 - traced: the credentials of the original initiator, of all the 691 delegates, including the immediate caller have to be forwarded. 693 7.3.1. GSS_Set_cred_controls call 695 Input : 697 - cred_handle OCTET STRING, 698 - required_acceptor_control AcceptorControl, 699 - replace_old_controls BOOLEAN 700 - new_cred_req BOOLEAN 701 - commit_cred_req BOOLEAN 703 Output : 705 - output_cred_handle OCTET STRING 707 Return major_status code: 709 - GSS_S_COMPLETE indicates that the controls 710 have been set. 711 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 712 credentials have expired. 713 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 714 credentials have been detected. 715 - GSS_S_FAILURE indicates a failure, 716 unspecified at the GSS-API 717 level. 718 - GSS_S_UNAUTHORIZED indicates that the function, or 719 an argument of the function was 720 not authorised. 721 - GSS_S_UNAVAILABLE indicates that the operation is 722 not supported. 724 This function supports requests to set context acceptor controls, 725 optionally replacing existing credentials controls or creating a new 726 set of credentials with new controls. The effect of this interface 727 is either cumulative or not depending on the value of the 728 replace_old_controls parameter. 730 Parameters for GSS_Set_cred_controls: 732 cred_handle 734 Handle for credentials claimed, it refers to an authenticated 735 principal. Supply NULL to use default credentials. 737 required_acceptor_control 739 The control settings required. 741 replace_old_controls 743 TRUE to replace acceptor controls existing in original credentials. 744 FALSE to specify additional controls. 746 new_cred_req 748 TRUE for a new credentials set, FALSE to modify the original. 750 commit_cred_req 752 TRUE for immediate action, FALSE for deferred action. 754 output_cred_handle 756 GSS_Set_cred_controls produces a modified version of the input 757 credentials (cred_handle). The original credentials are directly 758 changed if duplicate_cred_req is FALSE, otherwise the 759 output_cred_handle references a new, and potentially different, copy 760 of the original input credentials (which remain untouched). 761 gss_release_cred can be used when the caller is finished with any 762 new credentials created by this function. 764 7.3.2. GSS_Get_sec_controls call 766 Input : 768 - cred_handle OCTET STRING, 769 - context_handle INTEGER, 771 Output : 773 - acceptor_controls SET OF AcceptorControl, 775 Return major_status code : 777 - GSS_S_COMPLETE indicates that the acceptor 778 control 779 information has been returned 780 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 781 credentials have expired. 782 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 783 credentials have been detected. 784 - GSS_S_FAILURE indicates a failure, 785 unspecified at the GSS-API 786 level. 787 - GSS_S_UNAVAILABLE indicates that the operation is 788 not supported. 790 This function enables a caller to enquire the current value of the 791 acceptor controls in the specified credentials or context. 792 This function can be used by context initiators and context 793 acceptors to query acceptor controls in credentials or security 794 contexts. 796 Parameters for GSS_Get_sec_controls: 798 cred_handle 800 Handle to credentials. It refers to an authenticated principal. 801 Supply NULL to use default credentials, or a context handle. 803 context_handle 805 GSS-API security context handle, context_handle refers to a security 806 context that is part of an established association. Context_handle 807 is ignored if a non-NULL cred_handle is presented. (Note: it is 808 typically only necessary to use a context_handle parameter rather 809 than cred_handle for the case when a security context is emitted by 810 gss_accept_sec_context, but not with an accompanying set of 811 delegated credentials). 813 acceptor_controls 815 A set of acceptor controls. Acceptor controls are described in 816 section 6.2. 818 7.3.3. GSS_Compound_creds call 820 Input : 822 - delegated_cred_handle OCTET STRING 823 - cred_handle OCTET STRING, 825 Output : 827 - cred_handle_new OCTET STRING 829 Return major_status code : 831 GSS_S_COMPLETE indicates that the credentials 832 were successfully compounded 833 - GSS_S_CREDENTIALS_EXPIRED indicates that one or more of 834 the specified credentials have 835 expired. 836 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 837 credentials have been detected. 838 - GSS_S_FAILURE indicates a failure, 839 unspecified at the GSS-API 840 level. 841 - GSS_S_UNAVAILABLE indicates that the operation is 842 not supported. 844 Parameters for gss_compound_cred: 846 delegated_cred_handle 848 A handle to the credentials being delegated, it refers to one or 849 several authenticated principals. 851 cred_handle 853 A handle to claimed credentials of the caller, cred_handle refers to 854 an authenticated principal. 856 cred_handle_new 858 A handle to the compounded set of credentials. 860 8. C-LANGUAGE BINDINGS 862 This section specifies C language bindings for the extended GSS-API 863 functions. 865 8.1. DATA TYPES AND CALLING CONVENTIONS 867 The following data types : 869 � OM_uint32, 870 � gss_buffer_t, 871 � gss_OID, 872 � gss_OID_set, 873 � gss_cred_id_t, 874 � gss_ctx_id_t, 876 are defined in [RFC-1508], along with the calling conventions. 878 8.1.1. SECURITY ATTRIBUTES 880 A security attribute (see section 2) has the following data 881 structure: 883 typedef struct gss_sec_attr_desc { 884 gss_OID attribute_type; 885 gss_buffer_t defining_authority; 886 /* specify GSS_C_NO_BUFFER when 887 non present */ 888 gss_buffer_t security_value; 889 } gss_sec_attr; 891 8.1.2. SECURITY ATTRIBUTE SETS 893 A set of security attributes has the following structure: 895 typedef struct gss_sec_attr_set_desc { 896 OM_uint32 attribute_count; 897 gss_sec_attr* attributes; 898 } gss_sec_attr_set; 900 The attribute_count field contains the number of security attributes 901 in the set. 903 8.1.3. CREDENTIALS LIST 905 A list of credentials has the following structure: 907 typedef struct { 908 OM_uint3 cred_count; 909 gss_cred_id_t* cred_list; 910 } gss_cred_list; 912 The cred_count field contains the number of credentials in the list. 914 8.1.4. ACCEPTOR CONTROL 916 Acceptor control has the following structure: 918 typedef struct gss_acceptor_control_desc { 919 gss_sec_attr target_only; 920 /* specify GSS_C_NULL_SEC_ATTR when 921 non present */ 922 gss_sec_attr delegate_only; 923 /* specify GSS_C_NULL_SEC_ATTR when 924 non present */ 925 gss_sec_attr delegate_target; 926 /* specify GSS_C_NULL_SEC_ATTR when 927 non present */ 928 OM_uint32 delegation_mode; 929 /* specify NULL when non present */ 930 } gss_acceptor_control; 932 8.1.5. ACCEPTOR CONTROL SET 934 A set of Acceptor Control has the following structure : 936 typedef struct gss_control_set_desc { 937 OM_uint32 control_count; 938 gss_acceptor_control* acceptor_controls; 939 } gss_control_set; 941 The control_count field contains the number of acceptor controls in 942 the set. 944 8.1.6. IDENTIFIER 946 Identifiers have the following data structure: 948 typedef struct { 949 gss_type_en id_type 950 gss_value id_value; 951 } gss_id; 953 Where id_type identifies the syntax within the Identifier type: 954 typedef enum { 955 gss_oid_t, /* for OID */ 956 gss_integer, /* for Integer */ 957 gss_string, /* for character string */ 958 gss_uuid, /* for DCE UUID */ 959 gss_buffer_t; /* for gss_buffer */ 960 } gss_type_en; 962 And where id_value is the actual value of the data of type 963 Identifier: 965 struct union { 966 gss_OID OID; 967 OM_uint32* integer; 968 char* string; 969 uuid_t* uuid; 970 gss_buffer_t buffer; 971 } gss_value; 973 This C type is applicable for the following types of attribute: 974 access identity, primary group, capability, audit identity, issuer 975 domain name, and role name. 977 When one of these attributes is handled in a call, the 978 security_value field of the gss_sec_attr structure for this 979 attribute contains a pointer to the gss_id structure. 981 8.1.7. IDENTIFIER SET 983 Identifier sets have the following data structure: 985 typedef struct gss_id_set_desc { 986 OM_uint32 id_count; 987 gss_id* ids; 988 } gss_id_set; 990 The id_count field contains the number of Identifiers in the set. 992 This C type is applicable for the following types of attribute: 993 group, role, optional restrictions, mandatory restrictions, acceptor 994 name and application trust group. 996 When one of these attributes is handled in a call, the 997 security_value field of the gss_sec_attr structure for this 998 attribute contains a pointer to the gss_id_set structure. 1000 8.1.8. TIME PERIOD 1002 A time period has the following structure: 1004 typedef struct gss_time_period_desc { 1005 time_t start_time; 1006 /* NULL for unconstrained start time */ 1007 time_t end_time; 1008 /* NULL for unconstrained end time */ 1009 } gss_time_period; 1011 8.1.9. TIME PERIODS LIST 1013 Time period lists have the following data structure: 1015 typedef struct gss_period_list _desc { 1016 OM_uint32 period_count; 1017 gss_time_period* periods; 1018 } gss_period_list; 1020 The period_count field contains the number of time periods in the 1021 list. 1023 This C type is applicable for the miscellaneous attribute: time 1024 period. 1026 When a list of time periods is returned by a GSS_Get_sec_attributes 1027 call, or set by a GSS_Set_cred_attributes call, the security_value 1028 field of the gss_sec_attr structure in gss_sec_attr_set contains a 1029 pointer to the gss_period_list_structure. 1031 8.2. XGSS-API ROUTINE DESCRIPTIONS 1033 8.2.1. gss_set_cred_attributes 1035 /* set attributes values in credentials */ 1036 OM_uint32 gss_set_cred _attributes ( 1037 gss_cred_id_t cred_handle, /* IN */ 1038 gss_sec_attr_set required_attributes, /* IN */ 1039 OM_uint32 new_cred_req, /* IN */ 1040 OM_uint32 commit_cred_req, /* IN */ 1041 OM_uint32* minor_status, /* OUT*/ 1042 gss_cred_id_t* output_cred_handle); /* OUT*/ 1044 8.2.2. gss_get_sec_attributes 1046 /* get attributes associated with credentials or security context */ 1047 OM_uint32 gss_get_sec_attributes ( 1048 gss_cred_id_t cred_handle, /* IN */ 1049 gss_ctx_id_t context_handle, /* IN */ 1050 gss_OID_set attribute_types_required, /* IN */ 1051 OM_uint32* minor_status, /* OUT*/ 1052 gss_sec_attr_set** priv_attributes, /* OUT*/ 1053 gss_sec_attr_set** misc_attributes); /* OUT*/ 1054 OM_uint32 other_cred_present /* OUT*/ 1056 8.2.3. gss_get_received_creds 1058 /* get received credentials associated with a security context */ 1059 OM_uint32 gss_get_received_creds ( 1060 gss_ctx_id_t context_handle, /* IN */ 1061 OM_uint32* minor_status, /* OUT*/ 1062 gss_cred_list** received_creds); /* OUT*/ 1064 8.2.4. gss_set_cred_controls 1066 /* Set acceptor controls in credentials for context establishment 1067 */ 1068 OM_uint32 gss_set_cred_controls ( 1069 gss_cred_id_t cred_handle, /* IN */ 1070 gss_ control_set required_control, /* IN */ 1071 OM_uint32 replace_old_controls, /* IN */ 1072 OM_uint32 new_cred_req, /* IN */ 1073 OM_uint32 commit_cred_req, /* IN */ 1074 OM_uint32* minor_status, /* OUT*/ 1075 gss_cred_id_t* output_cred_handle); /* OUT*/ 1077 8.2.5. gss_get_sec_controls 1079 /* set context acceptor controls on credentials */ 1080 OM_uint32 gss_get_sec_controls ( 1081 gss_cred_id_t cred_handle, /* IN */ 1082 gss_ctx_id_t context_handle, /* IN */ 1083 OM_uint32* minor_status, /* OUT*/ 1084 gss_control_set* acceptor_controls); /* OUT*/ 1086 8.2.6. gss_compound_cred 1088 /* compound credentials for delegation */ 1089 OM_uint32 gss_compound_cred ( 1090 gss_cred_id_t delegated_cred_handle, /* IN */ 1091 gss_cred_id_t cred_handle, /* IN */ 1092 OM_uint32* minor_status, /* OUT*/ 1093 gss_cred_id_t cred_handle_new); /* OUT*/ 1095 9. ACKNOWLEDGEMENTS 1097 Acknowledgements are due to the following people : Eric Baize, 1098 Belinda Fairthorne, Stephen Farell, Jacques Lebastard and Tom Parker 1099 for providing material for the construction of this document and/or 1100 providing useful inputs. 1102 10. SECURITY CONSIDERATIONS 1104 Security issues are discussed throughout this memo. 1106 11. REFERENCES 1108 [RFC 1508] Generic Security Service API, J Linn, 1109 September 1993 1111 [RFC 1509] Generic Security Service API : C-bindings, J Wray, 1112 September 1993 1114 12. AUTHORS'S ADDRESSES 1116 Tom Parker Internet email: t.a.parker@win0199.wins.icl.co.uk 1117 ICL Enterprises Telephone: +44.1344.472169 1118 59 Old Road, Fax : +44.1249.822703 1119 Derry Hill, 1120 Calne, 1121 Wiltshire SN11 9NF, 1122 United Kingdom 1124 Denis Pinkas Internet email: Denis.Pinkas@bull.net 1125 Bull Telephone: +33 1 30 80 34 87 1126 Rue Jean-Jaures Fax: +33 1 30 80 33 21 1127 BP 68 1128 78340 Les Clayes-sous-Bois 1129 FRANCE 1131 13. CONTENT LIST 1132 1. STATUS OF THIS MEMO 1 1133 2. ABSTRACT 1 1134 3. SECURITY ATTRIBUTES 2 1135 3.1. PRINCIPAL ATTRIBUTES 2 1136 3.1.1. PRIVILEGES ATTRIBUTES 2 1137 3.1.2. MISCELLANEOUS ATTRIBUTES 3 1138 3.2. QUALIFIER ATTRIBUTES 3 1139 3.3. ATTRIBUTES DEFINITIONS 3 1140 3.3.1. Privilege attributes 3 1141 3.3.1.1. Role attribute 3 1142 3.4.1.2. Access identity 3 1143 3.4.1.3. Primary group 3 1144 3.4.1.4. Group 4 1145 3.4.1.5. Capability 4 1146 3.3.2. Miscellaneous attributes 4 1147 3.4.2.1. Audit identity 4 1148 3.4.2.2. Issuer domain name 4 1149 3.4.2.3. Validity periods 5 1150 3.4.2.4. Optional restrictions 5 1151 3.4.2.5. Mandatory restrictions 5 1152 3.3.3. QUALIFIER ATTRIBUTES 5 1153 3.4.3.1. Acceptor name 5 1154 3.4.3.2. Application trust group 6 1155 4. ATTRIBUTE SET REFERENCE 6 1156 4.1. ROLE NAME 6 1157 6. INTERFACE DESCRIPTIONS 6 1158 6.1. ATTRIBUTE HANDLING SUPPORT FUNCTIONS 6 1159 6.1.1. GSS_Set_cred_attributes 6 1160 6.1.2. GSS_Get_sec_attributes 6 1161 6.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 7 1162 6.2.1. GSS_Get_received_creds 7 1163 6.3. CONTEXT ACCEPTOR CONTROL FUNCTIONS 7 1164 6.3.1. GSS_Set_cred_controls function 7 1165 6.3.2. GSS_Get_sec_controls function 8 1166 6.3.3. GSS_Compound_creds function 8 1167 7. DETAILED DESCRIPTION OF THE CALLS 8 1168 7.1. Attribute handling calls 8 1169 7.1.1. GSS_Set_cred_attributes call 8 1170 7.1.2. GSS_Get_sec_attributes call 10 1171 7.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 11 1172 7.2.1. GSS_Get_received_creds call 12 1173 7.3. ACEPTOR CONTROL handling calls 13 1174 7.3.1. GSS_Set_cred_controls call 14 1175 7.3.2. GSS_Get_sec_controls call 15 1176 7.3.3. GSS_Compound_creds call 16 1177 8. C-LANGUAGE BINDINGS 17 1178 8.1. DATA TYPES AND CALLING CONVENTIONS 17 1179 8.1.1. Security attributes 17 1180 8.1.2. Security attribute sets 17 1181 8.1.3. Credentials list 18 1182 8.1.4. Acceptor control 18 1183 8.1.5. Acceptor control set 18 1184 8.1.6. Identifier 18 1185 8.1.7. Identifier set 19 1186 8.1.8. Time period 20 1187 8.1.9. Time periods list 20 1188 8.2. XGSS-API ROUTINE DESCRIPTIONS 20 1189 8.2.1. gss_set_cred_attributes 20 1190 8.2.2. gss_get_sec_attributes 20 1191 8.2.3. gss_get_received_creds 21 1192 8.2.4. gss_set_cred_controls 21 1193 8.2.5. gss_get_sec_controls 21 1194 8.2.6. gss_compound_cred 21 1195 9. ACKNOWLEDGEMENTS 21 1196 10. SECURITY CONSIDERATIONS 21 1197 11. REFERENCES 22 1198 12. AUTHORS'S ADDRESSES 22 1199 13. CONTENT LIST 23