doc/specifications/rfc2853.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                          J. Kabat
   8 Request for Comments: 2853                               ValiCert, Inc.
   9 Category: Standards Track                                   M. Upadhyay
  10                                                  Sun Microsystems, Inc.
  11                                                               June 2000
  12
  13
  14          Generic Security Service API Version 2 : Java Bindings
  15
  16 Status of this Memo
  17
  18    This document specifies an Internet standards track protocol for the
  19    Internet community, and requests discussion and suggestions for
  20    improvements.  Please refer to the current edition of the "Internet
  21    Official Protocol Standards" (STD 1) for the standardization state
  22    and status of this protocol.  Distribution of this memo is unlimited.
  23
  24 Copyright Notice
  25
  26    Copyright (C) The Internet Society (2000).  All Rights Reserved.
  27
  28 Abstract
  29
  30    The Generic Security Services Application Program Interface (GSS-API)
  31    offers application programmers uniform access to security services
  32    atop a variety of underlying cryptographic mechanisms. This document
  33    specifies the Java bindings for GSS-API which is described at a
  34    language independent conceptual level in RFC 2743 [GSSAPIv2-UPDATE].
  35
  36    The GSS-API allows a caller application to authenticate a principal
  37    identity, to delegate rights to a peer, and to apply security
  38    services such as confidentiality and integrity on a per-message
  39    basis. Examples of security mechanisms defined for GSS-API are The
  40    Simple Public-Key GSS-API Mechanism [SPKM] and The Kerberos Version 5
  41    GSS-API Mechanism [KERBV5].
  42
  43 Table of Contents
  44
  45    1.  Introduction . . . . . . . . . . . . . . . . . . . . . . .   5
  46    2.  GSS-API Operational Paradigm . . . . . . . . . . . . . . .   6
  47    3.  Additional Controls  . . . . . . . . . . . . . . . . . . .   8
  48    3.1.  Delegation . . . . . . . . . . . . . . . . . . . . . . .   9
  49    3.2.  Mutual Authentication  . . . . . . . . . . . . . . . . .  10
  50    3.3.  Replay and Out-of-Sequence Detection . . . . . . . . . .  10
  51    3.4.  Anonymous Authentication . . . . . . . . . . . . . . . .  11
  52    3.5.  Confidentiality  . . . . . . . . . . . . . . . . . . . .  12
  53    3.6.  Inter-process Context Transfer . . . . . . . . . . . . .  12
  54    3.7.  The Use of Incomplete Contexts . . . . . . . . . . . . .  13
  55
  56
  57
  58 Kabat & Upadhyay            Standards Track                     [Page 1]
  59 \f
  60 RFC 2853                 GSS-API Java Bindings                 June 2000
  61
  62
  63    4.  Calling Conventions  . . . . . . . . . . . . . . . . . . .  13
  64    4.1.  Package Name . . . . . . . . . . . . . . . . . . . . . .  13
  65    4.2.  Provider Framework . . . . . . . . . . . . . . . . . . .  13
  66    4.3.  Integer types  . . . . . . . . . . . . . . . . . . . . .  14
  67    4.4.  Opaque Data types  . . . . . . . . . . . . . . . . . . .  14
  68    4.5.  Strings  . . . . . . . . . . . . . . . . . . . . . . . .  15
  69    4.6.  Object Identifiers . . . . . . . . . . . . . . . . . . .  15
  70    4.7.  Object Identifier Sets . . . . . . . . . . . . . . . . .  15
  71    4.8.  Credentials  . . . . . . . . . . . . . . . . . . . . . .  16
  72    4.9.  Contexts . . . . . . . . . . . . . . . . . . . . . . . .  18
  73    4.10.  Authentication tokens . . . . . . . . . . . . . . . . .  18
  74    4.11.  Interprocess tokens . . . . . . . . . . . . . . . . . .  18
  75    4.12.  Error Reporting . . . . . . . . . . . . . . . . . . . .  19
  76    4.12.1.  GSS status codes  . . . . . . . . . . . . . . . . . .  19
  77    4.12.2.  Mechanism-specific status codes . . . . . . . . . . .  21
  78    4.12.3.  Supplementary status codes  . . . . . . . . . . . . .  21
  79    4.13.  Names . . . . . . . . . . . . . . . . . . . . . . . . .  22
  80    4.14.  Channel Bindings  . . . . . . . . . . . . . . . . . . .  25
  81    4.15.  Stream Objects  . . . . . . . . . . . . . . . . . . . .  26
  82    4.16.  Optional Parameters . . . . . . . . . . . . . . . . . .  26
  83    5.  Introduction to GSS-API Classes and Interfaces . . . . . .  26
  84    5.1.  GSSManager class . . . . . . . . . . . . . . . . . . . .  26
  85    5.2.  GSSName interface  . . . . . . . . . . . . . . . . . . .  27
  86    5.3.  GSSCredential interface  . . . . . . . . . . . . . . . .  28
  87    5.4.  GSSContext interface . . . . . . . . . . . . . . . . . .  28
  88    5.5.  MessageProp class  . . . . . . . . . . . . . . . . . . .  30
  89    5.6.  GSSException class . . . . . . . . . . . . . . . . . . .  30
  90    5.7.  Oid class  . . . . . . . . . . . . . . . . . . . . . . .  30
  91    5.8.  ChannelBinding class . . . . . . . . . . . . . . . . . .  31
  92    6.  Detailed GSS-API Class Description . . . . . . . . . . . .  31
  93    6.1.  public abstract class GSSManager . . . . . . . . . . . .  31
  94    6.1.1.  Example Code . . . . . . . . . . . . . . . . . . . . .  32
  95    6.1.2.  getInstance  . . . . . . . . . . . . . . . . . . . . .  33
  96    6.1.3.  getMechs . . . . . . . . . . . . . . . . . . . . . . .  33
  97    6.1.4.  getNamesForMech  . . . . . . . . . . . . . . . . . . .  33
  98    6.1.5.  getMechsForName  . . . . . . . . . . . . . . . . . . .  33
  99    6.1.6.  createName . . . . . . . . . . . . . . . . . . . . . .  33
 100    6.1.7.  createName . . . . . . . . . . . . . . . . . . . . . .  34
 101    6.1.8.  createName . . . . . . . . . . . . . . . . . . . . . .  35
 102    6.1.9.  createName . . . . . . . . . . . . . . . . . . . . . .  35
 103    6.1.10.  createCredential  . . . . . . . . . . . . . . . . . .  36
 104    6.1.11.  createCredential  . . . . . . . . . . . . . . . . . .  36
 105    6.1.12.  createCredential  . . . . . . . . . . . . . . . . . .  37
 106    6.1.13.  createContext . . . . . . . . . . . . . . . . . . . .  37
 107    6.1.14.  createContext . . . . . . . . . . . . . . . . . . . .  38
 108    6.1.15.  createContext . . . . . . . . . . . . . . . . . . . .  38
 109    6.1.16.  addProviderAtFront  . . . . . . . . . . . . . . . . .  38
 110    6.1.16.1.  Example Code  . . . . . . . . . . . . . . . . . . .  39
 111
 112
 113
 114 Kabat & Upadhyay            Standards Track                     [Page 2]
 115 \f
 116 RFC 2853                 GSS-API Java Bindings                 June 2000
 117
 118
 119    6.1.17.  addProviderAtEnd  . . . . . . . . . . . . . . . . . .  40
 120    6.1.17.1.  Example Code  . . . . . . . . . . . . . . . . . . .  41
 121    6.2.  public interface GSSName . . . . . . . . . . . . . . . .  42
 122    6.2.1.  Example Code . . . . . . . . . . . . . . . . . . . . .  42
 123    6.2.2.  Static Constants . . . . . . . . . . . . . . . . . . .  43
 124    6.2.3.  equals . . . . . . . . . . . . . . . . . . . . . . . .  44
 125    6.2.4.  equals . . . . . . . . . . . . . . . . . . . . . . . .  44
 126    6.2.5.  canonicalize . . . . . . . . . . . . . . . . . . . . .  44
 127    6.2.6.  export . . . . . . . . . . . . . . . . . . . . . . . .  45
 128    6.2.7.  toString . . . . . . . . . . . . . . . . . . . . . . .  45
 129    6.2.8.  getStringNameType  . . . . . . . . . . . . . . . . . .  45
 130    6.2.9.  isAnonymous  . . . . . . . . . . . . . . . . . . . . .  45
 131    6.2.10.  isMN  . . . . . . . . . . . . . . . . . . . . . . . .  45
 132    6.3.  public interface GSSCredential implements Cloneable  . .  45
 133    6.3.1.  Example Code . . . . . . . . . . . . . . . . . . . . .  46
 134    6.3.2.  Static Constants . . . . . . . . . . . . . . . . . . .  47
 135    6.3.3.  dispose  . . . . . . . . . . . . . . . . . . . . . . .  48
 136    6.3.4.  getName  . . . . . . . . . . . . . . . . . . . . . . .  48
 137    6.3.5.  getName  . . . . . . . . . . . . . . . . . . . . . . .  48
 138    6.3.6.  getRemainingLifetime . . . . . . . . . . . . . . . . .  48
 139    6.3.7.  getRemainingInitLifetime . . . . . . . . . . . . . . .  49
 140    6.3.8.  getRemainingAcceptLifetime . . . . . . . . . . . . . .  49
 141    6.3.9.  getUsage . . . . . . . . . . . . . . . . . . . . . . .  49
 142    6.3.10.  getUsage  . . . . . . . . . . . . . . . . . . . . . .  49
 143    6.3.11.  getMechs  . . . . . . . . . . . . . . . . . . . . . .  50
 144    6.3.12.  add . . . . . . . . . . . . . . . . . . . . . . . . .  50
 145    6.3.13.  equals  . . . . . . . . . . . . . . . . . . . . . . .  51
 146    6.4.  public interface GSSContext  . . . . . . . . . . . . . .  51
 147    6.4.1.  Example Code . . . . . . . . . . . . . . . . . . . . .  52
 148    6.4.2.  Static Constants . . . . . . . . . . . . . . . . . . .  54
 149    6.4.3.  initSecContext . . . . . . . . . . . . . . . . . . . .  54
 150    6.4.3.1.  Example Code . . . . . . . . . . . . . . . . . . . .  55
 151    6.4.4.  initSecContext . . . . . . . . . . . . . . . . . . . .  56
 152    6.4.4.1.  Example Code . . . . . . . . . . . . . . . . . . . .  56
 153    6.4.5.  acceptSecContext . . . . . . . . . . . . . . . . . . .  57
 154    6.4.5.1.  Example Code . . . . . . . . . . . . . . . . . . . .  58
 155    6.4.6.  acceptSecContext . . . . . . . . . . . . . . . . . . .  59
 156    6.4.6.1.  Example Code . . . . . . . . . . . . . . . . . . . .  59
 157    6.4.7.  isEstablished  . . . . . . . . . . . . . . . . . . . .  60
 158    6.4.8.  dispose  . . . . . . . . . . . . . . . . . . . . . . .  60
 159    6.4.9.  getWrapSizeLimit . . . . . . . . . . . . . . . . . . .  61
 160    6.4.10.  wrap  . . . . . . . . . . . . . . . . . . . . . . . .  61
 161    6.4.11.  wrap  . . . . . . . . . . . . . . . . . . . . . . . .  62
 162    6.4.12.  unwrap  . . . . . . . . . . . . . . . . . . . . . . .  63
 163    6.4.13.  unwrap  . . . . . . . . . . . . . . . . . . . . . . .  64
 164    6.4.14.  getMIC  . . . . . . . . . . . . . . . . . . . . . . .  65
 165    6.4.15.  getMIC  . . . . . . . . . . . . . . . . . . . . . . .  65
 166    6.4.16.  verifyMIC . . . . . . . . . . . . . . . . . . . . . .  66
 167
 168
 169
 170 Kabat & Upadhyay            Standards Track                     [Page 3]
 171 \f
 172 RFC 2853                 GSS-API Java Bindings                 June 2000
 173
 174
 175    6.4.17.  verifyMIC . . . . . . . . . . . . . . . . . . . . . .  67
 176    6.4.18.  export  . . . . . . . . . . . . . . . . . . . . . . .  68
 177    6.4.19.  requestMutualAuth . . . . . . . . . . . . . . . . . .  68
 178    6.4.20.  requestReplayDet  . . . . . . . . . . . . . . . . . .  69
 179    6.4.21.  requestSequenceDet  . . . . . . . . . . . . . . . . .  69
 180    6.4.22.  requestCredDeleg  . . . . . . . . . . . . . . . . . .  69
 181    6.4.23.  requestAnonymity  . . . . . . . . . . . . . . . . . .  69
 182    6.4.24.  requestConf . . . . . . . . . . . . . . . . . . . . .  70
 183    6.4.25.  requestInteg  . . . . . . . . . . . . . . . . . . . .  70
 184    6.4.26.  requestLifetime . . . . . . . . . . . . . . . . . . .  70
 185    6.4.27.  setChannelBinding . . . . . . . . . . . . . . . . . .  71
 186    6.4.28.  getCredDelegState . . . . . . . . . . . . . . . . . .  71
 187    6.4.29.  getMutualAuthState  . . . . . . . . . . . . . . . . .  71
 188    6.4.30.  getReplayDetState . . . . . . . . . . . . . . . . . .  71
 189    6.4.31.  getSequenceDetState . . . . . . . . . . . . . . . . .  71
 190    6.4.32.  getAnonymityState . . . . . . . . . . . . . . . . . .  72
 191    6.4.33.  isTransferable  . . . . . . . . . . . . . . . . . . .  72
 192    6.4.34.  isProtReady . . . . . . . . . . . . . . . . . . . . .  72
 193    6.4.35.  getConfState  . . . . . . . . . . . . . . . . . . . .  72
 194    6.4.36.  getIntegState . . . . . . . . . . . . . . . . . . . .  72
 195    6.4.37.  getLifetime . . . . . . . . . . . . . . . . . . . . .  73
 196    6.4.38.  getSrcName  . . . . . . . . . . . . . . . . . . . . .  73
 197    6.4.39.  getTargName . . . . . . . . . . . . . . . . . . . . .  73
 198    6.4.40.  getMech . . . . . . . . . . . . . . . . . . . . . . .  73
 199    6.4.41.  getDelegCred  . . . . . . . . . . . . . . . . . . . .  73
 200    6.4.42.  isInitiator . . . . . . . . . . . . . . . . . . . . .  73
 201    6.5.  public class MessageProp . . . . . . . . . . . . . . . .  74
 202    6.5.1.  Constructors . . . . . . . . . . . . . . . . . . . . .  74
 203    6.5.2.  getQOP . . . . . . . . . . . . . . . . . . . . . . . .  75
 204    6.5.3.  getPrivacy . . . . . . . . . . . . . . . . . . . . . .  75
 205    6.5.4.  getMinorStatus . . . . . . . . . . . . . . . . . . . .  75
 206    6.5.5.  getMinorString . . . . . . . . . . . . . . . . . . . .  75
 207    6.5.6.  setQOP . . . . . . . . . . . . . . . . . . . . . . . .  75
 208    6.5.7.  setPrivacy . . . . . . . . . . . . . . . . . . . . . .  75
 209    6.5.8.  isDuplicateToken . . . . . . . . . . . . . . . . . . .  76
 210    6.5.9.  isOldToken . . . . . . . . . . . . . . . . . . . . . .  76
 211    6.5.10.  isUnseqToken  . . . . . . . . . . . . . . . . . . . .  76
 212    6.5.11.  isGapToken  . . . . . . . . . . . . . . . . . . . . .  76
 213    6.5.12.  setSupplementaryStates  . . . . . . . . . . . . . . .  76
 214    6.6.  public class ChannelBinding  . . . . . . . . . . . . . .  77
 215    6.6.1.  Constructors . . . . . . . . . . . . . . . . . . . . .  77
 216    6.6.2.  getInitiatorAddress  . . . . . . . . . . . . . . . . .  78
 217    6.6.3.  getAcceptorAddress . . . . . . . . . . . . . . . . . .  78
 218    6.6.4.  getApplicationData . . . . . . . . . . . . . . . . . .  78
 219    6.6.5.  equals . . . . . . . . . . . . . . . . . . . . . . . .  78
 220    6.7.  public class Oid . . . . . . . . . . . . . . . . . . . .  79
 221    6.7.1.  Constructors . . . . . . . . . . . . . . . . . . . . .  79
 222    6.7.2.  toString . . . . . . . . . . . . . . . . . . . . . . .  80
 223
 224
 225
 226 Kabat & Upadhyay            Standards Track                     [Page 4]
 227 \f
 228 RFC 2853                 GSS-API Java Bindings                 June 2000
 229
 230
 231    6.7.3.  equals . . . . . . . . . . . . . . . . . . . . . . . .  80
 232    6.7.4.  getDER . . . . . . . . . . . . . . . . . . . . . . . .  80
 233    6.7.5.  containedIn  . . . . . . . . . . . . . . . . . . . . .  80
 234    6.8.  public class GSSException extends Exception  . . . . . .  80
 235    6.8.1.  Static Constants . . . . . . . . . . . . . . . . . . .  81
 236    6.8.2.  Constructors . . . . . . . . . . . . . . . . . . . . .  83
 237    6.8.3.  getMajor . . . . . . . . . . . . . . . . . . . . . . .  84
 238    6.8.4.  getMinor . . . . . . . . . . . . . . . . . . . . . . .  84
 239    6.8.5.  getMajorString . . . . . . . . . . . . . . . . . . . .  84
 240    6.8.6.  getMinorString . . . . . . . . . . . . . . . . . . . .  84
 241    6.8.7.  setMinor . . . . . . . . . . . . . . . . . . . . . . .  84
 242    6.8.8.  toString . . . . . . . . . . . . . . . . . . . . . . .  85
 243    6.8.9.  getMessage . . . . . . . . . . . . . . . . . . . . . .  85
 244    7.  Sample Applications  . . . . . . . . . . . . . . . . . . .  85
 245    7.1.  Simple GSS Context Initiator . . . . . . . . . . . . . .  85
 246    7.2.  Simple GSS Context Acceptor  . . . . . . . . . . . . . .  89
 247    8.  Security Considerations  . . . . . . . . . . . . . . . . .  93
 248    9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . .  94
 249    10.  Bibliography  . . . . . . . . . . . . . . . . . . . . . .  94
 250    11.  Authors' Addresses  . . . . . . . . . . . . . . . . . . .  95
 251    12.  Full Copyright Statement. . . . . . . . . . . . . . . . .  96
 252
 253 1.  Introduction
 254
 255    This document specifies Java language bindings for the Generic
 256    Security Services Application Programming Interface Version 2 (GSS-
 257    API).  GSS-API Version 2 is described in a language independent
 258    format in RFC 2743 [GSSAPIv2-UPDATE]. The GSS-API allows a caller
 259    application to authenticate a principal identity, to delegate rights
 260    to a peer, and to apply security services such as confidentiality and
 261    integrity on a per-message basis.
 262
 263    This document leverages the work performed by the WG in the area of
 264    RFC 2743 [GSSAPIv2-UPDATE] and the C-bindings RFC 2744 [GSSAPI-C].
 265    Whenever appropriate, text has been used from the C-bindings RFC 2744
 266    to explain generic concepts and provide direction to the
 267    implementors.
 268
 269    The design goals of this API have been to satisfy all the
 270    functionality defined in RFC 2743 and to provide these services in an
 271    object oriented method.  The specification also aims to satisfy the
 272    needs of both types of Java application developers, those who would
 273    like access to a "system-wide" GSS-API implementation, as well as
 274    those who would want to provide their own "custom" implementation.
 275
 276
 277
 278
 279
 280
 281
 282 Kabat & Upadhyay            Standards Track                     [Page 5]
 283 \f
 284 RFC 2853                 GSS-API Java Bindings                 June 2000
 285
 286
 287    A "system-wide" implementation is one that is available to all
 288    applications in the form of a library package.  It may be a standard
 289    package in the Java runtime environment (JRE) being used or it may be
 290    additionally installed and accessible to any application via the
 291    CLASSPATH.
 292
 293    A "custom" implementation of the GSS-API, on the other hand, is one
 294    that would, in most cases, be bundled with the application during
 295    distribution.  It is expected that such an implementation would be
 296    meant to provide for some particular need of the application, such as
 297    support for some specific mechanism.
 298
 299    The design of this API also aims to provide a flexible framework to
 300    add and manage GSS-API mechanisms. GSS-API leverages the Java
 301    Cryptography Architecture (JCA) provider model to support the
 302    plugability of mechanisms.  Mechanisms can be added on a "system-
 303    wide" basis, where all users of the framework will have them
 304    available. The specification also allows for the addition of
 305    mechanisms per-instance of the GSS-API.
 306
 307    Lastly, this specification presents an API that will naturally fit
 308    within the operation environment of the Java platform.  Readers are
 309    assumed to be familiar with both the GSS-API and the Java platform.
 310
 311 2.  GSS-API Operational Paradigm
 312
 313    The Generic Security Service Application Programming Interface
 314    Version 2 [GSSAPIv2-UPDATE] defines a generic security API to calling
 315    applications.  It allows a communicating application to authenticate
 316    the user associated with another application, to delegate rights to
 317    another application, and to apply security services such as
 318    confidentiality and integrity on a per-message basis.
 319
 320       There are four stages to using GSS-API:
 321
 322       1) The application acquires a set of credentials with which it may
 323          prove its identity to other processes.  The application's
 324          credentials vouch for its global identity, which may or may not
 325          be related to any local username under which it may be running.
 326
 327       2) A pair of communicating applications establish a joint security
 328          context using their credentials.  The security context
 329          encapsulates shared state information, which is required in
 330          order that per-message security services may be provided.
 331          Examples of state information that might be shared between
 332          applications as part of a security context are cryptographic
 333          keys, and message sequence numbers.  As part of the
 334          establishment of  a security context, the context initiator is
 335
 336
 337
 338 Kabat & Upadhyay            Standards Track                     [Page 6]
 339 \f
 340 RFC 2853                 GSS-API Java Bindings                 June 2000
 341
 342
 343          authenticated to the responder, and may require that the
 344          responder is authenticated back to the initiator.  The
 345          initiator may optionally give the responder the right to
 346          initiate further security contexts, acting as an agent or
 347          delegate of the initiator.  This transfer of rights is termed
 348          "delegation", and is achieved by creating a set of credentials,
 349          similar to those used by the initiating application, but which
 350          may be used by the responder.
 351
 352          A GSSContext object is used to establish and maintain the
 353          shared information that makes up the security context.  Certain
 354          GSSContext methods will generate a token, which applications
 355          treat as cryptographically protected, opaque data.  The caller
 356          of such GSSContext method is responsible for transferring the
 357          token to the peer application, encapsulated if necessary in an
 358          application-to-application protocol.  On receipt of such a
 359          token, the peer application should pass it to a corresponding
 360          GSSContext method which will decode the token and extract the
 361          information, updating the security context state information
 362          accordingly.
 363
 364       3) Per-message services are invoked on a GSSContext object to
 365          apply either:
 366
 367          integrity and data origin authentication, or
 368
 369          confidentiality, integrity and data origin authentication
 370
 371          to application data, which are treated by GSS-API as arbitrary
 372          octet-strings.  An application transmitting a message that it
 373          wishes to protect will call the appropriate GSSContext method
 374          (getMIC or wrap) to apply protection, and send the resulting
 375          token to the receiving application.  The receiver will pass the
 376          received token (and, in the case of data protected by getMIC,
 377          the accompanying message-data) to the corresponding decoding
 378          method of the GSSContext interface (verifyMIC or unwrap) to
 379          remove the protection and validate the data.
 380
 381       4) At the completion of a communications session (which may extend
 382          across several transport connections), each application uses a
 383          GSSContext method to invalidate the security context and
 384          release any system or cryptographic resources held.  Multiple
 385          contexts may also be used (either successively or
 386          simultaneously) within a single communications association, at
 387          the discretion of the applications.
 388
 389
 390
 391
 392
 393
 394 Kabat & Upadhyay            Standards Track                     [Page 7]
 395 \f
 396 RFC 2853                 GSS-API Java Bindings                 June 2000
 397
 398
 399 3.  Additional Controls
 400
 401    This section discusses the optional services that a context initiator
 402    may request of the GSS-API before the context establishment.  Each of
 403    these services is requested by calling the appropriate mutator method
 404    in the GSSContext object before the first call to init is performed.
 405    Only the context initiator can request context flags.
 406
 407    The optional services defined are:
 408
 409    Delegation
 410          The (usually temporary) transfer of rights from initiator to
 411          acceptor, enabling the acceptor to authenticate itself as an
 412          agent of the initiator.
 413
 414    Mutual Authentication
 415          In addition to the initiator authenticating its identity to the
 416          context acceptor, the context acceptor should also authenticate
 417          itself to the initiator.
 418
 419    Replay Detection
 420          In addition to providing message integrity services, GSSContext
 421          per-message operations of getMIC and wrap should include
 422          message numbering information  to enable verifyMIC and unwrap
 423          to detect if a message has been duplicated.
 424
 425    Out-of-Sequence Detection
 426          In addition to providing message integrity services, GSSContext
 427          per-message operations  (getMIC and wrap) should include
 428          message sequencing information to enable verifyMIC and unwrap
 429          to detect if a message has been received out of sequence.
 430
 431    Anonymous Authentication
 432          The establishment of the security context should not reveal the
 433          initiator's identity to the context acceptor.
 434
 435    Some mechanisms may not support all optional services, and some
 436    mechanisms may only support some services in conjunction with others.
 437    The GSSContext interface offers query methods to allow the
 438    verification by the calling application of which services will be
 439    available from the context when the establishment phase is complete.
 440    In general, if the security mechanism is capable of providing a
 441    requested service, it should do so even if additional services must
 442    be enabled in order to provide the requested service.  If the
 443    mechanism is incapable of providing a requested service, it should
 444    proceed without the service leaving the application to abort the
 445    context establishment process if it considers the requested service
 446    to be mandatory.
 447
 448
 449
 450 Kabat & Upadhyay            Standards Track                     [Page 8]
 451 \f
 452 RFC 2853                 GSS-API Java Bindings                 June 2000
 453
 454
 455    Some mechanisms may specify that support for some services is
 456    optional, and that implementors of the mechanism need not provide it.
 457    This is most commonly true of the confidentiality service, often
 458    because of legal restrictions on the use of data-encryption, but may
 459    apply to any of the services.  Such mechanisms are required to send
 460    at least one token from acceptor to initiator during context
 461    establishment when the initiator indicates a desire to use such a
 462    service, so that the initiating GSS-API can correctly indicate
 463    whether the service is supported by the acceptor's GSS-API.
 464
 465 3.1.  Delegation
 466
 467    The GSS-API allows delegation to be controlled by the initiating
 468    application via the requestCredDeleg method before the first call to
 469    init has been issued.  Some mechanisms do not support delegation, and
 470    for such mechanisms attempts by an application to enable delegation
 471    are ignored.
 472
 473    The acceptor of a security context, for which the initiator enabled
 474    delegation, can check if delegation was enabled by using the
 475    getCredDelegState method of the GSSContext interface.  In cases when
 476    it is, the delegated credential object can be obtained by calling the
 477    getDelegCred method.  The obtained GSSCredential object may then be
 478    used to initiate subsequent GSS-API security contexts as an agent or
 479    delegate of the initiator.  If the original initiator's identity is
 480    "A" and the delegate's identity is "B", then, depending on the
 481    underlying mechanism, the identity embodied by the delegated
 482    credential may be either "A" or "B acting for A".
 483
 484    For many mechanisms that support delegation, a simple boolean does
 485    not provide enough control.  Examples of additional aspects of
 486    delegation control that a mechanism might provide to an application
 487    are duration of delegation, network addresses from which delegation
 488    is valid, and constraints on the tasks that may be performed by a
 489    delegate.  Such controls are presently outside the scope of the GSS-
 490    API.  GSS-API implementations supporting mechanisms offering
 491    additional controls should provide extension routines that allow
 492    these controls to be exercised (perhaps by modifying the initiator's
 493    GSS-API credential object prior to its use in establishing a
 494    context).  However, the simple delegation control provided by GSS-API
 495    should always be able to over-ride other mechanism-specific
 496    delegation controls.  If the application instructs the GSSContext
 497    object that delegation is not desired, then the implementation must
 498    not permit delegation to occur.  This is an exception to the general
 499    rule that a mechanism may enable services even if they are not
 500    requested - delegation may only be provided at the explicit request
 501    of the application.
 502
 503
 504
 505
 506 Kabat & Upadhyay            Standards Track                     [Page 9]
 507 \f
 508 RFC 2853                 GSS-API Java Bindings                 June 2000
 509
 510
 511 3.2.  Mutual Authentication
 512
 513    Usually, a context acceptor will require that a context initiator
 514    authenticate itself so that the acceptor may make an access-control
 515    decision prior to performing a service for the initiator.  In some
 516    cases, the initiator may also request that the acceptor authenticate
 517    itself.  GSS-API allows the initiating application to request this
 518    mutual authentication service by calling the requestMutualAuth method
 519    of the GSSContext interface with a "true" parameter before making the
 520    first call to init.  The initiating application is informed as to
 521    whether or not the context acceptor has authenticated itself.  Note
 522    that some mechanisms may not support mutual authentication, and other
 523    mechanisms may always perform mutual authentication, whether or not
 524    the initiating application requests it.  In particular, mutual
 525    authentication may be required by some mechanisms in order to support
 526    replay or out-of-sequence message detection, and for such mechanisms
 527    a request for either of these services will automatically enable
 528    mutual authentication.
 529
 530 3.3.  Replay and Out-of-Sequence Detection
 531
 532    The GSS-API may provide detection of mis-ordered messages once a
 533    security context has been established.  Protection may be applied to
 534    messages by either application, by calling either getMIC or wrap
 535    methods of the GSSContext interface, and verified by the peer
 536    application by calling verifyMIC or unwrap for the peer's GSSContext
 537    object.
 538
 539    The getMIC method calculates a cryptographic checksum of an
 540    application message, and returns that checksum in a token.  The
 541    application should pass both the token and the message to the peer
 542    application, which presents them to the verifyMIC method of the
 543    peer's GSSContext object.
 544
 545    The wrap method calculates a cryptographic checksum of an application
 546    message, and places both the checksum and the message inside a single
 547    token.  The application should pass the token to the peer
 548    application, which presents it to the unwrap method of the peer's
 549    GSSContext object to extract the message and verify the checksum.
 550
 551    Either pair of routines may be capable of detecting out-of-sequence
 552    message delivery, or duplication of messages.  Details of such mis-
 553    ordered messages are indicated through supplementary query methods of
 554    the MessageProp object that is filled in by each of these routines.
 555
 556    A mechanism need not maintain a list of all tokens that have been
 557    processed in order to support these status codes.  A typical
 558    mechanism might retain information about only the most recent "N"
 559
 560
 561
 562 Kabat & Upadhyay            Standards Track                    [Page 10]
 563 \f
 564 RFC 2853                 GSS-API Java Bindings                 June 2000
 565
 566
 567    tokens processed, allowing it to distinguish duplicates and missing
 568    tokens within the most recent "N" messages; the receipt of a token
 569    older than the most recent "N" would result in the isOldToken method
 570    of the instance of MessageProp to return "true".
 571
 572 3.4.  Anonymous Authentication
 573
 574    In certain situations, an application may wish to initiate the
 575    authentication process to authenticate a peer, without revealing its
 576    own identity.  As an example, consider an application providing
 577    access to a database containing medical information, and offering
 578    unrestricted access to the service.  A client of such a service might
 579    wish to authenticate the service (in order to establish trust in any
 580    information retrieved from it), but might not wish the service to be
 581    able to obtain the client's identity (perhaps due to privacy concerns
 582    about the specific inquiries, or perhaps simply to avoid being placed
 583    on mailing-lists).
 584
 585    In normal use of the GSS-API, the initiator's identity is made
 586    available to the acceptor as a result of the context establishment
 587    process.  However, context initiators may request that their identity
 588    not be revealed to the context acceptor.  Many mechanisms do not
 589    support anonymous authentication, and for such mechanisms the request
 590    will not be honored.  An authentication token will still be
 591    generated, but the application is always informed if a requested
 592    service is unavailable, and has the option to abort context
 593    establishment if anonymity is valued above the other security
 594    services that would require a context to be established.
 595
 596    In addition to informing the application that a context is
 597    established anonymously (via the isAnonymous method of the GSSContext
 598    class), the getSrcName method of the acceptor's GSSContext object
 599    will, for such contexts, return a reserved internal-form name,
 600    defined by the implementation.
 601
 602    The toString method for a GSSName object representing an anonymous
 603    entity will return a printable name.  The returned value will be
 604    syntactically distinguishable from any valid principal name supported
 605    by the implementation.  The associated name-type object identifier
 606    will be an oid representing the value of NT_ANONYMOUS.  This name-
 607    type oid will be defined as a public, static Oid object of the
 608    GSSName class.  The printable form of an anonymous name should be
 609    chosen such that it implies anonymity, since this name may appear in,
 610    for example, audit logs.  For example, the string "<anonymous>" might
 611    be a good choice, if no valid printable names supported by the
 612    implementation can begin with "<" and end with ">".
 613
 614
 615
 616
 617
 618 Kabat & Upadhyay            Standards Track                    [Page 11]
 619 \f
 620 RFC 2853                 GSS-API Java Bindings                 June 2000
 621
 622
 623    When using the equal method of the GSSName interface, and one of the
 624    operands is a GSSName instance representing an anonymous entity, the
 625    method must return "false".
 626
 627 3.5.  Confidentiality
 628
 629    If a GSSContext supports the confidentiality service, wrap method may
 630    be used to encrypt application messages.  Messages are selectively
 631    encrypted, under the control of the setPrivacy method of the
 632    MessageProp object used in the wrap method.
 633
 634 3.6.  Inter-process Context Transfer
 635
 636    GSS-API V2 provides functionality which allows a security context to
 637    be transferred between processes on a single machine.  These are
 638    implemented using the export method of GSSContext and a byte array
 639    constructor of the same class.  The most common use for such a
 640    feature is a client-server design where the server is implemented as
 641    a single process that accepts incoming security contexts, which then
 642    launches child processes to deal with the data on these contexts.  In
 643    such a design, the child processes must have access to the security
 644    context object created within the parent so that they can use per-
 645    message protection services and delete the security context when the
 646    communication session ends.
 647
 648    Since the security context data structure is expected to contain
 649    sequencing information, it is impractical in general to share a
 650    context between processes.  Thus GSSContext interface provides an
 651    export method that the process, which currently owns the context, can
 652    call to declare that it has no intention to use the context
 653    subsequently, and to create an inter-process token containing
 654    information needed by the adopting process to successfully re-create
 655    the context.  After successful completion of export, the original
 656    security context is made inaccessible to the calling process by GSS-
 657    API and any further usage of this object will result in failures.
 658    The originating process transfers the inter-process token to the
 659    adopting process, which creates a new GSSContext object using the
 660    byte array constructor.  The properties of the context are equivalent
 661    to that of the original context.
 662
 663    The inter-process token may contain sensitive data from the original
 664    security context (including cryptographic keys).  Applications using
 665    inter-process tokens to transfer security contexts must take
 666    appropriate steps to protect these tokens in transit.
 667
 668
 669
 670
 671
 672
 673
 674 Kabat & Upadhyay            Standards Track                    [Page 12]
 675 \f
 676 RFC 2853                 GSS-API Java Bindings                 June 2000
 677
 678
 679    Implementations are not required to support the inter-process
 680    transfer of security contexts.  Calling the isTransferable method of
 681    the GSSContext interface will indicate if the context object is
 682    transferable.
 683
 684 3.7.  The Use of Incomplete Contexts
 685
 686    Some mechanisms may allow the per-message services to be used before
 687    the context establishment process is complete.  For example, a
 688    mechanism may include sufficient information in its initial context-
 689    level tokens for the context acceptor to immediately decode messages
 690    protected with wrap or getMIC.  For such a mechanism, the initiating
 691    application need not wait until subsequent context-level tokens have
 692    been sent and received before invoking the per-message protection
 693    services.
 694
 695    An application can invoke the isProtReady method of the GSSContext
 696    class to determine if the per-message services are available in
 697    advance of complete context establishment.  Applications wishing to
 698    use per-message protection services on partially-established contexts
 699    should query this method before attempting to invoke wrap or getMIC.
 700
 701 4.  Calling Conventions
 702
 703    Java provides the implementors with not just a syntax for the
 704    language, but also an operational environment.  For example, memory
 705    is automatically managed and does not require application
 706    intervention.  These language features have allowed for a simpler API
 707    and have led to the elimination of certain GSS-API functions.
 708
 709    Moreover, the JCA defines a provider model which allows for
 710    implementation independent access to security services. Using this
 711    model, applications can seamlessly switch between different
 712    implementations and dynamically add new services. The GSS-API
 713    specification leverages these concepts by the usage of providers for
 714    the mechanism implementations.
 715
 716 4.1.  Package Name
 717
 718    The classes and interfaces defined in this document reside in the
 719    package called "org.ietf.jgss".  Applications that wish to make use
 720    of this API should import this package name as shown in section 7.
 721
 722 4.2.  Provider Framework
 723
 724    The Java security API's use a provider architecture that allows
 725    applications to be implementation independent and security API
 726    implementations to be modular and extensible.  The
 727
 728
 729
 730 Kabat & Upadhyay            Standards Track                    [Page 13]
 731 \f
 732 RFC 2853                 GSS-API Java Bindings                 June 2000
 733
 734
 735    java.security.Provider class is an abstract class that a vendor
 736    extends.  This class maps various properties that represent different
 737    security services that are available to the names of the actual
 738    vendor classes that implement those services.  When requesting a
 739    service, an application simply specifies the desired provider and the
 740    API delegates the request to service classes available from that
 741    provider.
 742
 743    Using the Java security provider model insulates applications from
 744    implementation details of the services they wish to use.
 745    Applications can switch between providers easily and new providers
 746    can be added as needed, even at runtime.
 747
 748    The GSS-API may use providers to find components for specific
 749    underlying security mechanisms.  For instance, a particular provider
 750    might contain components that will allow the GSS-API to support the
 751    Kerberos v5 mechanism and another might contain components to support
 752    the SPKM mechanism.  By delegating mechanism specific functionality
 753    to the components obtained from providers the GSS-API can be extended
 754    to support an arbitrary list of mechanism.
 755
 756    How the GSS-API locates and queries these providers is beyond the
 757    scope of this document and is being deferred to a Service Provider
 758    Interface (SPI) specification.  The availability of such a SPI
 759    specification is not mandatory for the adoption of this API
 760    specification nor is it mandatory to use providers in the
 761    implementation of a GSS-API framework. However, by using the provider
 762    framework together with an SPI specification one can create an
 763    extensible and implementation independent GSS-API framework.
 764
 765 4.3.  Integer types
 766
 767    All numeric values are declared as "int" primitive Java type.  The
 768    Java specification guarantees that this will be a 32 bit two's
 769    complement signed number.
 770
 771    Throughout this API, the "boolean" primitive Java type is used
 772    wherever a boolean value is required or returned.
 773
 774 4.4.  Opaque Data types
 775
 776    Java byte arrays are used to represent opaque data types which are
 777    consumed and produced by the GSS-API in the forms of tokens.  Java
 778    arrays contain a length field which enables the users to easily
 779    determine their size.  The language has automatic garbage collection
 780    which alleviates the need by developers to release memory and
 781    simplifies buffer ownership issues.
 782
 783
 784
 785
 786 Kabat & Upadhyay            Standards Track                    [Page 14]
 787 \f
 788 RFC 2853                 GSS-API Java Bindings                 June 2000
 789
 790
 791 4.5.  Strings
 792
 793    The String object will be used to represent all textual data.  The
 794    Java String object, transparently treats all characters as two-byte
 795    Unicode characters which allows support for many locals.  All
 796    routines returning or accepting textual data will use the String
 797    object.
 798
 799 4.6.  Object Identifiers
 800
 801    An Oid object will be used to represent Universal Object Identifiers
 802    (Oids).  Oids are ISO-defined, hierarchically globally-interpretable
 803    identifiers used within the GSS-API framework to identify security
 804    mechanisms and name formats.  The Oid object can be created from a
 805    string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as
 806    well as from its ASN.1 DER encoding.  Methods are also provided to
 807    test equality and provide the DER representation for the object.
 808
 809    An important feature of the Oid class is that its instances are
 810    immutable - i.e.  there are no methods defined that allow one to
 811    change the contents of an Oid.  This property allows one to treat
 812    these objects as "statics" without the need to perform copies.
 813
 814    Certain routines allow the usage of a default oid.  A "null" value
 815    can be used in those cases.
 816
 817 4.7.  Object Identifier Sets
 818
 819    The Java bindings represents object identifiers sets as arrays of Oid
 820    objects.  All Java arrays contain a length field which allows for
 821    easy manipulation and reference.
 822
 823    In order to support the full functionality of RFC 2743, the Oid class
 824    includes a method which checks for existence of an Oid object within
 825    a specified array.  This is equivalent in functionality to
 826    gss_test_oid_set_member.  The use of Java arrays and Java's automatic
 827    garbage collection has eliminated the need for the following
 828    routines: gss_create_empty_oid_set, gss_release_oid_set, and
 829    gss_add_oid_set_member.  Java GSS-API implementations will not
 830    contain them.  Java's automatic garbage collection and the immutable
 831    property of the Oid object eliminates the complicated memory
 832    management issues of the C counterpart.
 833
 834    When ever a default value for an Object Identifier Set is required, a
 835    "null" value can be used.  Please consult the detailed method
 836    description for details.
 837
 838
 839
 840
 841
 842 Kabat & Upadhyay            Standards Track                    [Page 15]
 843 \f
 844 RFC 2853                 GSS-API Java Bindings                 June 2000
 845
 846
 847 4.8.  Credentials
 848
 849    GSS-API credentials are represented by the GSSCredential interface.
 850    The interface contains several constructs to allow for the creation
 851    of most common credential objects for the initiator and the acceptor.
 852    Comparisons are performed using the interface's "equals" method.  The
 853    following general description of GSS-API credentials is included from
 854    the C-bindings specification:
 855
 856    GSS-API credentials can contain mechanism-specific principal
 857    authentication data for multiple mechanisms.  A GSS-API credential is
 858    composed of a set of credential-elements, each of which is applicable
 859    to a single mechanism.  A credential may contain at most one
 860    credential-element for each supported mechanism.  A credential-
 861    element identifies the data needed by a single mechanism to
 862    authenticate a single principal, and conceptually contains two
 863    credential-references that describe the actual mechanism-specific
 864    authentication data, one to be used by GSS-API for initiating
 865    contexts, and one to be used for accepting contexts.  For mechanisms
 866    that do not distinguish between acceptor and initiator credentials,
 867    both references would point to the same underlying mechanism-specific
 868    authentication data.
 869
 870    Credentials describe a set of mechanism-specific principals, and give
 871    their holder the ability to act as any of those principals.  All
 872    principal identities asserted by a single GSS-API credential should
 873    belong to the same entity, although enforcement of this property is
 874    an implementation-specific matter.  A single GSSCredential object
 875    represents all the credential elements that have been acquired.
 876
 877    The creation's of an GSSContext object allows the value of "null" to
 878    be specified as the GSSCredential input parameter.  This will
 879    indicate a desire by the application to act as a default principal.
 880    While individual GSS-API implementations are free to determine such
 881    default behavior as appropriate to the mechanism, the following
 882    default behavior by these routines is recommended for portability:
 883
 884       For the initiator side of the context:
 885
 886       1) If there is only a single principal capable of initiating
 887          security contexts for the chosen mechanism that the application
 888          is authorized to act on behalf of, then that principal shall be
 889          used, otherwise
 890
 891
 892
 893
 894
 895
 896
 897
 898 Kabat & Upadhyay            Standards Track                    [Page 16]
 899 \f
 900 RFC 2853                 GSS-API Java Bindings                 June 2000
 901
 902
 903       2) If the platform maintains a concept of a default network-
 904          identity for the chosen mechanism, and if the application is
 905          authorized to act on behalf of that identity for the purpose of
 906          initiating security contexts, then the principal corresponding
 907          to that identity shall be used, otherwise
 908
 909       3) If the platform maintains a concept of a default local
 910          identity, and provides a means to map local identities into
 911          network-identities for the chosen mechanism, and if the
 912          application is authorized to act on behalf of the network-
 913          identity image of the default local identity for the purpose of
 914          initiating security contexts using the chosen mechanism, then
 915          the principal corresponding to that identity shall be used,
 916          otherwise
 917
 918       4) A user-configurable default identity should be used.
 919
 920       and for the acceptor side of the context
 921
 922       1) If there is only a single authorized principal identity capable
 923          of accepting security contexts for the chosen mechanism, then
 924          that principal shall be used, otherwise
 925
 926       2) If the mechanism can determine the identity of the target
 927          principal by examining the context-establishment token
 928          processed during the accept method, and if the accepting
 929          application is authorized to act as that principal for the
 930          purpose of accepting security contexts using the chosen
 931          mechanism, then that principal identity shall be used,
 932          otherwise
 933
 934       3) If the mechanism supports context acceptance by any principal,
 935          and if mutual authentication was not requested, any principal
 936          that the application is authorized to accept security contexts
 937          under using the chosen mechanism may be used, otherwise
 938
 939       4) A user-configurable default identity shall be used.
 940
 941    The purpose of the above rules is to allow security contexts to be
 942    established by both initiator and acceptor using the default behavior
 943    whenever possible.  Applications requesting default behavior are
 944    likely to be more portable across mechanisms and implementations than
 945    ones that instantiate an GSSCredential object representing a specific
 946    identity.
 947
 948
 949
 950
 951
 952
 953
 954 Kabat & Upadhyay            Standards Track                    [Page 17]
 955 \f
 956 RFC 2853                 GSS-API Java Bindings                 June 2000
 957
 958
 959 4.9.  Contexts
 960
 961    The GSSContext interface is used to represent one end of a GSS-API
 962    security context, storing state information appropriate to that end
 963    of the peer communication, including cryptographic state information.
 964    The instantiation of the context object is done differently by the
 965    initiator and the acceptor.  After the context has been instantiated,
 966    the initiator may choose to set various context options which will
 967    determine the characteristics of the desired security context.  When
 968    all the application desired characteristics have been set, the
 969    initiator will call the initSecContext method which will produce a
 970    token for consumption by the peer's acceptSecContext method.  It is
 971    the responsibility of the application to deliver the authentication
 972    token(s) between the peer applications for processing.  Upon
 973    completion of the context establishment phase, context attributes can
 974    be retrieved, by both the initiator and acceptor, using the accessor
 975    methods.  These will reflect the actual attributes of the established
 976    context.  At this point the context can be used by the application to
 977    apply cryptographic services to its data.
 978
 979 4.10.  Authentication tokens
 980
 981    A token is a caller-opaque type that GSS-API uses to maintain
 982    synchronization between each end of the GSS-API security context.
 983    The token is a cryptographically protected octet-string, generated by
 984    the underlying mechanism at one end of a GSS-API security context for
 985    use by the peer mechanism at the other end.  Encapsulation (if
 986    required) within the application protocol and transfer of the token
 987    are the responsibility of the peer applications.
 988
 989    Java GSS-API uses byte arrays to represent authentication tokens.
 990    Overloaded methods exist which allow the caller to supply input and
 991    output streams which will be used for the reading and writing of the
 992    token data.
 993
 994 4.11.  Interprocess tokens
 995
 996    Certain GSS-API routines are intended to transfer data between
 997    processes in multi-process programs.  These routines use a caller-
 998    opaque octet-string, generated by the GSS-API in one process for use
 999    by the GSS-API in another process.  The calling application is
