idnits 2.17.1 draft-ietf-cat-xgssapi-acc-cntrl-01.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-23) 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. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 24 longer pages, the longest (page 13) being 60 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 69: '...uthority OCTET STRING OPTIONAL,...' RFC 2119 keyword, line 233: '...3.4.2.4. OPTIONAL RESTRICTIONS...' RFC 2119 keyword, line 687: '... SEQUENCE OF SecAttribute OPTIONAL,...' RFC 2119 keyword, line 688: '... SEQUENCE OF SecAttribute OPTIONAL,...' RFC 2119 keyword, line 689: '... 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 (July 5, 1996) is 10154 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 933, but not defined ** Obsolete undefined reference: RFC 1508 (Obsoleted by RFC 2078) == Unused Reference: 'RFC 1508' is defined on line 1181, but no explicit reference was found in the text == Unused Reference: 'RFC 1509' is defined on line 1184, 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 (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft 4 Tom Parker , ICL 5 Denis Pinkas , Bull 6 IETF Common Authentication Technology WG 7 July 5, 1996 9 Extended Generic Security Service APIs: XGSS-APIs 10 Access control and delegation extensions 12 1. STATUS OF THIS MEMO 14 This document is an Internet Draft. Internet Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its Areas, 16 and its Working Groups. Note that other groups may also distribute 17 working documents as Internet Drafts. Internet Drafts are draft 18 documents valid for a maximum of six months. Internet Drafts may be 19 updated, replaced, or obsoleted by other documents at any time. It 20 is not appropriate to use Internet Drafts as reference material or 21 to cite them other than as a "working draft" or "work in progress." 22 Please check the I-D abstract listing contained in each Internet 23 Draft directory to learn the current status of this or any other 24 Internet Draft. 26 Comments on this document should be sent to "cat-ietf@MIT.EDU", the 27 IETF Common Authentication Technology WG discussion list. 29 2. ABSTRACT 31 The Generic Security Service Application Program Interface (GSS- 32 API), as defined in RFC-1508, provides security services to callers 33 in a generic fashion, supportable with a range of underlying 34 mechanisms and technologies and hence allowing source-level 35 portability of applications to different environments. It defines 36 GSS-API services and primitives at a level independent of underlying 37 mechanism and programming language environment. 39 The GSSAPI allows a caller application to authenticate a principal 40 identity associated with a peer application, to delegate rights to a 41 peer, and to apply security services such as confidentiality and 42 integrity on a per-message basis. 44 The primitives of the GSS-API do not currently allow support of 45 security attributes other than a single identity and do not allow 46 fine control of delegation. 48 The additional primitives described in this document provide support 49 for: 51 * the exchange of a variety of security attributes, and the 52 construction of authorization functions using these attributes, 53 including delegated ones, (attribute handling support functions), 55 Internet-Draft July 5, 199 56 6 58 * fine control over delegation by allowing specification of the 59 delegation method, the acceptor(s) of a security context, their type 60 and the restrictions that may apply (acceptor control and support 61 functions). 63 3. SECURITY ATTRIBUTES 65 A security attribute is defined as: 67 SecAttribute :: { 68 attributeType OBJECT IDENTIFIER, 69 definingAuthority OCTET STRING OPTIONAL, 70 securityValue OCTET STRING } 72 attributeType 74 Defines the type of the attribute. Attributes of the same type 75 have the same authorization semantics. 77 definingAuthority 79 It indicates the authority responsible for defining the value 80 within the attribute type. Some policies demand that multiple 81 sources of values for a given attribute type be supported (e.g. a 82 policy accepting attribute values defined outside the security 83 domain), These policies give rise to a risk of value clashes. The 84 definingAuthority field is used to separate these values. When not 85 present, the value defaults to the name of the authority that 86 issued the attribute. 88 securityValue 90 The value of the security attribute. Its syntax is determined by 91 the attribute type. 93 Security attributes are composed of principal attributes and of 94 qualifier attributes. 96 3.1. PRINCIPAL ATTRIBUTES 98 Principal attributes are composed of security privileges and 99 miscellaneous attributes. 101 3.1.1. PRIVILEGES ATTRIBUTES 103 Security privileges are defined as security attributes attached to a 104 principal, and only usable for access control purposes. Ones defined 105 here are: access identity, group memberships, clearance and 106 capability. The use of OBJECT IDENTIFIERS allows for other types to 107 be standardised. 109 Internet-Draft July 5, 199 110 6 112 3.1.2. MISCELLANEOUS ATTRIBUTES 114 Miscellaneous attributes are defined as security attributes attached 115 to a principal, which are not security privileges. They are used for 116 a variety of purposes. Ones defined here are: the domain name of the 117 issuer of the security attributes, an audit identity, restrictions 118 and validity time periods. 120 3.2. QUALIFIER ATTRIBUTES 122 Qualifier attributes describe the context acceptors for which 123 controls are to apply. Ones defined here are: acceptor name and 124 application trust group. 126 3.3. ATTRIBUTES DEFINITIONS 128 3.3.1. PRIVILEGE ATTRIBUTES 130 A privilege attribute is attached to a principal and is only usable 131 for access control purposes. Privileges are defined under the OID: 133 privilege-attribute OBJECT IDENTIFIER :: 134 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 135 security-in-open-systems(046) privilege-attribute(4) } 137 3.3.1.1. ROLE ATTRIBUTE 139 The role attribute represents the principal's role. The type of this 140 attribute is: 142 { privilege-attribute 1 } 144 The type and the value of this attribute can be set and returned. 146 3.4.1.2. ACCESS IDENTITY 148 The access identity represents an identity to be used for access 149 control purposes. A security context or a credential may not contain 150 more than a single access identity for a given principal. This attri- 151 bute does not need to be present. The type of this attribute is : 153 { privilege-attribute 2 } 155 The type and the value of this attribute can be set and returned. 157 3.4.1.3. PRIMARY GROUP 159 The primary group represents a uniquely prominent group to which a 160 principal belongs. A security context or a credential may not 161 contain more than one primary group for a given principal. The type 162 of this attribute is : 164 { privilege-attribute 3 } 166 Internet-Draft July 5, 199 167 6 169 The type and the value of this attribute can be set and returned. 171 3.4.1.4. GROUP 173 A group represents a characteristic common to several principals. 174 A security context or a credential may contain more than one group 175 for a given principal. The type of this attribute is : 177 { privilege-attribute 4 } 179 The type and the value of this attribute can be set and returned. 181 3.4.1.5. CAPABILITY 183 A capability nominates a resource and the operation(s) that can be 184 performed on that resource. The type of this attribute is : 186 { privilege-attribute 5 } 188 The type and the value of this attribute can be set and returned. 190 3.3.2. MISCELLANEOUS ATTRIBUTES 192 Miscellaneous attributes are defined under the OID: 194 misc-attributeOBJECT IDENTIFIER :: 195 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 196 security-in-open-systems(046) misc-attribute(3) } 198 3.4.2.1. AUDIT IDENTITY 200 The access identity represents the principal's identity to be used 201 for audit purposes. The type of this attribute is : 203 { misc-attribute 2 } 205 Only the type of this attribute can be set and both the type and the 206 value can be returned. 208 3.4.2.2. ISSUER DOMAIN NAME 210 The issuer domain name represents the name of the domain that has 211 issued the security attributes. It cannot be set by a call to 212 GSS_Set_cred_attributes. The type of this attribute is : 214 { misc-attribute 10 } 216 Only the type of this attribute can be set and both the type and the 217 value can be returned. This attribute may always be returned by a 218 call to GSS_Get_cred_attributes. 220 Internet-Draft July 5, 199 221 6 223 3.4.2.3. VALIDITY PERIODS 225 The validity periods represent a list of the time periods within 226 which the security attributes are valid. The type of this attribute 227 is : 229 { misc-attribute 11 } 231 The type and the values of this attribute can be set and returned. 233 3.4.2.4. OPTIONAL RESTRICTIONS 235 The Optional restrictions represent restrictions that apply to the 236 security context. The context may be accepted, even if the 237 application is unable to understand the optional restrictions. 238 The type of this attribute is : 240 { misc-attribute 12 } 242 The type and the values of this attribute can be set and returned. 244 3.4.2.5. MANDATORY RESTRICTIONS 246 The mandatory restrictions represent restrictions that apply to the 247 security context. The context must not be accepted if the 248 application is unable to understand the mandatory restrictions. The 249 type of this attribute is : 251 { misc-attribute 13 } 253 The type and the values of this attribute can be set and returned. 255 3.3.3. QUALIFIER ATTRIBUTES 257 Qualifier attributes are security attributes which define which 258 applications are authorized to be a security context acceptor. In 259 addition to the qualifier attribute it is possible to specify 260 whether delegation is authorized or not for the context acceptor. 262 Qualifier attributes describe the context acceptors for which 263 controls are to apply. Qualifier attributes are defined under the 264 OID: 266 qualifier-attribute OBJECT IDENTIFIER :: 267 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 268 security-in-open-systems(046) qualifier-attribute(5) } 270 3.4.3.1. ACCEPTOR NAME 272 An acceptor name represents the name of an application that can 273 potentially accept the security context. The type of this attribute 274 is : 276 Internet-Draft July 5, 199 277 6 279 { qualifier-attribute 1 } 281 3.4.3.2. APPLICATION TRUST GROUP 283 An application trust group represents a group of acceptors, defined 284 by the security administrator, that mutually trust each other not to 285 spoof each others' identity. The type of this attribute is : 287 { qualifier-attribute 2 } 289 4. ATTRIBUTE SET REFERENCE 291 Attribute set references are defined under the OID: 293 attribute-set-reference OBJECT IDENTIFIER :: 294 { iso(1) identified-organisation(3) icd-ecma(012) technical-report(1) 295 security-in-open-systems(046) attribute-set-reference (9) 297 An Attribute set reference is used to select a set of security 298 attributes and acceptor controls according to policy. At present 299 only a role name is defined. 301 4.1. ROLE NAME 303 The role name is an attribute set reference used to select a set of 304 security attributes. The type of this attribute is : 306 { attribute-set-reference 1 } 308 The type and the values of this reference can only be set. 310 6. INTERFACE DESCRIPTIONS 312 The interfaces are split between attribute handling support 313 functions and context acceptor control and support functions. 315 6.1. ATTRIBUTE HANDLING SUPPORT FUNCTIONS 317 Three attribute handling support functions are defined : 319 6.1.1. GSS_Set_cred_attributes 321 To enable a GSS-API context initiator to specify security 322 attributes, i.e. security privileges and miscellaneous security 323 attributes to be included in the caller credentials in order to 324 become part of a security context. 326 6.1.2. GSS_Get_sec_attributes 328 To extract security attributes, either from a GSS-API context, or 329 from a credential handle. Both privilege attributes and 330 miscellaneous attributes can be retrieved. The function can be 331 invoked either by a context initiator or by a context acceptor. When 333 Internet-Draft July 5, 199 334 6 336 applied to a GSS-API context and invoked by a context acceptor, if 337 delegation is being used, the privilege and miscellaneous attributes 338 which are returned and only those of the initiator, i.e. the 339 initiator of the delegation chain. 341 6.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 343 There is a single function. 345 6.2.1. GSS_Get_received_creds 347 To extract credential handles from a GSS-API context (established 348 with GSS_Accept_sec_context function). This is only applicable for 349 some forms of delegation supporting multiple incoming credentials, 350 and can only be invoked by a context acceptor. A call to 351 GSS_Get_received_creds is an intermediary step for an acceptor, 352 before extracting the security attributes of each set of credentials 353 with a call to GSS_Get_sec_attributes. The credential handles are 354 ordered. They start with the credentials of the first initiator and 355 finish with the the credentials of the immediate invoker. 357 6.3. CONTEXT ACCEPTOR CONTROL FUNCTIONS 359 These functions enable a GSS-API context initiator to impose 360 constraints on the security context to be established via 361 GSS_Init_sec_context function, and enable a GSS-API context acceptor 362 to retrieve the control information that applies to a security 363 context established using the GSS_Accept_sec_context function, and 364 to build credentials from others. 366 Three context acceptor control functions are defined: 368 6.3.1. GSS_Set_cred_controls function 370 To enable a GSS-API context initiator to specify acceptor controls 371 to be included in the caller's credentials in order to be part of a 372 security context. The controls determine the context acceptors with 373 which valid security contexts can be established using the 374 associated credentials, and whether they can act only as targets 375 only, delegates only as or as delegate/targets. 377 * an acceptor designated as being a target only may use the 378 privileges attributes in the received credentials when authorising 379 access to its own protected resources and may not forward them. 381 * an acceptor designated as being a delegate only may use the 382 privilege attributes in the received credentials to forward them 383 but should not use them when authorising access to its own 384 protected resources. 386 Note: Only the acceptor system's AEF (Access Enforcement 387 Facility as described in ISO/IEC 10181-3: The Access Control 388 Framework) can prevent an acceptor permitting access based on 390 Internet-Draft July 5, 199 391 6 393 attributes not intended for it. However it is not in the 394 interests of an acceptor or its AEF to permit access to 395 resources under their control on the basis of attributes that 396 are explicitly stated as not being appropriate. 398 * an acceptor designated as being both a target and a delegate may 399 use the privilege attributes in the received credentials when 400 authorising access to its own protected resources and may also 401 forward them. 403 Restrictions over the operations that are authorised under the 404 context can also be specified. 406 6.3.2. GSS_Get_sec_controls function 408 To enable a GSS-API context initiator or a GSS-API context acceptor 409 to extract acceptor control information either from a credential 410 handle or from a security context. 412 6.3.3. GSS_Compound_creds function 414 To enable a delegate (which is acting as a GSS-API target for a 415 context initiator, and as a GSS-API context initiator for another 416 delegate or target) to build new credentials made from received 417 credentials and its own credentials. 419 7. DETAILED DESCRIPTION OF THE CALLS 421 7.1. ATTRIBUTE HANDLING CALLS 423 7.1.1. GSS_Set_cred_attributes call 425 Input : 427 - cred_handle OCTET STRING, 428 - required_attributes SET OF SecAttribute, 429 - new_cred_req BOOLEAN 430 - commit_cred_req BOOLEAN 432 Output : 434 - output_cred_handle OCTET STRING 436 Return major_status code: 438 - GSS_S_COMPLETE indicates that the nominated 439 attributes are permitted to 440 the caller and have been set. 441 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 442 credentials have expired. 443 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 444 credentials have been detected. 445 - GSS_S_FAILURE indicates a failure,unspecified 446 at the GSS-API level. 448 Internet-Draft July 5, 199 449 6 451 - GSS_S_UNAUTHORIZED indicates that the function, or 452 an argument of the function was 453 not authorised. 454 - GSS_S_UNAVAILABLE indicates that the operation is 455 not supported. 457 This function enables a caller to request a set of privileges and 458 miscellaneous attributes, optionally replacing existing credentials 459 or creating a new set. The effect of this interface is not 460 cumulative, the requested attributes replace any existing attributes 461 in the credentials claimed. 463 Parameters for GSS_Set_cred_attributes: 465 cred_handle 467 Handle for credentials claimed, cred_handle refers to an 468 authenticated principal. Supply NULL to use default credentials. 470 required_attributes 472 A set of required privilege and miscellaneous attributes. NULL 473 specifies default attributes to be requested. Otherwise, only the 474 privilege and miscellaneous attributes specified will be present. 476 If a specified attribute is provided with a NULL value field, the 477 value allocated to the attribute will be the default for the 478 specified attribute available to the authenticated principal 479 according to the prevailing security policy. Otherwise the value 480 specified will be that present. If a value specified clashes with 481 policy, an error is returned. 483 If an attribute set reference (e.g.a role name) is specified as a 484 single attribute required, and policy permits the principal to use 485 it, it will be used as an attribute set reference to select a set of 486 attributes and acceptor controls according to policy. 488 If an attribute set reference (e.g.a role name) is specified along 489 with other required attributes, and policy permits the principal to 490 use the role name, the attributes potentially available for the 491 authenticated principal are taken from a set compounded of the 492 principal's authorised attributes, and the attributes associated 493 with the role name. 495 new_cred_req 497 TRUE for a new credentials set, FALSE replaces the original. 499 commit_cred_req 501 TRUE for immediate attribute acquisition, FALSE for deferred 502 attribute acquisition. 504 Internet-Draft July 5, 199 505 6 507 output_cred_handle 509 The credentials handle for the changed or new credentials. 510 GSS_Set_cred_attributes produces a modified version of the input 511 credentials (cred_handle). The original credentials are changed if 512 new_cred_req is FALSE, otherwise the output_cred_handle references a 513 new, and different, copy of the original input credentials (which 514 remain untouched). GSS_Release_cred can be used when the caller is 515 finished with any new credentials created by this function. 517 7.1.2. GSS_Get_sec_attributes call 519 Input : 521 - cred_handle OCTET STRING, 522 - context_handle INTEGER, 523 - attribute_types_required SET OF OBJECT IDENTIFIER 525 Output : 527 - priv_attributes SET OF SecAttribute 528 - misc_attributes SET OF SecAttribute 529 - other_cred_present BOOLEAN 531 Return major_status code : 533 - GSS_S_COMPLETE indicates that retrieval of 534 attributes is supported and 535 that all, some, or none of the 536 requested attribute types have 537 been returned. 538 - GSS_S_CONTEXT_EXPIRED indicates that the specified 539 security 540 context has expired. 541 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 542 credentials have expired. 543 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 544 credentials have been detected. 545 - GSS_S_FAILURE indicates a failure, 546 unspecified at the GSS-API 547 level. 548 - GSS_S_UNAVAILABLE indicates that the operation is 549 not supported. 551 This function can be used by context initiators and context 552 acceptors to query attributes in credentials or security contexts. 553 If the credentials or security context represents a delegation 554 chain, attributes are retrieved only from the initiator of the 555 chain. If the attribute_types_required parameter is not supplied, 556 then all attribute types are returned. This option could allow 557 clients of this interface to query all attributes and pass privilege 558 attributes to a separate authorization service to make a decision. 560 Internet-Draft July 5, 199 561 6 563 To obtain security attributes from intermediates in a delegation 564 chain, the caller should first call GSS_Get_received_creds (see 565 section 5.2.1 and section 6.2.1). 567 Parameters for GSS_Get_sec_attributes: 569 cred_handle 571 Handle to credentials, cred_handle refers to an authenticated 572 principal. Supply NULL to use default credentials, or a context 573 handle. Note that NULL, without a context handle, is only used for 574 obtaining the caller's own attributes. 576 context_handle 578 GSS-API security context handle, context_handle refers to an 579 established security context. Context_handle is ignored if a non- 580 NULL cred_handle is presented. (Note: it is typically only necessary 581 to use a context_handle parameter rather than cred_handle for the 582 case when a security context is emitted by gss_accept_sec_context, 583 but not with an accompanying set of delegated credentials). 585 attribute_types_required 587 A set of security attribute types. If the default (NULL) is 588 specified, then all miscellaneous and privilege attribute types are 589 returned. 591 This standard does not specify which attributes must be supported, 592 but some common security attributes are defined in section 2. 594 priv_attributes 596 A set of privilege attributes. Response is conditional on the 597 "attribute_types_required" input. 599 misc_attributes 601 A set of miscellaneous attributes. Response is conditional on the 602 "attribute_types_required" input. 604 other_cred_present 606 TRUE when the caller is a context acceptor querying a security 607 context and when more than one set of credentials is present. If 608 interested in the other credential(s), the caller should next call 609 GSS_Get_received_creds, 611 FALSE when either the caller is a context initiator or when the 612 caller is a context acceptor querying a security context and when no 613 other credential is present. 615 7.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 617 Internet-Draft July 5, 199 618 6 620 7.2.1. GSS_Get_received_creds call 622 Input : 624 - context_handle INTEGER, 626 Output : 628 - received_creds SEQUENCE OF OCTET STRING 630 Return major_status code : 632 - GSS_S_COMPLETE indicates that the requested 633 delegate 634 credentials were retrieved. 635 - GSS_S_CONTEXT_EXPIRED indicates that the specified 636 security 637 context has expired. 638 - GSS_S_FAILURE indicates a failure, 639 unspecified at the GSS-API 640 level. 641 - GSS_S_UNAUTHORIZED indicates that the function, or 642 an argument of the function was 643 not authorised. 644 - GSS_S_UNAVAILABLE indicates that the operation is 645 not supported. 647 This function supports the retrieval of all credentials received by 648 an acceptor. It is intended for context acceptors that require not 649 only the initiator's credentials, but also delegates' credentials, 650 to apply their local security policy. A typical example is the 651 retrieval of delegate credentials to subsequently obtain delegate 652 privilege attributes (using GSS_Get_sec_attributes) for use in 653 authorization decisions. 655 Parameters for GSS_Get_received_creds: 657 context_handle 659 GSS-API security context handle, context_handle refers to a security 660 context that is part of an established association. A default 661 context is assumed if no context_handle is supplied. 663 received_creds 665 Contains an ordered list of credentials for the original initiator 666 and for each of the intermediate delegates (if any) between the 667 original initiator and this context acceptor, the first of these 668 being the credentials of the original initiator, and the last being 669 of the immediately preceding delegate. It is expected that the 670 normal use for such credentials would merely be inspection via 671 GSS_Get_sec_attributes as most known mechanisms would not permit 673 Internet-Draft July 5, 199 674 6 676 such delegate credentials to be directly used for initiating further 677 security contexts. Note that it is the caller's responsibility to 678 free any received credentials returned from gss_get_received_creds 679 via gss_release_cred. 681 7.3. ACCEPTOR CONTROL HANDLING CALLS 683 The following construct is used in both the GSS_Set_cred_controls 684 and GSS_Get_sec_controls calls: 686 AcceptorControl :: SEQUENCE { 687 targetOnly SEQUENCE OF SecAttribute OPTIONAL, 688 delegateOnly SEQUENCE OF SecAttribute OPTIONAL, 689 delegateTarget SEQUENCE OF SecAttribute OPTIONAL, 690 delegationMode DelegationMode OPTIONAL,} 692 DelegationMode :: ENUMERATED { 693 default (0), 694 simple (1), 695 composite (2), 696 traced (3),} 698 The fields targetOnly, delegateOnly and delegateTarget specify one 699 or several qualifier attributes describing the acceptors (as 700 targets, delegates or delegate/targets) for which controls are to 701 apply. 703 * the targetOnly specifies that the qualifier(s) are identifying 704 one or more targets, none of which may use the credentials as a 705 delegate. 707 * the delegateOnly choice specifies that the qualifier(s) are 708 identifying one or more delegates, none of which should use the 709 privilege attributes in the credentials when authorising access to 710 their own protected resources, but which may use the received 711 credentials as a delegate. 713 * the delegateTarget choice specifies that the qualifier is 714 identifying one or more delegate/targets any of which can use the 715 received credentials as a delegate and can also use the privileges 716 attributes in the the credentials when authorising access to its 717 own protected resources. 719 delegationMode 721 Indicates the mode of delegation required. 723 Currently three delegation modes and one default are specified: 725 - default: whatever mode of delegation has been set as default (this 726 may be no delegation). 728 - simple: only the original initiator's credentials have to be 730 Internet-Draft July 5, 199 731 6 733 forwarded in the security context being established, 735 - composite: the credentials of the original initiator and of the 736 immediate caller have to be forwarded, 738 - traced: the credentials of the original initiator, of all the 739 delegates, including the immediate caller have to be forwarded. 741 7.3.1. GSS_Set_cred_controls call 743 Input : 745 - cred_handle OCTET STRING, 746 - required_acceptor_control AcceptorControl, 747 - replace_old_controls BOOLEAN 748 - new_cred_req BOOLEAN 749 - commit_cred_req BOOLEAN 751 Output : 753 - output_cred_handle OCTET STRING 755 Return major_status code: 757 - GSS_S_COMPLETE indicates that the controls 758 have been set. 759 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 760 credentials have expired. 761 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 762 credentials have been detected. 763 - GSS_S_FAILURE indicates a failure, 764 unspecified at the GSS-API 765 level. 766 - GSS_S_UNAUTHORIZED indicates that the function, or 767 an argument of the function was 768 not authorised. 769 - GSS_S_UNAVAILABLE indicates that the operation is 770 not supported. 772 This function supports requests to set context acceptor controls, 773 optionally replacing existing credentials controls or creating a new 774 set of credentials with new controls. The effect of this interface 775 is either cumulative or not depending on the value of the 776 replace_old_controls parameter. 778 Parameters for GSS_Set_cred_controls: 780 cred_handle 782 Handle for credentials claimed, it refers to an authenticated 783 principal. Supply NULL to use default credentials. 785 Internet-Draft July 5, 199 786 6 788 required_acceptor_control 790 The control settings required. 792 replace_old_controls 794 TRUE to replace acceptor controls existing in original credentials. 795 FALSE to specify additional controls. 797 new_cred_req 799 TRUE for a new credentials set, FALSE to modify the original. 801 commit_cred_req 803 TRUE for immediate action, FALSE for deferred action. 805 output_cred_handle 807 GSS_Set_cred_controls produces a modified version of the input 808 credentials (cred_handle). The original credentials are directly 809 changed if duplicate_cred_req is FALSE, otherwise the 810 output_cred_handle references a new, and potentially different, copy 811 of the original input credentials (which remain untouched). 812 gss_release_cred can be used when the caller is finished with any 813 new credentials created by this function. 815 7.3.2. GSS_Get_sec_controls call 817 Input : 819 - cred_handle OCTET STRING, 820 - context_handle INTEGER, 822 Output : 824 - acceptor_controls SET OF AcceptorControl, 826 Return major_status code : 828 - GSS_S_COMPLETE indicates that the acceptor 829 control 830 information has been returned 831 - GSS_S_CREDENTIALS_EXPIRED indicates that the specified 832 credentials have expired. 833 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 834 credentials have been detected. 835 - GSS_S_FAILURE indicates a failure, 836 unspecified at the GSS-API 837 level. 838 - GSS_S_UNAVAILABLE indicates that the operation is 839 not supported. 841 Internet-Draft July 5, 199 842 6 844 This function enables a caller to enquire the current value of the 845 acceptor controls in the specified credentials or context. 846 This function can be used by context initiators and context 847 acceptors to query acceptor controls in credentials or security 848 contexts. 850 Parameters for GSS_Get_sec_controls: 852 cred_handle 854 Handle to credentials. It refers to an authenticated principal. 855 Supply NULL to use default credentials, or a context handle. 857 context_handle 859 GSS-API security context handle, context_handle refers to a security 860 context that is part of an established association. Context_handle 861 is ignored if a non-NULL cred_handle is presented. (Note: it is 862 typically only necessary to use a context_handle parameter rather 863 than cred_handle for the case when a security context is emitted by 864 gss_accept_sec_context, but not with an accompanying set of 865 delegated credentials). 867 acceptor_controls 869 A set of acceptor controls. Acceptor controls are described in 870 section 6.2. 872 7.3.3. GSS_Compound_creds call 874 Input : 876 - delegated_cred_handle OCTET STRING 877 - cred_handle OCTET STRING, 879 Output : 881 - cred_handle_new OCTET STRING 883 Return major_status code : 885 GSS_S_COMPLETE indicates that the credentials 886 were successfully compounded 887 - GSS_S_CREDENTIALS_EXPIRED indicates that one or more of 888 the specified credentials have 889 expired. 890 - GSS_S_DEFECTIVE_CREDENTIAL indicates that defective 891 credentials have been detected. 892 - GSS_S_FAILURE indicates a failure, 893 unspecified at the GSS-API 894 level. 895 - GSS_S_UNAVAILABLE indicates that the operation is 896 not supported. 898 Internet-Draft July 5, 199 899 6 901 Parameters for gss_compound_cred: 903 delegated_cred_handle 905 A handle to the credentials being delegated, it refers to one or 906 several authenticated principals. 908 cred_handle 910 A handle to claimed credentials of the caller, cred_handle refers to 911 an authenticated principal. 913 cred_handle_new 915 A handle to the compounded set of credentials. 917 8. C-LANGUAGE BINDINGS 919 This section specifies C language bindings for the extended GSS-API 920 functions. 922 8.1. DATA TYPES AND CALLING CONVENTIONS 924 The following data types : 926 =FA OM_uint32, 927 =FA gss_buffer_t, 928 =FA gss_OID, 929 =FA gss_OID_set, 930 =FA gss_cred_id_t, 931 =FA gss_ctx_id_t, 933 are defined in [RFC-1508], along with the calling conventions. 935 8.1.1. SECURITY ATTRIBUTES 937 A security attribute (see section 2) has the following data 938 structure: 940 typedef struct gss_sec_attr_desc { 941 gss_OID attribute_type; 942 gss_buffer_t defining_authority; 943 /* specify GSS_C_NO_BUFFER when 944 non present */ 945 gss_buffer_t security_value; 946 } gss_sec_attr; 948 8.1.2. SECURITY ATTRIBUTE SETS 950 A set of security attributes has the following structure: 952 Internet-Draft July 5, 199 953 6 955 typedef struct gss_sec_attr_set_desc { 956 OM_uint32 attribute_count; 957 gss_sec_attr* attributes; 958 } gss_sec_attr_set; 960 The attribute_count field contains the number of security attributes 961 in the set. 963 8.1.3. CREDENTIALS LIST 965 A list of credentials has the following structure: 967 typedef struct { 968 OM_uint3 cred_count; 969 gss_cred_id_t* cred_list; 970 } gss_cred_list; 972 The cred_count field contains the number of credentials in the list. 974 8.1.4. ACCEPTOR CONTROL 976 Acceptor control has the following structure: 978 typedef struct gss_acceptor_control_desc { 979 gss_sec_attr target_only; 980 /* specify GSS_C_NULL_SEC_ATTR when 981 non present */ 982 gss_sec_attr delegate_only; 983 /* specify GSS_C_NULL_SEC_ATTR when 984 non present */ 985 gss_sec_attr delegate_target; 986 /* specify GSS_C_NULL_SEC_ATTR when 987 non present */ 988 OM_uint32 delegation_mode; 989 /* specify NULL when non present */ 990 } gss_acceptor_control; 992 8.1.5. ACCEPTOR CONTROL SET 994 A set of Acceptor Control has the following structure : 996 typedef struct gss_control_set_desc { 997 OM_uint32 control_count; 998 gss_acceptor_control* acceptor_controls; 999 } gss_control_set; 1001 The control_count field contains the number of acceptor controls in 1002 the set. 1004 8.1.6. IDENTIFIER 1006 Identifiers have the following data structure: 1008 Internet-Draft July 5, 199 1009 6 1011 typedef struct { 1012 gss_type_en id_type 1013 gss_value id_value; 1014 } gss_id; 1016 Where id_type identifies the syntax within the Identifier type: 1017 typedef enum { 1018 gss_oid_t, /* for OID */ 1019 gss_integer, /* for Integer */ 1020 gss_string, /* for character string */ 1021 gss_uuid, /* for DCE UUID */ 1022 gss_buffer_t; /* for gss_buffer */ 1023 } gss_type_en; 1025 And where id_value is the actual value of the data of type 1026 Identifier: 1028 struct union { 1029 gss_OID OID; 1030 OM_uint32* integer; 1031 char* string; 1032 uuid_t* uuid; 1033 gss_buffer_t buffer; 1034 } gss_value; 1036 This C type is applicable for the following types of attribute: 1037 access identity, primary group, capability, audit identity, issuer 1038 domain name, and role name. 1040 When one of these attributes is handled in a call, the 1041 security_value field of the gss_sec_attr structure for this 1042 attribute contains a pointer to the gss_id structure. 1044 8.1.7. IDENTIFIER SET 1046 Identifier sets have the following data structure: 1048 typedef struct gss_id_set_desc { 1049 OM_uint32 id_count; 1050 gss_id* ids; 1051 } gss_id_set; 1053 The id_count field contains the number of Identifiers in the set. 1055 This C type is applicable for the following types of attribute: 1056 group, role, optional restrictions, mandatory restrictions, acceptor 1057 name and application trust group. 1059 When one of these attributes is handled in a call, the 1060 security_value field of the gss_sec_attr structure for this 1061 attribute contains a pointer to the gss_id_set structure. 1063 Internet-Draft July 5, 199 1064 6 1066 8.1.8. TIME PERIOD 1068 A time period has the following structure: 1070 typedef struct gss_time_period_desc { 1071 time_t start_time; 1072 /* NULL for unconstrained start time */ 1073 time_t end_time; 1074 /* NULL for unconstrained end time */ 1075 } gss_time_period; 1077 8.1.9. TIME PERIODS LIST 1079 Time period lists have the following data structure: 1081 typedef struct gss_period_list _desc { 1082 OM_uint32 period_count; 1083 gss_time_period* periods; 1084 } gss_period_list; 1086 The period_count field contains the number of time periods in the 1087 list. 1089 This C type is applicable for the miscellaneous attribute: time 1090 period. 1092 When a list of time periods is returned by a GSS_Get_sec_attributes 1093 call, or set by a GSS_Set_cred_attributes call, the security_value 1094 field of the gss_sec_attr structure in gss_sec_attr_set contains a 1095 pointer to the gss_period_list_structure. 1097 8.2. XGSS-API ROUTINE DESCRIPTIONS 1099 8.2.1. gss_set_cred_attributes 1101 /* set attributes values in credentials */ 1102 OM_uint32 gss_set_cred _attributes ( 1103 gss_cred_id_t cred_handle, /* IN */ 1104 gss_sec_attr_set required_attributes, /* IN */ 1105 OM_uint32 new_cred_req, /* IN */ 1106 OM_uint32 commit_cred_req, /* IN */ 1107 OM_uint32* minor_status, /* OUT*/ 1108 gss_cred_id_t* output_cred_handle); /* OUT*/ 1110 8.2.2. gss_get_sec_attributes 1112 /* get attributes associated with credentials or security context */ 1113 OM_uint32 gss_get_sec_attributes ( 1114 gss_cred_id_t cred_handle, /* IN */ 1115 gss_ctx_id_t context_handle, /* IN */ 1116 gss_OID_set attribute_types_required, /* IN */ 1117 OM_uint32* minor_status, /* OUT*/ 1118 gss_sec_attr_set** priv_attributes, /* OUT*/ 1120 Internet-Draft July 5, 199 1121 6 1123 gss_sec_attr_set** misc_attributes); /* OUT*/ 1124 OM_uint32 other_cred_present /* OUT*/ 1126 8.2.3. gss_get_received_creds 1128 /* get received credentials associated with a security context */ 1129 OM_uint32 gss_get_received_creds ( 1130 gss_ctx_id_t context_handle, /* IN */ 1131 OM_uint32* minor_status, /* OUT*/ 1132 gss_cred_list** received_creds); /* OUT*/ 1134 8.2.4. gss_set_cred_controls 1136 /* Set acceptor controls in credentials for context establishment 1137 */ 1138 OM_uint32 gss_set_cred_controls ( 1139 gss_cred_id_t cred_handle, /* IN */ 1140 gss_ control_set required_control, /* IN */ 1141 OM_uint32 replace_old_controls, /* IN */ 1142 OM_uint32 new_cred_req, /* IN */ 1143 OM_uint32 commit_cred_req, /* IN */ 1144 OM_uint32* minor_status, /* OUT*/ 1145 gss_cred_id_t* output_cred_handle); /* OUT*/ 1147 8.2.5. gss_get_sec_controls 1149 /* set context acceptor controls on credentials */ 1150 OM_uint32 gss_get_sec_controls ( 1151 gss_cred_id_t cred_handle, /* IN */ 1152 gss_ctx_id_t context_handle, /* IN */ 1153 OM_uint32* minor_status, /* OUT*/ 1154 gss_control_set* acceptor_controls); /* OUT*/ 1156 8.2.6. gss_compound_cred 1158 /* compound credentials for delegation */ 1159 OM_uint32 gss_compound_cred ( 1160 gss_cred_id_t delegated_cred_handle, /* IN */ 1161 gss_cred_id_t cred_handle, /* IN */ 1162 OM_uint32* minor_status, /* OUT*/ 1163 gss_cred_id_t cred_handle_new); /* OUT*/ 1165 9. ACKNOWLEDGEMENTS 1167 Acknowledgements are due to the following people : Eric Baize, 1168 Belinda Fairthorne, Stephen Farell, Jacques Lebastard and Tom Parker 1169 for providing material for the construction of this document and/or 1170 providing useful inputs. 1172 10. SECURITY CONSIDERATIONS 1174 Security issues are discussed throughout this memo. 1176 Internet-Draft July 5, 199 1177 6 1179 11. REFERENCES 1181 [RFC 1508] Generic Security Service API, J Linn, 1182 September 1993 1184 [RFC 1509] Generic Security Service API : C-bindings, J Wray, 1185 September 1993 1187 12. AUTHORS'S ADDRESSES 1189 Tom Parker Internet email: t.a.parker(a)win0199.wins.icl.co.uk 1190 ICL Enterprises Telephone: +44.1344.472169 1191 59 Old Road, Fax : +44.1249.822703 1192 Derry Hill, 1193 Calne, 1194 Wiltshire SN11 9NF, 1195 United Kingdom 1197 Denis Pinkas Internet email: D.Pinkas@frcl.bull.fr 1198 Bull Telephone: +33 1 30 80 34 87 1199 Rue Jean-Jaures Fax: +33 1 30 80 33 21 1200 BP 68 1201 78340 Les Clayes-sous-Bois 1202 FRANCE 1204 Internet-Draft July 5, 199 1205 6 1207 13. CONTENT LIST 1208 1. STATUS OF THIS MEMO 1 1209 2. ABSTRACT 1 1210 3. SECURITY ATTRIBUTES 2 1211 3.1. PRINCIPAL ATTRIBUTES 2 1212 3.1.1. PRIVILEGES ATTRIBUTES 2 1213 3.1.2. MISCELLANEOUS ATTRIBUTES 3 1214 3.2. QUALIFIER ATTRIBUTES 3 1215 3.3. ATTRIBUTES DEFINITIONS 3 1216 3.3.1. Privilege attributes 3 1217 3.3.1.1. Role attribute 3 1218 3.4.1.2. Access identity 3 1219 3.4.1.3. Primary group 3 1220 3.4.1.4. Group 4 1221 3.4.1.5. Capability 4 1222 3.3.2. Miscellaneous attributes 4 1223 3.4.2.1. Audit identity 4 1224 3.4.2.2. Issuer domain name 4 1225 3.4.2.3. Validity periods 5 1226 3.4.2.4. Optional restrictions 5 1227 3.4.2.5. Mandatory restrictions 5 1228 3.3.3. QUALIFIER ATTRIBUTES 5 1229 3.4.3.1. Acceptor name 5 1230 3.4.3.2. Application trust group 6 1231 4. ATTRIBUTE SET REFERENCE 6 1232 4.1. ROLE NAME 6 1233 6. INTERFACE DESCRIPTIONS 6 1234 6.1. ATTRIBUTE HANDLING SUPPORT FUNCTIONS 6 1235 6.1.1. GSS_Set_cred_attributes 6 1236 6.1.2. GSS_Get_sec_attributes 6 1237 6.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 7 1238 6.2.1. GSS_Get_received_creds 7 1239 6.3. CONTEXT ACCEPTOR CONTROL FUNCTIONS 7 1240 6.3.1. GSS_Set_cred_controls function 7 1241 6.3.2. GSS_Get_sec_controls function 8 1242 6.3.3. GSS_Compound_creds function 8 1243 7. DETAILED DESCRIPTION OF THE CALLS 8 1244 7.1. Attribute handling calls 8 1245 7.1.1. GSS_Set_cred_attributes call 8 1246 7.1.2. GSS_Get_sec_attributes call 10 1247 7.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 11 1248 7.2.1. GSS_Get_received_creds call 12 1249 7.3. ACEPTOR CONTROL handling calls 13 1250 7.3.1. GSS_Set_cred_controls call 14 1251 7.3.2. GSS_Get_sec_controls call 15 1252 7.3.3. GSS_Compound_creds call 16 1253 8. C-LANGUAGE BINDINGS 17 1254 8.1. DATA TYPES AND CALLING CONVENTIONS 17 1255 8.1.1. Security attributes 17 1256 8.1.2. Security attribute sets 17 1257 8.1.3. Credentials list 18 1258 8.1.4. Acceptor control 18 1259 8.1.5. Acceptor control set 18 1261 Internet-Draft July 5, 199 1262 6 1264 8.1.6. Identifier 18 1265 8.1.7. Identifier set 19 1266 8.1.8. Time period 20 1267 8.1.9. Time periods list 20 1268 8.2. XGSS-API ROUTINE DESCRIPTIONS 20 1269 8.2.1. gss_set_cred_attributes 20 1270 8.2.2. gss_get_sec_attributes 20 1271 8.2.3. gss_get_received_creds 21 1272 8.2.4. gss_set_cred_controls 21 1273 8.2.5. gss_get_sec_controls 21 1274 8.2.6. gss_compound_cred 21 1275 9. ACKNOWLEDGEMENTS 21 1276 10. SECURITY CONSIDERATIONS 21 1277 11. REFERENCES 22 1278 12. AUTHORS'S ADDRESSES 22 1279 13. CONTENT LIST 23 1281 -- 1283 Denis Pinkas E-mail : D.Pinkas@frcl.bull.fr 1284 Bull S.A. 1285 Rue Jean Jaures B.P. 68 Phone : (33-1) 30 80 34 87 1286 78340 Les Clayes sous Bois. FRANCE Fax : (33-1) 30 80 33 21