third_party/heimdal/doc/standardisation/rfc5587.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        N. Williams
   8 Request for Comments: 5587                                           Sun
   9 Category: Standards Track                                      July 2009
  10
  11
  12         Extended Generic Security Service Mechanism Inquiry APIs
  13
  14 Abstract
  15
  16    This document introduces new application programming interfaces
  17    (APIs) to the Generic Security Services API (GSS-API) for extended
  18    mechanism attribute inquiry.  These interfaces are primarily intended
  19    to reduce instances of hardcoding of mechanism identifiers in GSS
  20    applications.
  21
  22    These interfaces include mechanism attributes and attribute sets, a
  23    function for inquiring the attributes of a mechanism, a function for
  24    indicating mechanisms that possess given attributes, and a function
  25    for displaying mechanism attributes.
  26
  27 Status of This Memo
  28
  29    This document specifies an Internet standards track protocol for the
  30    Internet community, and requests discussion and suggestions for
  31    improvements.  Please refer to the current edition of the "Internet
  32    Official Protocol Standards" (STD 1) for the standardization state
  33    and status of this protocol.  Distribution of this memo is unlimited.
  34
  35 Copyright Notice
  36
  37    Copyright (c) 2009 IETF Trust and the persons identified as the
  38    document authors.  All rights reserved.
  39
  40    This document is subject to BCP 78 and the IETF Trust's Legal
  41    Provisions Relating to IETF Documents in effect on the date of
  42    publication of this document (http://trustee.ietf.org/license-info).
  43    Please review these documents carefully, as they describe your rights
  44    and restrictions with respect to this document.
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58 Williams                    Standards Track                     [Page 1]
  59 \f
  60 RFC 5587               Extended GSS Mech Inquiry               July 2009
  61
  62
  63 Table of Contents
  64
  65    1. Introduction ....................................................2
  66    2. Conventions Used in This Document ...............................2
  67    3. New GSS-API Interfaces ..........................................3
  68       3.1. Mechanism Attributes and Attribute Sets ....................3
  69       3.2. List of Known Mechanism Attributes .........................4
  70       3.3. Mechanism Attribute Sets of Existing Mechs .................6
  71       3.4. New GSS-API Function Interfaces ............................8
  72            3.4.1. Mechanism Attribute Criticality .....................8
  73            3.4.2. GSS_Indicate_mechs_by_attrs() .......................9
  74            3.4.3. GSS_Inquire_attrs_for_mech() .......................10
  75            3.4.4. GSS_Display_mech_attr() ............................10
  76            3.4.5. New Major Status Values ............................11
  77            3.4.6. C-Bindings .........................................11
  78    4. Requirements for Mechanism Designers ...........................13
  79    5. IANA Considerations ............................................13
  80    6. Security Considerations ........................................13
  81    7. References .....................................................13
  82       7.1. Normative References ......................................13
  83       7.2. Informative References ....................................14
  84 Appendix A. Typedefs and C Bindings ..................................15
  85
  86 1.  Introduction
  87
  88    GSS-API [RFC2743] mechanisms have a number of properties that may be
  89    of interest to applications.  The lack of APIs for inquiring about
  90    available mechanisms' properties has meant that many GSS-API
  91    applications must hardcode mechanism Object Identifiers (OIDs).
  92    Ongoing work may result in a variety of new GSS-API mechanisms.
  93    Applications should not have to hardcode their OIDs.
  94
  95    For example, the Secure Shell version 2 (SSHv2) protocol [RFC4251]
  96    supports the use of GSS-API mechanisms for authentication [RFC4462]
  97    but explicitly prohibits the use of Simple and Protected GSS-API
  98    Negotiation (SPNEGO) [RFC4178].  Future mechanisms that negotiate
  99    mechanisms would have to be forbidden as well, but there is no way to
 100    implement applications that inquire what mechanisms are available and
 101    then programmatically exclude mechanisms "like SPNEGO".
 102
 103 2.  Conventions Used in This Document
 104
 105    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 106    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 107    document are to be interpreted as described in [RFC2119].
 108
 109
 110
 111
 112
 113
 114 Williams                    Standards Track                     [Page 2]
 115 \f
 116 RFC 5587               Extended GSS Mech Inquiry               July 2009
 117
 118
 119 3.  New GSS-API Interfaces
 120
 121    We introduce a new concept -- that of mechanism attributes.  By
 122    allowing applications to query the set of attributes associated with
 123    individual mechanisms and to find out which mechanisms support a
 124    given set of attributes, we allow applications to select mechanisms
 125    based on their attributes without having to hardcode mechanism OIDs.
 126
 127    Section 3.1 describes the mechanism attributes concept.  Sections
 128    3.4.2, 3.4.3, and 3.4.4 describe three new interfaces that deal in
 129    mechanisms and attribute sets:
 130
 131    o  GSS_Indicate_mechs_by_attrs()
 132
 133    o  GSS_Inquire_attrs_for_mech()
 134
 135    o  GSS_Display_mech_attr()
 136
 137 3.1.  Mechanism Attributes and Attribute Sets
 138
 139    An abstraction for the features provided by mechanisms and pseudo-
 140    mechanisms is needed in order to facilitate the programmatic
 141    selection of mechanisms.  Pseudo-mechanisms are mechanisms that make
 142    reference to other mechanisms in order to provide their services.
 143    For example, SPNEGO is a pseudo-mechanism, for without other
 144    mechanisms SPNEGO is useless.
 145
 146    Two data types are needed: one for individual mechanism attributes
 147    and one for mechanism attribute sets.  To simplify the mechanism
 148    attribute interfaces, we reuse the 'OID' and 'OID set' data types and
 149    model individual mechanism attribute types as OIDs.
 150
 151    To this end, we define an open namespace of mechanism attributes and
 152    assign them arcs off of this OID:
 153
 154    <1.3.6.1.5.5.13>
 155
 156    Each mechanism has a set of mechanism attributes that it supports as
 157    described in its specification.
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170 Williams                    Standards Track                     [Page 3]
 171 \f
 172 RFC 5587               Extended GSS Mech Inquiry               July 2009
 173
 174
 175 3.2.  List of Known Mechanism Attributes
 176
 177       +-------------------------+---------+-------------------------+
 178       | Mech Attr Name          | OID Arc | Arc Name                |
 179       +-------------------------+---------+-------------------------+
 180       | GSS_C_MA_MECH_CONCRETE  |     (1) | concrete-mech           |
 181       | GSS_C_MA_MECH_PSEUDO    |     (2) | pseudo-mech             |
 182       | GSS_C_MA_MECH_COMPOSITE |     (3) | composite-mech          |
 183       | GSS_C_MA_MECH_NEGO      |     (4) | mech-negotiation-mech   |
 184       | GSS_C_MA_MECH_GLUE      |     (5) | mech-glue               |
 185       | GSS_C_MA_NOT_MECH       |     (6) | not-mech                |
 186       | GSS_C_MA_DEPRECATED     |     (7) | mech-deprecated         |
 187       | GSS_C_MA_NOT_DFLT_MECH  |     (8) | mech-not-default        |
 188       | GSS_C_MA_ITOK_FRAMED    |     (9) | initial-is-framed       |
 189       | GSS_C_MA_AUTH_INIT      |    (10) | auth-init-princ         |
 190       | GSS_C_MA_AUTH_TARG      |    (11) | auth-targ-princ         |
 191       | GSS_C_MA_AUTH_INIT_INIT |    (12) | auth-init-princ-initial |
 192       | GSS_C_MA_AUTH_TARG_INIT |    (13) | auth-targ-princ-initial |
 193       | GSS_C_MA_AUTH_INIT_ANON |    (14) | auth-init-princ-anon    |
 194       | GSS_C_MA_AUTH_TARG_ANON |    (15) | auth-targ-princ-anon    |
 195       | GSS_C_MA_DELEG_CRED     |    (16) | deleg-cred              |
 196       | GSS_C_MA_INTEG_PROT     |    (17) | integ-prot              |
 197       | GSS_C_MA_CONF_PROT      |    (18) | conf-prot               |
 198       | GSS_C_MA_MIC            |    (19) | mic                     |
 199       | GSS_C_MA_WRAP           |    (20) | wrap                    |
 200       | GSS_C_MA_PROT_READY     |    (21) | prot-ready              |
 201       | GSS_C_MA_REPLAY_DET     |    (22) | replay-detection        |
 202       | GSS_C_MA_OOS_DET        |    (23) | oos-detection           |
 203       | GSS_C_MA_CBINDINGS      |    (24) | channel-bindings        |
 204       | GSS_C_MA_PFS            |    (25) | pfs                     |
 205       | GSS_C_MA_COMPRESS       |    (26) | compress                |
 206       | GSS_C_MA_CTX_TRANS      |    (27) | context-transfer        |
 207       | <reserved>              | (28...) |                         |
 208       +-------------------------+---------+-------------------------+
 209
 210                                   Table 1
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226 Williams                    Standards Track                     [Page 4]
 227 \f
 228 RFC 5587               Extended GSS Mech Inquiry               July 2009
 229
 230
 231    +-------------------------+-----------------------------------------+
 232    | Mech Attr Name          | Purpose                                 |
 233    +-------------------------+-----------------------------------------+
 234    | GSS_C_MA_MECH_CONCRETE  | Indicates that a mech is neither a      |
 235    |                         | pseudo-mechanism nor a composite        |
 236    |                         | mechanism.                              |
 237    | GSS_C_MA_MECH_PSEUDO    | Indicates that a mech is a              |
 238    |                         | pseudo-mechanism.                       |
 239    | GSS_C_MA_MECH_COMPOSITE | Indicates that a mech is a composite of |
 240    |                         | other mechanisms.  This is reserved for |
 241    |                         | a specification of "stackable"          |
 242    |                         | pseudo-mechanisms.                      |
 243    | GSS_C_MA_MECH_NEGO      | Indicates that a mech negotiates other  |
 244    |                         | mechs (e.g., SPNEGO has this            |
 245    |                         | attribute).                             |
 246    | GSS_C_MA_MECH_GLUE      | Indicates that the OID is not for a     |
 247    |                         | mechanism but for the GSS-API itself.   |
 248    | GSS_C_MA_NOT_MECH       | Indicates that the OID is known, yet it |
 249    |                         | is also known not to be the OID of any  |
 250    |                         | GSS-API mechanism (or of the GSS-API    |
 251    |                         | itself).                                |
 252    | GSS_C_MA_DEPRECATED     | Indicates that a mech (or its OID) is   |
 253    |                         | deprecated and MUST NOT be used as a    |
 254    |                         | default mechanism.                      |
 255    | GSS_C_MA_NOT_DFLT_MECH  | Indicates that a mech (or its OID) MUST |
 256    |                         | NOT be used as a default mechanism.     |
 257    | GSS_C_MA_ITOK_FRAMED    | Indicates that the given mechanism's    |
 258    |                         | initial context tokens are properly     |
 259    |                         | framed as per Section 3.1 of [RFC2743]. |
 260    | GSS_C_MA_AUTH_INIT      | Indicates support for authentication of |
 261    |                         | initiator to acceptor.                  |
 262    | GSS_C_MA_AUTH_TARG      | Indicates support for authentication of |
 263    |                         | acceptor to initiator.                  |
 264    | GSS_C_MA_AUTH_INIT_INIT | Indicates support for "initial"         |
 265    |                         | authentication of initiator to          |
 266    |                         | acceptor.  "Initial authentication"     |
 267    |                         | refers to the use of passwords, or keys |
 268    |                         | stored on tokens, for authentication.   |
 269    |                         | Whether a mechanism supports initial    |
 270    |                         | authentication may depend on IETF       |
 271    |                         | consensus (see Security                 |
 272    |                         | Considerations).                        |
 273    | GSS_C_MA_AUTH_TARG_INIT | Indicates support for initial           |
 274    |                         | authentication of acceptor to           |
 275    |                         | initiator.                              |
 276    | GSS_C_MA_AUTH_INIT_ANON | Indicates support for                   |
 277    |                         | GSS_C_NT_ANONYMOUS as an initiator      |
 278    |                         | principal name.                         |
 279
 280
 281
 282 Williams                    Standards Track                     [Page 5]
 283 \f
 284 RFC 5587               Extended GSS Mech Inquiry               July 2009
 285
 286
 287    | GSS_C_MA_AUTH_TARG_ANON | Indicates support for                   |
 288    |                         | GSS_C_NT_ANONYMOUS as a target          |
 289    |                         | principal name.                         |
 290    | GSS_C_MA_DELEG_CRED     | Indicates support for credential        |
 291    |                         | delegation.                             |
 292    | GSS_C_MA_INTEG_PROT     | Indicates support for per-message       |
 293    |                         | integrity protection.                   |
 294    | GSS_C_MA_CONF_PROT      | Indicates support for per-message       |
 295    |                         | confidentiality protection.             |
 296    | GSS_C_MA_MIC            | Indicates support for Message Integrity |
 297    |                         | Code (MIC) tokens.                      |
 298    | GSS_C_MA_WRAP           | Indicates support for WRAP tokens.      |
 299    | GSS_C_MA_PROT_READY     | Indicates support for per-message       |
 300    |                         | protection prior to full context        |
 301    |                         | establishment.                          |
 302    | GSS_C_MA_REPLAY_DET     | Indicates support for replay detection. |
 303    | GSS_C_MA_OOS_DET        | Indicates support for out-of-sequence   |
 304    |                         | detection.                              |
 305    | GSS_C_MA_CBINDINGS      | Indicates support for channel bindings. |
 306    | GSS_C_MA_PFS            | Indicates support for Perfect Forward   |
 307    |                         | Security.                               |
 308    | GSS_C_MA_COMPRESS       | Indicates support for compression of    |
 309    |                         | data inputs to GSS_Wrap().              |
 310    | GSS_C_MA_CTX_TRANS      | Indicates support for security context  |
 311    |                         | export/import.                          |
 312    +-------------------------+-----------------------------------------+
 313
 314                                   Table 2
 315
 316 3.3.  Mechanism Attribute Sets of Existing Mechs
 317
 318    The Kerberos V mechanism [RFC1964] provides the following mechanism
 319    attributes:
 320
 321    o  GSS_C_MA_MECH_CONCRETE
 322
 323    o  GSS_C_MA_ITOK_FRAMED
 324
 325    o  GSS_C_MA_AUTH_INIT
 326
 327    o  GSS_C_MA_AUTH_TARG
 328
 329    o  GSS_C_MA_DELEG_CRED
 330
 331    o  GSS_C_MA_INTEG_PROT
 332
 333    o  GSS_C_MA_CONF_PROT
 334
 335
 336
 337
 338 Williams                    Standards Track                     [Page 6]
 339 \f
 340 RFC 5587               Extended GSS Mech Inquiry               July 2009
 341
 342
 343    o  GSS_C_MA_MIC
 344
 345    o  GSS_C_MA_WRAP
 346
 347    o  GSS_C_MA_PROT_READY
 348
 349    o  GSS_C_MA_REPLAY_DET
 350
 351    o  GSS_C_MA_OOS_DET
 352
 353    o  GSS_C_MA_CBINDINGS
 354
 355    o  GSS_C_MA_CTX_TRANS (some implementations, using implementation-
 356       specific exported context token formats)
 357
 358    The Kerberos V mechanism also has a deprecated OID that has the same
 359    mechanism attributes as above as well as GSS_C_MA_DEPRECATED.
 360
 361    The mechanism attributes of the Simple Public-Key GSS-API Mechanism
 362    (SPKM) [RFC2025] family of mechanisms will be provided in a separate
 363    document, as SPKM is currently being reviewed for possibly
 364    significant changes due to problems in its specifications.
 365
 366    The Low Infrastructure Public Key (LIPKEY) mechanism [RFC2847] offers
 367    the following attributes:
 368
 369    o  GSS_C_MA_MECH_CONCRETE
 370
 371    o  GSS_C_MA_ITOK_FRAMED
 372
 373    o  GSS_C_MA_AUTH_INIT_INIT
 374
 375    o  GSS_C_MA_AUTH_TARG (from SPKM-3)
 376
 377    o  GSS_C_MA_AUTH_TARG_ANON (from SPKM-3)
 378
 379    o  GSS_C_MA_INTEG_PROT
 380
 381    o  GSS_C_MA_CONF_PROT
 382
 383    o  GSS_C_MA_REPLAY_DET
 384
 385    o  GSS_C_MA_OOS_DET
 386
 387    o  GSS_C_MA_CTX_TRANS (some implementations, using implementation-
 388       specific exported context token formats)
 389
 390
 391
 392
 393
 394 Williams                    Standards Track                     [Page 7]
 395 \f
 396 RFC 5587               Extended GSS Mech Inquiry               July 2009
 397
 398
 399       (LIPKEY should also provide GSS_C_MA_CBINDINGS, but SPKM-3
 400       requires clarifications on this point.)
 401
 402    The SPNEGO mechanism [RFC4178] provides the following attributes:
 403
 404    o  GSS_C_MA_MECH_NEGO
 405
 406    o  GSS_C_MA_ITOK_FRAMED
 407
 408    All other mechanisms' attributes will be described elsewhere.
 409
 410 3.4.  New GSS-API Function Interfaces
 411
 412    Several new interfaces are given by which, for example, GSS-API
 413    applications may determine what features are provided by a given
 414    mechanism and what mechanisms provide what features.
 415
 416    These new interfaces are all OPTIONAL.
 417
 418    Applications should use GSS_Indicate_mechs_by_attrs() instead of
 419    GSS_Indicate_mechs() wherever possible.
 420
 421    Applications can use GSS_Indicate_mechs_by_attrs() to determine what,
 422    if any, mechanisms provide a given set of features.
 423
 424    GSS_Indicate_mechs_by_attrs() can also be used to indicate (as in
 425    GSS_Indicate_mechs()) the set of available mechanisms of each type
 426    (concrete, mechanism negotiation pseudo-mechanism, etc.).
 427
 428 3.4.1.  Mechanism Attribute Criticality
 429
 430    Mechanism attributes may be added at any time.  Not only may
 431    attributes be added to the list of known mechanism attributes at any
 432    time, but the set of mechanism attributes supported by a mechanism
 433    can be changed at any time.
 434
 435    For example, new attributes might be added to reflect whether a
 436    mechanism's initiator must contact an online infrastructure and/or
 437    whether the acceptor must do so.  In this example, the Kerberos V
 438    mechanism would gain a new attribute even though the mechanism itself
 439    is not modified.
 440
 441    Applications making use of attributes not defined herein would then
 442    have no way of knowing whether a GSS-API implementation and its
 443    mechanisms know about new mechanism attributes.  To address this
 444    problem, GSS_Indicate_mechs_by_attrs() and
 445    GSS_Inquire_attrs_for_mech() support a notion of critical mechanism
 446    attributes.  Applications can search for mechanisms that understand
 447
 448
 449
 450 Williams                    Standards Track                     [Page 8]
 451 \f
 452 RFC 5587               Extended GSS Mech Inquiry               July 2009
 453
 454
 455    mechanism attributes that are critical to the application, and the
 456    application may ask what mechanism attributes are understood by a
 457    given mechanism.
 458
 459 3.4.2.  GSS_Indicate_mechs_by_attrs()
 460
 461    Inputs:
 462
 463    o  desired_mech_attrs SET OF OBJECT IDENTIFIER -- set of GSS_C_MA_*
 464       OIDs that the mechanisms indicated in the mechs output parameter
 465       MUST offer.
 466
 467    o  except_mech_attrs SET OF OBJECT IDENTIFIER -- set of GSS_C_MA_*
 468       OIDs that the mechanisms indicated in the mechs output parameter
 469       MUST NOT offer.
 470
 471    o  critical_mech_attrs SET OF OBJECT IDENTIFIER -- set of GSS_C_MA_*
 472       OIDs that the mechanisms indicated in the mechs output parameter
 473       MUST understand (i.e., mechs must know whether critical attributes
 474       are or are not supported).
 475
 476    Outputs:
 477
 478    o  major_status INTEGER
 479
 480    o  minor_status INTEGER
 481
 482    o  mechs SET OF OBJECT IDENTIFIER -- set of mechanisms that support
 483       the given desired_mech_attrs but not the except_mech_attrs, and
 484       all of which understand the given critical_mech_attrs (the caller
 485       must release this output with GSS_Release_oid_set()).
 486
 487    Return major_status codes:
 488
 489    o  GSS_S_COMPLETE indicates success; the output mechs parameter MAY
 490       be the empty set (GSS_C_NO_OID_SET).
 491
 492    o  GSS_S_FAILURE indicates that the request failed for some other
 493       reason.
 494
 495    GSS_Indicate_mechs_by_attrs() returns the set of OIDs corresponding
 496    to mechanisms that offer at least the desired_mech_attrs but none of
 497    the except_mech_attrs, and that understand all of the attributes
 498    listed in critical_mech_attrs.
 499
 500    When all three sets of OID input parameters are the empty set, this
 501    function acts as a version of GSS_indicate_mechs() that outputs the
 502    set of all supported mechanisms.
 503
 504
 505
 506 Williams                    Standards Track                     [Page 9]
 507 \f
 508 RFC 5587               Extended GSS Mech Inquiry               July 2009
 509
 510
 511 3.4.3.  GSS_Inquire_attrs_for_mech()
 512
 513    Inputs:
 514
 515    o  mech OBJECT IDENTIFIER -- mechanism OID
 516
 517    Outputs:
 518
 519    o  major_status INTEGER
 520
 521    o  minor_status INTEGER
 522
 523    o  mech_attrs SET OF OBJECT IDENTIFIER -- set of mech_attrs OIDs
 524       (GSS_C_MA_*) supported by the mechanism (the caller must release
 525       this output with GSS_Release_oid_set()).
 526
 527    o  known_mech_attrs SET OF OBJECT IDENTIFIER -- set of mech_attrs
 528       OIDs known to the mechanism implementation (the caller must
 529       release this output with GSS_Release_oid_set()).
 530
 531    Return major_status codes:
 532
 533    o  GSS_S_COMPLETE indicates success; the output mech_attrs parameter
 534       MAY be the empty set (GSS_C_NO_OID_SET).
 535
 536    o  GSS_S_BAD_MECH indicates that the mechanism named by the mech
 537       parameter does not exist or that the mech is GSS_C_NO_OID and no
 538       default mechanism could be determined.
 539
 540    o  GSS_S_FAILURE indicates that the request failed for some other
 541       reason.
 542
 543    GSS_Inquire_attrs_for_mech() indicates the set of mechanism
 544    attributes supported by a given mechanism.
 545
 546 3.4.4.  GSS_Display_mech_attr()
 547
 548    Inputs:
 549
 550    o  mech_attr OBJECT IDENTIFIER -- mechanism attribute OID
 551
 552    Outputs:
 553
 554    o  major_status INTEGER
 555
 556    o  minor_status INTEGER
 557
 558
 559
 560
 561
 562 Williams                    Standards Track                    [Page 10]
 563 \f
 564 RFC 5587               Extended GSS Mech Inquiry               July 2009
 565
 566
 567    o  name OCTET STRING, -- name of mechanism attribute (e.g.,
 568       GSS_C_MA_*).
 569
 570    o  short_desc OCTET STRING, -- a short description of the mechanism
 571       attribute (the caller must release this output with
 572       GSS_Release_buffer()).
 573
 574    o  long_desc OCTET STRING -- a longer description of the mechanism
 575       attribute (the caller must release this output with
 576       GSS_Release_buffer()).
 577
 578    Return major_status codes:
 579
 580    o  GSS_S_COMPLETE indicates success.
 581
 582    o  GSS_S_BAD_MECH_ATTR indicates that the mechanism attribute
 583       referenced by the mech_attr parameter is unknown to the
 584       implementation.
 585
 586    o  GSS_S_FAILURE indicates that the request failed for some other
 587       reason.
 588
 589    This function can be used to obtain human-readable descriptions of
 590    GSS-API mechanism attributes.
 591
 592 3.4.5.  New Major Status Values
 593
 594    A single, new, major status code is added for
 595    GSS_Display_mech_attr():
 596
 597    o  GSS_S_BAD_MECH_ATTR,
 598
 599    roughly corresponding to GSS_S_BAD_MECH but applicable to mechanism
 600    attribute OIDs rather than to mechanism OIDs.
 601
 602    For the C-bindings of the GSS-API [RFC2744], GSS_S_BAD_MECH_ATTR
 603    shall have a routine error number of 19 (this is shifted to the left
 604    by GSS_C_ROUTINE_ERROR_OFFSET).
 605
 606 3.4.6.  C-Bindings
 607
 608    Note that there is a bug in the C bindings of the GSS-APIv2u1
 609    [RFC2744] in that the C 'const' attribute is applied to types that
 610    are pointer typedefs.  This is a bug because it declares that the
 611    pointer argument is 'const' rather than that the object pointed by it
 612    is const.  To avoid this error, we hereby define new typedefs, which
 613    include const properly:
 614
 615
 616
 617
 618 Williams                    Standards Track                    [Page 11]
 619 \f
 620 RFC 5587               Extended GSS Mech Inquiry               July 2009
 621
 622
 623       typedef const gss_buffer_desc * gss_const_buffer_t;
 624       typedef const struct gss_channel_bindings_struct *
 625          gss_const_channel_bindings_t;
 626       typedef const <platform-specific> gss_const_ctx_id_t;
 627       typedef const <platform-specific> gss_const_cred_id_t;
 628       typedef const <platform-specific> gss_const_name_t;
 629       typedef const gss_OID_desc * gss_const_OID;
 630       typedef const gss_OID_set_desc * gss_const_OID_set;
 631
 632                          Figure 1: const typedefs
 633
 634    Note that only gss_const_OID and gss_const_OID_set are used below.
 635    We include the other const typedefs for convenience since the C
 636    bindings of the GSS-API do use const with pointer typedefs when it
 637    should often instead use the above typedefs instead.
 638
 639       #define GSS_S_BAD_MECH_ATTR (19ul << GSS_C_ROUTINE_ERROR_OFFSET)
 640
 641       OM_uint32 gss_indicate_mechs_by_attrs(
 642          OM_uint32         *minor_status,
 643          gss_const_OID_set  desired_mech_attrs,
 644          gss_const_OID_set  except_mech_attrs,
 645          gss_const_OID_set  critical_mech_attrs,
 646          gss_OID_set       *mechs);
 647
 648       OM_uint32 gss_inquire_attrs_for_mech(
 649          OM_uint32         *minor_status,
 650          gss_const_OID      mech,
 651          gss_OID_set       *mech_attrs,
 652          gss_OID_set       *known_mech_attrs);
 653
 654       OM_uint32 gss_display_mech_attr(
 655          OM_uint32         *minor_status,
 656          gss_const_OID      mech_attr,
 657          gss_buffer_t       name,
 658          gss_buffer_t       short_desc,
 659          gss_buffer_t       long_desc);
 660
 661                            Figure 2: C bindings
 662
 663    Note that output buffers must be released via gss_release_buffer().
 664    Output OID sets must be released via gss_release_oid_set().
 665
 666    Please see Appendix A for a full set of typedef fragments defined in
 667    this document and the necessary code license.
 668
 669
 670
 671
 672
 673
 674 Williams                    Standards Track                    [Page 12]
 675 \f
 676 RFC 5587               Extended GSS Mech Inquiry               July 2009
 677
 678
 679 4.  Requirements for Mechanism Designers
 680
 681    All future GSS-API mechanism specifications MUST:
 682
 683    o  list the set of GSS-API mechanism attributes associated with them.
 684
 685 5.  IANA Considerations
 686
 687    The namespace of programming-language symbols with names beginning
 688    with GSS_C_MA_* is reserved for allocation by IETF Consensus.  IANA
 689    allocated a base OID, as an arc of 1.3.6.1.5.5, for the set of
 690    GSS_C_MA_* described herein, and registered all of the GSS_C_MA_*
 691    values described in Section 3.2.
 692
 693 6.  Security Considerations
 694
 695    This document specifies extensions to a security-related API.  It
 696    imposes new requirements on future GSS-API mechanisms, and the
 697    specifications of future protocols that use the GSS-API should make
 698    reference to this document where applicable.  The ability to inquire
 699    about specific properties of mechanisms should improve security.
 700
 701    The semantics of each mechanism attribute may include a security
 702    component.
 703
 704    Application developers must understand that mechanism attributes may
 705    be added at any time -- both to the set of known mechanism attributes
 706    as well as to existing mechanisms' sets of supported mechanism
 707    attributes.  Therefore, application developers using the APIs
 708    described herein must understand what mechanism attributes their
 709    applications depend critically on, and must use the mechanism
 710    attribute criticality features of these APIs.
 711
 712 7.  References
 713
 714 7.1.  Normative References
 715
 716    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 717               Requirement Levels", BCP 14, RFC 2119, March 1997.
 718
 719    [RFC2743]  Linn, J., "Generic Security Service Application Program
 720               Interface Version 2, Update 1", RFC 2743, January 2000.
 721
 722    [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
 723               C-bindings", RFC 2744, January 2000.
 724
 725
 726
 727
 728
 729
 730 Williams                    Standards Track                    [Page 13]
 731 \f
 732 RFC 5587               Extended GSS Mech Inquiry               July 2009
 733
 734
 735 7.2.  Informative References
 736
 737    [RFC1964]  Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
 738               RFC 1964, June 1996.
 739
 740    [RFC2025]  Adams, C., "The Simple Public-Key GSS-API Mechanism
 741               (SPKM)", RFC 2025, October 1996.
 742
 743    [RFC2847]  Eisler, M., "LIPKEY - A Low Infrastructure Public Key
 744               Mechanism Using SPKM", RFC 2847, June 2000.
 745
 746    [RFC4178]  Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
 747               Simple and Protected Generic Security Service Application
 748               Program Interface (GSS-API) Negotiation Mechanism",
 749               RFC 4178, October 2005.
 750
 751    [RFC4251]  Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
 752               Protocol Architecture", RFC 4251, January 2006.
 753
 754    [RFC4462]  Hutzelman, J., Salowey, J., Galbraith, J., and V. Welch,
 755               "Generic Security Service Application Program Interface
 756               (GSS-API) Authentication and Key Exchange for the Secure
 757               Shell (SSH) Protocol", RFC 4462, May 2006.
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786 Williams                    Standards Track                    [Page 14]
 787 \f
 788 RFC 5587               Extended GSS Mech Inquiry               July 2009
 789
 790
 791 Appendix A.  Typedefs and C Bindings
 792
 793    This appendix contains the full set of code fragments defined in this
 794    document.
 795
 796    Copyright (c) 2009 IETF Trust and the persons identified as authors
 797    of the code.  All rights reserved.
 798
 799    Redistribution and use in source and binary forms, with or without
 800    modification, are permitted provided that the following conditions
 801    are met:
 802
 803    - Redistributions of source code must retain the above copyright
 804      notice, this list of conditions and the following disclaimer.
 805
 806    - Redistributions in binary form must reproduce the above copyright
 807      notice, this list of conditions and the following disclaimer in the
 808      documentation and/or other materials provided with the
 809      distribution.
 810
 811    - Neither the name of Internet Society, IETF or IETF Trust, nor the
 812      names of specific contributors, may be used to endorse or promote
 813      products derived from this software without specific prior written
 814      permission.
 815
 816    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 817    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 818    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
 819    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 820    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 821    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 822    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 823    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 824    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 825    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 826
 827    typedef const gss_buffer_desc * gss_const_buffer_t;
 828    typedef const struct gss_channel_bindings_struct *
 829       gss_const_channel_bindings_t;
 830    typedef const <platform-specific> gss_const_ctx_id_t;
 831    typedef const <platform-specific> gss_const_cred_id_t;
 832    typedef const <platform-specific> gss_const_name_t;
 833    typedef const gss_OID_desc * gss_const_OID;
 834    typedef const gss_OID_set_desc * gss_const_OID_set;
 835
 836
 837
 838
 839
 840
 841
 842 Williams                    Standards Track                    [Page 15]
 843 \f
 844 RFC 5587               Extended GSS Mech Inquiry               July 2009
 845
 846
 847    #define GSS_S_BAD_MECH_ATTR (19ul << GSS_C_ROUTINE_ERROR_OFFSET)
 848
 849    OM_uint32 gss_indicate_mechs_by_attrs(
 850       OM_uint32         *minor_status,
 851       gss_const_OID_set  desired_mech_attrs,
 852       gss_const_OID_set  except_mech_attrs,
 853       gss_const_OID_set  critical_mech_attrs,
 854       gss_OID_set       *mechs);
 855
 856    OM_uint32 gss_inquire_attrs_for_mech(
 857       OM_uint32         *minor_status,
 858       gss_const_OID      mech,
 859       gss_OID_set       *mech_attrs,
 860       gss_OID_set       *known_mech_attrs);
 861
 862    OM_uint32 gss_display_mech_attr(
 863       OM_uint32         *minor_status,
 864       gss_const_OID      mech_attr,
 865       gss_buffer_t       name,
 866       gss_buffer_t       short_desc,
 867       gss_buffer_t       long_desc);
 868
 869 Author's Address
 870
 871    Nicolas Williams
 872    Sun Microsystems
 873    5300 Riata Trace Ct
 874    Austin, TX  78727
 875    US
 876
 877    EMail: Nicolas.Williams@sun.com
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898 Williams                    Standards Track                    [Page 16]
 899 \f