idnits 2.17.1 draft-ietf-cat-genericsec-00.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-25) 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 document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** 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. ** Expected the document's filename to be given on the first page, but didn't find any ** 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 1 longer page, the longest (page 1) being 2950 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations 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. ** There are 480 instances of too long lines in the document, the longest one being 12 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 764 has weird spacing: '...t_token pro...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- Couldn't find a document date in the document -- date freshness check skipped. 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 section? '1' on line 42 looks like a reference -- Missing reference section? '3' on line 262 looks like a reference -- Missing reference section? '4' on line 397 looks like a reference -- Missing reference section? '6' on line 657 looks like a reference -- Missing reference section? '7' on line 932 looks like a reference -- Missing reference section? '8' on line 937 looks like a reference -- Missing reference section? '9' on line 2350 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 2567 looks like a reference Summary: 15 errors (**), 0 flaws (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Generic Security Service API: Internet-Draft 3 Common Authentication Technology WG: John Linn (DEC) 5 John Linn 6 Secure Systems 7 Digital Equipment Corporation 8 295 Foster Street, LTN1-1/D07 9 Littleton, MA 01460-1123 10 Linn@zendia.enet.dec.com 12 Generic Security Service Application Program Interface 14 1 GSS-API Characteristics and Concepts 16 This Generic Security Service Application Program Interface 17 (GSS-API) definition provides security services to callers in a 18 generic fashion, supportable with a range of underlying mecha- 19 nisms and technologies and hence allowing source-level porta- 20 bility of applications to different environments. This document 21 defines GSS-API services and primitives at a level independent 22 of underlying mechanism and programming language environment, 23 and is to be complemented by other, related documents: 25 o documents defining specific parameter bindings for particular 26 language environments 28 o documents defining token formats, protocols, and procedures 29 to be implemented in order to realize GSS-API services atop 30 particular security mechanisms 32 The GSS-API separates the operations of initializing a security 33 context between peers, achieving peer entity authentication[1] 34 (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), 35 from the operations of providing per-message data origin au- 36 thentication and data integrity protection (GSS_Sign() and GSS_ 37 Verify() calls) for messages subsequently transferred in con- 38 junction with that context. Per-message GSS_Seal() and GSS_ 39 Unseal() calls provide the data origin authentication and data 41 ___________________ 42 [1] This security service definition, and other definitions used 43 in this document, corresponds to that provided in Interna- 45 tional Standard ISO 7498-2-1988(E), Security Architecture. 47 11-June-1991 1 49 Generic Security Service API: Internet-Draft 50 Common Authentication Technology WG: John Linn (DEC) 52 integrity services which GSS_Sign() and GSS_Verify() offer, and 53 also support selection of confidentiality services as a caller 54 option. Additional calls provide supportive functions to the 55 GSS-API's users. 57 The GSS-API design assumes and addresses several basic goals, 58 including: 60 o Mechanism independence: The GSS-API defines an interface 61 to cryptographically implemented strong authentication and 62 other security services at a generic level which is inde- 63 pendent of particular underlying mechanisms. For example, 64 GSS-API-provided services can be implemented by secret-key 65 technologies (e.g., Kerberos) or public-key approaches (e.g., 66 X.509). 68 o Protocol environment independence: The GSS-API is indepen- 69 dent of the communications protocol suites with which it is 70 employed, permitting use in a broad range of protocol en- 71 vironments. In appropriate environments, an intermediate 72 implementation "veneer" which is oriented to a particular 73 communication protocol (e.g., RPC or ACSE) may be inter- 74 posed between applications and the GSS-API, invoking GSS-API 75 facilities in conjunction with the selected protocol. 77 o Protocol association independence: The GSS-API's security 78 context construct is independent of communications protocol 79 association constructs. This characteristic allows a single 80 GSS-API implementation to be utilized by a variety of in- 81 voking protocol modules on behalf of those modules' calling 82 applications. GSS-API services can also be invoked directly 83 by applications, wholly independent of protocol associations. 85 o Suitability to a range of implementation placements: GSS- 86 API clients are not constrained to reside within any Trusted 87 Computing Base (TCB) perimeter defined on a system where the 88 GSS-API is implemented; security services are specified in a 89 manner suitable to both intra-TCB and extra-TCB callers. 91 2 11-June-1991 93 Generic Security Service API: Internet-Draft 94 Common Authentication Technology WG: John Linn (DEC) 96 1.1 GSS-API Constructs 98 This section describes basic elements comprising the GSS-API. 100 1.1.1 Credentials 102 Credentials structures provide the prerequisites enabling peers 103 to establish security contexts with each other. GSS-API callers 104 reference credentials structures indirectly, through explicit 105 GSS-API-provided credential handles ("cred_handles"). Alter- 106 natively, a caller may designate that its default credential 107 be used for context establishment calls without presenting an 108 explicit handle to that credential. 110 A single credential structure may be used for initiation of 111 outbound contexts and acceptance of inbound contexts. Callers 112 needing to operate in only one of these modes may designate 113 this fact when credentials are acquired for use, allowing un- 114 derlying mechanisms to optimize their processing and storage 115 requirements. 117 A single credential structure may accomodate credential infor- 118 mation associated with multiple underlying mechanisms (mech_ 119 types); a credential structure's contents will vary depending on 120 the set of supported mech_types. Commonly, a single mech_type 121 will be used for all security contexts established by a partic- 122 ular initiator to a particular target; the primary motivation 123 for supporting credentials for multiple mech_types is to al- 124 low initiators on systems which are equipped to handle multiple 125 types to initiate contexts to targets on other systems which can 126 accomodate only a subset of the set supported at the initiator's 127 system. 129 It is the responsibility of underlying system-specific mech- 130 anisms and OS functions below the GSS-API to ensure that the 131 ability to acquire and use credentials associated with a given 133 11-June-1991 3 135 Generic Security Service API: Internet-Draft 136 Common Authentication Technology WG: John Linn (DEC) 138 identity is constrained to appropriate processes within a sys- 139 tem. This responsibility should be taken seriously by implemen- 140 tors, as the ability for an entity to utilize a principal's cre- 141 dentials is equivalent to the entity's ability to successfully 142 assert that principal's identity. 144 Once a set of GSS-API credentials is established, the transfer- 145 ability of that credentials set to other processes or analogous 146 constructs within a system is a local matter, not defined by the 147 GSS-API. An example local policy would be one in which any cre- 148 dentials received as a result of login to a given user account, 149 or of delegation of rights to that account, are accessible by, 150 or transferable to, processes running under that account. 152 The credential establishment process (particularly when per- 153 formed on behalf of users rather than server processes) is 154 likely to require access to passwords or other quantities which 155 should be protected locally and exposed for the shortest time 156 possible. As a result, it will often be appropriate for pre- 157 liminary credential establishment to be performed through local 158 means at user login time. The resulting preliminary credentials 159 would be set aside (in a system-specific fashion) for subsequent 160 use, either: 162 o to be accessed by an invocation of the GSS-API GSS_Acquire_ 163 cred() call, returning an explicit handle to reference that 164 credential 166 o as the default credentials installed on behalf of a process 168 1.1.2 Tokens 170 Tokens are data elements transferred between GSS-API callers, 171 and are divided into two classes. Context-level tokens are ex- 172 changed in order to establish and manage a security context 173 between peers. Per-message tokens are exchanged in conjunction 174 with an established context to provide protective security ser- 175 vices for corresponding data messages. The internal contents of 176 both classes of tokens are specific to the particular underlying 178 4 11-June-1991 180 Generic Security Service API: Internet-Draft 181 Common Authentication Technology WG: John Linn (DEC) 183 mechanism used to support the GSS-API; Appendix B of this docu- 184 ment provides a uniform recommendation for designers of GSS-API 185 support mechanisms, encapsulating mechanism-specific information 186 along with a globally-interpretable mechanism identifier. 188 Tokens are opaque from the viewpoint of GSS-API callers. They 189 are generated within the GSS-API implementation at an end sys- 190 tem, provided to a GSS-API caller to be transferred to the peer 191 GSS-API caller at a remote end system, and processed by the 192 GSS-API implementation at that remote end system. Tokens may 193 be output by GSS-API primitives (and are to be transferred to 194 GSS-API peers) independent of the status indications which those 195 primitives indicate. Token transfer may take place in an in-band 196 manner, integrated into the same protocol stream used by the 197 GSS-API callers for other data transfers, or in an out-of-band 198 manner across a logically separate channel. 200 Development of GSS-API support primitives based on a partic- 201 ular underlying cryptographic technique and protocol does not 202 necessarily imply that GSS-API callers invoking that GSS-API 203 mechanism type will be able to interoperate with peers invoking 204 the same technique and protocol outside the GSS-API paradigm. 205 For example, the format of GSS-API tokens defined in conjunc- 206 tion with a particular mechanism, and the techniques used to 207 integrate those tokens into callers' protocols, may not be the 208 same as those used by non-GSS-API callers of the same underlying 209 technique. 211 1.1.3 Security Contexts 213 Security contexts are established between peers, using cre- 214 dentials established locally in conjunction with each peer or 215 received by peers via delegation. Multiple contexts may ex- 216 ist simultaneously between a pair of peers, using the same or 217 different sets of credentials. Coexistence of multiple con- 218 texts using different credentials allows graceful rollover when 219 credentials expire. Distinction among multiple contexts based 221 11-June-1991 5 223 Generic Security Service API: Internet-Draft 224 Common Authentication Technology WG: John Linn (DEC) 226 on the same credentials serves applications by distinguishing 227 different message streams in a security sense. 229 The GSS-API is independent of underlying protocols and address- 230 ing structure, and depends on its callers to transport GSS-API- 231 provided data elements. As a result of these factors, it is a 232 caller responsibility to parse communicated messages, separat- 233 ing GSS-API-related data elements from caller-provided data. 234 The GSS-API is independent of connection vs. connectionless 235 orientation of the underlying communications service. 237 No correlation between security context and communications 238 protocol association is dictated[ 2]. This separation allows 239 the GSS-API to be used in a wide range of communications en- 240 vironments, and also simplifies the calling sequences of the 241 individual calls. In many cases (depending on underlying secu- 242 rity protocol, associated mechanism, and availability of cached 243 information), the state information required for context setup 244 can be sent concurrently with initial signed user data, without 245 interposing additional message exchanges. 247 1.1.4 Mechanism Types 249 In order to initiate a security context with a target peer, it 250 is necessary to identify an appropriate underlying mechanism 251 type (mech_type) which is shared[3] with that peer. It is recom- 252 mended that callers initiating contexts use a default mech_type 253 value, allowing system-specific functions within or invoked by 254 the GSS-API implementation to select the appropriate mech_type, 256 ___________________ 257 [ 2] The optional channel binding facility, discussed in Sec- 258 tion 1.1.6 of this document, represents an intentional excep- 259 tion to this rule, supporting additional protection features 261 within GSS-API supporting mechanisms. 262 [3] The set of mech_types which an entity may assert as an ini- 263 tiator in establishing contexts to others need not be the same 264 as the set of mech_types with which it can accept incoming 266 contexts from others. 268 6 11-June-1991 270 Generic Security Service API: Internet-Draft 271 Common Authentication Technology WG: John Linn (DEC) 273 but callers may direct that a particular mech_type be employed 274 when necessary. 276 The means for identifying a mech_type for use in establishing a 277 security context with a peer will vary in different environments 278 and circumstances; examples include (but are not limited to): 280 o use of a fixed mech_type, defined by configuration, within an 281 environment 283 o syntactic convention on a target-specific basis, through 284 examination of a target's name 286 o lookup of a target's name in a naming service or other 287 database in order to identify mech_types supported by that 288 target 290 o explicit negotiation between GSS-API callers in advance of 291 security context setup 293 When transferred between GSS-API peers, mech_type specifiers 294 serve to qualify the interpretation of associated tokens. To 295 preclude ambiguous interpretation of mech_type specifiers, use 296 of a centralized or hierarchically structured registry for such 297 specifiers' values is appropriate. 299 It is appropriate to provide some guidance and examples for 300 allocation of mech_type specifiers to different combinations of 301 underlying cryptographic mechanisms and protocols. Minimally, 302 mechanisms based on incompatible cryptographic techniques should 303 be distinguished with different mech_types; a pure Kerberos 304 implementation, for example, would not be directly interoperable 305 with a public-key implementation of X.509 strong authentication 306 and should be distinguished with a separate specifier. 308 Finer-grained mech_type discrimination within classes which 309 are based on common cryptographic techniques can also be appro- 310 priate. This is particularly true when it is necessary to dis- 311 tinguish among different security protocols requiring exchange 312 of different numbers of messages (e.g., Kerberos V5 single-TGT 313 vs. double-TGT cases). In this example, given availability of 315 11-June-1991 7 317 Generic Security Service API: Internet-Draft 318 Common Authentication Technology WG: John Linn (DEC) 320 a directory or other means to identify a prospective peer's 321 supported protocol set in advance, mech_type specification cor- 322 responding to a particular underlying protocol avoids the need 323 to exchange unnecessary peer-peer messages in order to dynam- 324 ically discover the specific protocol required to establish a 325 particular context. On the other hand, if an environment had no 326 out-of-band means available to determine the specific protocol 327 required for a particular peer, dynamic negotiation embodied 328 in defined tokens of a "Kerberos-negotiated" mech_type could be 329 appropriate. 331 1.1.5 Naming 333 The GSS-API avoids prescription of naming structures, treating 334 the names transferred across the interface in order to initiate 335 and accept security contexts as opaque octet string quantities. 336 This approach supports the GSS-API's goal of implementability 337 atop a range of underlying security mechanisms, recognizing the 338 fact that different mechanisms process and authenticate names 339 which are presented in different forms. Generalized services 340 offering translation functions among arbitrary sets of naming 341 environments are outside the scope of the GSS-API; availability 342 and use of local conversion functions to translate among the 343 naming formats supported within a given end system is antici- 344 pated. 346 Two distinct classes of name representations are used in con- 347 junction with different GSS-API parameters: 349 o a printable form (denoted by OCTET STRING), for acceptance 350 from and presentation to users; printable name forms are ac- 351 companied by OBJECT IDENTIFIER tags identifying the namespace 352 to which they correspond 354 o an internal form (denoted by INTERNAL NAME), opaque to 355 callers and defined by individual GSS-API implementations; 356 GSS-API implementations supporting multiple namespace types 357 are responsible for maintaining internal tags to disambiguate 358 the interpretation of particular names 360 8 11-June-1991 362 Generic Security Service API: Internet-Draft 363 Common Authentication Technology WG: John Linn (DEC) 365 Tagging of printable names allows GSS-API callers and underlying 366 GSS-API mechanisms to disambiguate name types and to determine 367 whether an associated name's type is one which they are capable 368 of processing, avoiding aliasing problems which could result 369 from misinterpreting a name of one type as a name of another 370 type. 372 In addition to providing means for names to be tagged with 373 types, this specification defines primitives to support a 374 level of naming environment independence for certain calling 375 applications. To provide basic services[4] oriented towards 376 the requirements of callers which need not themselves interpret 377 the internal syntax and semantics of names, GSS-API calls for 378 name comparison (GSS_Compare_name()), human-readable display 379 (GSS_Display_name()), input conversion (GSS_Import_name()), and 380 internal name deallocation (GSS_Release_name()) functions are 381 defined. 383 GSS_Import_name() implementations can, where appropriate, sup- 384 port more than one printable syntax corresponding to a given 385 namespace (e.g., alternative printable representations for X.500 386 Distinguished Names), allowing flexibility for their callers to 387 select among alternative representations. GSS_Display_name() 388 implementations output a printable syntax selected as appropri- 389 ate to their operational environments; this selection is a local 390 matter. Callers desiring portability across alternative print- 391 able syntaxes should refrain from implementing comparisons based 392 on printable name forms and should instead use the GSS_Compare_ 393 name() call to determine whether or not one internal-format 394 name matches another. 396 ___________________ 397 [4] It is anticipated that these proposed GSS-API calls will 398 be implemented in many end systems based on system-specific 399 name manipulation primitives already extant within those end 400 systems; inclusion within the GSS-API is intended to offer 401 GSS-API callers a portable means to perform specific opera- 402 tions, supportive of authorization and audit requirements, on 404 authenticated names. 406 11-June-1991 9 408 Generic Security Service API: Internet-Draft 409 Common Authentication Technology WG: John Linn (DEC) 411 1.1.6 Channel Bindings 413 The GSS-API accommodates the concept of caller-provided channel 414 binding ("chan_binding") information, used by GSS-API callers 415 to bind the establishment of a security context to relevant 416 characteristics (e.g., addresses, transformed representations of 417 encryption keys) of the underlying communications channel and of 418 protection mechanisms applied to that communications channel. 419 Verification by one peer of chan_binding information provided by 420 the other peer to a context serves to protect against various 421 active attacks. The caller initiating a security context must 422 determine the chan_binding values before making the GSS_Init_ 423 sec_context() call, and consistent values must be provided 424 by both peers to a context. Callers should not assume that 425 underlying mechanisms provide confidentiality protection for 426 channel binding information. 428 Use or non-use of the GSS-API channel binding facility is a 429 caller option, and GSS-API supporting mechanisms can support 430 operation in an environment where NULL channel bindings are 431 presented. When non-NULL channel bindings are used, certain 432 mechanisms will offer enhanced security value by interpreting 433 the bindings' content (rather than simply representing those 434 bindings, or signatures computed on them, within tokens) and 435 will therefore depend on presentation of specific data in a 436 defined format. To this end, agreements among mechanism im- 437 plementors are defining[ 5] conventional interpretations for 438 the contents of channel binding arguments, including address 439 specifiers (with content dependent on communications protocol 440 environment) for context initiators and acceptors. In order 441 for GSS-API callers to be portable across multiple mechanisms 442 and achieve the full security functionality available from each 443 mechanism, it is strongly recommended that GSS-API callers pro- 444 vide channel bindings consistent with these conventions and 445 those of the networking environment in which they operate. 447 ___________________ 448 [ 5] These conventions are being incorporated into related 450 documents. 452 10 11-June-1991 454 Generic Security Service API: Internet-Draft 455 Common Authentication Technology WG: John Linn (DEC) 457 1.2 GSS-API Features and Issues 459 This section describes aspects of GSS-API operations, of the 460 security services which the GSS-API provides, and provides 461 commentary on design issues. 463 1.2.1 Status Reporting 465 Each GSS-API call provides two status return values. Major_ 466 status values provide a mechanism-independent indication of call 467 status (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), 468 sufficient to drive normal control flow within the caller in 469 a generic fashion. Table 1 summarizes the defined major_status 470 return codes in tabular fashion. 472 ________________________________________________________________ 474 Table_1:__GSS-API_Major_Status_Codes____________________________ 476 FATAL ERROR CODES 478 GSS_BAD_BINDINGS channel binding mismatch 480 GSS_BAD_MECH unsupported mechanism requested 482 GSS_BAD_NAME invalid name provided 484 GSS_BAD_NAMETYPE name of unsupported type provided 486 GSS_BAD_STATUS invalid input status selector 488 GSS_BAD_SIG token had invalid signature 490 GSS_CONTEXT_EXPIRED specified security context expired 492 GSS_CREDENTIALS_EXPIRED expired credentials detected 494 11-June-1991 11 496 Generic Security Service API: Internet-Draft 497 Common Authentication Technology WG: John Linn (DEC) 499 ________________________________________________________________ 501 Table_1_(Cont.):__GSS-API_Major_Status_Codes____________________ 503 GSS_DEFECTIVE_CREDENTIAL defective credential detected 505 GSS_DEFECTIVE_TOKEN defective token detected 507 GSS_FAILURE failure, unspecified at GSS-API 508 level 510 GSS_NO_CONTEXT no valid security context specified 512 GSS_NO_CRED no valid credentials provided 514 INFORMATORY STATUS CODES 516 GSS_COMPLETE normal completion 518 GSS_CONTINUE_NEEDED continuation call to routine re- 519 quired 521 GSS_DUPLICATE_TOKEN duplicate per-message token de- 522 tected 524 GSS_OLD_TOKEN timed-out per-message token de- 525 tected 527 GSS_UNSEQ_TOKEN out-of-order per-message token 528 _____________________________detected___________________________ 530 Minor_status provides more detailed status information which may 531 include status codes specific to the underlying security mecha- 532 nism. Minor_status values are not specified in this document. 534 GSS_CONTINUE_NEEDED major_status returns, and optional mes- 535 sage outputs, are provided in GSS_Init_sec_context() and GSS_ 536 Accept_sec_context() calls so that invocations of multiple mes- 537 sage preamble transactions (as are required, for example, to 538 authenticate to a Kerberos V5 double-TGT service) need not be 540 12 11-June-1991 542 Generic Security Service API: Internet-Draft 543 Common Authentication Technology WG: John Linn (DEC) 545 reflected in separate code paths within calling applications. 546 The same mechanism is used to encapsulate mutual authentica- 547 tion within the GSS-API's context initiation calls. Figure 1 548 illustrates a GSS-API continuation scenario. 550 For mech_types which require interactions with third-party 551 servers in order to establish a security context, GSS-API con- 552 text establishment calls may block pending completion of such 553 third-party interactions. On the other hand, no GSS-API calls 554 pend on serialized interactions with GSS-API peer entities. 555 As a result, local GSS-API status returns cannot reflect un- 556 predictable or asynchronous exceptions occurring at remote 557 peers, and reflection of such status information is a caller 558 responsibility outside the GSS-API. 560 1.2.2 Per-Message Security Service Availability 562 When a context is established, two flags are returned to indi- 563 cate the set of per-message protection security services which 564 will be available on the context: 566 o the integ_avail flag indicates whether per-message integrity 567 and data origin authentication services are available 569 o the conf_avail flag indicates whether per-message confiden- 570 tiality services are available, and will never be returned 571 TRUE unless the integ_avail flag is also returned TRUE 573 GSS-API callers desiring per-message security services should 574 check the values of these flags at context establishment time, 575 and must be aware that a returned FALSE value for integ_avail 576 means that invocation of GSS_Sign() or GSS_Seal() primitives on 577 the associated context will apply no cryptographic protection to 578 user data messages. 580 11-June-1991 13 582 Generic Security Service API: Internet-Draft 583 Common Authentication Technology WG: John Linn (DEC) 585 1.2.3 Per-Message Replay Detection and Sequencing 587 Certain underlying mech_types are expected to offer support for 588 replay detection and/or sequencing of messages transferred on 589 the contexts they support. These optionally-selectable protec- 590 tion features are distinct from replay detection and sequencing 591 features applied to the context establishment operation itself; 592 the presence or absence of context-level replay or sequencing 593 features is wholly a function of the underlying mech_type's 594 capabilities, and is not selected or omitted as a caller option. 596 The caller initiating a context provides flags (replay_det_ 597 req_flag and sequence_req_flag) to specify whether the use of 598 per-message replay detection and sequencing features is desired 599 on the context being established. The GSS-API implementation 600 at the initiator system can determine whether these features 601 are supported (and whether they are optionally selectable) as a 602 function of mech_type, without need for bilateral negotiation 603 with the target. When enabled, these features provide recipients 604 with indicators as a result of GSS-API processing of incoming 605 messages, identifying whether those messages were detected as 606 duplicates or out-of-sequence. Detection of such events does not 607 prevent a suspect message from being provided to a recipient; 608 the appropriate course of action on a suspect message is a 609 matter of caller policy. 611 The semantics of the replay detection and sequencing services 612 applied to received messages, as visible across the interface 613 which the GSS-API provides to its clients, are as follows: 615 When replay_det_state is TRUE, the possible major_status returns 616 for well-formed and correctly signed messages are as follows: 618 1. GSS_COMPLETE indicates that the message was within the win- 619 dow (of time or sequence space) allowing replay events to 620 be detected, and that the message was not a replay of a 621 previously-processed message within that window. 623 14 11-June-1991 625 Generic Security Service API: Internet-Draft 626 Common Authentication Technology WG: John Linn (DEC) 628 2. GSS_DUPLICATE_TOKEN indicates that the signature on the re- 629 ceived message was correct, but that the message was recog- 630 nized as a duplicate of a previously-processed message. 632 3. GSS_OLD_TOKEN indicates that the signature on the received 633 message was correct, but that the message is too old to be 634 checked for duplication. 636 When sequence_state is TRUE, the possible major_status returns 637 for well-formed and correctly signed messages are as follows: 639 1. GSS_COMPLETE indicates that the message was within the win- 640 dow (of time or sequence space) allowing replay events to 641 be detected, and that the message was not a replay of a 642 previously-processed message within that window. 644 2. GSS_DUPLICATE_TOKEN indicates that the signature on the re- 645 ceived message was correct, but that the message was recog- 646 nized as a duplicate of a previously-processed message. 648 3. GSS_OLD_TOKEN indicates that the signature on the received 649 message was correct, but that the token is too old to be 650 checked for duplication. 652 4. GSS_UNSEQ_TOKEN indicates that the signature on the received 653 message was correct, but that it is earlier in a sequenced 654 stream [6] than a message already processed on the context. 656 ___________________ 657 [6] Mechanisms can be architected to provide a stricter form of 658 sequencing service, delivering particular messages to recipi- 659 ents only after all predecessor messages in an ordered stream 660 have been delivered. This type of support is incompatible 661 with the GSS-API paradigm in which recipients receive all mes- 662 sages, whether in order or not, and provide them (one at a 663 time, without intra-GSS-API message buffering) to GSS-API rou- 664 tines for validation. GSS-API facilities provide supportive 665 functions, aiding clients to achieve strict message stream in- 666 tegrity in an efficient manner in conjunction with sequencing 667 provisions in communications protocols, but the GSS-API does 668 not offer this level of message stream integrity service by 670 11-June-1991 15 672 Generic Security Service API: Internet-Draft 673 Common Authentication Technology WG: John Linn (DEC) 675 As the message stream integrity features (especially sequencing) 676 may interfere with certain applications' intended communications 677 paradigms, and since support for such features is likely to be 678 resource intensive, it is highly recommended that mech_types 679 supporting these features allow them to be activated selectively 680 on initiator request when a context is established. A context 681 initiator and target are provided with corresponding indicators 682 (replay_det_state and sequence_state), signifying whether these 683 features are active on a given context. 685 An example mech_type supporting per-message replay detection 686 could (when replay_det_state is TRUE) implement the feature as 687 follows: The underlying mechanism would insert timestamps in 688 data elements output by GSS_Sign() and GSS_Seal(), and would 689 maintain (within a time-limited window) a cache (qualified by 690 originator-recipient pair) identifying received data elements 691 processed by GSS_Verify() and GSS_Unseal(). When this feature 692 is active, exception status returns (GSS_DUPLICATE_TOKEN, GSS_ 693 OLD_TOKEN) will be provided when GSS_Verify() or GSS_Unseal() 694 is presented with a message which is either a detected duplicate 695 of a prior message or which is too old to validate against a 696 cache of recently received messages. 698 1.2.4 Quality of Protection 700 Some mech_types will provide their users with fine granularity 701 control over the means used to provide per-message protection, 702 allowing callers to trade off security processing overhead dy- 703 namically against the protection requirements of particular 704 messages. A per-message quality-of-protection parameter (anal- 705 ogous to quality-of-service, or QOS) selects among different 706 QOP options supported by that mechanism. On context establish- 707 ment for a multi-QOP mech_type, context-level data provides the 708 prerequisite data for a range of protection qualities. 710 ___________________ 712 itself. 714 16 11-June-1991 716 Generic Security Service API: Internet-Draft 717 Common Authentication Technology WG: John Linn (DEC) 719 It is expected that the majority of callers will not wish to 720 exert explicit mechanism-specific QOP control and will therefore 721 request selection of a default QOP. Definitions of, and choices 722 among, non-default QOP values are mechanism-specific, and no 723 ordered sequences of QOP values can be assumed equivalent across 724 different mechanisms. Meaningful use of non-default QOP values 725 demands that callers be familiar with the QOP definitions of 726 an underlying mechanism or mechanisms, and is therefore a non- 727 portable construct. 729 2 Interface Descriptions 731 This section describes the GSS-API's service interface, dividing 732 the set of calls offered into four groups. Credential management 733 calls are related to the acquisition and release of credentials 734 by principals. Context-level calls are related to the management 735 of security contexts between principals. Per-message calls are 736 related to the protection of individual messages on established 737 security contexts. Support calls provide ancillary functions 738 useful to GSS-API callers. Table 2 groups and summarizes the 739 calls in tabular fashion. 741 11-June-1991 17 743 Generic Security Service API: Internet-Draft 744 Common Authentication Technology WG: John Linn (DEC) 746 ________________________________________________________________ 748 Table_2:__GSS-API_Calls_________________________________________ 750 CREDENTIAL MANAGEMENT 752 GSS_Acquire_cred acquire credentials for use 754 GSS_Release_cred release credentials after use 756 CONTEXT-LEVEL CALLS 758 GSS_Init_sec_context initiate outbound security context 760 GSS_Accept_sec_context accept inbound security context 762 GSS_Delete_sec_context flush context when no longer needed 764 GSS_Process_context_token process received control token on 765 context 767 GSS_Context_time indicate validity time remaining on 768 context 770 PER-MESSAGE CALLS 772 GSS_Sign apply signature, receive as token 773 separate from message 775 GSS_Verify validate signature token along with 776 message 778 GSS_Seal sign, optionally encrypt, encapsu- 779 late 781 GSS_Unseal decapsulate, decrypt if needed, 782 validate signature 784 SUPPORT CALLS 786 GSS_Display_status translate status codes to printable 787 form 789 GSS_Indicate_mechs indicate mech_types supported on 790 local system 792 GSS_Compare_name compare two names for equality 794 GSS_Display_name translate name to printable form 796 GSS_Import_name convert printable name to normal- 797 ized form 799 GSS_Release_name free storage of normalized-form 800 name 802 GSS_Release_buffer free storage of printable name 804 GSS_Release_oid_set__________free_storage_of_OID_set_object_____ 806 Generic Security Service API: Internet-Draft 807 Common Authentication Technology WG: John Linn (DEC) 809 2.1 Credential management calls 811 These GSS-API calls provide functions related to the management 812 of credentials. Their characterization with regard to whether or 813 not they may block pending exchanges with other network entities 814 (e.g., directories or authentication servers) depends in part on 815 OS-specific (extra-GSS-API) issues, so is not specified in this 816 document. 818 The GSS_Acquire_cred() call is defined within the GSS-API in 819 support of application portability, with a particular orien- 820 tation towards support of portable server applications. It is 821 recognized that (for certain systems and mechanisms) creden- 822 tials for interactive users may be managed differently from 823 credentials for server processes; in such environments, it is 824 the GSS-API implementation's responsibility to distinguish these 825 cases and the procedures for making this distinction are a lo- 826 cal matter. The GSS_Release_cred() call provides a means for 827 callers to indicate to the GSS-API that use of a credentials 828 structure is no longer required. 830 2.1.1 GSS_Acquire_cred call 832 Inputs: 834 o desiredname INTERNAL NAME, -NULL requests locally-determined 835 default 837 o lifetime_req INTEGER,-in seconds; 0 requests default 839 o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests 840 system-selected default 842 o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 843 2=ACCEPT-ONLY 845 Outputs: 847 o major_status INTEGER, 849 o minor_status INTEGER, 851 11-June-1991 19 853 Generic Security Service API: Internet-Draft 854 Common Authentication Technology WG: John Linn (DEC) 856 o output_cred_handle OCTET STRING, 858 o lifetime_rec INTEGER -in seconds, or reserved value for 859 INDEFINITE 861 Return major_status codes: 863 o GSS_COMPLETE indicates that requested credentials were suc- 864 cessfully established, for the duration indicated in life- 865 time_rec, suitable for the usage requested in cred_usage, 866 and for all or a subset of the requested mech_types, and that 867 those credentials can be referenced for subsequent use with 868 the handle returned in output_cred_handle. 870 o GSS_BAD_MECH indicates that a mech_type unsupported by the 871 GSS-API implementation type was requested, causing the cre- 872 dential establishment operation to fail. 874 o GSS_BAD_NAMETYPE indicates that the provided desiredname is 875 uninterpretable or of a type unsupported by the supporting 876 GSS-API implementation, so no credentials could be estab- 877 lished for the accompanying desiredname. 879 o GSS_BAD_NAME indicates that the provided desiredname is in- 880 consistent in terms of internally-incorporated type specifier 881 information, so no credentials could be established for the 882 accompanying desiredname. 884 o GSS_FAILURE indicates that credential establishment failed 885 for reasons unspecified at the GSS-API level, including lack 886 of authorization to establish and use credentials associated 887 with the identity named in the input desiredname argument. 889 GSS_Acquire_cred() is used to acquire credentials so that a 890 principal can (as a function of the input cred_usage parameter) 891 initiate and/or accept security contexts under the identity 892 represented by the desiredname input argument. On successful 893 completion, the returned output_cred_handle result provides a 894 handle for subsequent references to the acquired credentials. 895 Typically, single-user client processes using only default 897 20 11-June-1991 899 Generic Security Service API: Internet-Draft 900 Common Authentication Technology WG: John Linn (DEC) 902 credentials for context establishment purposes will have no 903 need to invoke this call. 905 A caller may provide a reserved value for desiredname signifying 906 a request for credentials corresponding to a default princi- 907 pal identity; the procedures used by GSS-API implementations to 908 select the appropriate principal identity in response to this 909 form of request are local matters. It is possible that multiple 910 pre-established credentials may exist for the same principal 911 identity (for example, as a result of multiple user login ses- 912 sions) when GSS_Acquire_cred() is called; the means used in 913 such cases to select a specific credential are local matters[7]. 915 The lifetime_rec result indicates the length of time for which 916 the acquired credentials will be valid, as an offset from the 917 present. A mechanism may return a reserved value indicating IN- 918 DEFINITE if no constraints on credential lifetime are imposed. 919 A caller of GSS_Acquire_cred() can request a length of time for 920 which acquired credentials are to be valid (lifetime_req argu- 921 ment), beginning at the present[8], or can request credentials 922 with a default validity interval. Certain mechanisms and im- 923 plementations may bind in credential validity period specifiers 924 at a point preliminary to invocation of the GSS_Acquire_cred() 925 call (e.g., in conjunction with user login procedures). As a 926 result, callers requesting non-default values for lifetime_req 927 must recognize that such requests cannot always be honored and 928 must be prepared to accomodate the use of returned credentials 929 with different lifetimes as indicated in lifetime_rec. 931 ___________________ 932 [7] The input lifetime_req argument to GSS_Acquire_cred() may 933 provide useful information for local GSS-API implementations 934 to employ in making this disambiguation in a manner which will 936 best satisfy a caller's intent. 937 [8] Requests for postdated credentials are not supported within 939 the GSS-API. 941 11-June-1991 21 943 Generic Security Service API: Internet-Draft 944 Common Authentication Technology WG: John Linn (DEC) 946 The caller of GSS_Acquire_cred() can explicitly specify a set 947 of mech_types which are to be accomodated in the returned cre- 948 dentials (desired_mechs argument), or can request credentials 949 for a system-defined default set of mech_types. Selection of the 950 system-specified default set is recommended in the interests of 951 application portability. 953 2.1.2 GSS_Release_cred call 955 Input: 957 o cred_handle OCTET STRING 959 Outputs: 961 o major_status INTEGER, 963 o minor_status INTEGER 965 Return major_status codes: 967 o GSS_COMPLETE indicates that the credentials referenced by the 968 input cred_handle were released for purposes of subsequent 969 access by the caller. The effect on other processes which may 970 be authorized shared access to such credentials is a local 971 matter. 973 o GSS_NO_CRED indicates that no release operation was per- 974 formed, either because the input cred_handle was invalid or 975 because the caller lacks authorization to access the refer- 976 enced credentials. 978 o GSS_FAILURE indicates that the release operation failed for 979 reasons unspecified at the GSS-API level. 981 Provides a means for a caller to explicitly request that cre- 982 dentials be released when their use is no longer required. Note 983 that system-specific credential management functions are also 984 likely to exist, for example to assure that credentials shared 985 among processes are properly deleted when all affected processes 986 terminate, even if no explicit release requests are issued by 988 22 11-June-1991 990 Generic Security Service API: Internet-Draft 991 Common Authentication Technology WG: John Linn (DEC) 993 those processes. Given the fact that multiple callers are not 994 precluded from gaining authorized access to the same creden- 995 tials, invocation of GSS_Release_cred() cannot be assumed to 996 delete a particular set of credentials on a system-wide basis. 998 2.2 Context-level calls 1000 This group of calls is devoted to the establishment and manage- 1001 ment of security contexts between peers. A context's initiator 1002 calls GSS_Init_sec_context(), resulting in generation of a to- 1003 ken which the caller passes to the target. At the target, that 1004 token is passed to GSS_Accept_sec_context(). Depending on the 1005 underlying mech_type and specified options, additional token ex- 1006 changes may be performed in the course of context establishment; 1007 such exchanges are accomodated by GSS_CONTINUE_NEEDED status re- 1008 turns from GSS_Init_sec_context() and GSS_Accept_sec_context(). 1009 Either party to an established context may invoke GSS_Delete_ 1010 sec_context() to flush context information when a context is no 1011 longer required. GSS_Process_context_token() is used to process 1012 received tokens carrying context-level control information. GSS_ 1013 Context_time() allows a caller to determine the length of time 1014 for which an established context will remain valid. 1016 2.2.1 GSS_Init_sec_context call 1018 Inputs: 1020 o claimant_cred_handle OCTET STRING, -NULL specifies "use 1021 default" 1023 o input_context_handle INTEGER, -0 specifies "none assigned 1024 yet" 1026 o targname INTERNAL NAME, 1028 o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use 1029 default" 1031 o deleg_req_flag BOOLEAN, 1033 o mutual_req_flag BOOLEAN, 1035 11-June-1991 23 1037 Generic Security Service API: Internet-Draft 1038 Common Authentication Technology WG: John Linn (DEC) 1040 o replay_det_req_flag BOOLEAN, 1042 o sequence_req_flag BOOLEAN, 1044 o lifetime_req INTEGER,-0 specifies default lifetime 1046 o chan_bindings OCTET STRING, 1048 o input_token OCTET STRING-NULL or token received from target 1050 Outputs: 1052 o major_status INTEGER, 1054 o minor_status INTEGER, 1056 o output_context_handle INTEGER, 1058 o mech_type OBJECT IDENTIFIER, -actual mechanism always indi- 1059 cated, never NULL 1061 o output_token OCTET STRING, -NULL or token to pass to context 1062 target 1064 o deleg_state BOOLEAN, 1066 o mutual_state BOOLEAN, 1068 o replay_det_state BOOLEAN, 1070 o sequence_state BOOLEAN, 1072 o conf_avail BOOLEAN, 1074 o integ_avail BOOLEAN, 1076 o lifetime_rec INTEGER - in seconds, or reserved value for 1077 INDEFINITE 1079 This call may block pending network interactions for those mech_ 1080 types in which an authentication server or other network entity 1081 must be consulted on behalf of a context initiator in order 1082 to generate an output_token suitable for presentation to a 1083 specified target. 1085 24 11-June-1991 1087 Generic Security Service API: Internet-Draft 1088 Common Authentication Technology WG: John Linn (DEC) 1090 Return major_status codes: 1092 o GSS_COMPLETE indicates that context-level information was 1093 successfully initialized, and that the returned output_token 1094 will provide sufficient information for the target to perform 1095 per-message processing on the newly-established context. 1097 o GSS_CONTINUE_NEEDED indicates that control information in the 1098 returned output_token must be sent to the target, and that a 1099 reply must be received and passed as the input_token argument 1100 to a continuation call to GSS_Init_sec_context(), before 1101 per-message processing can be performed in conjunction with 1102 this context. 1104 o GSS_DEFECTIVE_TOKEN indicates that consistency checks per- 1105 formed on the input_token failed, preventing further process- 1106 ing from being performed based on that token. 1108 o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks 1109 performed on the credential structure referenced by claimant_ 1110 cred_handle failed, preventing further processing from being 1111 performed using that credential structure. 1113 o GSS_BAD_SIG indicates that the received input_token con- 1114 tains an incorrect signature, so context setup cannot be 1115 accomplished. 1117 o GSS_NO_CRED indicates that no context was established, ei- 1118 ther because the input cred_handle was invalid, because the 1119 referenced credentials are valid for context acceptor use 1120 only, or because the caller lacks authorization to access the 1121 referenced credentials. 1123 o GSS_CREDENTIALS_EXPIRED indicates that the credentials pro- 1124 vided through the input claimant_cred_handle argument are no 1125 longer valid, so context establishment cannot be completed. 1127 o GSS_BAD_BINDINGS indicates that a mismatch between the 1128 caller-provided chan_bindings and those extracted from the 1129 input_token was detected, signifying a security-relevant 1130 event and preventing context establishment. (This result will 1132 11-June-1991 25 1134 Generic Security Service API: Internet-Draft 1135 Common Authentication Technology WG: John Linn (DEC) 1137 be returned by GSS_Init_sec_context only for contexts where 1138 mutual_state is TRUE.) 1140 o GSS_NO_CONTEXT indicates that no valid context was recognized 1141 for the input context_handle provided; this major status will 1142 be returned only for successor calls following GSS_CONTINUE_ 1143 NEEDED status returns. 1145 o GSS_BAD_NAMETYPE indicates that the provided targname is of a 1146 type uninterpretable or unsupported by the supporting GSS-API 1147 implementation, so context establishment cannot be completed. 1149 o GSS_BAD_NAME indicates that the provided targname is incon- 1150 sistent in terms of internally-incorporated type specifier 1151 information, so context establishment cannot be accomplished. 1153 o GSS_FAILURE indicates that context setup could not be ac- 1154 complished for reasons unspecified at the GSS-API level, and 1155 that no interface-defined recovery action is available. 1157 Used by context initiator, providing an output_token suitable 1158 for use by the target within the selected mech_type's protocol. 1159 Using information in the credentials structure referenced by 1160 claimant_cred_handle, initialize the data structures required to 1161 establish a security context with target targname. The claimant_ 1162 cred_handle must correspond to the same valid credentials struc- 1163 ture on the initial call to GSS_Init_sec_context() and on any 1164 successor calls resulting from GSS_CONTINUE_NEEDED status re- 1165 turns; different protocol sequences modeled by the GSS_CONTINUE_ 1166 NEEDED mechanism will require access to credentials at different 1167 points in the context establishment sequence. 1169 The input_context_handle argument is 0, specifying "not yet as- 1170 signed", on the first GSS_Init_sec_context() call relating to 1171 a given context. That call returns an output_context_handle for 1172 future references to this context. When continuation attempts to 1173 GSS_Init_sec_context() are needed to perform context establish- 1174 ment, the previously-returned non-zero handle value is entered 1175 into the input_context_handle argument and will be echoed in the 1176 returned output_context_handle argument. On such continuation 1178 26 11-June-1991 1180 Generic Security Service API: Internet-Draft 1181 Common Authentication Technology WG: John Linn (DEC) 1183 attempts (and only on continuation attempts) the input_token 1184 value is used, to provide the token returned from the context's 1185 target. 1187 The chan_bindings argument is used by the caller to provide 1188 information binding the security context to security-related 1189 characteristics (e.g., addresses, cryptographic keys) of the 1190 underlying communications channel. See Section 1.1.6 of this 1191 document for more discussion of this argument's usage. 1193 The input_token argument contains a message received from the 1194 target, and is significant only on a call to GSS_Init_sec_ 1195 context() which follows a previous return indicating GSS_ 1196 CONTINUE_NEEDED major_status. 1198 It is the caller's responsibility to establish a communications 1199 path to the target, and to transmit any returned output_token 1200 (independent of the accompanying returned major_status value) 1201 to the target over that path. The output_token can, however, be 1202 transmitted along with the first application-provided input mes- 1203 sage to be processed by GSS_Sign() or GSS_Seal() in conjunction 1204 with this context. 1206 The initiator may request various context-level functions 1207 through input flags: the deleg_req_flag requests delegation 1208 of access rights, the mutual_req_flag requests mutual authenti- 1209 cation, the replay_det_req_flag requests that replay detection 1210 features be applied to messages transferred on the established 1211 context, and the sequence_req_flag requests that sequencing 1212 be enforced. (See Section 1.2.3 for more information on replay 1213 detection and sequencing features.) 1215 Not all of the optionally-requestable features will be available 1216 in all underlying mech_types; the corresponding return state 1217 values (deleg_state, mutual_state, replay_det_state, sequence_ 1218 state) indicate, as a function of mech_type processing capabil- 1219 ities and initiator-provided input flags, the set of features 1220 which will be active on the context. These state indicators' 1222 11-June-1991 27 1224 Generic Security Service API: Internet-Draft 1225 Common Authentication Technology WG: John Linn (DEC) 1227 values are undefined unless the routine's major_status indi- 1228 cates COMPLETE. Failure to provide the precise set of features 1229 requested by the caller does not cause context establishment 1230 to fail; it is the caller's prerogative to delete the context 1231 if the feature set provided is unsuitable for the caller's use. 1232 The returned mech_type value indicates the specific mechanism 1233 employed on the context, and will never indicate the value for 1234 "default". 1236 The conf_avail return value indicates whether the context sup- 1237 ports per-message confidentiality services, and so informs the 1238 caller whether or not a request for encryption through the conf_ 1239 req_flag input to GSS_Seal() can be honored. In similar fash- 1240 ion, the integ_avail return value indicates whether per-message 1241 integrity services are available (through either GSS_Sign() or 1242 GSS_Seal()) on the established context. 1244 The lifetime_req input specifies a desired upper bound for the 1245 lifetime of the context to be established, with a value of 0 1246 used to request a default lifetime. The lifetime_rec return 1247 value indicates the length of time for which the context will 1248 be valid, expressed as an offset from the present; depending on 1249 mechanism capabilities, credential lifetimes, and local policy, 1250 it may not correspond to the value requested in lifetime_req. 1251 If no constraints on context lifetime are imposed, this may be 1252 indicated by returning a reserved value representing INDEFI- 1253 NITE lifetime_req. The values of conf_avail, integ_avail, and 1254 lifetime_rec are undefined unless the routine's major_status 1255 indicates COMPLETE. 1257 If the mutual_state is TRUE, this fact will be reflected within 1258 the output_token. A call to GSS_Accept_sec_context() at the 1259 target in conjunction with such a context will return a to- 1260 ken, to be processed by a continuation call to GSS_Init_sec_ 1261 context(), in order to achieve mutual authentication. 1263 28 11-June-1991 1265 Generic Security Service API: Internet-Draft 1266 Common Authentication Technology WG: John Linn (DEC) 1268 2.2.2 GSS_Accept_sec_context call 1270 Inputs: 1272 o acceptor_cred_handle OCTET STRING,-NULL specifies "use de- 1273 fault" 1275 o input_context_handle INTEGER, -0 specifies "not yet assigned" 1277 o chan_bindings OCTET STRING, 1279 o input_token OCTET STRING 1281 Outputs: 1283 o major_status INTEGER, 1285 o minor_status INTEGER, 1287 o srcname INTERNAL NAME, 1289 o mech_type OBJECT IDENTIFIER, 1291 o output_context_handle INTEGER, 1293 o deleg_state BOOLEAN, 1295 o mutual_state BOOLEAN, 1297 o replay_det_state BOOLEAN, 1299 o sequence_state BOOLEAN, 1301 o conf_avail BOOLEAN, 1303 o integ_avail BOOLEAN, 1305 o lifetime_rec INTEGER, - in seconds, or reserved value for 1306 INDEFINITE 1308 o delegated_cred_handle OCTET STRING, 1310 o output_token OCTET STRING -NULL or token to pass to context 1311 initiator 1313 11-June-1991 29 1315 Generic Security Service API: Internet-Draft 1316 Common Authentication Technology WG: John Linn (DEC) 1318 This call may block pending network interactions for those 1319 mech_types in which a directory service or other network entity 1320 must be consulted on behalf of a context acceptor in order to 1321 validate a received input_token. 1323 Return major_status codes: 1325 o GSS_COMPLETE indicates that context-level data structures 1326 were successfully initialized, and that per-message process- 1327 ing can now be performed in conjunction with this context. 1329 o GSS_CONTINUE_NEEDED indicates that control information in the 1330 returned output_token must be sent to the initiator, and that 1331 a response must be received and passed as the input_token 1332 argument to a continuation call to GSS_Accept_sec_context(), 1333 before per-message processing can be performed in conjunction 1334 with this context. 1336 o GSS_DEFECTIVE_TOKEN indicates that consistency checks per- 1337 formed on the input_token failed, preventing further process- 1338 ing from being performed based on that token. 1340 o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks 1341 performed on the credential structure referenced by acceptor_ 1342 cred_handle failed, preventing further processing from being 1343 performed using that credential structure. 1345 o GSS_BAD_SIG indicates that the received input_token con- 1346 tains an incorrect signature, so context setup cannot be 1347 accomplished. 1349 o GSS_DUPLICATE_TOKEN indicates that the signature on the 1350 received input_token was correct, but that the input_token 1351 was recognized as a duplicate of an input_token already 1352 processed. No new context is established. 1354 o GSS_OLD_TOKEN indicates that the signature on the received 1355 input_token was correct, but that the input_token is too old 1356 to be checked for duplication against previously-processed 1357 input_tokens. No new context is established. 1359 30 11-June-1991 1361 Generic Security Service API: Internet-Draft 1362 Common Authentication Technology WG: John Linn (DEC) 1364 o GSS_NO_CRED indicates that no context was established, ei- 1365 ther because the input cred_handle was invalid, because the 1366 referenced credentials are valid for context initiator use 1367 only, or because the caller lacks authorization to access the 1368 referenced credentials. 1370 o GSS_CREDENTIALS_EXPIRED indicates that the credentials pro- 1371 vided through the input acceptor_cred_handle argument are no 1372 longer valid, so context establishment cannot be completed. 1374 o GSS_BAD_BINDINGS indicates that a mismatch between the 1375 caller-provided chan_bindings and those extracted from the 1376 input_token was detected, signifying a security-relevant 1377 event and preventing context establishment. 1379 o GSS_NO_CONTEXT indicates that no valid context was recognized 1380 for the input context_handle provided; this major status will 1381 be returned only for successor calls following GSS_CONTINUE_ 1382 NEEDED status returns. 1384 o GSS_FAILURE indicates that context setup could not be ac- 1385 complished for reasons unspecified at the GSS-API level, and 1386 that no interface-defined recovery action is available. 1388 Used by context target. Using information in the credentials 1389 structure referenced by the input acceptor_cred_handle, verify 1390 the incoming input_token and (assuming success) return the au- 1391 thenticated srcname and the mech_type used. The acceptor_cred_ 1392 handle must correspond to the same valid credentials structure 1393 on the initial call to GSS_Accept_sec_context() and on any suc- 1394 cessor calls resulting from GSS_CONTINUE_NEEDED status returns; 1395 different protocol sequences modeled by the GSS_CONTINUE_NEEDED 1396 mechanism will require access to credentials at different points 1397 in the context establishment sequence. 1399 The input_context_handle argument is 0, specifying "not yet as- 1400 signed", on the first GSS_Accept_sec_context() call relating to 1401 a given context. That call returns an output_context_handle for 1402 future references to this context; when continuation attempts 1404 11-June-1991 31 1406 Generic Security Service API: Internet-Draft 1407 Common Authentication Technology WG: John Linn (DEC) 1409 to GSS_Accept_sec_context() are needed to perform context es- 1410 tablishment, that handle value will be entered into the input_ 1411 context_handle argument. 1413 The chan_bindings argument is used by the caller to provide 1414 information binding the security context to security-related 1415 characteristics (e.g., addresses, cryptographic keys) of the 1416 underlying communications channel. See Section 1.1.6 of this 1417 document for more discussion of this argument's usage. 1419 The returned state results (deleg_state, mutual_state, replay_ 1420 det_state, and sequence_state) reflect the same context state 1421 values as returned to GSS_Init_sec_context()'s caller at the 1422 initiator system. 1424 The conf_avail return value indicates whether the context sup- 1425 ports per-message confidentiality services, and so informs the 1426 caller whether or not a request for encryption through the conf_ 1427 req_flag input to GSS_Seal() can be honored. In similar fash- 1428 ion, the integ_avail return value indicates whether per-message 1429 integrity services are available (through either GSS_Sign() or 1430 GSS_Seal()) on the established context. 1432 The lifetime_rec return value indicates the length of time for 1433 which the context will be valid, expressed as an offset from the 1434 present. The values of deleg_state, mutual_state, replay_det_ 1435 state, sequence_state, conf_avail, integ_avail, and lifetime_rec 1436 are undefined unless the accompanying major_status indicates 1437 COMPLETE. 1439 The delegated_cred_handle result is significant only when deleg_ 1440 state is TRUE, and provides a means for the target to reference 1441 the delegated credentials. The output_token result, when non- 1442 NULL, provides a context-level token to be returned to the 1443 context initiator to continue a multi-step context establishment 1444 sequence. As noted with GSS_Init_sec_context(), any returned 1445 token should be transferred to the context's peer (in this 1446 case, the context initiator), independent of the value of the 1447 accompanying returned major_status. 1449 32 11-June-1991 1451 Generic Security Service API: Internet-Draft 1452 Common Authentication Technology WG: John Linn (DEC) 1454 Note: A target must be able to distinguish a context-level in- 1455 put_token, which is passed to GSS_Accept_sec_context(), from 1456 the per-message data elements passed to GSS_Verify() or GSS_ 1457 Unseal(). These data elements may arrive in a single applica- 1458 tion message, and GSS_Accept_sec_context() must be performed 1459 before per-message processing can be performed successfully. 1461 2.2.3 GSS_Delete_sec_context call 1463 Input: 1465 o context_handle INTEGER 1467 Outputs: 1469 o major_status INTEGER, 1471 o minor_status INTEGER, 1473 o output_context_token OCTET STRING 1475 Return major_status codes: 1477 o GSS_COMPLETE indicates that the context was recognized, that 1478 relevant context-specific information was flushed, and that 1479 the returned output_context_token is ready for transfer to 1480 the context's peer. 1482 o GSS_NO_CONTEXT indicates that no valid context was recognized 1483 for the input context_handle provide, so no deletion was 1484 performed. 1486 o GSS_FAILURE indicates that the context is recognized, but 1487 that the GSS_Delete_sec_context() operation could not be 1488 performed for reasons unspecified at the GSS-API level. 1490 This call may block pending network interactions for mech_types 1491 in which active notification must be made to a central server 1492 when a security context is to be deleted. 1494 11-June-1991 33 1496 Generic Security Service API: Internet-Draft 1497 Common Authentication Technology WG: John Linn (DEC) 1499 This call can be made by either peer in a security context, 1500 to flush context-specific information and to return an output_ 1501 context_token which can be passed to the context's peer in- 1502 forming it that the peer's corresponding context information 1503 can also be flushed. (Once a context is established, the peers 1504 involved are expected to retain cached credential and context- 1505 related information until the information's expiration time is 1506 reached or until a GSS_Delete_sec_context() call is made.) At- 1507 tempts to perform per-message processing on a deleted context 1508 will result in error returns. 1510 2.2.4 GSS_Process_context_token call 1512 Inputs: 1514 o context_handle INTEGER, 1516 o input_context_token OCTET STRING 1518 Outputs: 1520 o major_status INTEGER, 1522 o minor_status INTEGER, 1524 Return major_status codes: 1526 o GSS_COMPLETE indicates that the input_context_token was suc- 1527 cessfully processed in conjunction with the context refer- 1528 enced by context_handle. 1530 o GSS_DEFECTIVE_TOKEN indicates that consistency checks per- 1531 formed on the received context_token failed, preventing 1532 further processing from being performed with that token. 1534 o GSS_NO_CONTEXT indicates that no valid context was recognized 1535 for the input context_handle provided. 1537 o GSS_FAILURE indicates that the context is recognized, but 1538 that the GSS_Process_context_token() operation could not be 1539 performed for reasons unspecified at the GSS-API level. 1541 34 11-June-1991 1543 Generic Security Service API: Internet-Draft 1544 Common Authentication Technology WG: John Linn (DEC) 1546 This call is used to process context_tokens received from a peer 1547 once a context has been established, with corresponding impact 1548 on context-level state information. One use for this facility is 1549 processing of the context_tokens generated by GSS_Delete_sec_ 1550 context(); GSS_Process_context_token() will not block pending 1551 network interactions for that purpose. Another use is to process 1552 tokens indicating remote-peer context establishment failures 1553 after the point where the local GSS-API implementation has 1554 already indicated GSS_COMPLETE status. 1556 2.2.5 GSS_Context_time call 1558 Input: 1560 o context_handle INTEGER, 1562 Outputs: 1564 o major_status INTEGER, 1566 o minor_status INTEGER, 1568 o lifetime_rec INTEGER - in seconds, or reserved value for 1569 INDEFINITE 1571 Return major_status codes: 1573 o GSS_COMPLETE indicates that the referenced context is valid, 1574 and will remain valid for the amount of time indicated in 1575 lifetime_rec. 1577 o GSS_CONTEXT_EXPIRED indicates that data items related to the 1578 referenced context have expired. 1580 o GSS_CREDENTIALS_EXPIRED indicates that the context is recog- 1581 nized, but that its associated credentials have expired. 1583 o GSS_NO_CONTEXT indicates that no valid context was recognized 1584 for the input context_handle provided. 1586 o GSS_FAILURE indicates that the requested operation failed for 1587 reasons unspecified at the GSS-API level. 1589 11-June-1991 35 1591 Generic Security Service API: Internet-Draft 1592 Common Authentication Technology WG: John Linn (DEC) 1594 This call is used to determine the amount of time for which a 1595 currently established context will remain valid. 1597 2.3 Per-message calls 1599 This group of calls is used to perform per-message protection 1600 processing on an established security context. None of these 1601 calls block pending network interactions. These calls may be 1602 invoked by a context's initiator or by the context's target. 1603 The four members of this group should be considered as two 1604 pairs; the output from GSS_Sign() is properly input to GSS_ 1605 Verify(), and the output from GSS_Seal() is properly input to 1606 GSS_Unseal(). 1608 GSS_Sign() and GSS_Verify() support data origin authentication 1609 and data integrity services. When GSS_Sign() is invoked on 1610 an input message, it yields a per-message token containing 1611 data items which allow underlying mechanisms to provide the 1612 specified security services. The original message, along with 1613 the generated per-message token, is passed to the remote peer; 1614 these two data elements are processed by GSS_Verify(), which 1615 validates the message in conjunction with the separate token. 1617 GSS_Seal() and GSS_Unseal() support caller-requested confiden- 1618 tiality in addition to the data origin authentication and data 1619 integrity services offered by GSS_Sign() and GSS_Verify(). GSS_ 1620 Seal() outputs a single data element, encapsulating optionally- 1621 enciphered user data as well as associated token data items. 1622 The data element output from GSS_Seal() is passed to the remote 1623 peer and processed by GSS_Unseal() at that system. GSS_Unseal() 1624 combines decipherment (as required) with validation of data 1625 items related to authentication and integrity. 1627 36 11-June-1991 1629 Generic Security Service API: Internet-Draft 1630 Common Authentication Technology WG: John Linn (DEC) 1632 2.3.1 GSS_Sign call 1634 Inputs: 1636 o context_handle INTEGER, 1638 o qop_req INTEGER,-0 specifies default QOP 1640 o message OCTET STRING 1642 Outputs: 1644 o major_status INTEGER, 1646 o minor_status INTEGER, 1648 o per_msg_token OCTET STRING 1650 Return major_status codes: 1652 o GSS_COMPLETE indicates that a signature, suitable for an 1653 established security context, was successfully applied and 1654 that the message and corresponding per_msg_token are ready 1655 for transmission. 1657 o GSS_CONTEXT_EXPIRED indicates that context-related data 1658 items have expired, so that the requested operation cannot be 1659 performed. 1661 o GSS_CREDENTIALS_EXPIRED indicates that the context is recog- 1662 nized, but that its associated credentials have expired, so 1663 that the requested operation cannot be performed. 1665 o GSS_NO_CONTEXT indicates that no valid context was recognized 1666 for the input context_handle provided. 1668 o GSS_FAILURE indicates that the context is recognized, but 1669 that the requested operation could not be performed for 1670 reasons unspecified at the GSS-API level. 1672 11-June-1991 37 1674 Generic Security Service API: Internet-Draft 1675 Common Authentication Technology WG: John Linn (DEC) 1677 Using the security context referenced by context_handle, apply 1678 a signature to the input message (along with timestamps and/or 1679 other data included in support of mech_type-specific mechanisms) 1680 and return the result in per_msg_token. The qop_req parameter 1681 allows quality-of-protection control. The caller passes the 1682 message and the per_msg_token to the target. 1684 The GSS_Sign() function completes before the message and per_ 1685 msg_token is sent to the peer; successful application of GSS_ 1686 Sign() does not guarantee that a corresponding GSS_Verify() has 1687 been (or can necessarily be) performed successfully when the 1688 message arrives at the destination. 1690 2.3.2 GSS_Verify call 1692 Inputs: 1694 o context_handle INTEGER, 1696 o message OCTET STRING, 1698 o per_msg_token OCTET STRING 1700 Outputs: 1702 o qop_state INTEGER, 1704 o major_status INTEGER, 1706 o minor_status INTEGER, 1708 Return major_status codes: 1710 o GSS_COMPLETE indicates that the message was successfully 1711 verified. 1713 o GSS_DEFECTIVE_TOKEN indicates that consistency checks per- 1714 formed on the received per_msg_token failed, preventing 1715 further processing from being performed with that token. 1717 o GSS_BAD_SIG indicates that the received per_msg_token con- 1718 tains an incorrect signature for the message. 1720 38 11-June-1991 1722 Generic Security Service API: Internet-Draft 1723 Common Authentication Technology WG: John Linn (DEC) 1725 o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN 1726 values appear in conjunction with the optional per-message 1727 replay detection features described in Section 1.2.3; their 1728 semantics are described in that section. 1730 o GSS_CONTEXT_EXPIRED indicates that context-related data 1731 items have expired, so that the requested operation cannot be 1732 performed. 1734 o GSS_CREDENTIALS_EXPIRED indicates that the context is recog- 1735 nized, but that its associated credentials have expired, so 1736 that the requested operation cannot be performed. 1738 o GSS_NO_CONTEXT indicates that no valid context was recognized 1739 for the input context_handle provided. 1741 o GSS_FAILURE indicates that the context is recognized, but 1742 that the GSS_Verify() operation could not be performed for 1743 reasons unspecified at the GSS-API level. 1745 Using the security context referenced by context_handle, verify 1746 that the input per_msg_token contains an appropriate signature 1747 for the input message, and apply any active replay detection 1748 or sequencing features. Return an indication of the quality- 1749 of-protection applied to the processed message in the qop_state 1750 result. 1752 2.3.3 GSS_Seal call 1754 Inputs: 1756 o context_handle INTEGER, 1758 o conf_req_flag BOOLEAN, 1760 o qop_req INTEGER,-0 specifies default QOP 1762 o input_message OCTET STRING 1764 Outputs: 1766 o major_status INTEGER, 1768 11-June-1991 39 1770 Generic Security Service API: Internet-Draft 1771 Common Authentication Technology WG: John Linn (DEC) 1773 o minor_status INTEGER, 1775 o conf_state BOOLEAN, 1777 o output_message OCTET STRING 1779 Return major_status codes: 1781 o GSS_COMPLETE indicates that the input_message was success- 1782 fully processed and that the output_message is ready for 1783 transmission. 1785 o GSS_CONTEXT_EXPIRED indicates that context-related data 1786 items have expired, so that the requested operation cannot be 1787 performed. 1789 o GSS_CREDENTIALS_EXPIRED indicates that the context is recog- 1790 nized, but that its associated credentials have expired, so 1791 that the requested operation cannot be performed. 1793 o GSS_NO_CONTEXT indicates that no valid context was recognized 1794 for the input context_handle provided. 1796 o GSS_FAILURE indicates that the context is recognized, but 1797 that the GSS_Seal() operation could not be performed for 1798 reasons unspecified at the GSS-API level. 1800 Performs the data origin authentication and data integrity 1801 functions of GSS_Sign(). If the input conf_req_flag is TRUE, 1802 requests that confidentiality be applied to the input_message. 1803 Confidentiality may not be supported in all mech_types or by all 1804 implementations; the returned conf_state flag indicates whether 1805 confidentiality was provided for the input_message. The qop_req 1806 parameter allows quality-of-protection control. 1808 In all cases, the GSS_Seal() call yields a single output_ 1809 message data element containing (optionally enciphered) user 1810 data as well as control information. 1812 40 11-June-1991 1814 Generic Security Service API: Internet-Draft 1815 Common Authentication Technology WG: John Linn (DEC) 1817 2.3.4 GSS_Unseal call 1819 Inputs: 1821 o context_handle INTEGER, 1823 o input_message OCTET STRING 1825 Outputs: 1827 o conf_state BOOLEAN, 1829 o qop_state INTEGER, 1831 o major_status INTEGER, 1833 o minor_status INTEGER, 1835 o output_message OCTET STRING 1837 Return major_status codes: 1839 o GSS_COMPLETE indicates that the input_message was success- 1840 fully processed and that the resulting output_message is 1841 available. 1843 o GSS_DEFECTIVE_TOKEN indicates that consistency checks per- 1844 formed on the per_msg_token extracted from the input_message 1845 failed, preventing further processing from being performed. 1847 o GSS_BAD_SIG indicates that an incorrect signature was de- 1848 tected for the message. 1850 o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN 1851 values appear in conjunction with the optional per-message 1852 replay detection features described in Section 1.2.3; their 1853 semantics are described in that section. 1855 o GSS_CONTEXT_EXPIRED indicates that context-related data 1856 items have expired, so that the requested operation cannot be 1857 performed. 1859 o GSS_CREDENTIALS_EXPIRED indicates that the context is recog- 1860 nized, but that its associated credentials have expired, so 1861 that the requested operation cannot be performed. 1863 11-June-1991 41 1865 Generic Security Service API: Internet-Draft 1866 Common Authentication Technology WG: John Linn (DEC) 1868 o GSS_NO_CONTEXT indicates that no valid context was recognized 1869 for the input context_handle provided. 1871 o GSS_FAILURE indicates that the context is recognized, but 1872 that the GSS_Unseal() operation could not be performed for 1873 reasons unspecified at the GSS-API level. 1875 Processes a data element generated (and optionally enciphered) 1876 by GSS_Seal(), provided as input_message. The returned conf_ 1877 state value indicates whether confidentiality was applied to the 1878 input_message. If conf_state is TRUE, GSS_Unseal() deciphers 1879 the input_message. Returns an indication of the quality-of- 1880 protection applied to the processed message in the qop_state 1881 result. GSS_Seal() performs the data integrity and data ori- 1882 gin authentication checking functions of GSS_Verify() on the 1883 plaintext data. Plaintext data is returned in output_message. 1885 2.4 Support calls 1887 This group of calls provides support functions useful to GSS-API 1888 callers, independent of the state of established contexts. Their 1889 characterization with regard to blocking or non-blocking status 1890 in terms of network interactions is unspecified. 1892 2.4.1 GSS_Display_status call 1894 Inputs: 1896 o status_value INTEGER,-GSS-API major_status or minor_status 1897 return value 1899 o status_type INTEGER,-1 if major_status, 2 if minor_status 1901 o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ 1902 status translation 1904 Outputs: 1906 o major_status INTEGER, 1908 o minor_status INTEGER, 1910 42 11-June-1991 1912 Generic Security Service API: Internet-Draft 1913 Common Authentication Technology WG: John Linn (DEC) 1915 o status_string_set SET OF OCTET STRING 1917 Return major_status codes: 1919 o GSS_COMPLETE indicates that a valid printable status repre- 1920 sentation (possibly representing more than one status event 1921 encoded within the status_value) is available in the returned 1922 status_string_set. 1924 o GSS_BAD_MECH indicates that translation in accordance with an 1925 unsupported mech_type was requested, so translation could not 1926 be performed. 1928 o GSS_BAD_STATUS indicates that the input status_value was 1929 invalid, or that the input status_type carried a value other 1930 than 1 or 2, so translation could not be performed. 1932 o GSS_FAILURE indicates that the requested operation could not 1933 be performed for reasons unspecified at the GSS-API level. 1935 Provides a means for callers to translate GSS-API-returned major 1936 and minor status codes into printable string representations. 1938 2.4.2 GSS_Indicate_mechs call 1940 Input: 1942 o (none) 1944 Outputs: 1946 o major_status INTEGER, 1948 o minor_status INTEGER, 1950 o mech_set SET OF OBJECT IDENTIFIER 1952 Return major_status codes: 1954 o GSS_COMPLETE indicates that a set of available mechanisms has 1955 been returned in mech_set. 1957 11-June-1991 43 1959 Generic Security Service API: Internet-Draft 1960 Common Authentication Technology WG: John Linn (DEC) 1962 o GSS_FAILURE indicates that the requested operation could not 1963 be performed for reasons unspecified at the GSS-API level. 1965 Allows callers to determine the set of mechanism types avail- 1966 able on the local system. This call is intended for support of 1967 specialized callers who need to request non-default mech_type 1968 sets from GSS_Acquire_cred(), and should not be needed by other 1969 callers. 1971 2.4.3 GSS_Compare_name call 1973 Inputs: 1975 o name1 INTERNAL NAME, 1977 o name2 INTERNAL NAME, 1979 o name2_type OBJECT IDENTIFIER 1981 Outputs: 1983 o major_status INTEGER, 1985 o minor_status INTEGER, 1987 o name_equal BOOLEAN 1989 Return major_status codes: 1991 o GSS_COMPLETE indicates that name1 and name2 were comparable, 1992 and that the name_equal result indicates whether name1 and 1993 name2 were equal or unequal. 1995 o GSS_BAD_NAMETYPE indicates that one or both of name1 and 1996 name2 contained internal type specifiers uninterpretable 1997 by the supporting GSS-API implementation, or that the two 1998 names' types are different and incomparable, so the equality 1999 comparison could not be completed. 2001 o GSS_BAD_NAME indicates that one or both of the input names 2002 was ill-formed in terms of its internal type specifier, so 2003 the equality comparison could not be completed. 2005 44 11-June-1991 2007 Generic Security Service API: Internet-Draft 2008 Common Authentication Technology WG: John Linn (DEC) 2010 o GSS_FAILURE indicates that the requested operation could not 2011 be performed for reasons unspecified at the GSS-API level. 2013 Allows callers to compare two internal name representations for 2014 equality. 2016 2.4.4 GSS_Display_name call 2018 Inputs: 2020 o name INTERNAL NAME 2022 Outputs: 2024 o major_status INTEGER, 2026 o minor_status INTEGER, 2028 o name_string OCTET STRING, 2030 o name_type OBJECT IDENTIFIER 2032 Return major_status codes: 2034 o GSS_COMPLETE indicates that a valid printable name represen- 2035 tation is available in the returned name_string. 2037 o GSS_BAD_NAMETYPE indicates that the provided name was of a 2038 type uninterpretable by the supporting GSS-API implementa- 2039 tion, so no printable representation could be generated. 2041 o GSS_BAD_NAME indicates that the contents of the provided name 2042 were inconsistent with the internally-indicated name type, so 2043 no printable representation could be generated. 2045 o GSS_FAILURE indicates that the requested operation could not 2046 be performed for reasons unspecified at the GSS-API level. 2048 Allows callers to translate an internal name representation into 2049 a printable form with associated namespace type descriptor. The 2050 syntax of the printable form is a local matter. 2052 11-June-1991 45 2054 Generic Security Service API: Internet-Draft 2055 Common Authentication Technology WG: John Linn (DEC) 2057 2.4.5 GSS_Import_name call 2059 Inputs: 2061 o input_name_string OCTET STRING, 2063 o input_name_type OBJECT IDENTIFIER 2065 Outputs: 2067 o major_status INTEGER, 2069 o minor_status INTEGER, 2071 o output_name INTERNAL NAME 2073 Return major_status codes: 2075 o GSS_COMPLETE indicates that a valid name representation is 2076 output in output_name and described by the type value in 2077 output_name_type. 2079 o GSS_BAD_NAMETYPE indicates that the input_name_type is unsup- 2080 ported by the GSS-API implementation, so the import operation 2081 could not be completed. 2083 o GSS_BAD_NAME indicates that the provided input_name_string 2084 is ill-formed in terms of the input_name_type, so the import 2085 operation could not be completed. 2087 o GSS_FAILURE indicates that the requested operation could not 2088 be performed for reasons unspecified at the GSS-API level. 2090 Allows callers to provide a printable name representation, 2091 designate the type of namespace in conjunction with which it 2092 should be parsed, and convert that printable representation to 2093 an internal form suitable for input to other GSS-API routines. 2094 The syntax of the input_name is a local matter. 2096 46 11-June-1991 2098 Generic Security Service API: Internet-Draft 2099 Common Authentication Technology WG: John Linn (DEC) 2101 2.4.6 GSS_Release_name call 2103 Inputs: 2105 o name INTERNAL NAME 2107 Outputs: 2109 o major_status INTEGER, 2111 o minor_status INTEGER 2113 Return major_status codes: 2115 o GSS_COMPLETE indicates that the storage associated with the 2116 input name was successfully released. 2118 o GSS_BAD_NAME indicates that the input name argument did not 2119 contain a valid name. 2121 o GSS_FAILURE indicates that the requested operation could not 2122 be performed for reasons unspecified at the GSS-API level. 2124 Allows callers to release the storage associated with an inter- 2125 nal name representation. 2127 2.4.7 GSS_Release_buffer call 2129 Inputs: 2131 o buffer OCTET STRING 2133 Outputs: 2135 o major_status INTEGER, 2137 o minor_status INTEGER 2139 Return major_status codes: 2141 o GSS_COMPLETE indicates that the storage associated with the 2142 input buffer was successfully released. 2144 11-June-1991 47 2146 Generic Security Service API: Internet-Draft 2147 Common Authentication Technology WG: John Linn (DEC) 2149 o GSS_FAILURE indicates that the requested operation could not 2150 be performed for reasons unspecified at the GSS-API level. 2152 Allows callers to release the storage associated with an OCTET 2153 STRING buffer allocated by another GSS-API call. 2155 2.4.8 GSS_Release_oid_set call 2157 Inputs: 2159 o buffer SET OF OBJECT IDENTIFIER 2161 Outputs: 2163 o major_status INTEGER, 2165 o minor_status INTEGER 2167 Return major_status codes: 2169 o GSS_COMPLETE indicates that the storage associated with the 2170 input object identifier set was successfully released. 2172 o GSS_FAILURE indicates that the requested operation could not 2173 be performed for reasons unspecified at the GSS-API level. 2175 Allows callers to release the storage associated with an object 2176 identifier set object allocated by another GSS-API call. 2178 3 Example Scenarios 2180 These discussions are intended as examples for clarification, 2181 demonstrating how GSS-API functions can be used and implemented 2182 by candidate underlying mechanisms. They should not be regarded 2183 as constrictive to implementations or as defining the only 2184 means through which GSS-API functions can be realized with a 2185 particular underlying technology, and do not demonstrate all 2186 GSS-API features with each technology. 2188 48 11-June-1991 2190 Generic Security Service API: Internet-Draft 2191 Common Authentication Technology WG: John Linn (DEC) 2193 3.1 Client-Oriented Scenario 2195 Figure 2 illustrates the dataflows involved in use of the GSS- 2196 API by a client and server in a mechanism-independent fashion, 2197 establishing a security context and transferring a protected 2198 message. The example assumes that credential acquisition has 2199 already been completed. Only a subset of parameter and result 2200 values are illustrated, for reasons of clarity in exposition. 2202 The client calls GSS_Init_sec_context() to establish a security 2203 context to the server identified by targname, and elects to set 2204 the mutual_req_flag so that mutual authentication is performed 2205 in the course of context establishment. GSS_Init_sec_context() 2206 returns an output_token to be passed to the server, and in- 2207 dicates GSS_CONTINUE_NEEDED status pending completion of the 2208 mutual authentication sequence. Had mutual_req_flag not been 2209 set, the initial call to GSS_Init_sec_context() would have re- 2210 turned GSS_COMPLETE status. The client sends the output_token to 2211 the server. 2213 The server passes the received token as the input_token pa- 2214 rameter to GSS_Accept_sec_context(). GSS_Accept_sec_context 2215 indicates GSS_COMPLETE status, provides the client's authenti- 2216 cated identity in the srcname result, and provides an output_ 2217 token to be passed to the client. The server sends the output_ 2218 token to the client. 2220 The client passes the received token as the input_token pa- 2221 rameter to a successor call to GSS_Init_sec_context(), which 2222 processes data included in the token in order to achieve mu- 2223 tual authentication from the client's viewpoint. This call 2224 to GSS_Init_sec_context() returns GSS_COMPLETE status, indi- 2225 cating successful mutual authentication and completed context 2226 establishment. 2228 11-June-1991 49 2230 Generic Security Service API: Internet-Draft 2231 Common Authentication Technology WG: John Linn (DEC) 2233 The client generates a data message and passes it to GSS_ 2234 Seal(). GSS_Seal() performs data origin authentication, data 2235 integrity, and (optional) confidentiality processing on the mes- 2236 sage and encapsulates the result into output_message, indicating 2237 GSS_COMPLETE status. The client sends the output_message to the 2238 server. 2240 The server passes the received message to GSS_Unseal(). GSS_ 2241 Unseal inverts the encapsulation performed by GSS_Seal(), de- 2242 ciphers the message if optional confidentiality was applied, 2243 and validates the data origin authentication and data integrity 2244 checking quantities. GSS_Unseal() indicates successful valida- 2245 tion by returning GSS_COMPLETE status along with the resultant 2246 output_message. 2248 For purposes of this example, we assume that the server knows 2249 by out-of-band means that this context will have no further 2250 use after one protected message is transferred from client to 2251 server. Given this premise, the server now calls GSS_Delete_sec_ 2252 context() to flush context-level information. GSS_Delete_sec_ 2253 context returns a context_token for the server to pass to the 2254 client. 2256 The client passes the returned context_token to GSS_Process_ 2257 context_token(), which returns GSS_COMPLETE status after delet- 2258 ing context-level information at the client system. 2260 3.2 Mechanism-Specific Scenarios 2262 This section provides illustrative overviews of the use of 2263 various candidate mechanism types to support the GSS-API. 2265 50 11-June-1991 2267 Generic Security Service API: Internet-Draft 2268 Common Authentication Technology WG: John Linn (DEC) 2270 3.2.1 Kerberos V5, single-TGT 2272 OS-specific login functions yield a TGT to the local realm Ker- 2273 beros server; TGT is placed in a credentials structure for the 2274 client. Client calls GSS_Acquire_cred() to acquire a cred_ 2275 handle in order to reference the credentials for use in estab- 2276 lishing security contexts. 2278 Client calls GSS_Init_sec_context(). If the requested service 2279 is located in a different realm, GSS_Init_sec_context() gets 2280 the necessary TGT/key pairs needed to traverse the path from 2281 local to target realm; these data are placed in the owner's TGT 2282 cache. After any needed remote realm resolution, GSS_Init_sec_ 2283 context() yields a service ticket to the requested service with 2284 a corresponding session key; these data are stored in conjunc- 2285 tion with the context. GSS-API code sends KRB_TGS_REQ request(s) 2286 and receives KRB_TGS_REP response(s) (in the successful case) or 2287 KRB_ERROR. 2289 Assuming success, GSS_Init_sec_context() builds a Kerberos- 2290 formatted KRB_AP_REQ message, and returns it in output_token. 2291 The client sends the output_token to the service. 2293 The service passes the received token as the input_token argu- 2294 ment to GSS_Accept_sec_context(), which verifies the authen- 2295 ticator, provides the service with the client's authenticated 2296 name, and returns an output_context_handle. 2298 Both parties now hold the session key associated with the ser- 2299 vice ticket, and can use this key in subsequent GSS_Sign(), 2300 GSS_Verify(), GSS_Seal(), and GSS_Unseal() operations. 2302 3.2.2 Kerberos V5, double-TGT 2304 TGT acquisition as above. 2306 Note: To avoid unnecessary frequent invocations of error paths 2307 when implementing the GSS-API atop Kerberos V5, it seems appro- 2308 priate to represent "single-TGT K-V5" and "double-TGT K-V5" with 2309 separate mech_types, and this discussion makes that assumption. 2311 11-June-1991 51 2313 Generic Security Service API: Internet-Draft 2314 Common Authentication Technology WG: John Linn (DEC) 2316 Based on the (specified or defaulted) mech_type, GSS_Init_ 2317 sec_context() determines that the double-TGT protocol should 2318 be employed for the specified target. GSS_Init_sec_context() 2319 returns GSS_CONTINUE_NEEDED major_status[9], and its returned 2320 output_token contains a request to the service for the service's 2321 TGT. (If a service TGT with suitably long remaining lifetime 2322 already exists in a cache, it may be usable, obviating the 2323 need for this step.) The client passes the output_token to the 2324 service. 2326 The service passes the received token as the input_token ar- 2327 gument to GSS_Accept_sec_context(), which recognizes it as 2328 a request for TGT. (Note that current Kerberos V5 defines no 2329 intra-protocol mechanism to represent such a request.) GSS_ 2330 Accept_sec_context() returns GSS_CONTINUE_NEEDED major_status 2331 and provides the service's TGT in its output_token. The service 2332 sends the output_token to the client. 2334 The client passes the received token as the input_token argument 2335 to a continuation of GSS_Init_sec_context(). GSS_Init_sec_ 2336 context() caches the received service TGT and uses it as part 2337 of a service ticket request to the Kerberos authentication 2338 server, storing the returned service ticket and session key 2339 in conjunction with the context. GSS_Init_sec_context() builds 2340 a Kerberos-formatted authenticator, and returns it in output_ 2341 token along with GSS_COMPLETE return major_status. The client 2342 sends the output_token to the service. 2344 Service passes the received token as the input_token argument 2345 to a continuation call to GSS_Accept_sec_context(). GSS_Accept_ 2346 sec_context() verifies the authenticator, provides the service 2347 with the client's authenticated name, and returns major_status 2348 GSS_COMPLETE. 2349 ___________________ 2350 [9] This scenario illustrates a different use for the GSS_ 2351 CONTINUE_NEEDED status return facility than that described 2352 in Section 3.1 for purposes of mutual authentication; note 2353 that both uses can coexist as successive operations within a 2355 single context establishment operation. 2357 52 11-June-1991 2359 Generic Security Service API: Internet-Draft 2360 Common Authentication Technology WG: John Linn (DEC) 2362 GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as 2363 above. 2365 3.2.3 X.509 Authentication Framework 2367 This example illustrates use of the GSS-API in conjunction 2368 with public-key mechanisms, consistent with the X.509 Directory 2369 Authentication Framework. 2371 The GSS_Acquire_cred() call establishes a credentials struc- 2372 ture, making the client's private key accessible for use on 2373 behalf of the client. 2375 The client calls GSS_Init_sec_context(), which interrogates 2376 the Directory to acquire (and validate) a chain of public-key 2377 certificates, thereby collecting the public key of the service. 2378 The certificate validation operation determines that suitable 2379 signatures were applied by trusted authorities and that those 2380 certificates have not expired. GSS_Init_sec_context() generates 2381 a secret key for use in per-message protection operations on 2382 the context, and enciphers that secret key under the service's 2383 public key. 2385 The enciphered secret key, along with an authenticator quantity 2386 signed with the client's private key, is included in the out- 2387 put_token from GSS_Init_sec_context(). The output_token also 2388 carries a certification path, consisting of a certificate chain 2389 leading from the service to the client; a variant approach would 2390 defer this path resolution to be performed by the service in- 2391 stead of being asserted by the client. The client application 2392 sends the output_token to the service. 2394 The service passes the received token as the input_token ar- 2395 gument to GSS_Accept_sec_context(). GSS_Accept_sec_context() 2396 validates the certification path, and as a result determines a 2397 certified binding between the client's distinguished name and 2398 the client's public key. Given that public key, GSS_Accept_sec_ 2399 context() can process the input_token's authenticator quantity 2400 and verify that the client's private key was used to sign the 2402 11-June-1991 53 2404 Generic Security Service API: Internet-Draft 2405 Common Authentication Technology WG: John Linn (DEC) 2407 input_token. At this point, the client is authenticated to the 2408 service. The service uses its private key to decipher the en- 2409 ciphered secret key provided to it for per-message protection 2410 operations on the context. 2412 The client calls GSS_Sign() or GSS_Seal() on a data mes- 2413 sage, which causes per-message authentication, integrity, and 2414 (optional) confidentiality facilities to be applied to that 2415 message. The service uses the context's shared secret key to 2416 perform corresponding GSS_Verify() and GSS_Unseal() calls. 2418 4 Related Activities 2420 In order to implement the GSS-API atop existing, emerging, and 2421 future security mechanisms: 2423 o object identifiers must be assigned to candidate GSS-API 2424 mechanisms and the name types which they support 2426 o concrete data element formats must be defined for candidate 2427 mechanisms (encapsulation within the mechanism-independent 2428 token format definition in Appendix B of this document is 2429 recommended to mechanism designers) 2431 Calling applications must implement formatting conventions which 2432 will enable them to distinguish GSS-API tokens from other data 2433 carried in their application protocols. 2435 Concrete language bindings are required for the programming en- 2436 vironments in which the GSS-API is to be employed; such bindings 2437 for the C language are being developed as of this writing. 2439 54 11-June-1991 2441 Generic Security Service API: Internet-Draft 2442 Common Authentication Technology WG: John Linn (DEC) 2444 5 Acknowledgments 2446 This proposal is the result of a collaborative effort. Acknowl- 2447 edgments are due to Kannan Alagappan, Doug Barlow, Bill Brown, 2448 Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard Pitkin, Joe 2449 Tardo, and John Wray of Digital Equipment Corporation, and John 2450 Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of MIT 2451 and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, 2452 Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, 2453 provided inputs which helped to focus and clarify directions. 2454 Precursor work by Richard Pitkin, meetings of the Trusted Sys- 2455 tems Interoperability Group (TSIG), helped to demonstrate the 2456 value of a generic, mechanism-independent security service API. 2458 11-June-1991 55 2460 APPENDIX A 2462 PACS AND AUTHORIZATION SERVICES 2464 Consideration has been given to modifying the GSS-API service 2465 interface to recognize and manipulate Privilege Attribute Cer- 2466 tificates (PACs) as in ECMA 138, carrying authorization data as 2467 a side effect of establishing a security context, but no such 2468 modifications have been incorporated at this time. This appendix 2469 provides rationale for this decision and discusses compatibility 2470 alternatives between PACs and the GSS-API which do not require 2471 that PACs be made visible to GSS-API callers. 2473 Existing candidate mechanism types such as Kerberos and X.509 2474 do not incorporate PAC manipulation features, and exclusion of 2475 such mechanisms from the set of candidates equipped to fully 2476 support the GSS-API seems inappropriate. Inclusion (and GSS-API 2477 visibility) of a feature supported by only a limited number of 2478 mechanisms could encourage the development of allegedly portable 2479 applications which would in fact have only limited portability. 2481 The status quo, in which PACs are not visible across the GSS-API 2482 interface, does not preclude implementations in which PACs are 2483 carried transparently, within the tokens defined and used for 2484 certain mech_types, and stored within peers' credentials and 2485 context-level data structures. While invisible to API callers, 2486 such PACs could be used by operating system or other local 2487 functions as inputs in the course of mediating access requests 2488 made by callers. This course of action allows dynamic selection 2489 of PAC contents, if such selection is administratively-directed 2490 rather than caller-directed. 2492 PACs and Authorization Services 57 2494 Generic Security Service API: Internet-Draft 2495 Common Authentication Technology WG: John Linn (DEC) 2497 In a distributed computing environment, authentication must 2498 span different systems; the need for such authentication pro- 2499 vides motivation for GSS-API definition and usage. Heterogeneous 2500 systems in a network can intercommunicate, with globally au- 2501 thenticated names comprising the common bond between locally 2502 defined access control policies. Access control policies to 2503 which authentication provides inputs are often local, or spe- 2504 cific to particular operating systems or environments. If the 2505 GSS-API made particular authorization models visible across its 2506 service interface, its scope of application would become less 2507 general. The current GSS-API paradigm is consistent with the 2508 precedent set by Kerberos, neither defining the interpretation 2509 of authorization-related data nor enforcing access controls 2510 based on such data. 2512 The GSS-API is a general interface, whose callers may reside 2513 inside or outside any defined TCB or NTCB boundaries. Given this 2514 characteristic, it appears more realistic to provide facilities 2515 which provide "value-added" security services to its callers 2516 than to offer facilities which enforce restrictions on those 2517 callers. Authorization decisions must often be mediated below 2518 the GSS-API level in a local manner against (or in spite of) 2519 applications, and cannot be selectively invoked or omitted 2520 at those applications' discretion. Given that the GSS-API's 2521 placement prevents it from providing a comprehensive solution 2522 to the authorization issue, the value of a partial contribution 2523 specific to particular authorization models is debatable. 2525 58 PACs and Authorization Services 2527 APPENDIX B 2529 MECHANISM-INDEPENDENT TOKEN FORMAT 2531 This appendix specifies a mechanism-independent level of en- 2532 capsulating representation for the initial token of a GSS-API 2533 context establishment sequence, incorporating an identifier 2534 of the mechanism type to be used on that context. Use of this 2535 format (with ASN.1-encoded data elements represented in BER, 2536 constrained in the interests of parsing simplicity to the Dis- 2537 tinguished Encoding Rule (DER) BER subset defined in X.509, 2538 clause 8.7) is recommended to the designers of GSS-API imple- 2539 mentations based on various mechanisms, so that tokens can be 2540 interpreted unambiguously at GSS-API peers. There is no require- 2541 ment that the mechanism-specific innerContextToken, innerMs- 2542 gToken, and sealedUserData data elements be encoded in ASN.1 2543 BER. 2545 -- optional top-level token definitions to frame different mechanisms 2547 GSS-API DEFINITIONS ::= 2549 BEGIN 2551 MechType ::= OBJECT IDENTIFIER 2552 -- data structure definitions 2554 -- callers must be able to distinguish among 2555 -- InitialContextToken, SubsequentContextToken, 2556 -- PerMsgToken, and SealedMessage data elements 2557 -- based on the usage in which they occur 2559 Mechanism-Independent Token Format 59 2561 Generic Security Service API: Internet-Draft 2562 Common Authentication Technology WG: John Linn (DEC) 2564 InitialContextToken ::= 2565 -- option indication (delegation, etc.) indicated within 2566 -- mechanism-specific token 2567 [APPLICATION 0] IMPLICIT SEQUENCE { 2568 thisMech MechType, 2569 innerContextToken ANY DEFINED BY thisMech 2570 -- contents mechanism-specific 2571 } 2573 SubsequentContextToken ::= innerContextToken ANY 2574 -- interpretation based on predecessor InitialContextToken 2576 PerMsgToken ::= 2577 -- as emitted by GSS_Sign and processed by GSS_Verify 2578 innerMsgToken ANY 2580 SealedMessage ::= 2581 -- as emitted by GSS_Seal and processed by GSS_Unseal 2582 -- includes internal, mechanism-defined indicator 2583 -- of whether or not encrypted 2584 sealedUserData ANY 2586 END 2588 60 Mechanism-Independent Token Format