1000    responsible for transferring such tokens between processes.  Note
1001    that, while GSS-API implementors are encouraged to avoid placing
1002    sensitive information within interprocess tokens, or to
1003    cryptographically protect them, many implementations will be unable
1004    to avoid placing key material or other sensitive data within them.
1005    It is the application's responsibility to ensure that interprocess
1006    tokens are protected in transit, and transferred only to processes
1007
1008
1009
1010 Kabat & Upadhyay            Standards Track                    [Page 18]
1011 \f
1012 RFC 2853                 GSS-API Java Bindings                 June 2000
1013
1014
1015    that are trustworthy.  An interprocess token is represented using a
1016    byte array emitted from the export method of the GSSContext
1017    interface.  The receiver of the interprocess token would initialize
1018    an GSSContext object with this token to create a new context.  Once a
1019    context has been exported, the GSSContext object is invalidated and
1020    is no longer available.
1021
1022 4.12.  Error Reporting
1023
1024    RFC 2743 defined the usage of major and minor status values for
1025    signaling of GSS-API errors.  The major code, also called GSS status
1026    code, is used to signal errors at the GSS-API level independent of
1027    the underlying mechanism(s).  The minor status value or Mechanism
1028    status code, is a mechanism defined error value indicating a
1029    mechanism specific error code.
1030
1031    Java GSS-API uses exceptions implemented by the GSSException class to
1032    signal both minor and major error values.  Both mechanism specific
1033    errors and GSS-API level errors are signaled through instances of
1034    this class.  The usage of exceptions replaces the need for major and
1035    minor codes to be used within the API calls.  GSSException class also
1036    contains methods to obtain textual representations for both the major
1037    and minor values, which is equivalent to the functionality of
1038    gss_display_status.
1039
1040 4.12.1.  GSS status codes
1041
1042    GSS status codes indicate errors that are independent of the
1043    underlying mechanism(s) used to provide the security service.  The
1044    errors that can be indicated via a GSS status code are generic API
1045    routine errors (errors that are defined in the GSS-API
1046    specification).  These bindings take advantage of the Java exceptions
1047    mechanism, thus eliminating the need for calling errors.
1048
1049    A GSS status code indicates a single fatal generic API error from the
1050    routine that has thrown the GSSException.  Using exceptions announces
1051    that a fatal error has occurred during the execution of the method.
1052    The GSS-API operational model also allows for the signaling of
1053    supplementary status information from the per-message calls.  These
1054    need to be handled as return values since using exceptions is not
1055    appropriate for informatory or warning-like information.  The methods
1056    that are capable of producing supplementary information are the two
1057    per-message methods GSSContext.verifyMIC() and GSSContext.unwrap().
1058    These methods fill the supplementary status codes in the MessageProp
1059    object that was passed in.
1060
1061
1062
1063
1064
1065
1066 Kabat & Upadhyay            Standards Track                    [Page 19]
1067 \f
1068 RFC 2853                 GSS-API Java Bindings                 June 2000
1069
1070
1071    GSSException object, along with providing the functionality for
1072    setting of the various error codes and translating them into textual
1073    representation, also contains the definitions of all the numeric
1074    error values.  The following table lists the definitions of error
1075    codes:
1076
1077       Table: GSS Status Codes
1078
1079       Name                   Value   Meaning
1080
1081       BAD_MECH                 1     An unsupported mechanism
1082                                      was requested.
1083
1084       BAD_NAME                 2     An invalid name was supplied.
1085
1086       BAD_NAMETYPE             3     A supplied name was of an
1087                                      unsupported type.
1088
1089       BAD_BINDINGS             4     Incorrect channel bindings were
1090                                      supplied.
1091
1092       BAD_STATUS               5     An invalid status code was
1093                                      supplied.
1094
1095       BAD_MIC                  6     A token had an invalid MIC.
1096
1097       NO_CRED                  7     No credentials were supplied, or
1098                                      the credentials were unavailable
1099                                      or inaccessible.
1100
1101       NO_CONTEXT               8     Invalid context has been
1102                                      supplied.
1103
1104       DEFECTIVE_TOKEN          9     A supplied token was invalid.
1105
1106       DEFECTIVE_CREDENTIAL    10     A supplied credential was
1107                                      invalid.
1108
1109       CREDENTIALS_EXPIRED     11     The referenced credentials
1110                                      have expired.
1111
1112       CONTEXT_EXPIRED         12     The context has expired.
1113
1114       FAILURE                 13     Miscellaneous failure,
1115                                      unspecified at the GSS-API level.
1116
1117       BAD_QOP                 14     The quality-of-protection
1118                                      requested could not be provided.
1119
1120
1121
1122 Kabat & Upadhyay            Standards Track                    [Page 20]
1123 \f
1124 RFC 2853                 GSS-API Java Bindings                 June 2000
1125
1126
1127       UNAUTHORIZED            15     The operation is forbidden by
1128                                      local security policy.
1129
1130       UNAVAILABLE             16     The operation or option is
1131                                      unavailable.
1132
1133       DUPLICATE_ELEMENT       17     The requested credential
1134                                      element already exists.
1135
1136       NAME_NOT_MN             18     The provided name was not a
1137                                      mechanism name.
1138
1139       OLD_TOKEN               19     The token's validity period has
1140                                      expired.
1141
1142       DUPLICATE_TOKEN         20     The token was a duplicate of an
1143                                      earlier version.
1144
1145    The GSS major status code of FAILURE is used to indicate that the
1146    underlying mechanism detected an error for which no specific GSS
1147    status code is defined.  The mechanism-specific status code can
1148    provide more details about the error.
1149
1150    The different major status codes that can be contained in the
1151    GSSException object thrown by the methods in this specification are
1152    the same as the major status codes returned by the corresponding
1153    calls in RFC 2743 [GSSAPIv2-UPDATE].
1154
1155 4.12.2.  Mechanism-specific status codes
1156
1157    Mechanism-specific status codes are communicated in two ways, they
1158    are part of any GSSException thrown from the mechanism specific layer
1159    to signal a fatal error, or they are part of the MessageProp object
1160    that the per-message calls use to signal non-fatal errors.
1161
1162    A default value of 0 in either the GSSException object or the
1163    MessageProp object will be used to represent the absence of any
1164    mechanism specific status code.
1165
1166 4.12.3.  Supplementary status codes
1167
1168    Supplementary status codes are confined to the per-message methods of
1169    the GSSContext interface.  Because of the informative nature of these
1170    errors it is not appropriate to use exceptions to signal them.
1171    Instead, the per-message operations of the GSSContext interface
1172    return these values in a MessageProp object.
1173
1174
1175
1176
1177
1178 Kabat & Upadhyay            Standards Track                    [Page 21]
1179 \f
1180 RFC 2853                 GSS-API Java Bindings                 June 2000
1181
1182
1183    The MessageProp class defines query methods which return boolean
1184    values indicating the following supplementary states:
1185
1186       Table: Supplementary Status Methods
1187
1188       Method Name       Meaning when "true" is returned
1189
1190       isDuplicateToken   The token was a duplicate of an
1191                          earlier token.
1192
1193       isOldToken         The token's validity period has
1194                          expired.
1195
1196       isUnseqToken       A later token has already been
1197                          processed.
1198
1199       isGapToken         An expected per-message token was
1200                          not received.
1201
1202    "true" return value for any of the above methods indicates that the
1203    token exhibited the specified property.  The application must
1204    determine the appropriate course of action for these supplementary
1205    values.  They are not treated as errors by the GSS-API.
1206
1207 4.13.  Names
1208
1209    A name is used to identify a person or entity.  GSS-API authenticates
1210    the relationship between a name and the entity claiming the name.
1211
1212    Since different authentication mechanisms may employ different
1213    namespaces for identifying their principals, GSS-API's naming support
1214    is necessarily complex in multi-mechanism environments (or even in
1215    some single-mechanism environments where the underlying mechanism
1216    supports multiple namespaces).
1217
1218    Two distinct conceptual representations are defined for names:
1219
1220    1) A GSS-API form represented by implementations of the GSSName
1221       interface: A single GSSName object may contain multiple names from
1222       different namespaces, but all names should refer to the same
1223       entity.  An example of such an internal name would be the name
1224       returned from a call to the getName method of the GSSCredential
1225       interface, when applied to a credential containing credential
1226       elements for multiple authentication mechanisms employing
1227       different namespaces.  This GSSName object will contain a distinct
1228       name for the entity for each authentication mechanism.
1229
1230
1231
1232
1233
1234 Kabat & Upadhyay            Standards Track                    [Page 22]
1235 \f
1236 RFC 2853                 GSS-API Java Bindings                 June 2000
1237
1238
1239       For GSS-API implementations supporting multiple namespaces,
1240       GSSName implementations must contain sufficient information to
1241       determine the namespace to which each primitive name belongs.
1242
1243    2) Mechanism-specific contiguous byte array and string forms:
1244       Different GSSName initialization methods are provided to handle
1245       both byte array and string formats and to accommodate various
1246       calling applications and name types.  These formats are capable of
1247       containing only a single name (from a single namespace).
1248       Contiguous string names are always accompanied by an object
1249       identifier specifying the namespace to which the name belongs, and
1250       their format is dependent on the authentication mechanism that
1251       employs that name.  The string name forms are assumed to be
1252       printable, and may therefore be used by GSS-API applications for
1253       communication with their users.  The byte array name formats are
1254       assumed to be in non-printable formats (e.g.  the byte array
1255       returned from the export method of the GSSName interface).
1256
1257    A GSSName object can be converted to a contiguous representation by
1258    using the toString method.  This will guarantee that the name will be
1259    converted to a printable format.  Different initialization methods in
1260    the GSSName interface are defined allowing support for multiple
1261    syntaxes for each supported namespace, and allowing users the freedom
1262    to choose a preferred name representation.  The toString method
1263    should use an implementation-chosen printable syntax for each
1264    supported name-type.  To obtain the printable name type,
1265    getStringNameType method can be used.
1266
1267    There is no guarantee that calling the toString method on the GSSName
1268    interface will produce the same string form as the original imported
1269    string name.  Furthermore, it is possible that the name was not even
1270    constructed from a string representation.  The same applies to name-
1271    space identifiers which may not necessarily survive unchanged after a
1272    journey through the internal name-form.  An example of this might be
1273    a mechanism that authenticates X.500 names, but provides an
1274    algorithmic mapping of Internet DNS names into X.500.  That
1275    mechanism's implementation of GSSName might, when presented with a
1276    DNS name, generate an internal name that contained both the original
1277    DNS name and the equivalent X.500 name.  Alternatively, it might only
1278    store the X.500 name.  In the latter case, the toString method of
1279    GSSName would most likely generate a printable X.500 name, rather
1280    than the original DNS name.
1281
1282    The context acceptor can obtain a GSSName object representing the
1283    entity performing the context initiation (through the usage of
1284    getSrcName method).  Since this name has been authenticated by a
1285    single mechanism, it contains only a single name (even if the
1286    internal name presented by the context initiator to the GSSContext
1287
1288
1289
1290 Kabat & Upadhyay            Standards Track                    [Page 23]
1291 \f
1292 RFC 2853                 GSS-API Java Bindings                 June 2000
1293
1294
1295    object had multiple components).  Such names are termed internal
1296    mechanism names, or "MN"s and the names emitted by GSSContext
1297    interface in the getSrcName and getTargName are always of this type.
1298    Since some applications may require MNs without wanting to incur the
1299    overhead of an authentication operation, creation methods are
1300    provided that take not only the name buffer and name type, but also
1301    the mechanism oid for which this name should be created.  When
1302    dealing with an existing GSSName object, the canonicalize method may
1303    be invoked to convert a general internal name into an MN.
1304
1305    GSSName objects can be compared using their equal method, which
1306    returns "true" if the two names being compared refer to the same
1307    entity.  This is the preferred way to perform name comparisons
1308    instead of using the printable names that a given GSS-API
1309    implementation may support.  Since GSS-API assumes that all primitive
1310    names contained within a given internal name refer to the same
1311    entity, equal can return "true" if the two names have at least one
1312    primitive name in common.  If the implementation embodies knowledge
1313    of equivalence relationships between names taken from different
1314    namespaces, this knowledge may also allow successful comparisons of
1315    internal names containing no overlapping primitive elements.
1316
1317    When used in large access control lists, the overhead of creating an
1318    GSSName object on each name and invoking the equal method on each
1319    name from the ACL may be prohibitive.  As an alternative way of
1320    supporting this case, GSS-API defines a special form of the
1321    contiguous byte array name which may be compared directly (byte by
1322    byte).  Contiguous names suitable for comparison are generated by the
1323    export method.  Exported names may be re-imported by using the byte
1324    array constructor and specifying the NT_EXPORT_NAME as the name type
1325    object identifier.  The resulting GSSName name will also be a MN.
1326    The GSSName interface defines public static Oid objects representing
1327    the standard name types.  Structurally, an exported name object
1328    consists of a header containing an OID identifying the mechanism that
1329    authenticated the name, and a trailer containing the name itself,
1330    where the syntax of the trailer is defined by the individual
1331    mechanism specification.  Detailed description of the format is
1332    specified in the language-independent GSS-API specification
1333    [GSSAPIv2-UPDATE].
1334
1335    Note that the results obtained by using the equals method will in
1336    general be different from those obtained by invoking canonicalize and
1337    export, and then comparing the byte array output.  The first series
1338    of operation determines whether two (unauthenticated) names identify
1339    the same principal; the second whether a particular mechanism would
1340    authenticate them as the same principal.  These two operations will
1341    in general give the same results only for MNs.
1342
1343
1344
1345
1346 Kabat & Upadhyay            Standards Track                    [Page 24]
1347 \f
1348 RFC 2853                 GSS-API Java Bindings                 June 2000
1349
1350
1351    It is important to note that the above are guidelines as how GSSName
1352    implementations should behave, and are not intended to be specific
1353    requirements of how names objects must be implemented.  The mechanism
1354    designers are free to decide on the details of their implementations
1355    of the GSSName interface as long as the behavior satisfies the above
1356    guidelines.
1357
1358 4.14.  Channel Bindings
1359
1360    GSS-API supports the use of user-specified tags to identify a given
1361    context to the peer application.  These tags are intended to be used
1362    to identify the particular communications channel that carries the
1363    context.  Channel bindings are communicated to the GSS-API using the
1364    ChannelBinding object.  The application may use byte arrays to
1365    specify the application data to be used in the channel binding as
1366    well as using instances of the InetAddress.  The InetAddress for the
1367    initiator and/or acceptor can be used within an instance of a
1368    ChannelBinding.  ChannelBinding can be set for the GSSContext object
1369    using the setChannelBinding method before the first call to init or
1370    accept has been performed.  Unless the setChannelBinding method has
1371    been used to set the ChannelBinding for a GSSContext object, "null"
1372    ChannelBinding will be assumed.  InetAddress is currently the only
1373    address type defined within the Java platform and as such, it is the
1374    only one supported within the ChannelBinding class.  Applications
1375    that use other types of addresses can include them as part of the
1376    application specific data.
1377
1378    Conceptually, the GSS-API concatenates the initiator and acceptor
1379    address information, and the application supplied byte array to form
1380    an octet string.  The mechanism calculates a MIC over this octet
1381    string and binds the MIC to the context establishment token emitted
1382    by init method of the GSSContext interface.  The same bindings are
1383    set by the context acceptor for its GSSContext object and during
1384    processing of the accept method a MIC is calculated in the same way.
1385    The calculated MIC is compared with that found in the token, and if
1386    the MICs differ, accept will throw a GSSException with the  major
1387    code set to BAD_BINDINGS, and the context will not be established.
1388    Some mechanisms may include the actual channel binding data in the
1389    token (rather than just a MIC); applications should therefore not use
1390    confidential data as channel-binding components.
1391
1392    Individual mechanisms may impose additional constraints on addresses
1393    that may appear in channel bindings.  For example, a mechanism may
1394    verify that the initiator address field of the channel binding
1395    contains the correct network address of the host system.  Portable
1396    applications should therefore ensure that they either provide correct
1397    information for the address fields, or omit setting of the addressing
1398    information.
1399
1400
1401
1402 Kabat & Upadhyay            Standards Track                    [Page 25]
1403 \f
1404 RFC 2853                 GSS-API Java Bindings                 June 2000
1405
1406
1407 4.15.  Stream Objects
1408
1409    The context object provides overloaded methods which use input and
1410    output streams as the means to convey authentication and per-message
1411    GSS-API tokens.  It is important to note that the streams are
1412    expected to contain the usual GSS-API tokens which would otherwise be
1413    handled through the usage of byte arrays.  The tokens are expected to
1414    have a definite start and an end.  The callers are responsible for
1415    ensuring that the supplied streams will not block, or expect to block
1416    until a full token is processed by the GSS-API method.  Only a single
1417    GSS-API token will be processed per invocation of the stream based
1418    method.
1419
1420    The usage of streams allows the callers to have control and
1421    management of the supplied buffers.  Because streams are non-
1422    primitive objects, the callers can make the streams as complicated or
1423    as simple as desired simply by using the streams defined in the
1424    java.io package or creating their own through the use of inheritance.
1425    This will allow for the application's greatest flexibility.
1426
1427 4.16.  Optional Parameters
1428
1429    Whenever the application wishes to omit an optional parameter the
1430    "null" value shall be used.  The detailed method descriptions
1431    indicate which parameters are optional.  Methods overloading has also
1432    been used as a technique to indicate default parameters.
1433
1434 5.  Introduction to GSS-API Classes and Interfaces
1435
1436    This section presents a brief description of the classes and
1437    interfaces that constitute the GSS-API.  The implementations of these
1438    are obtained from the CLASSPATH defined by the application.  If Java
1439    GSS becomes part of the standard Java API's then these classes will
1440    be available by default on all systems as part of the JRE's system
1441    classes.
1442
1443    This section also shows the corresponding RFC 2743 functionality
1444    implemented by each of the classes.  Detailed description of these
1445    classes and their methods is presented in section 6.
1446
1447 5.1.  GSSManager class
1448
1449    This abstract class serves as a factory to instantiate
1450    implementations of the GSS-API interfaces and also provides methods
1451    to make queries about underlying security mechanisms.
1452
1453
1454
1455
1456
1457
1458 Kabat & Upadhyay            Standards Track                    [Page 26]
1459 \f
1460 RFC 2853                 GSS-API Java Bindings                 June 2000
1461
1462
1463    A default implementation can be obtained using the static method
1464    getInstance(). Applications that desire to provide their own
1465    implementation of the GSSManager class can simply extend the abstract
1466    class themselves.
1467
1468    This class contains equivalents of the following RFC 2743 routines:
1469
1470    gss_import_name              Create an internal name from   6.1.9-
1471                                 the supplied information.      6.1.12
1472
1473    gss_acquire_cred             Acquire credential             6.1.13-
1474                                 for use.                       6.1.15
1475
1476    gss_import_sec_context       Create a previously exported   6.1.18
1477                                 context.
1478
1479    gss_indicate_mechs           List the mechanisms            6.1.6
1480                                 supported by this GSS-API
1481                                 implementation.
1482
1483    gss_inquire_mechs_for_name   List the mechanisms            6.1.8
1484                                 supporting the
1485                                 specified name type.
1486
1487    gss_inquire_names_for_mech   List the name types            6.1.7
1488                                 supported by the
1489                                 specified mechanism.
1490
1491 5.2.  GSSName interface
1492
1493    GSS-API names are represented in the Java bindings through the
1494    GSSName interface.  Different name formats and their definitions are
1495    identified with universal Object Identifiers (oids).  The format of
1496    the names can be derived based on the unique oid of each name type.
1497    The following GSS-API routines are provided by the GSSName interface:
1498
1499    RFC 2743 Routine                 Function               Section(s)
1500
1501
1502    gss_display_name        Covert internal name             6.2.7
1503                            representation to text format.
1504
1505    gss_compare_name        Compare two internal names.      6.2.3, 6.2.4
1506
1507    gss_release_name        Release resources associated     N/A
1508                            with the internal name.
1509
1510
1511
1512
1513
1514 Kabat & Upadhyay            Standards Track                    [Page 27]
1515 \f
1516 RFC 2853                 GSS-API Java Bindings                 June 2000
1517
1518
1519    gss_canonicalize_name   Convert an internal name to a    6.1.11,
1520                            mechanism name.
1521
1522    gss_export_name         Convert a mechanism name to      6.2.6
1523                            export format.
1524
1525    gss_duplicate_name      Create a copy of the internal    N/A
1526                            name.
1527
1528    The gss_release_name call is not provided as Java does its own
1529    garbage collection. The gss_duplicate_name call is also redundant;
1530    the GSSName interface has no mutator methods that can change the
1531    state of the object so it is safe for sharing.
1532
1533 5.3.  GSSCredential interface
1534
1535    The GSSCredential interface is responsible for the encapsulation of
1536    GSS-API credentials.  Credentials identify a single entity and
1537    provide the necessary cryptographic information to enable the
1538    creation of a context on behalf of that entity.  A single credential
1539    may contain multiple mechanism specific credentials, each referred to
1540    as a credential element.  The GSSCredential interface provides the
1541    functionality of the following GSS-API routines:
1542
1543    RFC 2743 Routine               Function                Section(s)
1544
1545    gss_add_cred               Constructs credentials        6.3.12
1546                               incrementally.
1547
1548    gss_inquire_cred           Obtain information about   6.3.4,6.3.5
1549                               credential.
1550
1551    gss_inquire_cred_by_mech   Obtain per-mechanism       6.3.5-6.3.10
1552                               information about
1553                               a credential.
1554
1555    gss_release_cred           Disposes of credentials       6.3.3
1556                               after use.
1557
1558 5.4.  GSSContext interface
1559
1560    This interface encapsulates the functionality of context-level calls
1561    required for security context establishment and management between
1562    peers as well as the per-message services offered to applications.  A
1563    context is established between a pair of peers and allows the usage
1564    of security services on a per-message basis on application data.  It
1565
1566
1567
1568
1569
1570 Kabat & Upadhyay            Standards Track                    [Page 28]
1571 \f
1572 RFC 2853                 GSS-API Java Bindings                 June 2000
1573
1574
1575    is created over a single security mechanism.  The GSSContext
1576    interface provides the functionality of the following GSS-API
1577    routines:
1578
1579    RFC 2743 Routine                 Function                Section(s)
1580
1581    gss_init_sec_context     Initiate the creation of a       6.4.3,
1582                             security context with a peer.    6.4.4
1583
1584    gss_accept_sec_context   Accept a security context        6.4.5,
1585                             initiated by a peer.             6.4.6
1586
1587    gss_delete_sec_context   Destroy a security context.      6.4.8
1588
1589    gss_context_time         Obtain remaining context         6.4.37
1590                             time.
1591
1592    gss_inquire_context      Obtain context                   6.4.29 to
1593                             characteristics.                 6.3.42
1594
1595    gss_wrap_size_limit      Determine token-size limit       6.4.9
1596                             for gss_wrap.
1597
1598    gss_export_sec_context   Transfer security context        6.4.18
1599                             to another process.
1600
1601
1602    gss_get_mic              Calculate a cryptographic        6.4.14,
1603                             Message Integrity Code (MIC)     6.4.15
1604                             for a message.
1605
1606    gss_verify_mic           Verify integrity on a received   6.4.16,
1607                             message.                         6.4.17
1608
1609    gss_wrap                 Attach a MIC to a message and    6.4.10,
1610                             optionally encrypt the message   6.4.11
1611                             content.
1612
1613    gss_unwrap               Obtain a previously wrapped      6.4.12,
1614                             application message verifying    6.4.13
1615                             its integrity and optionally
1616                             decrypting it.
1617
1618    The functionality offered by the gss_process_context_token routine
1619    has not been included in the Java bindings specification.  The
1620    corresponding functionality of gss_delete_sec_context has also been
1621    modified to not return any peer tokens.  This has been proposed in
1622
1623
1624
1625
1626 Kabat & Upadhyay            Standards Track                    [Page 29]
1627 \f
1628 RFC 2853                 GSS-API Java Bindings                 June 2000
1629
1630
1631    accordance to the recommendations stated in RFC 2743.  GSSContext
1632    does offer the functionality of destroying the locally-stored context
1633    information.
1634
1635 5.5.  MessageProp class
1636
1637    This helper class is used in the per-message operations on the
1638    context.  An instance of this class is created by the application and
1639    then passed into the per-message calls.  In some cases, the
1640    application conveys information to the GSS-API implementation through
1641    this object and in other cases the GSS-API returns information to the
1642    application by setting it in this object.  See the description of the
1643    per-message operations wrap, unwrap, getMIC, and verifyMIC in the
1644    GSSContext interfaces for details.
1645
1646 5.6.  GSSException class
1647
1648    Exceptions are used in the Java bindings to signal fatal errors to
1649    the calling applications.  This replaces the major and minor codes
1650    used in the C-bindings specification as a method of signaling
1651    failures.  The GSSException class handles both minor and major codes,
1652    as well as their translation into textual representation.  All GSS-
1653    API methods are declared as throwing this exception.
1654
1655    RFC 2743 Routine           Function              Section
1656
1657    gss_display_status   Retrieve textual          6.8.5, 6.8.6,
1658                         representation of error   6.8.8, 6.8.9
1659                         codes.
1660
1661 5.7.  Oid class
1662
1663    This utility class is used to represent Universal Object Identifiers
1664    and their associated operations.  GSS-API uses object identifiers to
1665    distinguish between security mechanisms and name types.  This class,
1666    aside from being used whenever an object identifier is needed,
1667    implements the following GSS-API functionality:
1668
1669    RFC 2743 Routine                  Function              Section
1670
1671    gss_test_oid_set_member   Determine if the specified oid   6.7.5
1672                              is part of a set of oids.
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682 Kabat & Upadhyay            Standards Track                    [Page 30]
1683 \f
1684 RFC 2853                 GSS-API Java Bindings                 June 2000
1685
1686
1687 5.8.  ChannelBinding class
1688
1689    An instance of this class is used to specify channel binding
1690    information to the GSSContext object before the start of a security
1691    context establishment.  The application may use a byte array to
1692    specify application data to be used in the channel binding as well as
1693    use instances of the InetAddress.  InetAddress is currently the only
1694    address type defined within the Java platform and as such, it is the
1695    only one supported within the ChannelBinding class. Applications that
1696    use other types of addresses can include them as part of the
1697    application data.
1698
1699 6.  Detailed GSS-API Class Description
1700
1701    This section lists a detailed description of all the public methods
1702    that each of the GSS-API classes and interfaces must provide.
1703
1704 6.1.  public abstract class GSSManager
1705
1706    The GSSManager class is an abstract class that serves as a factory
1707    for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It
1708    also provides methods for applications to determine what mechanisms
1709    are available from the GSS implementation and what nametypes these
1710    mechanisms support. An instance of the default GSSManager subclass
1711    may be obtained through the static method getInstance(), but
1712    applications are free to instantiate other subclasses of GSSManager.
1713
1714    All but one method in this class are declared abstract. This means
1715    that subclasses have to provide the complete implementation for those
1716    methods. The only exception to this is the static method
1717    getInstance() which will have platform specific code to return an
1718    instance of the default subclass.
1719
1720    Platform providers of GSS are required not to add any constructors to
1721    this class, private, public, or protected. This will ensure that all
1722    subclasses invoke only the default constructor provided to the base
1723    class by the compiler.
1724
1725    A subclass extending the GSSManager abstract class may be implemented
1726    as a modular provider based layer that utilizes some well known
1727    service provider specification. The GSSManager API provides the
1728    application with methods to set provider preferences on such an
1729    implementation. These methods also allow the implementation to throw
1730    a well-defined exception in case provider based configuration is not
1731    supported. Applications that expect to be portable should be aware of
1732    this and recover cleanly by catching the exception.
1733
1734
1735
1736
1737
1738 Kabat & Upadhyay            Standards Track                    [Page 31]
1739 \f
1740 RFC 2853                 GSS-API Java Bindings                 June 2000
1741
1742
1743    It is envisioned that there will be three most common ways in which
1744    providers will be used:
1745
1746       1) The application does not care about what provider is used (the
1747          default case).
1748
1749       2) The application wants a particular provider to be used
1750          preferentially, either for a particular mechanism or all the
1751          time, irrespective of mechanism.
1752
1753       3) The application wants to use the locally configured providers
1754          as far as possible but if support is missing for one or more
1755          mechanisms then it wants to fall back on its own provider.
1756
1757    The GSSManager class has two methods that enable these modes of
1758    usage:  addProviderAtFront() and addProviderAtEnd(). These methods
1759    have the effect of creating an ordered list of <provider, oid> pairs
1760    where each pair indicates a preference of provider for a given oid.
1761
1762    The use of these methods does not require any knowledge of whatever
1763    service provider specification the GSSManager subclass follows. It is
1764    hoped that these methods will serve the needs of most applications.
1765    Additional methods may be added to an extended GSSManager that could
1766    be part of a service provider specification that is standardized
1767    later.
1768
1769 6.1.1.  Example Code
1770
1771    GSSManager mgr = GSSManager.getInstance();
1772
1773    // What mechs are available to us?
1774    Oid[] supportedMechs = mgr.getMechs();
1775
1776    // Set a preference for the provider to be used when support is needed
1777    // for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1".
1778
1779    Oid krb = new Oid("1.2.840.113554.1.2.2");
1780    Oid spkm1 = new Oid("1.3.6.1.5.5.1.1");
1781
1782    Provider p = (Provider) (new com.foo.security.Provider());
1783
1784    mgr.addProviderAtFront(p, krb);
1785    mgr.addProviderAtFront(p, spkm1);
1786
1787    // What name types does this spkm implementation support?
1788    Oid[] nameTypes = mgr.getNamesForMech(spkm1);
1789
1790
1791
1792
1793
1794 Kabat & Upadhyay            Standards Track                    [Page 32]
1795 \f
1796 RFC 2853                 GSS-API Java Bindings                 June 2000
1797
1798
1799 6.1.2.  getInstance
1800
1801    public static GSSManager getInstance()
1802
1803    Returns the default GSSManager implementation.
1804
1805 6.1.3.  getMechs
1806
1807    public abstract Oid[] getMechs()
1808
1809    Returns an array of Oid objects indicating mechanisms available to
1810    GSS-API callers.  A "null" value is returned when no mechanism are
1811    available (an example of this would be when mechanism are dynamically
1812    configured, and currently no mechanisms are installed).
1813
1814 6.1.4.  getNamesForMech
1815
1816    public abstract  Oid[] getNamesForMech(Oid mech)
1817                           throws GSSException
1818
1819    Returns name type Oid's supported by the specified mechanism.
1820
1821    Parameters:
1822
1823       mech      The Oid object for the mechanism to query.
1824
1825 6.1.5.  getMechsForName
1826
1827    public abstract  Oid[] getMechsForName(Oid nameType)
1828
1829    Returns an array of Oid objects corresponding to the mechanisms that
1830    support the specific name type.  "null" is returned when no
1831    mechanisms are found to support the specified name type.
1832
1833    Parameters:
1834
1835       nameType  The Oid object for the name type.
1836
1837 6.1.6.  createName
1838
1839    public abstract GSSName createName(String nameStr, Oid nameType)
1840                    throws GSSException
1841
1842    Factory method to convert a contiguous string name from the specified
1843    namespace to a GSSName object.  In general, the GSSName object
1844    created will not be an MN; two examples that are exceptions to this
1845    are when the namespace type parameter indicates NT_EXPORT_NAME or
1846    when the GSS-API implementation is not multi-mechanism.
1847
1848
1849
1850 Kabat & Upadhyay            Standards Track                    [Page 33]
1851 \f
1852 RFC 2853                 GSS-API Java Bindings                 June 2000
1853
1854
1855    Parameters:
1856
1857       nameStr   The string representing a printable form of the name
1858                 to create.
1859
1860       nameType  The Oid specifying the namespace of the printable name
1861                 supplied. Note that nameType serves to describe and
1862                 qualify the interpretation of the input nameStr, it
1863                 does not necessarily imply a type for the output
1864                 GSSName implementation. "null" value can be used to
1865                 specify that a mechanism specific default printable
1866                 syntax should be assumed by each mechanism that
1867                 examines nameStr.
1868
1869 6.1.7.  createName
1870
1871    public abstract GSSName createName(byte name[], Oid nameType)
1872                    throws GSSException
1873
1874    Factory method to convert a contiguous byte array containing a name
1875    from the specified namespace to a GSSName object.  In general, the
1876    GSSName object created will not be an MN; two examples that are
1877    exceptions to this are when the namespace type parameter indicates
1878    NT_EXPORT_NAME or when the GSS-API implementation is not multi-
1879    mechanism.
1880
1881    Parameters:
1882
1883       name      The byte array containing the name to create.
1884
1885       nameType  The Oid specifying the namespace of the name supplied
1886                 in the byte array.  Note that nameType serves to
1887                 describe and qualify the interpretation of the input
1888                 name byte array, it does not necessarily imply a type
1889                 for the output GSSName implementation. "null" value
1890                 can be used to specify that a mechanism specific
1891                 default syntax should be assumed by each mechanism
1892                 that examines the byte array.
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906 Kabat & Upadhyay            Standards Track                    [Page 34]
1907 \f
1908 RFC 2853                 GSS-API Java Bindings                 June 2000
1909
1910
1911 6.1.8.  createName
1912
1913    public abstract GSSName createName(String nameStr, Oid nameType,
1914                    Oid mech) throws GSSException
1915
1916    Factory method to convert a contiguous string name from the specified
1917    namespace to an GSSName object that is a mechanism name (MN).  In
1918    other words, this method is a utility that does the equivalent of two
1919    steps: the createName described in 6.1.7 and then also the
1920    GSSName.canonicalize() described in 6.2.5.
1921
1922    Parameters:
1923
1924       nameStr   The string representing a printable form of the name
1925                 to create.
1926
1927       nameType  The Oid specifying the namespace of the printable name
1928                 supplied.  Note that nameType serves to describe and
1929                 qualify the interpretation of the input nameStr, it
1930                 does not necessarily imply a type for the output
1931                 GSSName implementation. "null" value can be used to
1932                 specify that a mechanism specific default printable
1933                 syntax should be assumed when the mechanism examines
1934                 nameStr.
1935
1936       mech      Oid specifying the mechanism for which this name
1937                 should be created.
1938
1939 6.1.9.  createName
1940
1941    public abstract createName(byte name[], Oid nameType, Oid mech)
1942                    throws GSSException
1943
1944    Factory method to convert a contiguous byte array containing a name
1945    from the specified namespace to a GSSName object that is an MN.  In
1946    other words, this method is a utility that does the equivalent of two
1947    steps: the createName described in 6.1.8 and then also the
1948    GSSName.canonicalize() described in 6.2.5.
1949
1950    Parameters:
1951
1952       name      The byte array representing the name to create.
1953
1954       nameType  The Oid specifying the namespace of the name supplied
1955                 in the byte array.  Note that nameType serves to
1956                 describe and qualify the interpretation of the input
1957                 name byte array, it does not necessarily imply a type
1958                 for the output GSSName implementation. "null" value
1959
1960
1961
1962 Kabat & Upadhyay            Standards Track                    [Page 35]
1963 \f
1964 RFC 2853                 GSS-API Java Bindings                 June 2000
1965
1966
1967                 can be used to specify that a mechanism specific
1968                 default syntax should be assumed by each mechanism
1969                 that examines the byte array.
1970
1971       mech      Oid specifying the mechanism for which this name
1972                 should be created.
1973
1974 6.1.10.  createCredential
1975
1976    public abstract GSSCredential createCredential (int usage)
1977                    throws GSSException
1978
1979    Factory method for acquiring default credentials.  This will cause
1980    the GSS-API to use system specific defaults for the set of
1981    mechanisms, name, and a DEFAULT lifetime.
1982
1983    Parameters:
1984
1985       usage     The intended usage for this credential object.  The
1986                 value of this parameter must be one of:
1987                 GSSCredential.ACCEPT_AND_INITIATE,
1988                 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY
1989
1990 6.1.11.  createCredential
1991
1992    public abstract GSSCredential createCredential (GSSName aName,
1993                    int lifetime, Oid mech, int usage)
1994                    throws GSSException
1995
1996    Factory method for acquiring a single mechanism credential.
1997
1998    Parameters:
1999
2000       aName     Name of the principal for whom this credential is to
2001                 be acquired.  Use "null" to specify the default
2002                 principal.
2003
2004       lifetime  The number of seconds that credentials should remain
2005                 valid.  Use GSSCredential.INDEFINITE_LIFETIME to
2006                 request that the credentials have the maximum
2007                 permitted lifetime.  Use
2008                 GSSCredential.DEFAULT_LIFETIME to request default
2009                 credential lifetime.
2010
2011       mech      The oid of the desired mechanism.  Use "(Oid) null" to
2012                 request the default mechanism(s).
2013
2014
2015
2016
2017
2018 Kabat & Upadhyay            Standards Track                    [Page 36]
2019 \f
2020 RFC 2853                 GSS-API Java Bindings                 June 2000
2021
2022
2023       usage     The intended usage for this credential object.  The
2024                 value of this parameter must be one of:
2025                 GSSCredential.ACCEPT_AND_INITIATE,
2026                 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY
2027
2028 6.1.12.  createCredential
2029
2030    public abstract GSSCredential createCredential(GSSName aName,
2031                    int lifetime, Oid mechs[], int usage)
2032                    throws GSSException
2033
2034    Factory method for acquiring credentials over a set of mechanisms.
2035    Acquires credentials for each of the mechanisms specified in the
2036    array called mechs.  To determine the list of mechanisms' for which
2037    the acquisition of credentials succeeded, the caller should use the
2038    GSSCredential.getMechs() method.
2039
2040    Parameters:
2041
2042       aName     Name of the principal for whom this credential is to
2043                 be acquired.  Use "null" to specify the default
2044                 principal.
2045
2046       lifetime  The number of seconds that credentials should remain
2047                 valid.  Use GSSCredential.INDEFINITE_LIFETIME to
2048                 request that the credentials have the maximum
2049                 permitted lifetime.  Use
2050                 GSSCredential.DEFAULT_LIFETIME to request default
2051                 credential lifetime.
2052
2053       mechs     The array of mechanisms over which the credential is
2054                 to be acquired.  Use "(Oid[]) null" for requesting a
2055                 system specific default set of mechanisms.
2056
2057       usage     The intended usage for this credential object.  The
2058                 value of this parameter must be one of:
2059                 GSSCredential.ACCEPT_AND_INITIATE,
2060                 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY
2061
2062 6.1.13.  createContext
2063
2064    public abstract GSSContext createContext(GSSName peer, Oid mech,
2065                    GSSCredential myCred, int lifetime)
2066                    throws GSSException
2067
2068    Factory method for creating a context on the initiator's side.
2069    Context flags may be modified through the mutator methods prior to
2070    calling GSSContext.initSecContext().
2071
2072
2073
2074 Kabat & Upadhyay            Standards Track                    [Page 37]
2075 \f
2076 RFC 2853                 GSS-API Java Bindings                 June 2000
2077
2078
2079    Parameters:
2080
2081       peer      Name of the target peer.
2082
2083       mech      Oid of the desired mechanism.  Use "(Oid) null" to
2084                 request default mechanism.
2085
2086       myCred    Credentials of the initiator.  Use "null" to act as a
2087                 default initiator principal.
2088
2089       lifetime  The request lifetime, in seconds, for the context.
2090                 Use GSSContext.INDEFINITE_LIFETIME and
2091                 GSSContext.DEFAULT_LIFETIME to request indefinite or
2092                 default context lifetime.
2093
2094 6.1.14.  createContext
2095
2096    public abstract GSSContext createContext(GSSCredential myCred)
2097                    throws GSSException
2098
2099    Factory method for creating a context on the acceptor' side.  The
2100    context's properties will be determined from the input token supplied
2101    to the accept method.
2102
2103    Parameters:
2104
2105       myCred    Credentials for the acceptor.  Use "null" to act as a
2106                 default acceptor principal.
2107
2108 6.1.15.  createContext
2109
2110    public abstract GSSContext createContext(byte [] interProcessToken)
2111                    throws GSSException
2112
2113    Factory method for creating a previously exported context.  The
2114    context properties will be determined from the input token and can't
2115    be modified through the set methods.
2116
2117    Parameters:
2118
2119       interProcessToken
2120                 The token previously emitted from the export method.
2121
2122 6.1.16.  addProviderAtFront
2123
2124    public abstract void addProviderAtFront(Provider p, Oid mech)
2125                 throws GSSException
2126
2127
2128
2129
2130 Kabat & Upadhyay            Standards Track                    [Page 38]
2131 \f
2132 RFC 2853                 GSS-API Java Bindings                 June 2000
2133
2134
2135    This method is used to indicate to the GSSManager that the
2136    application would like a particular provider to be used ahead of all
2137    others when support is desired for the given mechanism. When a value
2138    of null is used instead of an Oid for the mechanism, the GSSManager
2139    must use the indicated provider ahead of all others no matter what
2140    the mechanism is. Only when the indicated provider does not support
2141    the needed mechanism should the GSSManager move on to a different
2142    provider.
2143
2144    Calling this method repeatedly preserves the older settings but
2145    lowers them in preference thus forming an ordered list of provider
2146    and Oid pairs that grows at the top.
2147
2148    Calling addProviderAtFront with a null Oid will remove all previous
2149    preferences that were set for this provider in the GSSManager
2150    instance. Calling addProviderAtFront with a non-null Oid will remove
2151    any previous preference that was set using this mechanism and this
2152    provider together.
2153
2154    If the GSSManager implementation does not support an SPI with a
2155    pluggable provider architecture it should throw a GSSException with
2156    the status code GSSException.UNAVAILABLE to indicate that the
2157    operation is unavailable.
2158
2159    Parameters:
2160
2161       p         The provider instance that should be used whenever
2162                 support is needed for mech.
2163
2164       mech      The mechanism for which the provider is being set
2165
2166 6.1.16.1.  Example Code
2167
2168    Suppose an application desired that the provider A always be checked
2169    first when any mechanism is needed, it would call:
2170
2171            GSSManager mgr = GSSManager.getInstance();
2172            // mgr may at this point have its own pre-configured list
2173            // of provider preferences. The following will prepend to
2174            // any such list:
2175
2176            mgr.addProviderAtFront(A, null);
2177
2178    Now if it also desired that the mechanism of Oid m1 always be
2179    obtained from the provider B before the previously set A was checked,
2180    it would call:
2181
2182            mgr.addProviderAtFront(B, m1);
2183
2184
2185
2186 Kabat & Upadhyay            Standards Track                    [Page 39]
2187 \f
2188 RFC 2853                 GSS-API Java Bindings                 June 2000
2189
2190
2191    The GSSManager would then first check with B if m1 was needed. In
2192    case B did not provide support for m1, the GSSManager would continue
2193    on to check with A.  If any mechanism m2 is needed where m2 is
2194    different from m1 then the GSSManager would skip B and check with A
2195    directly.
2196
2197    Suppose at a later time the following call is made to the same
2198    GSSManager instance:
2199
2200            mgr.addProviderAtFront(B, null)
2201
2202    then the previous setting with the pair (B, m1) is subsumed by this
2203    and should be removed. Effectively the list of preferences now
2204    becomes {(B, null), (A, null),
2205            ... //followed by the pre-configured list.
2206
2207    Please note, however, that the following call:
2208
2209            mgr.addProviderAtFront(A, m3)
2210
2211    does not subsume the previous setting of (A, null) and the list will
2212    effectively become {(A, m3), (B, null), (A, null), ...}
2213
2214 6.1.17.  addProviderAtEnd
2215
2216    public abstract addProviderAtEnd(Provider p, Oid mech)
2217                    throws GSSException
2218
2219    This method is used to indicate to the GSSManager that the
2220    application would like a particular provider to be used if no other
2221    provider can be found that supports the given mechanism. When a value
2222    of null is used instead of an Oid for the mechanism, the GSSManager
2223    must use the indicated provider for any mechanism.
2224
2225    Calling this method repeatedly preserves the older settings but
2226    raises them above newer ones in preference thus forming an ordered
2227    list of providers and Oid pairs that grows at the bottom. Thus the
2228    older provider settings will be utilized first before this one is.
2229
2230    If there are any previously existing preferences that conflict with
2231    the preference being set here, then the GSSManager should ignore this
2232    request.
2233
2234    If the GSSManager implementation does not support an SPI with a
2235    pluggable provider architecture it should throw a GSSException with
2236    the status code GSSException.UNAVAILABLE to indicate that the
2237    operation is unavailable.
2238
2239
2240
2241
2242 Kabat & Upadhyay            Standards Track                    [Page 40]
2243 \f
2244 RFC 2853                 GSS-API Java Bindings                 June 2000
2245
2246
2247    Parameters:
2248
2249       p         The provider instance that should be used whenever
2250                 support is needed for mech.
2251
2252       mech      The mechanism for which the provider is being set
2253
2254 6.1.17.1.  Example Code
2255
2256    Suppose an application desired that when a mechanism of Oid m1 is
2257    needed the system default providers always be checked first, and only
2258    when they do not support m1 should a provider A be checked. It would
2259    then make the call:
2260
2261            GSSManager mgr = GSSManager.getInstance();
2262
2263            mgr.addProviderAtEnd(A, m1);
2264
2265    Now, if it also desired that for all mechanisms the provider B be
2266    checked after all configured providers have been checked, it would
2267    then call:
2268
2269            mgr.addProviderAtEnd(B, null);
2270
2271    Effectively the list of preferences now becomes {..., (A, m1), (B,
2272    null)}.
2273
2274    Suppose at a later time the following call is made to the same
2275    GSSManager instance:
2276
2277            mgr.addProviderAtEnd(B, m2)
2278
2279    then the previous setting with the pair (B, null) subsumes this and
2280    therefore this request should be ignored. The same would happen if a
2281    request is made for the already existing pairs of (A, m1) or (B,
2282    null).
2283
2284    Please note, however, that the following call:
2285
2286            mgr.addProviderAtEnd(A, null)
2287
2288    is not subsumed by the previous setting of (A, m1) and the list will
2289    effectively become {..., (A, m1), (B, null), (A, null)}
2290
2291
2292
2293
2294
2295
2296
2297
2298 Kabat & Upadhyay            Standards Track                    [Page 41]
2299 \f
2300 RFC 2853                 GSS-API Java Bindings                 June 2000
2301
2302
2303 6.2.  public interface GSSName
2304
2305    This interface encapsulates a single GSS-API principal entity.
2306    Different name formats and their definitions are identified with
2307    universal Object Identifiers (Oids).  The format of the names can be
2308    derived based on the unique oid of its namespace type.
2309
2310 6.2.1.  Example Code
2311
2312    Included below are code examples utilizing the GSSName interface.
2313    The code below creates a GSSName, converts it to a mechanism name
2314    (MN), performs a comparison, obtains a printable representation of
2315    the name, exports it and then re-imports to obtain a new GSSName.
2316
2317    GSSManager mgr = GSSManager.getInstance();
2318
2319    // create a host based service name
2320    GSSName name = mgr.createName("service@host",
2321                    GSSName.NT_HOSTBASED_SERVICE);
2322
2323    Oid krb5 = new Oid("1.2.840.113554.1.2.2");
2324
2325    GSSName mechName = name.canonicalize(krb5);
2326
2327    // the above two steps are equivalent to the following
2328    GSSName mechName = mgr.createName("service@host",
2329                    GSSName.NT_HOSTBASED_SERVICE, krb5);
2330
2331    // perform name comparison
2332    if (name.equals(mechName))
2333            print("Names are equals.");
2334
2335    // obtain textual representation of name and its printable
2336    // name type
2337    print(mechName.toString() +
2338                    mechName.getStringNameType().toString());
2339
2340    // export and re-import the name
2341    byte [] exportName = mechName.export();
2342
2343    // create a new name object from the exported buffer
2344    GSSName newName = mgr.createName(exportName,
2345                    GSSName.NT_EXPORT_NAME);
2346
2347
2348
2349
2350
2351
2352
2353
2354 Kabat & Upadhyay            Standards Track                    [Page 42]
2355 \f
2356 RFC 2853                 GSS-API Java Bindings                 June 2000
2357
2358
2359 6.2.2.  Static Constants
2360
2361    public static final Oid NT_HOSTBASED_SERVICE
2362
2363    Oid indicating a host-based service name form.  It is used to
2364    represent services associated with host computers.  This name form is
2365    constructed using two elements, "service" and "hostname", as follows:
2366
2367         service@hostname
2368
2369    Values for the "service" element are registered with the IANA. It
2370    represents the following value: { 1(iso), 3(org), 6(dod),
2371    1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) }
2372
2373    public static final Oid NT_USER_NAME
2374
2375    Name type to indicate a named user on a local system.  It represents
2376    the following value: { iso(1) member-body(2) United States(840)
2377    mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) }
2378
2379    public static final Oid NT_MACHINE_UID_NAME
2380
2381    Name type to indicate a numeric user identifier corresponding to a
2382    user on a local system. (e.g. Uid).  It represents the following
2383    value: { iso(1) member-body(2) United States(840) mit(113554)
2384    infosys(1) gssapi(2) generic(1) machine_uid_name(2) }
2385
2386    public static final Oid NT_STRING_UID_NAME
2387
2388    Name type to indicate a string of digits representing the numeric
2389    user identifier of a user on a local system. It represents the
2390    following value:  { iso(1) member-body(2) United States(840)
2391    mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) }
2392
2393    public static final Oid NT_ANONYMOUS
2394
2395    Name type for representing an anonymous entity. It represents the
2396    following value: { 1(iso), 3(org), 6(dod), 1(internet), 5(security),
2397    6(nametypes), 3(gss-anonymous-name) }
2398
2399    public static final Oid NT_EXPORT_NAME
2400
2401    Name type used to indicate an exported name produced by the export
2402    method. It represents the following value: { 1(iso), 3(org), 6(dod),
2403    1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) }
2404
2405
2406
2407
2408
2409
2410 Kabat & Upadhyay            Standards Track                    [Page 43]
2411 \f
2412 RFC 2853                 GSS-API Java Bindings                 June 2000
2413
2414
2415 6.2.3.  equals
2416
2417    public boolean equals(GSSName another) throws GSSException
2418
2419    Compares two GSSName objects to determine whether they refer to the
2420    same entity.  This method may throw a GSSException when the names
2421    cannot be compared.  If either of the names represents an anonymous
2422    entity, the method will return "false".
2423
2424    Parameters:
2425
2426       another   GSSName object to compare with.
2427
2428 6.2.4.  equals
2429
2430    public boolean equals(Object another)
2431
2432    A variation of the equals method described in 6.2.3 that is provided
2433    to override the Object.equals() method that the implementing class
2434    will inherit.  The behavior is exactly the same as that in 6.2.3
2435    except that no GSSException is thrown; instead, false will be
2436    returned in the situation where an error occurs.  (Note that the Java
2437    language specification requires that two objects that are equal
2438    according to the equals(Object) method must return the same integer
2439    result when the hashCode() method is called on them.)
2440
2441    Parameters:
2442
2443       another   GSSName object to compare with.
2444
2445 6.2.5.  canonicalize
2446
2447    public GSSName canonicalize(Oid mech) throws GSSException
2448
2449    Creates a mechanism name (MN) from an arbitrary internal name.  This
2450    is equivalent to using the factory methods described in 6.1.9 or
2451    6.1.10 that take the mechanism name as one of their parameters.
2452
2453    Parameters:
2454
2455       mech      The oid for the mechanism for which the canonical form
2456                 of the name is requested.
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466 Kabat & Upadhyay            Standards Track                    [Page 44]
2467 \f
2468 RFC 2853                 GSS-API Java Bindings                 June 2000
2469
2470
2471 6.2.6.  export
2472
2473    public byte[] export() throws GSSException
2474
2475    Returns a canonical contiguous byte representation of a mechanism
2476    name (MN), suitable for direct, byte by byte comparison by
2477    authorization functions.  If the name is not an MN, implementations
2478    may throw a GSSException with the NAME_NOT_MN status code.  If an
2479    implementation chooses not to throw an exception, it should use some
2480    system specific default mechanism to canonicalize the name and then
2481    export it.  The format of the header of the output buffer is
2482    specified in RFC 2743.
2483
2484 6.2.7.  toString
2485
2486    public String toString()
2487
2488    Returns a textual representation of the GSSName object.  To retrieve
2489    the printed name format, which determines the syntax of the returned
2490    string, the getStringNameType method can be used.
2491
2492 6.2.8.  getStringNameType
2493
2494    public Oid getStringNameType() throws GSSException
2495
2496    Returns the oid representing the type of name returned through the
2497    toString method.  Using this oid, the syntax of the printable name
2498    can be determined.
2499
2500 6.2.9.  isAnonymous
2501
2502    public boolean isAnonymous()
2503
2504    Tests if this name object represents an anonymous entity.  Returns
2505    "true" if this is an anonymous name.
2506
2507 6.2.10.  isMN
2508
2509    public boolean isMN()
2510
2511    Tests if this name object contains only one mechanism element and is
2512    thus a mechanism name as defined by RFC 2743.
2513
2514 6.3.  public interface GSSCredential implements Cloneable
2515
2516    This interface encapsulates the GSS-API credentials for an entity.  A
2517    credential contains all the necessary cryptographic information to
2518    enable the creation of a context on behalf of the entity that it
2519
2520
2521
2522 Kabat & Upadhyay            Standards Track                    [Page 45]
2523 \f
2524 RFC 2853                 GSS-API Java Bindings                 June 2000
2525
2526
2527    represents.  It may contain multiple, distinct, mechanism specific
2528    credential elements, each containing information for a specific
2529    security mechanism, but all referring to the same entity.
2530
2531    A credential may be used to perform context initiation, acceptance,
2532    or both.
2533
2534    GSS-API implementations must impose a local access-control policy on
2535    callers to prevent unauthorized callers from acquiring credentials to
2536    which they are not entitled.  GSS-API credential creation is not
2537    intended to provide a "login to the network" function, as such a
2538    function would involve the creation of new credentials rather than
2539    merely acquiring a handle to existing credentials.  Such functions,
2540    if required, should be defined in implementation-specific extensions
2541    to the API.
2542
2543    If credential acquisition is time-consuming for a mechanism, the
2544    mechanism may choose to delay the actual acquisition until the
2545    credential is required (e.g.  by GSSContext).  Such mechanism-
2546    specific implementation decisions should be invisible to the calling
2547    application; thus the query methods immediately following the
2548    creation of a credential object must return valid credential data,
2549    and may therefore incur the overhead of a deferred credential
2550    acquisition.
2551
2552    Applications will create a credential object passing the desired
2553    parameters.  The application can then use the query methods to obtain
2554    specific information about the instantiated credential object
2555    (equivalent to the gss_inquire routines).  When the credential is no
2556    longer needed, the application should call the dispose (equivalent to
2557    gss_release_cred) method to release any resources held by the
2558    credential object and to destroy any cryptographically sensitive
2559    information.
2560
2561    Classes implementing this interface also implement the Cloneable
2562    interface. This indicates the the class will support the clone()
2563    method that will allow the creation of duplicate credentials.  This
2564    is useful when called just before the add() call to retain a copy of
2565    the original credential.
2566
2567 6.3.1.  Example Code
2568
2569    This example code demonstrates the creation of a GSSCredential
2570    implementation for a specific entity, querying of its fields, and its
2571    release when it is no longer needed.
2572
2573
2574
2575
2576
2577
2578 Kabat & Upadhyay            Standards Track                    [Page 46]
2579 \f
2580 RFC 2853                 GSS-API Java Bindings                 June 2000
2581
2582
2583    GSSManager mgr = GSSManager.getInstance();
2584
2585    // start by creating a name object for the entity
2586    GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME);
2587
2588    // now acquire credentials for the entity
2589    GSSCredential cred = mgr.createCredential(name,
2590                    GSSCredential.ACCEPT_ONLY);
2591
2592    // display credential information - name, remaining lifetime,
2593    // and the mechanisms it has been acquired over
2594    print(cred.getName().toString());
2595    print(cred.getRemainingLifetime());
2596
2597    Oid [] mechs = cred.getMechs();
2598    if (mechs != null) {
2599            for (int i = 0; i < mechs.length; i++)
2600                    print(mechs[i].toString());
2601    }
2602
2603    // release system resources held by the credential
2604    cred.dispose();
2605
2606 6.3.2.  Static Constants
2607
2608    public static final int INITIATE_AND_ACCEPT
2609
2610    Credential usage flag requesting that it be able to be used for both
2611    context initiation and acceptance.
2612
2613    public static final int INITIATE_ONLY
2614
2615    Credential usage flag requesting that it be able to be used for
2616    context initiation only.
2617
2618    public static final int ACCEPT_ONLY
2619
2620    Credential usage flag requesting that it be able to be used for
2621    context acceptance only.
2622
2623    public static final int DEFAULT_LIFETIME
2624
2625    A lifetime constant representing the default credential lifetime.
2626
2627    This value must be set to 0.
2628
2629    public static final int INDEFINITE_LIFETIME
2630
2631
2632
2633
2634 Kabat & Upadhyay            Standards Track                    [Page 47]
2635 \f
2636 RFC 2853                 GSS-API Java Bindings                 June 2000
2637
2638
2639    A lifetime constant representing indefinite credential lifetime.
2640    This value must be set to the maximum integer value in Java -
2641    Integer.MAX_VALUE.
2642
2643 6.3.3.  dispose
2644
2645    public void dispose() throws GSSException
2646
2647    Releases any sensitive information that the GSSCredential object may
2648    be containing.  Applications should call this method as soon as the
2649    credential is no longer needed to minimize the time any sensitive
2650    information is maintained.
2651
2652 6.3.4.  getName
2653
2654    public GSSName getName() throws GSSException
2655
2656    Retrieves the name of the entity that the credential asserts.
2657
2658 6.3.5.  getName
2659
2660    public GSSName getName(Oid mechOID) throws GSSException
2661
2662    Retrieves a mechanism name of the entity that the credential asserts.
2663    Equivalent to calling canonicalize() on the name returned by 7.3.3.
2664
2665    Parameters:
2666
2667       mechOID   The mechanism for which information should be
2668                 returned.
2669
2670 6.3.6.  getRemainingLifetime
2671
2672    public int getRemainingLifetime() throws GSSException
2673
2674    Returns the remaining lifetime in seconds for a credential.  The
2675    remaining lifetime is the minimum lifetime for any of the underlying
2676    credential mechanisms.  A return value of
2677    GSSCredential.INDEFINITE_LIFETIME indicates that the credential does
2678    not expire.  A return value of 0 indicates that the credential is
2679    already expired.
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690 Kabat & Upadhyay            Standards Track                    [Page 48]
2691 \f
2692 RFC 2853                 GSS-API Java Bindings                 June 2000
2693
2694
2695 6.3.7.  getRemainingInitLifetime
2696
2697    public int getRemainingInitLifetime(Oid mech) throws GSSException
2698
2699    Returns the remaining lifetime is seconds for the credential to
2700    remain capable of initiating security contexts under the specified
2701    mechanism.  A return value of GSSCredential.INDEFINITE_LIFETIME
2702    indicates that the credential does not expire for context initiation.
2703    A return value of 0 indicates that the credential is already expired.
2704
2705    Parameters:
2706
2707       mechOID   The mechanism for which information should be
2708                 returned.
2709
2710 6.3.8.  getRemainingAcceptLifetime
2711
2712    public int getRemainingAcceptLifetime(Oid mech) throws GSSException
2713
2714    Returns the remaining lifetime is seconds for the credential to
2715    remain capable of accepting security contexts under the specified
2716    mechanism.  A return value of GSSCredential.INDEFINITE_LIFETIME
2717    indicates that the credential does not expire for context acceptance.
2718    A return value of 0 indicates that the credential is already expired.
2719
2720    Parameters:
2721
2722       mechOID   The mechanism for which information should be
2723                 returned.
2724
2725 6.3.9.  getUsage
2726
2727    public int getUsage() throws GSSException
2728
2729    Returns the credential usage flag.  The return value will be one of
2730    GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or
2731    GSSCredential.INITIATE_AND_ACCEPT.
2732
2733 6.3.10.  getUsage
2734
2735    public int getUsage(Oid mechOID) throws GSSException
2736
2737    Returns the credential usage flag for the specified credential
2738    mechanism.  The return value will be one of
2739    GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or
2740    GSSCredential.INITIATE_AND_ACCEPT.
2741
2742
2743
2744
2745
2746 Kabat & Upadhyay            Standards Track                    [Page 49]
2747 \f
2748 RFC 2853                 GSS-API Java Bindings                 June 2000
2749
2750
2751    Parameters:
2752
2753       mechOID   The mechanism for which information should be
2754                 returned.
2755
2756 6.3.11.  getMechs
2757
2758    public Oid[] getMechs() throws GSSException
2759
2760    Returns an array of mechanisms supported by this credential.
2761
2762 6.3.12.  add
2763
2764    public void add(GSSName aName, int initLifetime, int acceptLifetime,
2765                    Oid mech, int usage) throws GSSException
2766
2767    Adds a mechanism specific credential-element to an existing
2768    credential.  This method allows the construction of credentials one
2769    mechanism at a time.
2770
2771    This routine is envisioned to be used mainly by context acceptors
2772    during the creation of acceptance credentials which are to be used
2773    with a variety of clients using different security mechanisms.
2774
2775    This routine adds the new credential element "in-place".  To add the
2776    element in a new credential, first call clone() to obtain a copy of
2777    this credential, then call its add() method.
2778
2779    Parameters:
2780
2781       aName     Name of the principal for whom this credential is to
2782                 be acquired. Use "null" to specify the default
2783                 principal.
2784
2785       initLifetime
2786                 The number of seconds that credentials should remain
2787                 valid for initiating of security contexts.  Use
2788                 GSSCredential.INDEFINITE_LIFETIME to request that the
2789                 credentials have the maximum permitted lifetime. Use
2790                 GSSCredential.DEFAULT_LIFETIME to request default
2791                 credential lifetime.
2792
2793       acceptLifetime
2794                 The number of seconds that credentials should remain
2795                 valid for accepting of security contexts.  Use
2796                 GSSCredential.INDEFINITE_LIFETIME to request that the
2797
2798
2799
2800
2801
2802 Kabat & Upadhyay            Standards Track                    [Page 50]
2803 \f
2804 RFC 2853                 GSS-API Java Bindings                 June 2000
2805
2806
2807                 credentials have the maximum permitted lifetime.  Use
2808                 GSSCredential.DEFAULT_LIFETIME to request default
2809                 credential lifetime.
2810
2811       mech      The mechanisms over which the credential is to be
2812                 acquired.
2813
2814       usage     The intended usage for this credential object. The
2815                 value of this parameter must be one of:
2816                 GSSCredential.ACCEPT_AND_INITIATE,
2817                 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY
2818
2819 6.3.13.  equals
2820
2821    public boolean equals(Object another)
2822
2823    Tests if this GSSCredential refers to the same entity as the supplied
2824    object.  The two credentials must be acquired over the same
2825    mechanisms and must refer to the same principal.  Returns "true" if
2826    the two GSSCredentials refer to the same entity; "false" otherwise.
2827    (Note that the Java language specification requires that two objects
2828    that are equal according to the equals(Object) method must return the
2829    same integer result when the hashCode() method is called on them.)
2830
2831    Parameters:
2832
2833       another   Another GSSCredential object for comparison.
2834
2835 6.4.  public interface GSSContext
2836
2837    This interface encapsulates the GSS-API security context and provides
2838    the security services (wrap, unwrap, getMIC, verifyMIC) that are
2839    available over the context.  Security contexts are established
2840    between peers using locally acquired credentials.  Multiple contexts
2841    may exist simultaneously between a pair of peers, using the same or
2842    different set of credentials.  GSS-API functions in a manner
2843    independent of the underlying transport protocol and depends on its
2844    calling application to transport its tokens between peers.
2845
2846    Before the context establishment phase is initiated, the context
2847    initiator may request specific characteristics desired of the
2848    established context.  These can be set using the set methods.  After
2849    the context is established, the caller can check the actual
2850    characteristic and services offered by the context using the query
2851    methods.
2852
2853
2854
2855
2856
2857
2858 Kabat & Upadhyay            Standards Track                    [Page 51]
2859 \f
2860 RFC 2853                 GSS-API Java Bindings                 June 2000
2861
2862
2863    The context establishment phase begins with the first call to the
2864    init method by the context initiator.  During this phase the
2865    initSecContext and acceptSecContext methods will produce GSS-API
2866    authentication tokens which the calling application needs to send to
2867    its peer.  If an error occurs at any point, an exception will get
2868    thrown and the code will start executing in a catch block.  If not,
2869    the normal flow of code continues and the application can make a call
2870    to the isEstablished() method.  If this method returns false it
2871    indicates that a token is needed from its peer in order to continue
2872    the context establishment phase.  A return value of true signals that
2873    the local end of the context is established.  This may still require
2874    that a token be sent to the peer, if one is produced by GSS-API.
2875    During the context establishment phase, the isProtReady() method may
2876    be called to determine if the context can be used for the per-message
2877    operations.  This allows applications to use per-message operations
2878    on contexts which aren't fully established.
2879
2880    After the context has been established or the isProtReady() method
2881    returns "true", the query routines can be invoked to determine the
2882    actual characteristics and services of the established context.  The
2883    application can also start using the per-message methods of wrap and
2884    getMIC to obtain cryptographic operations on application supplied
2885    data.
2886
2887    When the context is no longer needed, the application should call
2888    dispose to release any system resources the context may be using.
2889
2890 6.4.1.  Example Code
2891
2892    The example code presented below demonstrates the usage of the
2893    GSSContext interface for the initiating peer.  Different operations
2894    on the GSSContext object are presented, including: object
2895    instantiation, setting of desired flags, context establishment, query
2896    of actual context flags, per-message operations on application data,
2897    and finally context deletion.
2898
2899    GSSManager mgr = GSSManager.getInstance();
2900
2901    // start by creating the name for a service entity
2902    GSSName targetName = mgr.createName("service@host",
2903                    GSSName.NT_HOSTBASED_SERVICE);
2904
2905    // create a context using default credentials for the above entity
2906    // and the implementation specific default mechanism
2907    GSSContext context = mgr.createContext(targetName,
2908                    null,   /* default mechanism */
2909                    null,   /* default credentials */
2910                    GSSContext.INDEFINITE_LIFETIME);
2911
2912
2913
2914 Kabat & Upadhyay            Standards Track                    [Page 52]
2915 \f
2916 RFC 2853                 GSS-API Java Bindings                 June 2000
2917
2918
2919    // set desired context options - all others are false by default
2920    context.requestConf(true);
2921    context.requestMutualAuth(true);
2922    context.requestReplayDet(true);
2923    context.requestSequenceDet(true);
2924
2925    // establish a context between peers - using byte arrays
2926    byte []inTok = new byte[0];
2927
2928    try {
2929            do {
2930                    byte[] outTok = context.initSecContext(inTok, 0,
2931                                                      inTok.length);
2932
2933                    // send the token if present
2934                    if (outTok != null)
2935                            sendToken(outTok);
2936
2937                    // check if we should expect more tokens
2938                    if (context.isEstablished())
2939                            break;
2940
2941                    // another token expected from peer
2942                    inTok = readToken();
2943
2944            } while (true);
2945
2946    } catch (GSSException e) {
2947            print("GSSAPI error: " + e.getMessage());
2948    }
2949
2950
2951    // display context information
2952    print("Remaining lifetime in seconds = " + context.getLifetime());
2953    print("Context mechanism = " + context.getMech().toString());
2954    print("Initiator = " + context.getSrcName().toString());
2955    print("Acceptor = " + context.getTargName().toString());
2956
2957    if (context.getConfState())
2958            print("Confidentiality security service available");
2959
2960    if (context.getIntegState())
2961            print("Integrity security service available");
2962
2963    // perform wrap on an application supplied message, appMsg,
2964    // using QOP = 0, and requesting privacy service
2965    byte [] appMsg ...
2966
2967
2968
2969
2970 Kabat & Upadhyay            Standards Track                    [Page 53]
2971 \f
2972 RFC 2853                 GSS-API Java Bindings                 June 2000
2973
2974
2975    MessageProp mProp = new MessageProp(0, true);
2976
2977    byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);
2978
2979    if (mProp.getPrivacy())
2980            print("Message protected with privacy.");
2981
2982    sendToken(tok);
2983
2984
2985    // release the local-end of the context
2986    context.dispose();
2987
2988 6.4.2.  Static Constants
2989
2990    public static final int DEFAULT_LIFETIME
2991
2992    A lifetime constant representing the default context lifetime.  This
2993    value must be set to 0.
2994
2995    public static final int INDEFINITE_LIFETIME
2996
2997    A lifetime constant representing indefinite context lifetime.  This
2998    value must be set to the maximum integer value in Java -
2999    Integer.MAX_VALUE.
3000
3001 6.4.3.  initSecContext
3002
3003    public byte[] initSecContext(byte inputBuf[], int offset, int len)
3004                    throws GSSException
3005
3006    Called by the context initiator to start the context creation
3007    process.  This is equivalent to the stream based method except that
3008    the token buffers are handled as byte arrays instead of using stream
3009    objects.  This method may return an output token which the
3010    application will need to send to the peer for processing by the
3011    accept call.  Typically, the application would do so by calling the
3012    flush() method on an OutputStream that encapsulates the connection
3013    between the two peers.  The application can call isEstablished() to
3014    determine if the context establishment phase is complete for this
3015    peer.  A return value of "false" from isEstablished() indicates that
3016    more tokens are expected to be supplied to the initSecContext()
3017    method.  Note that it is possible that the initSecContext() method
3018    return a token for the peer, and isEstablished() return "true" also.
3019    This indicates that the token needs to be sent to the peer, but the
3020    local end of the context is now fully established.
3021
3022
3023
3024
3025
3026 Kabat & Upadhyay            Standards Track                    [Page 54]
3027 \f
3028 RFC 2853                 GSS-API Java Bindings                 June 2000
3029
3030
3031    Upon completion of the context establishment, the available context
3032    options may be queried through the get methods.
3033
3034    Parameters:
3035
3036       inputBuf  Token generated by the peer. This parameter is ignored
3037                 on the first call.
3038
3039       offset    The offset within the inputBuf where the token begins.
3040
3041       len       The length of the token within the inputBuf (starting
3042                 at the offset).
3043
3044 6.4.3.1.  Example Code
3045
3046    // Create a new GSSContext implementation object.
3047    // GSSContext wrapper implements interface GSSContext.
3048    GSSContext context = mgr.createContext(...);
3049
3050
3051    byte []inTok = new byte[0];
3052
3053    try {
3054
3055            do {
3056                    byte[] outTok = context.initSecContext(inTok, 0,
3057                                            inTok.length);
3058
3059                    // send the token if present
3060                    if (outTok != null)
3061                            sendToken(outTok);
3062
3063
3064                    // check if we should expect more tokens
3065                    if (context.isEstablished())
3066                            break;
3067
3068                    // another token expected from peer
3069                    inTok = readToken();
3070            } while (true);
3071
3072    } catch (GSSException e) {
3073            print("GSSAPI error: " + e.getMessage());
3074    }
3075
3076
3077
3078
3079
3080
3081
3082 Kabat & Upadhyay            Standards Track                    [Page 55]
3083 \f
3084 RFC 2853                 GSS-API Java Bindings                 June 2000
3085
3086
3087 6.4.4.  initSecContext
3088
3089    public int initSecContext(InputStream inStream,
3090                    OutputStream outStream) throws GSSException
3091
3092    Called by the context initiator to start the context creation
3093    process.  This is equivalent to the byte array based method.  This
3094    method may write an output token to the outStream, which the
3095    application will need to send to the peer for processing by the
3096    accept call. Typically, the application would do so by calling the
3097    flush() method on an OutputStream that encapsulates the connection
3098    between the two peers.  The application can call isEstablished() to
3099    determine if the context establishment phase is complete for this
3100    peer.  A return value of "false" from isEstablished indicates that
3101    more tokens are expected to be supplied to the initSecContext method.
3102    Note that it is possible that the initSecContext() method return a
3103    token for the peer, and isEstablished() return "true" also.  This
3104    indicates that the token needs to be sent to the peer, but the local
3105    end of the context is now fully established.
3106
3107    The GSS-API authentication tokens contain a definitive start and end.
3108    This method will attempt to read one of these tokens per invocation,
3109    and may block on the stream if only part of the token is available.
3110
3111    Upon completion of the context establishment, the available context
3112    options may be queried through the get methods.
3113
3114    Parameters:
3115
3116       inStream  Contains the token generated by the peer. This
3117                 parameter is ignored on the first call.
3118
3119       outStream Output stream where the output token will be written.
3120                 During the final stage of context establishment, there
3121                 may be no bytes written.
3122
3123 6.4.4.1.  Example Code
3124
3125    This sample code merely demonstrates the token exchange during the
3126    context establishment phase. It is expected that most Java
3127    applications will use custom implementations of the Input and Output
3128    streams that encapsulate the communication routines.  For instance, a
3129    simple read on the application InputStream, when called by the
3130    Context, might cause a token to be read from the peer, and a simple
3131    flush() on the application OutputStream might cause a previously
3132    written token to be transmitted to the peer.
3133
3134    // Create a new GSSContext implementation object.
3135
3136
3137
3138 Kabat & Upadhyay            Standards Track                    [Page 56]
3139 \f
3140 RFC 2853                 GSS-API Java Bindings                 June 2000
3141
3142
3143    // GSSContext wrapper implements interface GSSContext.
3144    GSSContext context = mgr.createContext(...);
3145
3146    // use standard java.io stream objects
3147    ByteArrayOutputStream os = new ByteArrayOutputStream();
3148    ByteArrayInputStream is = null;
3149
3150
3151    try {
3152
3153            do {
3154                    context.initSecContext(is, os);
3155
3156                    // send token if present
3157                    if (os.size() > 0)
3158                            sendToken(os);
3159
3160                    // check if we should expect more tokens
3161                    if (context.isEstablished())
3162                            break;
3163
3164                    // another token expected from peer
3165                    is = recvToken();
3166
3167            } while (true);
3168
3169    } catch (GSSException e) {
3170            print("GSSAPI error: " + e.getMessage());
3171    }
3172
3173 6.4.5.  acceptSecContext
3174
3175    public byte[] acceptSecContext(byte inTok[], int offset, int len)
3176                    throws GSSException
3177
3178    Called by the context acceptor upon receiving a token from the peer.
3179    This call is equivalent to the stream based method except that the
3180    token buffers are handled as byte arrays instead of using stream
3181    objects.
3182
3183    This method may return an output token which the application will
3184    need to send to the peer for further processing by the init call.
3185
3186    "null" return value indicates that no token needs to be sent to the
3187    peer.  The application can call isEstablished() to determine if the
3188    context establishment phase is complete for this peer.  A return
3189    value of "false" from isEstablished() indicates that more tokens are
3190    expected to be supplied to this method.
3191
3192
3193
3194 Kabat & Upadhyay            Standards Track                    [Page 57]
3195 \f
3196 RFC 2853                 GSS-API Java Bindings                 June 2000
3197
3198
3199    Note that it is possible that acceptSecContext() return a token for
3200    the peer, and isEstablished() return "true" also.  This indicates
3201    that the token needs to be sent to the peer, but the local end of the
3202    context is now fully established.
3203
3204    Upon completion of the context establishment, the available context
3205    options may be queried through the get methods.
3206
3207    Parameters:
3208
3209       inTok     Token generated by the peer.
3210
3211       offset    The offset within the inTok where the token begins.
3212
3213       len       The length of the token within the inTok (starting at
3214                 the offset).
3215
3216 6.4.5.1.  Example Code
3217
3218    // acquire server credentials
3219    GSSCredential server = mgr.createCredential(...);
3220
3221    // create acceptor GSS-API context from the default provider
3222    GSSContext context = mgr.createContext(server, null);
3223
3224    try {
3225            do {
3226                    byte [] inTok = readToken();
3227
3228                    byte []outTok = context.acceptSecContext(inTok, 0,
3229                                            inTok.length);
3230
3231                    // possibly send token to peer
3232                    if (outTok != null)
3233                            sendToken(outTok);
3234
3235                    // check if local context establishment is complete
3236                    if (context.isEstablished())
3237                            break;
3238            } while (true);
3239
3240    } catch (GSSException e) {
3241            print("GSS-API error: " + e.getMessage());
3242    }
3243
3244
3245
3246
3247
3248
3249
3250 Kabat & Upadhyay            Standards Track                    [Page 58]
3251 \f
3252 RFC 2853                 GSS-API Java Bindings                 June 2000
3253
3254
3255 6.4.6.  acceptSecContext
3256
3257    public void acceptSecContext(InputStream inStream,
3258                    OutputStream outStream) throws GSSException
3259
3260    Called by the context acceptor upon receiving a token from the peer.
3261    This call is equivalent to the byte array method.  It may write an
3262    output token to the outStream, which the application will need to
3263    send to the peer for processing by its initSecContext method.
3264    Typically, the application would do so by calling the flush() method
3265    on an OutputStream that encapsulates the connection between the two
3266    peers. The application can call isEstablished() to determine if the
3267    context establishment phase is complete for this peer.  A return
3268    value of "false" from isEstablished() indicates that more tokens are
3269    expected to be supplied to this method.
3270
3271    Note that it is possible that acceptSecContext() return a token for
3272    the peer, and isEstablished() return "true" also.  This indicates
3273    that the token needs to be sent to the peer, but the local end of the
3274    context is now fully established.
3275
3276    The GSS-API authentication tokens contain a definitive start and end.
3277    This method will attempt to read one of these tokens per invocation,
3278    and may block on the stream if only part of the token is available.
3279
3280    Upon completion of the context establishment, the available context
3281    options may be queried through the get methods.
3282
3283    Parameters:
3284
3285       inStream  Contains the token generated by the peer.
3286
3287       outStream Output stream where the output token will be written.
3288                 During the final stage of context establishment, there
3289                 may be no bytes written.
3290
3291 6.4.6.1.  Example Code
3292
3293    This sample code merely demonstrates the token exchange during the
3294    context establishment phase. It is expected that most Java
3295    applications will use custom implementations of the Input and Output
3296    streams that encapsulate the communication routines.  For instance, a
3297    simple read on the application InputStream, when called by the
3298    Context, might cause a token to be read from the peer, and a simple
3299    flush() on the application OutputStream might cause a previously
3300    written token to be transmitted to the peer.
3301
3302    // acquire server credentials
3303
3304
3305
3306 Kabat & Upadhyay            Standards Track                    [Page 59]
3307 \f
3308 RFC 2853                 GSS-API Java Bindings                 June 2000
3309
3310
3311    GSSCredential server = mgr.createCredential(...);
3312
3313    // create acceptor GSS-API context from the default provider
3314    GSSContext context = mgr.createContext(server, null);
3315
3316    // use standard java.io stream objects
3317    ByteArrayOutputStream os = new ByteArrayOutputStream();
3318    ByteArrayInputStream is = null;
3319
3320    try {
3321            do {
3322
3323                    is = recvToken();
3324
3325                    context.acceptSecContext(is, os);
3326
3327                    // possibly send token to peer
3328                    if (os.size() > 0)
3329                            sendToken(os);
3330
3331                    // check if local context establishment is complete
3332                    if (context.isEstablished())
3333                            break;
3334            } while (true);
3335
3336    } catch (GSSException e) {
3337            print("GSS-API error: " + e.getMessage());
3338    }
3339
3340 6.4.7.  isEstablished
3341
3342    public boolean isEstablished()
3343
3344    Used during context establishment to determine the state of the
3345    context.  Returns "true" if this is a fully established context on
3346    the caller's side and no more tokens are needed from the peer.
3347    Should be called after a call to initSecContext() or
3348    acceptSecContext() when no GSSException is thrown.
3349
3350 6.4.8.  dispose
3351
3352    public void dispose() throws GSSException
3353
3354    Releases any system resources and cryptographic information stored in
3355    the context object.  This will invalidate the context.
3356
3357
3358
3359
3360
3361
3362 Kabat & Upadhyay            Standards Track                    [Page 60]
3363 \f
3364 RFC 2853                 GSS-API Java Bindings                 June 2000
3365
3366
3367 6.4.9.  getWrapSizeLimit
3368
3369    public int getWrapSizeLimit(int qop, boolean confReq,
3370                    int maxTokenSize) throws GSSException
3371
3372    Returns the maximum message size that, if presented to the wrap
3373    method with the same confReq and qop parameters, will result in an
3374    output token containing no more than the maxTokenSize bytes.
3375
3376    This call is intended for use by applications that communicate over
3377    protocols that impose a maximum message size.  It enables the
3378    application to fragment messages prior to applying protection.
3379
3380    GSS-API implementations are recommended but not required to detect
3381    invalid QOP values when getWrapSizeLimit is called.  This routine
3382    guarantees only a maximum message size, not the availability of
3383    specific QOP values for message protection.
3384
3385    Successful completion of this call does not guarantee that wrap will
3386    be able to protect a message of the computed length, since this
3387    ability may depend on the availability of system resources at the
3388    time that wrap is called.  However, if the implementation itself
3389    imposes an upper limit on the length of messages that may be
3390    processed by wrap, the implementation should not return a value that
3391    is greater than this length.
3392
3393    Parameters:
3394
3395       qop       Indicates the level of protection wrap will be asked
3396                 to provide.
3397
3398       confReq   Indicates if wrap will be asked to provide privacy
3399                 service.
3400
3401       maxTokenSize
3402                 The desired maximum size of the token emitted by wrap.
3403
3404 6.4.10.  wrap
3405
3406    public byte[] wrap(byte inBuf[], int offset, int len,
3407                    MessageProp msgProp) throws GSSException
3408
3409    Applies per-message security services over the established security
3410    context.  The method will return a token with a cryptographic MIC and
3411    may optionally encrypt the specified inBuf.  This method is
3412    equivalent in functionality to its stream counterpart.  The returned
3413    byte array will contain both the MIC and the message.
3414
3415
3416
3417
3418 Kabat & Upadhyay            Standards Track                    [Page 61]
3419 \f
3420 RFC 2853                 GSS-API Java Bindings                 June 2000
3421
3422
3423    The MessageProp object is instantiated by the application and used to
3424    specify a QOP value which selects cryptographic algorithms, and a
3425    privacy service to optionally encrypt the message.  The underlying
3426    mechanism that is used in the call may not be able to provide the
3427    privacy service.  It sets the actual privacy service that it does
3428    provide in this MessageProp object which the caller should then query
3429    upon return.  If the mechanism is not able to provide the requested
3430    QOP, it throws a GSSException with the BAD_QOP code.
3431
3432    Since some application-level protocols may wish to use tokens emitted
3433    by wrap to provide "secure framing", implementations should support
3434    the wrapping of zero-length messages.
3435
3436    The application will be responsible for sending the token to the
3437    peer.
3438
3439    Parameters:
3440
3441       inBuf     Application data to be protected.
3442
3443       offset    The offset within the inBuf where the data begins.
3444
3445       len       The length of the data within the inBuf (starting at
3446                 the offset).
3447
3448       msgProp   Instance of MessageProp that is used by the
3449                 application to set the desired QOP and privacy state.
3450                 Set the desired QOP to 0 to request the default QOP.
3451                 Upon return from this method, this object will contain
3452                 the the actual privacy state that was applied to the
3453                 message by the underlying mechanism.
3454
3455 6.4.11.  wrap
3456
3457    public void wrap(InputStream inStream, OutputStream outStream,
3458                    MessageProp msgProp) throws GSSException
3459
3460    Allows to apply per-message security services over the established
3461    security context.  The method will produce a token with a
3462    cryptographic MIC and may optionally encrypt the message in inStream.
3463    The outStream will contain both the MIC and the message.
3464
3465    The MessageProp object is instantiated by the application and used to
3466    specify a QOP value which selects cryptographic algorithms, and a
3467    privacy service to optionally encrypt the message.  The underlying
3468    mechanism that is used in the call may not be able to provide the
3469    privacy service.  It sets the actual privacy service that it does
3470
3471
3472
3473
3474 Kabat & Upadhyay            Standards Track                    [Page 62]
3475 \f
3476 RFC 2853                 GSS-API Java Bindings                 June 2000
3477
3478
3479    provide in this MessageProp object which the caller should then query
3480    upon return.  If the mechanism is not able to provide the requested
3481    QOP, it throws a GSSException with the BAD_QOP code.
3482
3483    Since some application-level protocols may wish to use tokens emitted
3484    by wrap to provide "secure framing", implementations should support
3485    the wrapping of zero-length messages.
3486
3487    The application will be responsible for sending the token to the
3488    peer.
3489
3490    Parameters:
3491
3492       inStream  Input stream containing the application data to be
3493                 protected.
3494
3495       outStream The output stream to write the protected message to.
3496                 The application is responsible for sending this to the
3497                 other peer for processing in its unwrap method.
3498
3499       msgProp   Instance of MessageProp that is used by the
3500                 application to set the desired QOP and privacy state.
3501                 Set the desired QOP to 0 to request the default QOP.
3502                 Upon return from this method, this object will contain
3503                 the the actual privacy state that was applied to the
3504                 message by the underlying mechanism.
3505
3506 6.4.12.  unwrap
3507
3508    public byte [] unwrap(byte[] inBuf, int offset, int len,
3509                    MessageProp msgProp) throws GSSException
3510
3511    Used by the peer application to process tokens generated with the
3512    wrap call.  This call is equal in functionality to its stream
3513    counterpart.  The method will return the message supplied in the peer
3514    application to the wrap call, verifying the embedded MIC.
3515
3516    The MessageProp object is instantiated by the application and is used
3517    by the underlying mechanism to return information to the caller such
3518    as the QOP, whether confidentiality was applied to the message, and
3519    other supplementary message state information.
3520
3521    Since some application-level protocols may wish to use tokens emitted
3522    by wrap to provide "secure framing", implementations should support
3523    the wrapping and unwrapping of zero-length messages.
3524
3525
3526
3527
3528
3529
3530 Kabat & Upadhyay            Standards Track                    [Page 63]
3531 \f
3532 RFC 2853                 GSS-API Java Bindings                 June 2000
3533
3534
3535    Parameters:
3536
3537       inBuf     GSS-API wrap token received from peer.
3538
3539       offset    The offset within the inBuf where the token begins.
3540
3541       len       The length of the token within the inBuf (starting at
3542                 the offset).
3543
3544       msgProp   Upon return from the method, this object will contain
3545                 the applied QOP, the privacy state of the message, and
3546                 supplementary information described in 4.12.3 stating
3547                 whether the token was a duplicate, old, out of
3548                 sequence or arriving after a gap.
3549
3550 6.4.13.  unwrap
3551
3552    public void unwrap(InputStream inStream, OutputStream outStream,
3553                    MessageProp msgProp) throws GSSException
3554
3555    Used by the peer application to process tokens generated with the
3556    wrap call.  This call is equal in functionality to its byte array
3557    counterpart.  It will produce the message supplied in the peer
3558    application to the wrap call, verifying the embedded MIC.
3559
3560    The MessageProp object is instantiated by the application and is used
3561    by the underlying mechanism to return information to the caller such
3562    as the QOP, whether confidentiality was applied to the message, and
3563    other supplementary message state information.
3564
3565    Since some application-level protocols may wish to use tokens emitted
3566    by wrap to provide "secure framing", implementations should support
3567    the wrapping and unwrapping of zero-length messages.
3568
3569    Parameters:
3570
3571       inStream  Input stream containing the GSS-API wrap token
3572                 received from the peer.
3573
3574       outStream The output stream to write the application message to.
3575
3576       msgProp   Upon return from the method, this object will contain
3577                 the applied QOP, the privacy state of the message, and
3578                 supplementary information described in 4.12.3 stating
3579                 whether the token was a duplicate, old, out of
3580                 sequence or arriving after a gap.
3581
3582
3583
3584
3585
3586 Kabat & Upadhyay            Standards Track                    [Page 64]
3587 \f
3588 RFC 2853                 GSS-API Java Bindings                 June 2000
3589
3590
3591 6.4.14.  getMIC
3592
3593    public byte[] getMIC(byte []inMsg, int offset, int len,
3594                    MessageProp msgProp) throws GSSException
3595
3596    Returns a token containing a cryptographic MIC for the supplied
3597    message,  for transfer to the peer application.  Unlike wrap, which
3598    encapsulates the user message in the returned token, only the message
3599    MIC is returned in the output token.  This method is identical in
3600    functionality to its stream counterpart.
3601
3602    Note that privacy can only be applied through the wrap call.
3603
3604    Since some application-level protocols may wish to use tokens emitted
3605    by getMIC to provide "secure framing", implementations should support
3606    derivation of MICs from zero-length messages.
3607
3608    Parameters:
3609
3610       inMsg     Message to generate MIC over.
3611
3612       offset    The offset within the inMsg where the token begins.
3613
3614       len       The length of the token within the inMsg (starting at
3615                 the offset).
3616
3617       msgProp   Instance of MessageProp that is used by the
3618                 application to set the desired QOP.  Set the desired
3619                 QOP to 0 in msgProp to request the default QOP.
3620                 Alternatively pass in "null" for msgProp to request
3621                 default QOP.
3622
3623 6.4.15.  getMIC
3624
3625    public void getMIC(InputStream inStream, OutputStream outStream,
3626                    MessageProp msgProp) throws GSSException
3627
3628    Produces a token containing a cryptographic MIC for the supplied
3629    message, for transfer to the peer application.  Unlike wrap, which
3630    encapsulates the user message in the returned token, only the message
3631    MIC is produced in the output token.  This method is identical in
3632    functionality to its byte array counterpart.
3633
3634    Note that privacy can only be applied through the wrap call.
3635
3636    Since some application-level protocols may wish to use tokens emitted
3637    by getMIC to provide "secure framing", implementations should support
3638    derivation of MICs from zero-length messages.
3639
3640
3641
3642 Kabat & Upadhyay            Standards Track                    [Page 65]
3643 \f
3644 RFC 2853                 GSS-API Java Bindings                 June 2000
3645
3646
3647    Parameters:
3648
3649       inStream  inStream  Input stream containing the message to
3650                 generate MIC over.
3651
3652       outStream outStream Output stream to write the GSS-API output
3653                 token to.
3654
3655       msgProp   Instance of MessageProp that is used by the
3656                 application to set the desired QOP.  Set the desired
3657                 QOP to 0 in msgProp to request the default QOP.
3658                 Alternatively pass in "null" for msgProp to request
3659                 default QOP.
3660
3661 6.4.16.  verifyMIC
3662
3663    public void verifyMIC(byte []inTok, int tokOffset, int tokLen,
3664                    byte[] inMsg, int msgOffset, int msgLen,
3665                    MessageProp msgProp) throws GSSException
3666
3667    Verifies the cryptographic MIC, contained in the token parameter,
3668    over the supplied message.  This method is equivalent in
3669    functionality to its stream counterpart.
3670
3671    The MessageProp object is instantiated by the application and is used
3672    by the underlying mechanism to return information to the caller such
3673    as the QOP indicating the strength of protection that was applied to
3674    the message and other supplementary message state information.
3675
3676    Since some application-level protocols may wish to use tokens emitted
3677    by getMIC to provide "secure framing", implementations should support
3678    the calculation and verification of MICs over zero-length messages.
3679
3680    Parameters:
3681
3682       inTok     Token generated by peer's getMIC method.
3683
3684       tokOffset The offset within the inTok where the token begins.
3685
3686       tokLen    The length of the token within the inTok (starting at
3687                 the offset).
3688
3689       inMsg     Application message to verify the cryptographic MIC
3690                 over.
3691
3692       msgOffset The offset within the inMsg where the message begins.
3693
3694
3695
3696
3697
3698 Kabat & Upadhyay            Standards Track                    [Page 66]
3699 \f
3700 RFC 2853                 GSS-API Java Bindings                 June 2000
3701
3702
3703       msgLen    The length of the message within the inMsg (starting
3704                 at the offset).
3705
3706       msgProp   Upon return from the method, this object will contain
3707                 the applied QOP and supplementary information
3708                 described in 4.12.3 stating whether the token was a
3709                 duplicate, old, out of sequence or arriving after a
3710                 gap.  The confidentiality state will be set to
3711                 "false".
3712
3713 6.4.17.  verifyMIC
3714
3715    public void verifyMIC(InputStream tokStream, InputStream msgStream,
3716                    MessageProp msgProp) throws GSSException
3717
3718    Verifies the cryptographic MIC, contained in the token parameter,
3719    over the supplied message.  This method is equivalent in
3720    functionality to its byte array counterpart.
3721
3722    The MessageProp object is instantiated by the application and is used
3723    by the underlying mechanism to return information to the caller such
3724    as the QOP indicating the strength of protection that was applied to
3725    the message and other supplementary message state information.
3726
3727    Since some application-level protocols may wish to use tokens emitted
3728    by getMIC to provide "secure framing", implementations should support
3729    the calculation and verification of MICs over zero-length messages.
3730
3731    Parameters:
3732
3733       tokStream Input stream containing the token generated by peer's
3734                 getMIC method.
3735
3736       msgStream Input stream containing the application message to
3737                 verify the cryptographic MIC over.
3738
3739       msgProp   Upon return from the method, this object will contain
3740                 the applied QOP and supplementary information
3741                 described in 4.12.3 stating whether the token was a
3742                 duplicate, old, out of sequence or arriving after a
3743                 gap.  The confidentiality state will be set to
3744                 "false".
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754 Kabat & Upadhyay            Standards Track                    [Page 67]
3755 \f
3756 RFC 2853                 GSS-API Java Bindings                 June 2000
3757
3758
3759 6.4.18.  export
3760
3761    public byte [] export() throws GSSException
3762
3763    Provided to support the sharing of work between multiple processes.
3764    This routine will typically be used by the context-acceptor, in an
3765    application where a single process receives incoming connection
3766    requests and accepts security contexts over them, then passes the
3767    established context to one or more other processes for message
3768    exchange.
3769
3770    This method deactivates the security context and creates an
3771    interprocess token which, when passed to the byte array constructor
3772    of the GSSContext interface in another process, will re-activate the
3773    context in the second process.  Only a single instantiation of a
3774    given context may be active at any one time; a subsequent attempt by
3775    a context exporter to access the exported security context will fail.
3776
3777    The implementation may constrain the set of processes by which the
3778    interprocess token may be imported, either as a function of local
3779    security policy, or as a result of implementation decisions.  For
3780    example, some implementations may constrain contexts to be passed
3781    only between processes that run under the same account, or which are
3782    part of the same process group.
3783
3784    The interprocess token may contain security-sensitive information
3785    (for example cryptographic keys).  While mechanisms are encouraged to
3786    either avoid placing such sensitive information within interprocess
3787    tokens, or to encrypt the token before returning it to the
3788    application, in a typical GSS-API implementation this may not be
3789    possible.  Thus the application must take care to protect the
3790    interprocess token, and ensure that any process to which the token is
3791    transferred is trustworthy.
3792
3793 6.4.19.  requestMutualAuth
3794
3795    public void requestMutualAuth(boolean state) throws GSSException
3796
3797    Sets the request state of the mutual authentication flag for the
3798    context.  This method is only valid before the context creation
3799    process begins and only for the initiator.
3800
3801    Parameters:
3802
3803       state     Boolean representing if mutual authentication should
3804                 be requested during context establishment.
3805
3806
3807
3808
3809
3810 Kabat & Upadhyay            Standards Track                    [Page 68]
3811 \f
3812 RFC 2853                 GSS-API Java Bindings                 June 2000
3813
3814
3815 6.4.20.  requestReplayDet
3816
3817    public void requestReplayDet(boolean state) throws GSSException
3818
3819    Sets the request state of the replay detection service for the
3820    context.  This method is only valid before the context creation
3821    process begins and only for the initiator.
3822
3823    Parameters:
3824
3825       state     Boolean representing if replay detection is desired
3826                 over the established context.
3827
3828 6.4.21.  requestSequenceDet
3829
3830    public void requestSequenceDet(boolean state) throws GSSException
3831
3832    Sets the request state for the sequence checking service of the
3833    context.  This method is only valid before the context creation
3834    process begins and only for the initiator.
3835
3836    Parameters:
3837
3838       state     Boolean representing if sequence detection is desired
3839                 over the established context.
3840
3841 6.4.22.  requestCredDeleg
3842
3843    public void requestCredDeleg(boolean state) throws GSSException
3844
3845    Sets the request state for the credential delegation flag for the
3846    context.  This method is only valid before the context creation
3847    process begins and only for the initiator.
3848
3849    Parameters:
3850
3851       state     Boolean representing if credential delegation is
3852                 desired.
3853
3854 6.4.23.  requestAnonymity
3855
3856    public void requestAnonymity(boolean state) throws GSSException
3857
3858    Requests anonymous support over the context.  This method is only
3859    valid before the context creation process begins and only for the
3860    initiator.
3861
3862
3863
3864
3865
3866 Kabat & Upadhyay            Standards Track                    [Page 69]
3867 \f
3868 RFC 2853                 GSS-API Java Bindings                 June 2000
3869
3870
3871    Parameters:
3872
3873       state     Boolean representing if anonymity support is
3874                 requested.
3875
3876 6.4.24.  requestConf
3877
3878    public void requestConf(boolean state) throws GSSException
3879
3880    Requests that confidentiality service be available over the context.
3881    This method is only valid before the context creation process begins
3882    and only for the initiator.
3883
3884    Parameters:
3885
3886       state     Boolean indicating if confidentiality services are to
3887                 be requested for the context.
3888
3889 6.4.25.  requestInteg
3890
3891    public void requestInteg(boolean state) throws GSSException
3892
3893    Requests that integrity services be available over the context.  This
3894    method is only valid before the context creation process begins and
3895    only for the initiator.
3896
3897    Parameters:
3898
3899       state     Boolean indicating if integrity services are to be
3900                 requested for the context.
3901
3902 6.4.26.  requestLifetime
3903
3904    public void requestLifetime(int lifetime) throws GSSException
3905
3906    Sets the desired lifetime for the context in seconds.  This method is
3907    only valid before the context creation process begins and only for
3908    the initiator. Use GSSContext.INDEFINITE_LIFETIME and
3909    GSSContext.DEFAULT_LIFETIME to request indefinite or default context
3910    lifetime.
3911
3912    Parameters:
3913
3914       lifetime  The desired context lifetime in seconds.
3915
3916
3917
3918
3919
3920
3921
3922 Kabat & Upadhyay            Standards Track                    [Page 70]
3923 \f
3924 RFC 2853                 GSS-API Java Bindings                 June 2000
3925
3926
3927 6.4.27.  setChannelBinding
3928
3929    public void setChannelBinding(ChannelBinding cb) throws GSSException
3930
3931    Sets the channel bindings to be used during context establishment.
3932    This method is only valid before the context creation process begins.
3933
3934    Parameters:
3935
3936       cb        Channel bindings to be used.
3937
3938 6.4.28.  getCredDelegState
3939
3940    public boolean getCredDelegState()
3941
3942    Returns the state of the delegated credentials for the context.  When
3943    issued before context establishment is completed or when the
3944    isProtReady method returns "false", it returns the desired state,
3945    otherwise it will indicate the actual state over the established
3946    context.
3947
3948 6.4.29.  getMutualAuthState
3949
3950    public boolean getMutualAuthState()
3951
3952    Returns the state of the mutual authentication option for the
3953    context.  When issued before context establishment completes or when
3954    the isProtReady method returns "false", it returns the desired state,
3955    otherwise it will indicate the actual state over the established
3956    context.
3957
3958 6.4.30.  getReplayDetState
3959
3960    public boolean getReplayDetState()
3961
3962    Returns the state of the replay detection option for the context.
3963    When issued before context establishment completes or when the
3964    isProtReady method returns "false", it returns the desired state,
3965    otherwise it will indicate the actual state over the established
3966    context.
3967
3968 6.4.31.  getSequenceDetState
3969
3970    public boolean getSequenceDetState()
3971
3972    Returns the state of the sequence detection option for the context.
3973    When issued before context establishment completes or when the
3974    isProtReady method returns "false", it returns the desired state,
3975
3976
3977
3978 Kabat & Upadhyay            Standards Track                    [Page 71]
3979 \f
3980 RFC 2853                 GSS-API Java Bindings                 June 2000
3981
3982
3983    otherwise it will indicate the actual state over the established
3984    context.
3985
3986 6.4.32.  getAnonymityState
3987
3988    public boolean getAnonymityState()
3989
3990    Returns "true" if this is an anonymous context.  When issued before
3991    context establishment completes or when the isProtReady method
3992    returns "false", it returns the desired state, otherwise it will
3993    indicate the actual state over the established context.
3994
3995 6.4.33.  isTransferable
3996
3997    public boolean isTransferable() throws GSSException
3998
3999    Returns "true" if the context is transferable to other processes
4000    through the use of the export method.  This call is only valid on
4001    fully established contexts.
4002
4003 6.4.34.  isProtReady
4004
4005    public boolean isProtReady()
4006
4007    Returns "true" if the per message operations can be applied over the
4008    context.  Some mechanisms may allow the usage of per-message
4009    operations before the context is fully established.  This will also
4010    indicate that the get methods will return actual context state
4011    characteristics instead of the desired ones.
4012
4013 6.4.35.  getConfState
4014
4015    public boolean getConfState()
4016
4017    Returns the confidentiality service state over the context.  When
4018    issued before context establishment completes or when the isProtReady
4019    method returns "false", it returns the desired state, otherwise it
4020    will indicate the actual state over the established context.
4021
4022 6.4.36.  getIntegState
4023
4024    public boolean getIntegState()
4025
4026    Returns the integrity service state over the context.  When issued
4027    before context establishment completes or when the isProtReady method
4028    returns "false", it returns the desired state, otherwise it will
4029    indicate the actual state over the established context.
4030
4031
4032
4033
4034 Kabat & Upadhyay            Standards Track                    [Page 72]
4035 \f
4036 RFC 2853                 GSS-API Java Bindings                 June 2000
4037
4038
4039 6.4.37.  getLifetime
4040
4041    public int getLifetime()
4042
4043    Returns the context lifetime in seconds.  When issued before context
4044    establishment completes or when the isProtReady method returns
4045    "false", it returns the desired lifetime, otherwise it will indicate
4046    the remaining lifetime for the context.
4047
4048 6.4.38.  getSrcName
4049
4050    public GSSName getSrcName() throws GSSException
4051
4052    Returns the name of the context initiator.  This call is valid only
4053    after the context is fully established or the isProtReady method
4054    returns "true".  It is guaranteed to return an MN.
4055
4056 6.4.39.  getTargName
4057
4058    public GSSName getTargName() throws GSSException
4059
4060    Returns the name of the context target (acceptor).  This call is
4061    valid only after the context is fully established or the isProtReady
4062    method returns "true".  It is guaranteed to return an MN.
4063
4064 6.4.40.  getMech
4065
4066    public Oid getMech() throws GSSException
4067
4068    Returns the mechanism oid for this context. This method may be called
4069    before the context is fully established, but the mechanism returned
4070    may change on successive calls in negotiated mechanism case.
4071
4072 6.4.41.  getDelegCred
4073
4074    public GSSCredential getDelegCred() throws GSSException
4075
4076    Returns the delegated credential object on the acceptor's side.  To
4077    check for availability of delegated credentials call
4078    getDelegCredState.  This call is only valid on fully established
4079    contexts.
4080
4081 6.4.42.  isInitiator
4082
4083    public boolean isInitiator() throws GSSException
4084
4085    Returns "true" if this is the initiator of the context.  This call is
4086    only valid after the context creation process has started.
4087
4088
4089
4090 Kabat & Upadhyay            Standards Track                    [Page 73]
4091 \f
4092 RFC 2853                 GSS-API Java Bindings                 June 2000
4093
4094
4095 6.5.  public class MessageProp
4096
4097    This is a utility class used within the per-message GSSContext
4098    methods to convey per-message properties.
4099
4100    When used with the GSSContext interface's wrap and getMIC methods, an
4101    instance of this class is used to indicate the desired QOP and to
4102    request if confidentiality services are to be applied to caller
4103    supplied data (wrap only).  To request default QOP, the value of 0
4104    should be used for QOP.
4105
4106    When used with the unwrap and verifyMIC methods of the GSSContext
4107    interface, an instance of this class will be used to indicate the
4108    applied QOP and confidentiality services over the supplied message.
4109    In the case of verifyMIC, the confidentiality state will always be
4110    "false".  Upon return from these methods, this object will also
4111    contain any supplementary status values applicable to the processed
4112    token.  The supplementary status values can indicate old tokens, out
4113    of sequence tokens, gap tokens or duplicate tokens.
4114
4115 6.5.1.  Constructors
4116
4117    public MessageProp(boolean privState)
4118
4119    Constructor which sets QOP to 0 indicating that the default QOP is
4120    requested.
4121
4122    Parameters:
4123
4124       privState The desired privacy state. "true" for privacy and
4125                 "false" for integrity only.
4126
4127
4128    public MessageProp(int qop, boolean privState)
4129
4130    Constructor which sets the values for the qop and privacy state.
4131
4132    Parameters:
4133
4134       qop       The desired QOP.  Use 0 to request a default QOP.
4135
4136       privState The desired privacy state. "true" for privacy and
4137                 "false" for integrity only.
4138
4139
4140
4141
4142
4143
4144
4145
4146 Kabat & Upadhyay            Standards Track                    [Page 74]
4147 \f
4148 RFC 2853                 GSS-API Java Bindings                 June 2000
4149
4150
4151 6.5.2.  getQOP
4152
4153    public int getQOP()
4154
4155    Retrieves the QOP value.
4156
4157 6.5.3.  getPrivacy
4158
4159    public boolean getPrivacy()
4160
4161    Retrieves the privacy state.
4162
4163 6.5.4.  getMinorStatus
4164
4165    public int getMinorStatus()
4166
4167    Retrieves the minor status that the underlying mechanism might have
4168    set.
4169
4170 6.5.5.  getMinorString
4171
4172    public String getMinorString()
4173
4174    Returns a string explaining the mechanism specific error code. null
4175    will be returned when no mechanism error code has been set.
4176
4177 6.5.6.  setQOP
4178
4179    public void setQOP(int qopVal)
4180
4181    Sets the QOP value.
4182
4183    Parameters:
4184
4185       qopVal    The QOP value to be set.  Use 0 to request a default
4186                 QOP value.
4187
4188 6.5.7.  setPrivacy
4189
4190    public void setPrivacy(boolean privState)
4191
4192    Sets the privacy state.
4193
4194    Parameters:
4195
4196       privState The privacy state to set.
4197
4198
4199
4200
4201
4202 Kabat & Upadhyay            Standards Track                    [Page 75]
4203 \f
4204 RFC 2853                 GSS-API Java Bindings                 June 2000
4205
4206
4207 6.5.8.  isDuplicateToken
4208
4209    public boolean isDuplicateToken()
4210
4211    Returns "true" if this is a duplicate of an earlier token.
4212
4213 6.5.9.  isOldToken
4214
4215    public boolean isOldToken()
4216
4217    Returns "true" if the token's validity period has expired.
4218
4219 6.5.10.  isUnseqToken
4220
4221    public boolean isUnseqToken()
4222
4223    Returns "true" if a later token has already been processed.
4224
4225 6.5.11.  isGapToken
4226
4227    public boolean isGapToken()
4228
4229    Returns "true" if an expected per-message token was not received.
4230
4231 6.5.12.  setSupplementaryStates
4232
4233    public void setSupplementaryStates(boolean duplicate,
4234                    boolean old, boolean unseq, boolean gap,
4235                    int minorStatus, String minorString)
4236
4237    This method sets the state for the supplementary information flags
4238    and the minor status in MessageProp.  It is not used by the
4239    application but by the GSS implementation to return this information
4240    to the caller of a per-message context method.
4241
4242    Parameters:
4243
4244       duplicate true if the token was a duplicate of an earlier token,
4245                 false otherwise
4246
4247       old       true if the token's validity period has expired, false
4248                 otherwise
4249
4250       unseq     true if a later token has already been processed,
4251                 false otherwise
4252
4253       gap       true if one or more predecessor tokens have not yet
4254                 been successfully processed, false otherwise
4255
4256
4257
4258 Kabat & Upadhyay            Standards Track                    [Page 76]
4259 \f
4260 RFC 2853                 GSS-API Java Bindings                 June 2000
4261
4262
4263       minorStatus   the integer minor status code that the underlying
4264                     mechanism wants to set
4265
4266       minorString   the textual representation of the minorStatus
4267                     value
4268
4269 6.6.  public class ChannelBinding
4270
4271    The GSS-API accommodates the concept of caller-provided channel
4272    binding information.  Channel bindings are used to strengthen the
4273    quality with which peer entity authentication is provided during
4274    context establishment.  They enable the GSS-API callers to bind the
4275    establishment of the security context to relevant characteristics
4276    like addresses or to application specific data.
4277
4278    The caller initiating the security context must determine the
4279    appropriate channel binding values to set in the GSSContext object.
4280    The acceptor must provide an identical binding in order to validate
4281    that received tokens possess correct channel-related characteristics.
4282
4283    Use of channel bindings is optional in GSS-API.  Since channel-
4284    binding information may be transmitted in context establishment
4285    tokens, applications should therefore not use confidential data as
4286    channel-binding components.
4287
4288 6.6.1.  Constructors
4289
4290    public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr,
4291                    byte[] appData)
4292
4293    Create a ChannelBinding object with user supplied address information
4294    and data.  "null" values can be used for any fields which the
4295    application does not want to specify.
4296
4297    Parameters:
4298
4299       initAddr  The address of the context initiator.  "null" value
4300                 can be supplied to indicate that the application does
4301                 not want to set this value.
4302
4303       acceptAddrThe address of the context acceptor.  "null" value can
4304                 be supplied to indicate that the application does not
4305                 want to set this value.
4306
4307       appData   Application supplied data to be used as part of the
4308                 channel bindings.  "null" value can be supplied to
4309                 indicate that the application does not want to set
4310                 this value.
4311
4312
4313
4314 Kabat & Upadhyay            Standards Track                    [Page 77]
4315 \f
4316 RFC 2853                 GSS-API Java Bindings                 June 2000
4317
4318
4319    public ChannelBinding(byte[] appData)
4320
4321    Creates a ChannelBinding object without any addressing information.
4322
4323    Parameters:
4324
4325       appData   Application supplied data to be used as part of the
4326                 channel bindings.
4327
4328 6.6.2.  getInitiatorAddress
4329
4330    public InetAddress getInitiatorAddress()
4331
4332    Returns the initiator's address for this channel binding. "null" is
4333    returned if the address has not been set.
4334
4335 6.6.3.  getAcceptorAddress
4336
4337    public InetAddress getAcceptorAddress()
4338
4339    Returns the acceptor's address for this channel binding. "null" is
4340    returned if the address has not been set.
4341
4342 6.6.4.  getApplicationData
4343
4344    public byte[] getApplicationData()
4345
4346    Returns application data being used as part of the ChannelBinding.
4347    "null" is returned if no application data has been specified for the
4348    channel binding.
4349
4350 6.6.5.  equals
4351
4352    public boolean equals(Object obj)
4353
4354    Returns "true" if two channel bindings match. (Note that the Java
4355    language specification requires that two objects that are equal
4356    according to the equals(Object) method must return the same integer
4357    result when the hashCode() method is called on them.)
4358
4359    Parameters:
4360
4361       obj       Another channel binding to compare with.
4362
4363
4364
4365
4366
4367
4368
4369
4370 Kabat & Upadhyay            Standards Track                    [Page 78]
4371 \f
4372 RFC 2853                 GSS-API Java Bindings                 June 2000
4373
4374
4375 6.7.  public class Oid
4376
4377    This class represents Universal Object Identifiers (Oids) and their
4378    associated operations.
4379
4380    Oids are hierarchically globally-interpretable identifiers used
4381    within the GSS-API framework to identify mechanisms and name formats.
4382
4383    The structure and encoding of Oids is defined in ISOIEC-8824 and
4384    ISOIEC-8825.  For example the Oid representation of Kerberos V5
4385    mechanism is "1.2.840.113554.1.2.2"
4386
4387    The GSSName name class contains public static Oid objects
4388    representing the standard name types defined in GSS-API.
4389
4390 6.7.1.  Constructors
4391
4392    public Oid(String strOid) throws GSSException
4393
4394    Creates an Oid object from a string representation of its integer
4395    components (e.g. "1.2.840.113554.1.2.2").
4396
4397    Parameters:
4398
4399       strOid    The string representation for the oid.
4400
4401    public Oid(InputStream derOid) throws GSSException
4402
4403    Creates an Oid object from its DER encoding.  This refers to the full
4404    encoding including tag and length.  The structure and encoding of
4405    Oids is defined in ISOIEC-8824 and ISOIEC-8825.  This method is
4406    identical in functionality to its byte array counterpart.
4407
4408    Parameters:
4409
4410       derOid    Stream containing the DER encoded oid.
4411
4412    public Oid(byte[] DEROid) throws GSSException
4413
4414    Creates an Oid object from its DER encoding.  This refers to the full
4415    encoding including tag and length.  The structure and encoding of
4416    Oids is defined in ISOIEC-8824 and ISOIEC-8825.  This method is
4417    identical in functionality to its byte array counterpart.
4418
4419    Parameters:
4420
4421       derOid    Byte array storing a DER encoded oid.
4422
4423
4424
4425
4426 Kabat & Upadhyay            Standards Track                    [Page 79]
4427 \f
4428 RFC 2853                 GSS-API Java Bindings                 June 2000
4429
4430
4431 6.7.2.  toString
4432
4433    public String toString()
4434
4435    Returns a string representation of the oid's integer components in
4436    dot separated notation (e.g. "1.2.840.113554.1.2.2").
4437
4438 6.7.3.  equals
4439
4440    public boolean equals(Object Obj)
4441
4442    Returns "true" if the two Oid objects represent the same oid value.
4443    (Note that the Java language specification requires that two objects
4444    that are equal according to the equals(Object) method must return the
4445    same integer result when the hashCode() method is called on them.)
4446
4447    Parameters:
4448
4449       obj       Another Oid object to compare with.
4450
4451 6.7.4.  getDER
4452
4453    public byte[] getDER()
4454
4455    Returns the full ASN.1 DER encoding for this oid object, which
4456    includes the tag and length.
4457
4458 6.7.5.  containedIn
4459
4460    public boolean containedIn(Oid[] oids)
4461
4462    A utility method to test if an Oid object is contained within the
4463    supplied Oid object array.
4464
4465    Parameters:
4466
4467       oids      An array of oids to search.
4468
4469 6.8.  public class GSSException extends Exception
4470
4471    This exception is thrown whenever a fatal GSS-API error occurs
4472    including mechanism specific errors.  It may contain both, the major
4473    and minor, GSS-API status codes.  The mechanism implementers are
4474    responsible for setting appropriate minor status codes when throwing
4475    this exception.  Aside from delivering the numeric error code(s) to
4476    the caller, this class performs the mapping from their numeric values
4477    to textual representations.  All Java GSS-API methods are declared
4478    throwing this exception.
4479
4480
4481
4482 Kabat & Upadhyay            Standards Track                    [Page 80]
4483 \f
4484 RFC 2853                 GSS-API Java Bindings                 June 2000
4485
4486
4487    All implementations are encouraged to use the Java
4488    internationalization techniques to provide local translations of the
4489    message strings.
4490
4491 6.8.1.  Static Constants
4492
4493    All valid major GSS-API error code values are declared as constants
4494    in this class.
4495
4496    public static final int BAD_BINDINGS
4497
4498    Channel bindings mismatch error.
4499
4500
4501    public static final int BAD_MECH
4502
4503    Unsupported mechanism requested error.
4504
4505
4506    public static final int BAD_NAME
4507
4508    Invalid name provided error.
4509
4510
4511    public static final int BAD_NAMETYPE
4512
4513    Name of unsupported type provided error.
4514
4515
4516    public static final int BAD_STATUS
4517
4518    Invalid status code error - this is the default status value.
4519
4520
4521    public static final int BAD_MIC
4522
4523    Token had invalid integrity check error.
4524
4525
4526    public static final int CONTEXT_EXPIRED
4527
4528    Specified security context expired error.
4529
4530
4531    public static final int CREDENTIALS_EXPIRED
4532
4533    Expired credentials detected error.
4534
4535
4536
4537
4538 Kabat & Upadhyay            Standards Track                    [Page 81]
4539 \f
4540 RFC 2853                 GSS-API Java Bindings                 June 2000
4541
4542
4543    public static final int DEFECTIVE_CREDENTIAL
4544
4545    Defective credential error.
4546
4547
4548    public static final int DEFECTIVE_TOKEN
4549
4550    Defective token error.
4551
4552
4553    public static final int FAILURE
4554
4555    General failure, unspecified at GSS-API level.
4556
4557
4558    public static final int NO_CONTEXT
4559
4560    Invalid security context error.
4561
4562
4563    public static final int NO_CRED
4564
4565    Invalid credentials error.
4566
4567
4568    public static final int BAD_QOP
4569
4570    Unsupported QOP value error.
4571
4572
4573    public static final int UNAUTHORIZED
4574
4575    Operation unauthorized error.
4576
4577
4578    public static final int UNAVAILABLE
4579
4580    Operation unavailable error.
4581
4582
4583    public static final int DUPLICATE_ELEMENT
4584
4585    Duplicate credential element requested error.
4586
4587
4588    public static final int NAME_NOT_MN
4589
4590    Name contains multi-mechanism elements error.
4591
4592
4593
4594 Kabat & Upadhyay            Standards Track                    [Page 82]
4595 \f
4596 RFC 2853                 GSS-API Java Bindings                 June 2000
4597
4598
4599    public static final int DUPLICATE_TOKEN
4600
4601    The token was a duplicate of an earlier token.  This is a fatal error
4602    code that may occur during context establishment.  It is not used to
4603    indicate supplementary status values.  The MessageProp object is used
4604    for that purpose.
4605
4606    public static final int OLD_TOKEN
4607
4608    The token's validity period has expired.  This is a fatal error code
4609    that may occur during context establishment.  It is not used to
4610    indicate supplementary status values.  The MessageProp object is used
4611    for that purpose.
4612
4613    public static final int UNSEQ_TOKEN
4614
4615    A later token has already been processed.  This is a fatal error code
4616    that may occur during context establishment.  It is not used to
4617    indicate supplementary status values.  The MessageProp object is used
4618    for that purpose.
4619
4620    public static final int GAP_TOKEN
4621
4622    An expected per-message token was not received.  This is a fatal
4623    error code that may occur during context establishment.  It is not
4624    used to indicate supplementary status values.  The MessageProp object
4625    is used for that purpose.
4626
4627 6.8.2.  Constructors
4628
4629    public GSSException(int majorCode)
4630
4631    Creates a GSSException object with a specified major code.
4632
4633    Parameters:
4634
4635       majorCode The GSS error code causing this exception to be
4636                 thrown.
4637
4638    public GSSException(int majorCode, int minorCode, String minorString)
4639
4640    Creates a GSSException object with the specified major code, minor
4641    code, and minor code textual explanation.  This constructor is to be
4642    used when the exception is originating from the security mechanism.
4643    It allows to specify the GSS code and the mechanism code.
4644
4645
4646
4647
4648
4649
4650 Kabat & Upadhyay            Standards Track                    [Page 83]
4651 \f
4652 RFC 2853                 GSS-API Java Bindings                 June 2000
4653
4654
4655    Parameters:
4656
4657       majorCode      The GSS error code causing this exception to be
4658                      thrown.
4659
4660       minorCode      The mechanism error code causing this exception
4661                      to be thrown.
4662
4663       minorString    The textual explanation of the mechanism error
4664                      code.
4665
4666 6.8.3.  getMajor
4667
4668    public int getMajor()
4669
4670    Returns the major code representing the GSS error code that caused
4671    this exception to be thrown.
4672
4673 6.8.4.  getMinor
4674
4675    public int getMinor()
4676
4677    Returns the mechanism error code that caused this exception.  The
4678    minor code is set by the underlying mechanism.  Value of 0 indicates
4679    that mechanism error code is not set.
4680
4681 6.8.5.  getMajorString
4682
4683    public String getMajorString()
4684
4685    Returns a string explaining the GSS major error code causing this
4686    exception to be thrown.
4687
4688 6.8.6.  getMinorString
4689
4690    public String getMinorString()
4691
4692    Returns a string explaining the mechanism specific error code.  null
4693    will be returned when no mechanism error code has been set.
4694
4695 6.8.7.  setMinor
4696
4697    public void setMinor(int minorCode, String message)
4698
4699    Used internally by the GSS-API implementation and the underlying
4700    mechanisms to set the minor code and its textual representation.
4701
4702
4703
4704
4705
4706 Kabat & Upadhyay            Standards Track                    [Page 84]
4707 \f
4708 RFC 2853                 GSS-API Java Bindings                 June 2000
4709
4710
4711    Parameters:
4712
4713       minorCode The mechanism specific error code.
4714
4715       message   A textual explanation of the mechanism error code.
4716
4717 6.8.8.  toString
4718
4719    public String toString()
4720
4721    Returns a textual representation of both the major and minor status
4722    codes.
4723
4724 6.8.9.  getMessage
4725
4726    public String getMessage()
4727
4728    Returns a detailed message of this exception.  Overrides
4729    Throwable.getMessage.  It is customary in Java to use this method to
4730    obtain exception information.
4731
4732 7.  Sample Applications
4733
4734 7.1.  Simple GSS Context Initiator
4735
4736    import org.ietf.jgss.*;
4737
4738    /**
4739     * This is a partial sketch for a simple client program that acts
4740     * as a GSS context initiator.  It illustrates how to use the Java
4741     * bindings for the GSS-API specified in
4742     * Generic Security Service API Version 2 : Java bindings
4743     *
4744     *
4745     * This code sketch assumes the existence of a GSS-API
4746     * implementation that supports the mechanism that it will need and
4747     * is present as a library package (org.ietf.jgss) either as part of
4748     * the standard JRE or in the CLASSPATH the application specifies.
4749     */
4750
4751    public class SimpleClient {
4752
4753        private String serviceName; // name of peer (ie. server)
4754        private GSSCredential clientCred = null;
4755        private GSSContext context = null;
4756        private Oid mech; // underlying mechanism to use
4757
4758        private GSSManager mgr = GSSManager.getInstance();
4759
4760
4761
4762 Kabat & Upadhyay            Standards Track                    [Page 85]
4763 \f
4764 RFC 2853                 GSS-API Java Bindings                 June 2000
4765
4766
4767        ...
4768        ...
4769
4770        private void clientActions() {
4771            initializeGSS();
4772            establishContext();
4773            doCommunication();
4774        }
4775
4776        /**
4777         * Acquire credentials for the client.
4778         */
4779        private void initializeGSS() {
4780
4781            try {
4782
4783                clientCred = mgr.createCredential(null /*default princ*/,
4784                    GSSCredential.INDEFINITE_LIFETIME /* max lifetime */,
4785                    mech /* mechanism  to use */,
4786                    GSSCredential.INITIATE_ONLY /* init context */);
4787
4788                print("GSSCredential created for " +
4789                      cred.getName().toString());
4790                print("Credential lifetime (sec)=" +
4791                      cred.getRemainingLifetime());
4792            } catch (GSSException e) {
4793                    print("GSS-API error in credential acquisition: "
4794                          + e.getMessage());
4795                    ...
4796                    ...
4797            }
4798
4799            ...
4800            ...
4801        }
4802
4803        /**
4804         * Does the security context establishment with the
4805         * server.
4806         */
4807        private void establishContext() {
4808
4809            byte[] inToken = new byte[0];
4810            byte[] outToken = null;
4811
4812            try {
4813
4814                GSSName peer = mgr.createName(serviceName,
4815
4816
4817
4818 Kabat & Upadhyay            Standards Track                    [Page 86]
4819 \f
4820 RFC 2853                 GSS-API Java Bindings                 June 2000
4821
4822
4823                                   GSSName.NT_HOSTBASED_SERVICE);
4824
4825                context = mgr.createContext(peer, mech, gssCred,
4826                         GSSContext.INDEFINITE_LIFETIME/*lifetime*/);
4827
4828                // Will need to support confidentiality
4829                context.requestConf(true);
4830
4831                while (!context.isEstablished()) {
4832
4833                    outToken = context.initSecContext(inToken, 0,
4834                                                      inToken.length);
4835
4836                    if (outToken != null)
4837                        writeGSSToken(outToken);
4838
4839                    if (!context.isEstablished())
4840                        inToken = readGSSToken();
4841                }
4842
4843                GSSName peer = context.getSrcName();
4844                print("Security context established with " + peer +
4845                      " using underlying mechanism " + mech.toString());
4846            } catch (GSSException e) {
4847                    print("GSS-API error during context establishment: "
4848                          + e.getMessage());
4849                ...
4850                ...
4851            }
4852
4853            ...
4854            ...
4855        }
4856
4857        /**
4858         * Sends some data to the server and reads back the
4859         * response.
4860         */
4861        private void doCommunication()  {
4862                byte[] inToken = null;
4863                byte[] outToken = null;
4864                byte[] buffer;
4865
4866                // Container for multiple input-output arguments to and
4867                // from the per-message routines (e.g., wrap/unwrap).
4868                MessageProp messgInfo = new MessageProp();
4869
4870                try {
4871
4872
4873
4874 Kabat & Upadhyay            Standards Track                    [Page 87]
4875 \f
4876 RFC 2853                 GSS-API Java Bindings                 June 2000
4877
4878
4879                    /*
4880                     * Now send some bytes to the server to be
4881                     * processed. They will be integrity protected but
4882                     * not encrypted for privacy.
4883                     */
4884
4885                    buffer = readFromFile();
4886
4887                    // Set privacy to false and use the default QOP
4888                    messgInfo.setPrivacy(false);
4889
4890                    outToken = context.wrap(buffer, 0, buffer.length,
4891                                            messgInfo);
4892
4893                    writeGSSToken(outToken);
4894
4895                    /*
4896                     * Now read the response from the server.
4897                     */
4898
4899                    inToken = readGSSToken();
4900                    buffer = context.unwrap(inToken, 0, inToken.length,
4901                                            messgInfo);
4902                    // All ok if no exception was thrown!
4903
4904                    GSSName peer = context.getSrcName();
4905
4906                    print("Message from "       + peer.toString()
4907                          + " arrived.");
4908                    print("Was it encrypted? "  +
4909                          messgInfo.getPrivacy());
4910                    print("Duplicate Token? "   +
4911                          messgInfo.isDuplicateToken());
4912                    print("Old Token? "         +
4913                          messgInfo.isOldToken());
4914                    print("Unsequenced Token? " +
4915                          messgInfo.isUnseqToken());
4916                    print("Gap Token? "         +
4917                          messgInfo.isGapToken());
4918
4919                    ...
4920                    ...
4921
4922                } catch (GSSException e) {
4923                    print("GSS-API error in per-message calls: "
4924                          + e.getMessage());
4925                    ...
4926                    ...
4927
4928
4929
4930 Kabat & Upadhyay            Standards Track                    [Page 88]
4931 \f
4932 RFC 2853                 GSS-API Java Bindings                 June 2000
4933
4934
4935                }
4936
4937                ...
4938
4939                ...
4940
4941        } // end of doCommunication method
4942
4943        ...
4944        ...
4945
4946    } // end of class SimpleClient
4947
4948 7.2.  Simple GSS Context Acceptor
4949
4950    import org.ietf.jgss.*;
4951
4952    /**
4953     * This is a partial sketch for a simple server program that acts
4954     * as a GSS context acceptor. It illustrates how to use the Java
4955     * bindings for the GSS-API specified in
4956     * Generic Security Service API Version 2 : Java bindings
4957     *
4958     * This code sketch assumes the existence of a GSS-API
4959     * implementation that supports the mechanisms that it will need and
4960     * is present as a library package (org.ietf.jgss) either as part of
4961     * the standard JRE or in the CLASSPATH the application specifies.
4962     */
4963
4964    import org.ietf.jgss.*;
4965
4966    public class SimpleServer {
4967
4968        private String serviceName;
4969        private GSSName name;
4970        private GSSCredential cred;
4971
4972        private GSSManager mgr;
4973
4974        ...
4975        ...
4976
4977        /**
4978         * Wait for client connections, establish security contexts and
4979         * provide service.
4980         */
4981        private void loop() {
4982
4983
4984
4985
4986 Kabat & Upadhyay            Standards Track                    [Page 89]
4987 \f
4988 RFC 2853                 GSS-API Java Bindings                 June 2000
4989
4990
4991        ...
4992        ...
4993
4994            mgr = GSSManager.getInstance();
4995
4996            name = mgr.createName(serviceName,
4997                       GSSName.NT_HOSTBASED_SERVICE);
4998
4999            cred = mgr.createCredential(name,
5000                       GSSCredential.INDEFINITE_LIFETIME,
5001                       null,
5002                       GSSCredential.ACCEPT_ONLY);
5003
5004
5005            // Loop infinitely
5006            while (true) {
5007
5008                Socket s = serverSock.accept();
5009
5010                // Start a new thread to serve this connection
5011                Thread serverThread = new ServerThread(s);
5012                serverThread.start();
5013
5014            }
5015        }
5016
5017        /**
5018         * Inner class ServerThread whose run() method provides the
5019         * secure service to a connection.
5020         */
5021
5022        private class ServerThread extends Thread {
5023
5024        ...
5025        ...
5026
5027            /**
5028             * Deals with the connection from one client. It also
5029             * handles all GSSException's thrown while talking to
5030             * this client.
5031             */
5032            public void run() {
5033
5034                byte[] inToken = null;
5035                byte[] outToken = null;
5036                byte[] buffer;
5037
5038                GSSName peer;
5039
5040
5041
5042 Kabat & Upadhyay            Standards Track                    [Page 90]
5043 \f
5044 RFC 2853                 GSS-API Java Bindings                 June 2000
5045
5046
5047                // Container for multiple input-output arguments to and
5048                // from the per-message routines (ie. wrap/unwrap).
5049                MessageProp supplInfo = new MessageProp();
5050
5051                GSSContext secContext = null;
5052
5053                try {
5054
5055
5056                    // Now do the context establishment loop
5057
5058                    GSSContext context = mgr.createContext(cred);
5059
5060                    while (!context.isEstablished()) {
5061
5062                        inToken = readGSSToken();
5063
5064                        outToken = context.acceptSecContext(inToken, 0,
5065                                                    inToken.length);
5066
5067                        if (outToken != null)
5068                            writeGSSToken(outToken);
5069
5070                    }
5071
5072
5073                    // SimpleServer wants confidentiality to be
5074                    // available. Check for it.
5075                    if (!context.getConfState()){
5076                        ...
5077                        ...
5078                    }
5079
5080                    GSSName peer = context.getSrcName();
5081                    Oid mech = context.getMech();
5082                    print("Security context established with " +
5083                          peer.toString() +
5084                          " using underlying mechanism " +
5085                          mech.toString() +
5086                          " from Provider " +
5087                          context.getProvider().getName());
5088
5089
5090                    // Now read the bytes sent by the client to be
5091                    // processed.
5092                    inToken = readGSSToken();
5093
5094                    // Unwrap the message
5095
5096
5097
5098 Kabat & Upadhyay            Standards Track                    [Page 91]
5099 \f
5100 RFC 2853                 GSS-API Java Bindings                 June 2000
5101
5102
5103                    buffer = context.unwrap(inToken, 0, inToken.length,
5104                                              supplInfo);
5105                    // All ok if no exception was thrown!
5106
5107                    // Print other supplementary per-message status
5108                    // information
5109
5110                    print("Message from " +
5111                            peer.toString() + " arrived.");
5112                    print("Was it encrypted? " +
5113                            supplInfo.getPrivacy());
5114                    print("Duplicate Token? " +
5115                            supplInfo.isDuplicateToken());
5116                    print("Old Token? "  + supplInfo.isOldToken());
5117                    print("Unsequenced Token? " +
5118                            supplInfo.isUnseqToken());
5119                    print("Gap Token? "  + supplInfo.isGapToken());
5120
5121                    /*
5122                     * Now process the bytes and send back an encrypted
5123                     * response.
5124                     */
5125
5126                    buffer = serverProcess(buffer);
5127
5128                    // Encipher it and send it across
5129
5130                    supplInfo.setPrivacy(true); // privacy requested
5131                    supplInfo.setQOP(0); // default QOP
5132                    outToken = context.wrap(buffer, 0, buffer.length,
5133                                               supplInfo);
5134                    writeGSSToken(outToken);
5135
5136                } catch (GSSException e) {
5137                    print("GSS-API Error: " + e.getMessage());
5138                    // Alternatively, could call e.getMajorMessage()
5139                    // and e.getMinorMessage()
5140                    print("Abandoning security context.");
5141
5142                    ...
5143                    ...
5144
5145                }
5146
5147                ...
5148                ...
5149
5150            } // end of run method in ServerThread
5151
5152
5153
5154 Kabat & Upadhyay            Standards Track                    [Page 92]
5155 \f
5156 RFC 2853                 GSS-API Java Bindings                 June 2000
5157
5158
5159        } // end of inner class ServerThread
5160
5161        ...
5162        ...
5163
5164    } // end of class SimpleServer
5165
5166 8.  Security Considerations
5167
5168    The Java language security model allows platform providers to have
5169    policy based fine-grained access control over any resource that an
5170    application wants. When using a Java security manager (such as, but
5171    not limited to, the case of applets running in browsers) the
5172    application code is in a sandbox by default.
5173
5174    Administrators of the platform JRE determine what permissions, if
5175    any, are to be given to source from different codebases. Thus the
5176    administrator has to be aware of any special requirements that the
5177    GSS provider might have for system resources. For instance, a
5178    Kerberos provider might wish to make a network connection to the KDC
5179    to obtain initial credentials. This would not be allowed under the
5180    sandbox unless the administrator had granted permissions for this.
5181    Also note that this granting and checking of permissions happens
5182    transparently to the application and is outside the scope of this
5183    document.
5184
5185    The Java language allows administrators to pre-configure a list of
5186    security service providers in the <JRE>/lib/security/java.security
5187    file. At runtime, the system approaches these providers in order of
5188    preference when looking for security related services. Applications
5189    have a means to modify this list through methods in the "Security"
5190    class in the "java.security" package. However, since these
5191    modifications would be visible in the entire JVM and thus affect all
5192    code executing in it, this operation is not available in the sandbox
5193    and requires special permissions to perform. Thus when a GSS
5194    application has special needs that are met by a particular security
5195    provider, it has two choices:
5196
5197       1) To install the provider on a JVM wide basis using the
5198          java.security.Security class and then depend on the system to
5199          find the right provider automatically when the need arises.
5200          (This would require the application to be granted a
5201          "insertProvider SecurityPermission".)
5202
5203       2) To pass an instance of the provider to the local instance of
5204          GSSManager so that only factory calls going through that
5205          GSSManager use the desired provider. (This would not require
5206          any permissions.)
5207
5208
5209
5210 Kabat & Upadhyay            Standards Track                    [Page 93]
5211 \f
5212 RFC 2853                 GSS-API Java Bindings                 June 2000
5213
5214
5215 9.  Acknowledgments
5216
5217    This proposed API leverages earlier work performed by the IETF's CAT
5218    WG as outlined in both RFC 2743 and RFC 2744.  Many conceptual
5219    definitions, implementation directions, and explanations have been
5220    included from these documents.
5221
5222    We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael
5223    Saltz and other members of Sun's development team for their helpful
5224    input, comments and suggestions.
5225
5226    We would also like to thank Joe Salowey, and Michael Smith for many
5227    insightful ideas and suggestions that have contributed to this
5228    document.
5229
5230 10.  Bibliography
5231
5232    [GSSAPIv2]        Linn, J., "Generic Security Service Application
5233                      Program Interface, Version 2", RFC 2078, January
5234                      1997.
5235
5236    [GSSAPIv2-UPDATE] Linn, J., "Generic Security Service Application
5237                      Program Interface, Version 2, Update 1", RFC 2743,
5238                      January 2000.
5239
5240    [GSSAPI-Cbind]    Wray, J., "Generic Security Service API Version 2 :
5241                      C-bindings", RFC 2744, January 2000.
5242
5243    [KERBV5]          Linn, J., "The Kerberos Version 5 GSS-API
5244                      Mechanism", RFC 1964, June 1996.
5245
5246    [SPKM]            Adams, C., "The Simple Public-Key GSS-API
5247                      Mechanism", RFC 2025, October 1996.
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266 Kabat & Upadhyay            Standards Track                    [Page 94]
5267 \f
5268 RFC 2853                 GSS-API Java Bindings                 June 2000
5269
5270
5271 11.  Authors' Addresses
5272
5273    Address comments related to this memorandum to:
5274
5275         <cat-ietf@mit.edu>
5276
5277    Jack Kabat
5278    ValiCert, Inc.
5279    339 N. Bernardo Avenue
5280    Mountain View, CA
5281    94043, USA
5282
5283    Phone: +1-650-567-5496
5284    EMail: jackk@valicert.com
5285
5286
5287    Mayank Upadhyay
5288    Sun Microsystems, Inc.
5289    901 San Antonio Road, MS CUP02-102
5290    Palo Alto, CA 94303
5291
5292    Phone: +1-408-517-5956
5293    EMail: mdu@eng.sun.com
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322 Kabat & Upadhyay            Standards Track                    [Page 95]
5323 \f
5324 RFC 2853                 GSS-API Java Bindings                 June 2000
5325
5326
5327 12.  Full Copyright Statement
5328
5329    Copyright (C) The Internet Society (2000).  All Rights Reserved.
5330
5331    This document and translations of it may be copied and furnished to
5332    others, and derivative works that comment on or otherwise explain it
5333    or assist in its implementation may be prepared, copied, published
5334    and distributed, in whole or in part, without restriction of any
5335    kind, provided that the above copyright notice and this paragraph are
5336    included on all such copies and derivative works.  However, this
5337    document itself may not be modified in any way, such as by removing
5338    the copyright notice or references to the Internet Society or other
5339    Internet organizations, except as needed for the purpose of
5340    developing Internet standards in which case the procedures for
5341    copyrights defined in the Internet Standards process must be
5342    followed, or as required to translate it into languages other than
5343    English.
5344
5345    The limited permissions granted above are perpetual and will not be
5346    revoked by the Internet Society or its successors or assigns.
5347
5348    This document and the information contained herein is provided on an
5349    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
5350    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
5351    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
5352    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
5353    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
5354
5355 Acknowledgement
5356
5357    Funding for the RFC Editor function is currently provided by the
5358    Internet Society.
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378 Kabat & Upadhyay            Standards Track                    [Page 96]
5379 \f