source4/heimdal/doc/standardisation/draft-ietf-kitten-gssapi-naming-exts-00.txt

   1 Internet-Draft                                                       Sun
   2 Expires: November 14, 2005                                  May 13, 2005
   3
   4
   5                        GSS-API Naming Extensions
   6               draft-ietf-kitten-gssapi-naming-exts-00.txt
   7
   8 Status of this Memo
   9
  10    By submitting this Internet-Draft, each author represents that any
  11    applicable patent or other IPR claims of which he or she is aware
  12    have been or will be disclosed, and any of which he or she becomes
  13    aware will be disclosed, in accordance with Section 6 of BCP 79.
  14
  15    Internet-Drafts are working documents of the Internet Engineering
  16    Task Force (IETF), its areas, and its working groups.  Note that
  17    other groups may also distribute working documents as Internet-
  18    Drafts.
  19
  20    Internet-Drafts are draft documents valid for a maximum of six months
  21    and may be updated, replaced, or obsoleted by other documents at any
  22    time.  It is inappropriate to use Internet-Drafts as reference
  23    material or to cite them other than as "work in progress."
  24
  25    The list of current Internet-Drafts can be accessed at
  26    http://www.ietf.org/ietf/1id-abstracts.txt.
  27
  28    The list of Internet-Draft Shadow Directories can be accessed at
  29    http://www.ietf.org/shadow.html.
  30
  31    This Internet-Draft will expire on November 14, 2005.
  32
  33 Copyright Notice
  34
  35    Copyright (C) The Internet Society (2005).
  36
  37 Abstract
  38
  39    The Generic Security Services API (GSS-API) provides a simple naming
  40    architecture that supports name-based authorization.  This document
  41    introduces new APIs that extend the GSS-API naming and authorization
  42    model.
  43
  44
  45
  46
  47
  48
  49
  50
  51 Williams                Expires November 14, 2005               [Page 1]
  52 \f
  53 Internet-Draft          GSS-API Naming Extensions               May 2005
  54
  55
  56 Table of Contents
  57
  58    1.    Conventions used in this document  . . . . . . . . . . . . .  3
  59    2.    Introduction . . . . . . . . . . . . . . . . . . . . . . . .  3
  60    3.    Name Attribute Sources and Criticality . . . . . . . . . . .  3
  61    4.    Name Attributes/Values as ACL Subjects . . . . . . . . . . .  4
  62    5.    Mapping Mechanism Facilities to Name Attributes  . . . . . .  4
  63    5.1   Kerberos V and SPKM Authorization-Data . . . . . . . . . . .  4
  64    5.2   Kerberos V Cross-Realm Transit Paths . . . . . . . . . . . .  5
  65    5.3   PKIX Certificate Extensions  . . . . . . . . . . . . . . . .  5
  66    5.3.1 PKIX EKUs  . . . . . . . . . . . . . . . . . . . . . . . . .  5
  67    5.3.2 PKIX Certificate Alternative Names . . . . . . . . . . . . .  6
  68    5.3.3 Other PKIX Certificate Extensions and Attributes . . . . . .  6
  69    5.4   PKIX Certificate CA Paths and Trust Anchors  . . . . . . . .  6
  70    6.    GSS_Inquire_name_attribute() . . . . . . . . . . . . . . . .  6
  71    6.1   C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . .  7
  72    6.2   Java Bindings  . . . . . . . . . . . . . . . . . . . . . . .  7
  73    7.    GSS_Display_name_ext() . . . . . . . . . . . . . . . . . . .  7
  74    7.1   C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . .  8
  75    7.2   Java Bindings  . . . . . . . . . . . . . . . . . . . . . . .  8
  76    8.    GSS_Inquire_name() . . . . . . . . . . . . . . . . . . . . .  8
  77    8.1   C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . .  9
  78    8.2   Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 10
  79    9.    GSS_Get_name_attribute() . . . . . . . . . . . . . . . . . . 10
  80    9.1   C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 11
  81    9.2   Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 11
  82    10.   GSS_Set_name_attribute() . . . . . . . . . . . . . . . . . . 12
  83    10.1  C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 12
  84    10.2  Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 12
  85    11.   GSS_Delete_name_attribute()  . . . . . . . . . . . . . . . . 13
  86    11.1  C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 13
  87    11.2  Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 13
  88    12.   GSS_Export_name_composite()  . . . . . . . . . . . . . . . . 14
  89    12.1  C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 14
  90    12.2  Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 14
  91    13.   GSS_Map_name_to_any()  . . . . . . . . . . . . . . . . . . . 15
  92    13.1  C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 15
  93    13.2  Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 16
  94    14.   GSS_Release_any_name_mapping() . . . . . . . . . . . . . . . 16
  95    14.1  C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 16
  96    14.2  Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . 17
  97    15.   IANA Considerations  . . . . . . . . . . . . . . . . . . . . 17
  98    16.   Security Considerations  . . . . . . . . . . . . . . . . . . 17
  99    17.   References . . . . . . . . . . . . . . . . . . . . . . . . . 18
 100    17.1  Normative References . . . . . . . . . . . . . . . . . . . . 18
 101    17.2  Informative References . . . . . . . . . . . . . . . . . . . 18
 102          Author's Address . . . . . . . . . . . . . . . . . . . . . . 18
 103          Intellectual Property and Copyright Statements . . . . . . . 20
 104
 105
 106
 107 Williams                Expires November 14, 2005               [Page 2]
 108 \f
 109 Internet-Draft          GSS-API Naming Extensions               May 2005
 110
 111
 112 1.  Conventions used in this document
 113
 114    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 115    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 116    document are to be interpreted as described in [RFC2119].
 117
 118 2.  Introduction
 119
 120    As described in [I-D.GSS-NAMING] the GSS-API's naming architecture
 121    suffers from certain limitations.  This document proposes concrete
 122    GSS-API extensions as outlined in [I-D.GSS-NAMING].
 123
 124    A number of extensions to the GSS-API are described herein with the
 125    goal of making authorization information, and other information that
 126    can be modelled as "name attributes" available as such to
 127    applications.  For example, Kerberos V authorization data elements,
 128    both, in their raw forms as well as mapped to more useful value
 129    types, can be made available to GSS-API applications through these
 130    interfaces.
 131
 132    The model is that GSS names have attributes.  The attributes of a
 133    name may be authenticated by the credential whence the name comes, or
 134    may have been set locally on a GSS name for the purpose of
 135    "asserting" the attribute during credential acquisition or security
 136    context exchange.  Name attributes' values are network
 137    representations thereof (e.g., the actual value octets of the
 138    contents of an X.509 certificate extension, for example) and are
 139    intended to be useful for constructing portable access control
 140    facilities.  Applications may often require language- or platform-
 141    specific data types, rather than network representations of name
 142    attributes, so a function is provided to obtain objects of such types
 143    associated with names and name attributes.
 144
 145 3.  Name Attribute Sources and Criticality
 146
 147    A given GSS name object's name attributes may be authenticated or
 148    asserted by an associated credential, or it may be mapped or derived
 149    from another attribute of the same name.
 150
 151    That a given name's given attribute is 'mapped' means that it was
 152    obtained through some mapping mechanism applied to another attribute
 153    of the name that was not, itself, mapped.  For example, such
 154    attributes as platform-specific internal identifiers may sometimes be
 155    mapped from other name attributes.
 156
 157    Name attributes may be "critical," meaning that applications that do
 158    not understand them MUST reject security contexts where the peer has
 159    such unknown, critical attributes.
 160
 161
 162
 163 Williams                Expires November 14, 2005               [Page 3]
 164 \f
 165 Internet-Draft          GSS-API Naming Extensions               May 2005
 166
 167
 168 4.  Name Attributes/Values as ACL Subjects
 169
 170    Some name attributes (e.g., numeric user or group identifiers) may be
 171    useful as subjects of access control list (ACL) entries, some may not
 172    (e.g., time of day login restrictions).  The
 173    GSS_Inquire_name_attribute() function indicates this.
 174
 175    To facilitate the development of portable applications that make use
 176    of name attributes to construct and evaluate portable ACLs the GSS-
 177    API makes name attribute values available in canonical network
 178    encodings thereof.
 179
 180    To facilitate the development of platform- or language-specific
 181    applications that need access to native types of representations of
 182    name attributes an optional facility is provided,
 183    GSS_Map_name_to_any().
 184
 185 5.  Mapping Mechanism Facilities to Name Attributes
 186
 187    [NOTE:  This entire section should probably be split into one or more
 188    separate Internet-Drafts.  It is here in the -00 of this I-D to help
 189    readers understand how to mechanism-specific name attributes would be
 190    accessed through these GSS-API extensions.]
 191
 192    Kerberos V [I-D.ietf-krb-wg-kerberos-clarifications] and the Simple
 193    Public-Key GSS-API Mechanism, SPKM [RFC2025], both support the
 194    concept and encoding of containers of "authorization-data" as
 195    described in [I-D.ietf-krb-wg-kerberos-clarifications].
 196
 197    PKIX [RFC3280] supports a number of authorization-data-like features,
 198    like Extended Key Usage values (EKUs) and certificate extensions.
 199
 200    The authorization data can be accessed through the GSS-API name
 201    attributes facility defined herein.
 202
 203 5.1  Kerberos V and SPKM Authorization-Data
 204
 205    Authorization-data non-container elements asserted in Kerberos V AP-
 206    REQ Authenticators MUST be mapped into *asserted* GSS-API name
 207    attributes; if not contained in AD-IF-RELEVANT then they MUST be
 208    mapped into *critical* GSS-API name attributes.  AD-AND-OR
 209    authorization-data elements MUST be mapped into a single *critical*
 210    attribute, (TBD).
 211
 212    Authorization-data included in Kerberos V Tickets that is not
 213    contained in AD-KDCIssued (with valid signature) MUST be mapped into
 214    *asserted* GSS-API name attributes.  Conversely, authorization-data
 215    elements in Kerberos V Tickets contained by AD-KDCIssued MUST be
 216
 217
 218
 219 Williams                Expires November 14, 2005               [Page 4]
 220 \f
 221 Internet-Draft          GSS-API Naming Extensions               May 2005
 222
 223
 224    mapped into *authenticated* GSS-API name attributes
 225
 226    As with authorization-data elements in Authenticators, authorization-
 227    data elements in Tickets not contained in AD-IF-RELEVANT are to be
 228    mapped to *critical* name attributes, and similarly with AD-AND-OR
 229    (see above).
 230
 231    The OIDs for authorization-data elements are to be the authorization-
 232    data element's 'ad-type' integer ID, relative to the base OID <TBD>
 233    [NOTE: what about negative ad-type's?  OID arcs are positive
 234    integers... ad-type is an Int32, so clearly something can be done.]
 235
 236 5.2  Kerberos V Cross-Realm Transit Paths
 237
 238    [Add text on how to represent/encode/interpret krb5 realm transit
 239    paths as name attribute values.  And text on PKINIT too...  Basically
 240    Ticket's 'transited' field should be exposed as an authenticated name
 241    attribute, with some uncompressed encoding, possibly encompassing
 242    certificate validation paths of client certs used for PKINIT, with
 243    criticality determined by the presence of the transit-policy-checked
 244    flag.]
 245
 246 5.3  PKIX Certificate Extensions
 247
 248    [NOTE:  In the Kerberos V authorization-data case we can tell when AD
 249    elements are "authenticated" and when the are asserted, but what
 250    about x.509 certificate extensions?  Clearly KU, EKUs and
 251    subjectAltNames are authenticated in that no CA should sign a cert
 252    with, say, arbitrary subjectAltNames not understood by the CA, but,
 253    does that also apply to all other x.509 certificate extensions?  The
 254    answer may depend on actual CA operator practices...  At worst a new
 255    extension may be needed, like Kerberos V's AD-KDCIssued AD container
 256    element; at best this text can just say "all cert extensions MUST be
 257    mapped to authenticated..." below.]
 258
 259    PKI certificate extensions MAY/SHOULD/MUST (see comment above) be
 260    mapped to *authenticated* GSS-API name attributes with the _same_
 261    OIDs, and if they be marked critical in the certificate then they
 262    MUST be mapped as *critical* GSS-API name attributes.
 263    SubjectAltNames and EKUs, specifically, MUST be mapped to
 264    *authenticated* GSS-API name attributes; see below.  Certificate
 265    extensions MUST be mapped to GSS-API name attributes whose OIDs are
 266    the same as the extensions'
 267
 268 5.3.1  PKIX EKUs
 269
 270    Extended Key Usage extensions, specifically, MUST be mapped as
 271    described above, except that GSS-API name attributes for EKUs MUST
 272
 273
 274
 275 Williams                Expires November 14, 2005               [Page 5]
 276 \f
 277 Internet-Draft          GSS-API Naming Extensions               May 2005
 278
 279
 280    have NULL values (i.e., zero-length OCTET STRINGs).
 281
 282    PKI certificate key usages (KUs, but not EKUs), MUST NOT be mapped to
 283    GSS-API name attributes.
 284
 285 5.3.2  PKIX Certificate Alternative Names
 286
 287    PKI certificate subjectAltNames MUST be mapped as *authenticated*,
 288    *non-critical* GSS-API name attributes.
 289
 290    PKI certificate extensions MUST be mapped to *authenticated* GSS-API
 291    name attributes with the _same_ OIDs, and if they be marked critical
 292    in the certificate then they MUST be mapped as *critical* GSS-API
 293    name attributes.
 294
 295    Extended Key Usage extensions, specifically, MUST be mapped as
 296    described above, except that GSS-API name attributes for EKUs MUST
 297    have NULL values (i.e., zero-length OCTET STRINGs).
 298
 299 5.3.3  Other PKIX Certificate Extensions and Attributes
 300
 301    [Add text...]
 302
 303 5.4  PKIX Certificate CA Paths and Trust Anchors
 304
 305    [Add text on how to represent/encode/interpret PKI certificate
 306    validation CA paths as name attribute values, much as with Kerberos V
 307    transited paths.]
 308
 309 6.  GSS_Inquire_name_attribute()
 310
 311    Inputs:
 312
 313
 314    o  attr OBJECT IDENTIFIER
 315
 316    Outputs:
 317
 318
 319    o  major_status INTEGER,
 320
 321    o  minor_status INTEGER,
 322
 323    o  attr_name OCTET STRING,
 324
 325    o  attr_description OCTET STRING,
 326
 327    o  attr_is_a_name BOOLEAN,
 328
 329
 330
 331 Williams                Expires November 14, 2005               [Page 6]
 332 \f
 333 Internet-Draft          GSS-API Naming Extensions               May 2005
 334
 335
 336    o  attr_is_trust_indicator BOOLEAN
 337
 338    Return major_status codes:
 339
 340    o  GSS_S_COMPLETE indicates no error.
 341
 342    o  GSS_S_UNAVAILABLE indicates that the given attribute OID is not
 343       known (even if present as a name's attribute).
 344
 345    o  GSS_S_FAILURE indicates a general error.
 346
 347    This function outputs a name for the given name attribute,
 348    description for display to users, indicates whether the given name
 349    attribute's values are useful as the subject of an access control
 350    list entry and/or whether the given name attribute's values are
 351    useful as indicators of trust (for example, whether they name PKIX
 352    trust anchors).
 353
 354 6.1  C-Bindings
 355
 356    OM_uint32 gss_inquire_name_attribute(
 357      OM_uint32                     *minor_status,
 358      gss_OID                       attr,
 359      gss_buffer_t                  attr_name,
 360      gss_buffer_t                  attr_description,
 361      int                           *attr_is_a_name,
 362      int                           *attr_is_trust_indicator
 363    );
 364
 365
 366 6.2  Java Bindings
 367
 368    public String nameAttributeName(Oid attr)
 369       throws GSSException
 370    public String nameAttributeDescription(Oid attr)
 371       throws GSSException
 372    public boolean nameAttributeIsName(Oid attr)
 373       throws GSSException
 374    public boolean nameAttributeIsTrustIndicator(Oid attr)
 375       throws GSSException
 376
 377
 378 7.  GSS_Display_name_ext()
 379
 380    Inputs:
 381
 382
 383    o  name NAME,
 384
 385
 386
 387 Williams                Expires November 14, 2005               [Page 7]
 388 \f
 389 Internet-Draft          GSS-API Naming Extensions               May 2005
 390
 391
 392    o  display_as_name_type OBJECT IDENTIFIER
 393
 394    Outputs:
 395
 396
 397    o  major_status INTEGER,
 398
 399    o  minor_status INTEGER,
 400
 401    o  display_name STRING
 402
 403    Return major_status codes:
 404
 405    o  GSS_S_COMPLETE indicates no error.
 406
 407    o  GSS_S_UNAVAILABLE indicates that the given name could not be
 408       displayed using the syntax of the given name type.
 409
 410    o  GSS_S_FAILURE indicates a general error.
 411
 412    This function displays a given name using the given name syntax, if
 413    possible.  This operation may require mapping MNs to generic name
 414    syntaxes or generic name syntaxes to mechanism-specific name
 415    syntaxes; such mappings may not always be feasible and MAY be inexact
 416    or lossy.
 417
 418 7.1  C-Bindings
 419
 420    OM_uint32 GSS_Display_name_ext(
 421      OM_uint32                     *minor_status,
 422      gss_name_t                    name,
 423      gss_OID                       display_as_name_type,
 424      gss_buffer_t                  display_name
 425    );
 426
 427
 428 7.2  Java Bindings
 429
 430    public String displayExtended(Oid display_as_name_type)
 431       throws GSSException
 432
 433
 434 8.  GSS_Inquire_name()
 435
 436    Inputs:
 437
 438
 439    o  name NAME
 440
 441
 442
 443 Williams                Expires November 14, 2005               [Page 8]
 444 \f
 445 Internet-Draft          GSS-API Naming Extensions               May 2005
 446
 447
 448    Outputs:
 449
 450
 451    o  major_status INTEGER,
 452
 453    o  minor_status INTEGER,
 454
 455    o  name_is_MN BOOLEAN,
 456
 457    o  mn_mech OBJECT IDENTIFIER
 458
 459    o  asserted_attrs SET OF OBJECT IDENTIFIER
 460
 461    o  authenticated_attrs SET OF OBJECT IDENTIFIER
 462
 463    o  critical_attrs SET OF OBJECT IDENTIFIER
 464
 465    o  all_attrs SET OF OBJECT IDENTIFIER
 466
 467    o  [NOTE: Perhaps this function should also output an indicator as to
 468       the provenance of the name, of which, in the GSS-API, there are
 469       three: imported, inquired from a credential, and a peer's name
 470       inquired from a security context.]
 471
 472    Return major_status codes:
 473
 474    o  GSS_S_COMPLETE indicates no error.
 475
 476    o  GSS_S_FAILURE indicates a general error.
 477
 478    This function outputs the sets of attributes of a name, that are
 479    authenticated, asserted or critical.  It also indicates if a given
 480    NAME is an MN or not and, if it is, what mechanism it's an MN of.
 481
 482 8.1  C-Bindings
 483
 484    OM_uint32 gss_inquire_name(
 485      OM_uint32                     *minor_status,
 486      gss_name_t                    name,
 487      int                           name_is_MN,
 488      gss_OID                       *MN_mech,
 489      gss_OID_set                   *authenticated,
 490      gss_OID_set                   *asserted,
 491      gss_OID_set                   *critical,
 492      gss_OID_set                   *all_attrs
 493    );
 494
 495
 496
 497
 498
 499 Williams                Expires November 14, 2005               [Page 9]
 500 \f
 501 Internet-Draft          GSS-API Naming Extensions               May 2005
 502
 503
 504 8.2  Java Bindings
 505
 506    public boolean isMN(boolean authenticated, boolean critical)
 507       throws GSSException
 508    public Oid mnMech(boolean authenticated, boolean critical)
 509       throws GSSException
 510    public Oid[] allAttributes(boolean authenticated, boolean critical)
 511       throws GSSException
 512    public Oid[] authenticatedAttributes(boolean authenticated,
 513       boolean critical) throws GSSException
 514    public Oid[] assertedAttributes(boolean authenticated,
 515       boolean critical) throws GSSException
 516    public Oid[] criticalAttributes(boolean authenticated,
 517       boolean critical) throws GSSException
 518
 519
 520 9.  GSS_Get_name_attribute()
 521
 522    Inputs:
 523
 524
 525    o  name NAME,
 526
 527    o  attr OBJECT IDENTIFIER
 528
 529    Outputs:
 530
 531
 532    o  major_status INTEGER,
 533
 534    o  minor_status INTEGER,
 535
 536    o  authenticated BOOLEAN,
 537
 538    o  mapped BOOLEAN,
 539
 540    o  critical BOOLEAN,
 541
 542    o  values SET OF OCTET STRING,
 543
 544    o  display_values SET OF STRING
 545
 546    Return major_status codes:
 547
 548    o  GSS_S_COMPLETE indicates no error.
 549
 550    o  GSS_S_UNAVAILABLE indicates that the given attribute OID is not
 551       known or set.
 552
 553
 554
 555 Williams                Expires November 14, 2005              [Page 10]
 556 \f
 557 Internet-Draft          GSS-API Naming Extensions               May 2005
 558
 559
 560    o  GSS_S_FAILURE indicates a general error.
 561
 562    This function outputs the value(s) associated with a given GSS name
 563    object for a given name attribute.
 564
 565 9.1  C-Bindings
 566
 567    The C-bindings of GSS_Get_name_attribute() requires one function call
 568    per-attribute value, for multi-valued name attributes.  This is done
 569    by using a single gss_buffer_t for each value and an input/output
 570    integer parameter to distinguish initial and subsequent calls and to
 571    indicate when all values have been obtained.
 572
 573    The 'more' input/output parameter should point to an integer variable
 574    whose value, on first call to gss_name_attribute_get() MUST be -1,
 575    and whose value upon function call return will be non-zero to
 576    indicate that additional values remain, or zero to indicate that no
 577    values remain.  The caller should not modify this parameter after the
 578    initial call.
 579
 580    OM_uint32 gss_get_name_attribute(
 581      OM_uint32                     *minor_status,
 582      gss_name_t                    name,
 583      gss_OID                       attr,
 584      int                           *authenticated,
 585      int                           *mapped,
 586      int                           *critical,
 587      gss_buffer_t                  value,
 588      gss_buffer_t                  display_value,
 589      int                           *more
 590    );
 591
 592
 593 9.2  Java Bindings
 594
 595    public byte[] getAttributeValue(Oid attr)
 596       throws GSSException
 597    public String getAttributeDisplayValue(Oid attr)
 598       throws GSSException
 599    public boolean isAttributeAuthenticated(Oid attr)
 600       throws GSSException
 601    public boolean isAttributeMapped(Oid attr)
 602       throws GSSException
 603    public boolean getAttributeCriticality(Oid attr)
 604       throws GSSException
 605
 606
 607 10.  GSS_Set_name_attribute()
 608
 609
 610
 611 Williams                Expires November 14, 2005              [Page 11]
 612 \f
 613 Internet-Draft          GSS-API Naming Extensions               May 2005
 614
 615
 616    Inputs:
 617
 618
 619    o  name NAME,
 620
 621    o  critical BOOLEAN,
 622
 623    o  attr OBJECT IDENTIFIER,
 624
 625    o  values SET OF OCTET STRING
 626
 627    Outputs:
 628
 629
 630    o  major_status INTEGER,
 631
 632    o  minor_status INTEGER
 633
 634    Return major_status codes:
 635
 636    o  GSS_S_COMPLETE indicates no error.
 637
 638    o  GSS_S_UNAVAILABLE indicates that the given attribute OID is not
 639       known or could not be set.
 640
 641    o  GSS_S_FAILURE indicates a general error.
 642
 643
 644 10.1  C-Bindings
 645
 646    The C-bindings of GSS_Set_name_attribute() requires one function call
 647    per-attribute value, for multi-valued name attributes -- each call
 648    adds one value.  To replace an attribute's every value delete the
 649    attribute's values first with GSS_Delete_name_attribute().
 650
 651    OM_uint32 gss_set_name_attribute(
 652      OM_uint32                     *minor_status,
 653      gss_name_t                    name,
 654      int                           critical,
 655      gss_OID                       attr,
 656      gss_buffer_t                  value
 657    );
 658
 659
 660 10.2  Java Bindings
 661
 662    The Java-bindings of GSS_Set_name_attribute() requires one function
 663    call per-attribute value, for multi-valued name attributes -- each
 664
 665
 666
 667 Williams                Expires November 14, 2005              [Page 12]
 668 \f
 669 Internet-Draft          GSS-API Naming Extensions               May 2005
 670
 671
 672    call adds one value.  To replace an attribute's every value delete
 673    the attribute's values first with GSS_Delete_name_attribute().
 674
 675    public abstract setAttribute(Oid attr, boolean critical,
 676                                 byte[] value)
 677       throws GSSException
 678
 679
 680 11.  GSS_Delete_name_attribute()
 681
 682    Inputs:
 683
 684
 685    o  name NAME,
 686
 687    o  attr OBJECT IDENTIFIER,
 688
 689    Outputs:
 690
 691
 692    o  major_status INTEGER,
 693
 694    o  minor_status INTEGER
 695
 696    Return major_status codes:
 697
 698    o  GSS_S_COMPLETE indicates no error.
 699
 700    o  GSS_S_UNAVAILABLE indicates that the given attribute OID is not
 701       known.
 702
 703    o  GSS_S_FAILURE indicates a general error.
 704
 705
 706 11.1  C-Bindings
 707
 708    OM_uint32 gss_delete_name_attribute(
 709      OM_uint32                     *minor_status,
 710      gss_name_t                    name,
 711      gss_OID                       attr
 712    );
 713
 714
 715 11.2  Java Bindings
 716
 717    public abstract deleteAttribute(Oid attr, boolean critical)
 718       throws GSSException
 719
 720
 721
 722
 723 Williams                Expires November 14, 2005              [Page 13]
 724 \f
 725 Internet-Draft          GSS-API Naming Extensions               May 2005
 726
 727
 728 12.  GSS_Export_name_composite()
 729
 730    Inputs:
 731
 732
 733    o  name NAME
 734
 735    Outputs:
 736
 737
 738    o  major_status INTEGER,
 739
 740    o  minor_status INTEGER,
 741
 742    o  exp_composite_name OCTET STRING
 743
 744    Return major_status codes:
 745
 746    o  GSS_S_COMPLETE indicates no error.
 747
 748    o  GSS_S_FAILURE indicates a general error.
 749
 750    This function outputs a token which can be imported with
 751    GSS_Import_name(), using GSS_C_NT_COMPOSITE_EXPORT as the name type
 752    and which preserves any name attribute information associated with
 753    the input name (which GSS_Export_name() may well not).  The token
 754    format is no specified here as this facility is intended for inter-
 755    process communication only; however, all such tokens MUST start with
 756    a two-octet token ID, hex 04 02, in network byte order.
 757
 758    The OID for GSS_C_NT_COMPOSITE_EXPORT is <TBD>.
 759
 760 12.1  C-Bindings
 761
 762    OM_uint32 gss_export_name_composite(
 763      OM_uint32                     *minor_status,
 764      gss_name_t                    name,
 765      gss_buffer_t                  exp_composite_name
 766    );
 767
 768
 769 12.2  Java Bindings
 770
 771    public byte[] exportComposite()
 772       throws GSSException
 773
 774
 775 13.  GSS_Map_name_to_any()
 776
 777
 778
 779 Williams                Expires November 14, 2005              [Page 14]
 780 \f
 781 Internet-Draft          GSS-API Naming Extensions               May 2005
 782
 783
 784    Inputs:
 785
 786
 787    o  name NAME,
 788
 789    o  authenticated BOOLEAN, -- if TRUE no data will be output unless it
 790       is authenticated
 791
 792    o  type_id OBJECT IDENTIFIER
 793
 794    Outputs:
 795
 796
 797    o  major_status INTEGER,
 798
 799    o  minor_status INTEGER,
 800
 801    o  output ANY DEFINED BY type_id
 802
 803    Return major_status codes:
 804
 805    o  GSS_S_COMPLETE indicates no error.
 806
 807    o  GSS_S_UNAVAILABLE indicates that the mapping or conversion could
 808       not be done.  The minor status code may provide additional
 809       information.
 810
 811    o  GSS_S_FAILURE indicates a general error.  The minor status code
 812       may provide additional information.
 813
 814    Whereas name attribute's values are encoded in some network
 815    representation applications often require native, language- and/or
 816    platform-specific data types.  This function provides access to such
 817    types.
 818
 819 13.1  C-Bindings
 820
 821    struct gss_any;
 822    typedef struct gss_any *gss_any_t;
 823    OM_uint32 gss_map_name_to_any(
 824      OM_uint32                     *minor_status,
 825      gss_name_t                    name,
 826      int                           authenticated,
 827      gss_OID                       type_id,
 828      gss_any_t                     output
 829    );
 830
 831
 832
 833
 834
 835 Williams                Expires November 14, 2005              [Page 15]
 836 \f
 837 Internet-Draft          GSS-API Naming Extensions               May 2005
 838
 839
 840 13.2  Java Bindings
 841
 842    ...
 843
 844
 845 14.  GSS_Release_any_name_mapping()
 846
 847    Inputs:
 848
 849
 850    o  name NAME,
 851
 852    o  type_id OBJECT IDENTIFIER,
 853
 854    o  input ANY DEFINED BY type_id
 855
 856    Outputs:
 857
 858
 859    o  major_status INTEGER,
 860
 861    o  minor_status INTEGER,
 862
 863    Return major_status codes:
 864
 865    o  GSS_S_COMPLETE indicates no error.
 866
 867    o  GSS_S_UNAVAILABLE indicates that the mapping or conversion could
 868       not be done.  The minor status code may provide additional
 869       information.
 870
 871    o  GSS_S_FAILURE indicates a general error.  The minor status code
 872       may provide additional information.
 873
 874    This function releases, if possible, the objects of language- and/or
 875    platform-specific types output by GSS_Map_name_to_any().  If such
 876    types have native release functions applications MAY use either those
 877    or this function to release the given object.
 878
 879 14.1  C-Bindings
 880
 881    struct gss_any;
 882    typedef struct gss_any *gss_any_t;
 883    OM_uint32 gss_release_any_name_mapping(
 884      OM_uint32                     *minor_status,
 885      gss_name_t                    name,
 886      gss_OID                       type_id,
 887      gss_any_t                     *input
 888
 889
 890
 891 Williams                Expires November 14, 2005              [Page 16]
 892 \f
 893 Internet-Draft          GSS-API Naming Extensions               May 2005
 894
 895
 896    );
 897
 898
 899 14.2  Java Bindings
 900
 901    ...
 902
 903
 904 15.  IANA Considerations
 905
 906    This document creates a namespace of GSS-API name attributes.
 907    Attributes are named by OID, so no single authority might be needed
 908    for allocation, however, in the interest of providing the community
 909    with an authority for name attribute OID allocation and a way to find
 910    the existing set of name attributes, the IANA should establish both,
 911    a single OID off of which name attributes could be allocated, and a
 912    registry of known GSS name attributes.
 913
 914    GSS-API name attribute registry entries should contain all the
 915    information that GSS_Inquire_name_attribute() may return about the
 916    given name attributes and their OIDs:
 917
 918    o  a name attribute OID (this is a unique key)
 919
 920    o  a name attribute symbolic name, starting with "GSS_C_NA_" (this is
 921       a unique key)
 922
 923    o  a brief description, in English
 924
 925    o  whether the attribute is useful as the subject of access control
 926       list entries
 927
 928    o  whether the attribute is useful as an indicator of trust
 929
 930    o  an optional normative reference to documentation for the given
 931       name attribute
 932
 933    The allocation and registration policy should be first come, first
 934    served.  Registry entries' OIDs need not be based on the base OID
 935    given above.
 936
 937 16.  Security Considerations
 938
 939    <TBA>
 940
 941    [In particular, the status of a name attribute as "authenticated" vs.
 942    "asserted" requires close review, particularly with respect to PKIX
 943    certificate extensions.]
 944
 945
 946
 947 Williams                Expires November 14, 2005              [Page 17]
 948 \f
 949 Internet-Draft          GSS-API Naming Extensions               May 2005
 950
 951
 952 17.  References
 953
 954 17.1  Normative References
 955
 956    [I-D.GSS-NAMING]
 957               Hartman, S., "Desired Enhancements to GSSAPI Naming",
 958               draft-ietf-kitten-gss-naming-01.txt (work in progress),
 959               February 2005.
 960
 961    [I-D.ietf-krb-wg-kerberos-clarifications]
 962               Neuman, C., "The Kerberos Network Authentication Service
 963               (V5)", draft-ietf-krb-wg-kerberos-clarifications-07 (work
 964               in progress), September 2004.
 965
 966    [RFC2025]  Adams, C., "The Simple Public-Key GSS-API Mechanism
 967               (SPKM)", RFC 2025, October 1996.
 968
 969    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 970               Requirement Levels", BCP 14, RFC 2119, March 1997.
 971
 972    [RFC2743]  Linn, J., "Generic Security Service Application Program
 973               Interface Version 2, Update 1", RFC 2743, January 2000.
 974
 975    [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
 976               C-bindings", RFC 2744, January 2000.
 977
 978    [RFC3280]  Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
 979               X.509 Public Key Infrastructure Certificate and
 980               Certificate Revocation List (CRL) Profile", RFC 3280,
 981               April 2002.
 982
 983 17.2  Informative References
 984
 985    [RFC1750]  Eastlake, D., Crocker, S., and J. Schiller, "Randomness
 986               Recommendations for Security", RFC 1750, December 1994.
 987
 988    [RFC1964]  Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
 989               RFC 1964, June 1996.
 990
 991
 992 Author's Address
 993
 994    Nicolas Williams
 995    Sun Microsystems
 996    5300 Riata Trace Ct
 997    Austin, TX  78727
 998    US
 999
1000
1001
1002
1003 Williams                Expires November 14, 2005              [Page 18]
1004 \f
1005 Internet-Draft          GSS-API Naming Extensions               May 2005
1006
1007
1008    Email: Nicolas.Williams@sun.com
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059 Williams                Expires November 14, 2005              [Page 19]
1060 \f
1061 Internet-Draft          GSS-API Naming Extensions               May 2005
1062
1063
1064 Intellectual Property Statement
1065
1066    The IETF takes no position regarding the validity or scope of any
1067    Intellectual Property Rights or other rights that might be claimed to
1068    pertain to the implementation or use of the technology described in
1069    this document or the extent to which any license under such rights
1070    might or might not be available; nor does it represent that it has
1071    made any independent effort to identify any such rights.  Information
1072    on the procedures with respect to rights in RFC documents can be
1073    found in BCP 78 and BCP 79.
1074
1075    Copies of IPR disclosures made to the IETF Secretariat and any
1076    assurances of licenses to be made available, or the result of an
1077    attempt made to obtain a general license or permission for the use of
1078    such proprietary rights by implementers or users of this
1079    specification can be obtained from the IETF on-line IPR repository at
1080    http://www.ietf.org/ipr.
1081
1082    The IETF invites any interested party to bring to its attention any
1083    copyrights, patents or patent applications, or other proprietary
1084    rights that may cover technology that may be required to implement
1085    this standard.  Please address the information to the IETF at
1086    ietf-ipr@ietf.org.
1087
1088
1089 Disclaimer of Validity
1090
1091    This document and the information contained herein are provided on an
1092    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1093    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
1094    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
1095    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1096    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1097    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1098
1099
1100 Copyright Statement
1101
1102    Copyright (C) The Internet Society (2005).  This document is subject
1103    to the rights, licenses and restrictions contained in BCP 78, and
1104    except as set forth therein, the authors retain all their rights.
1105
1106
1107 Acknowledgment
1108
1109    Funding for the RFC Editor function is currently provided by the
1110    Internet Society.
1111
1112
1113
1114
1115 Williams                Expires November 14, 2005              [Page 20]
1116 \f
1117