1  
   2  
   3  
   4  
   5  Network Working Group                                        M. Upadhyay
   6  Internet-Draft                                                    Google
   7  Obsoletes: 5653 (if approved)                                 S. Malkani
   8  Intended status: Standards Track                           ActivIdentity
   9  Expires: August 12, 2018                                         W. Wang
  10                                                                    Oracle
  11                                                          February 8, 2018
  12  
  13  
  14        Generic Security Service API Version 2: Java Bindings Update
  15                      draft-ietf-kitten-rfc5653bis-07
  16  
  17  Abstract
  18  
  19     The Generic Security Services Application Program Interface (GSS-API)
  20     offers application programmers uniform access to security services
  21     atop a variety of underlying cryptographic mechanisms.  This document
  22     updates the Java bindings for the GSS-API that are specified in
  23     "Generic Security Service API Version 2 : Java Bindings Update" (RFC
  24     5653).  This document obsoletes RFC 5653 by adding a new output token
  25     field to the GSSException class so that when the initSecContext or
  26     acceptSecContext methods of the GSSContext class fails it has a
  27     chance to emit an error token which can be sent to the peer for
  28     debugging or informational purpose.  The stream-based GSSContext
  29     methods are also removed in this version.
  30  
  31     The GSS-API is described at a language-independent conceptual level
  32     in "Generic Security Service Application Program Interface Version 2,
  33     Update 1" (RFC 2743).  The GSS-API allows a caller application to
  34     authenticate a principal identity, to delegate rights to a peer, and
  35     to apply security services such as confidentiality and integrity on a
  36     per-message basis.  Examples of security mechanisms defined for GSS-
  37     API are "The Simple Public-Key GSS-API Mechanism" (RFC 2025) and "The
  38     Kerberos Version 5 Generic Security Service Application Program
  39     Interface (GSS-API) Mechanism: Version 2" (RFC 4121).
  40  
  41  Status of This Memo
  42  
  43     This Internet-Draft is submitted in full conformance with the
  44     provisions of BCP 78 and BCP 79.
  45  
  46     Internet-Drafts are working documents of the Internet Engineering
  47     Task Force (IETF).  Note that other groups may also distribute
  48     working documents as Internet-Drafts.  The list of current Internet-
  49     Drafts is at http://datatracker.ietf.org/drafts/current/.
  50  
  51     Internet-Drafts are draft documents valid for a maximum of six months
  52     and may be updated, replaced, or obsoleted by other documents at any
  53     time.  It is inappropriate to use Internet-Drafts as reference
  54     material or to cite them other than as "work in progress."
  55  
  56     This Internet-Draft will expire on August 12, 2018.
  57  
  58  Copyright Notice
  59  
  60     Copyright (c) 2018 IETF Trust and the persons identified as the
  61     document authors.  All rights reserved.
  62  
  63     This document is subject to BCP 78 and the IETF Trust's Legal
  64     Provisions Relating to IETF Documents
  65     (http://trustee.ietf.org/license-info) in effect on the date of
  66     publication of this document.  Please review these documents
  67     carefully, as they describe your rights and restrictions with respect
  68     to this document.  Code Components extracted from this document must
  69     include Simplified BSD License text as described in Section 4.e of
  70     the Trust Legal Provisions and are provided without warranty as
  71     described in the Simplified BSD License.
  72  
  73     This document may contain material from IETF Documents or IETF
  74     Contributions published or made publicly available before November
  75     10, 2008.  The person(s) controlling the copyright in some of this
  76     material may not have granted the IETF Trust the right to allow
  77     modifications of such material outside the IETF Standards Process.
  78     Without obtaining an adequate license from the person(s) controlling
  79     the copyright in such materials, this document may not be modified
  80     outside the IETF Standards Process, and derivative works of it may
  81     not be created outside the IETF Standards Process, except to format
  82     it for publication as an RFC or to translate it into languages other
  83     than English.
  84  
  85  Table of Contents
  86  
  87     1.  Introduction
  88     2.  Notational Conventions
  89     3.  GSS-API Operational Paradigm
  90     4.  Additional Controls
  91       4.1.  Delegation
  92       4.2.  Mutual Authentication
  93       4.3.  Replay and Out-of-Sequence Detection
  94       4.4.  Anonymous Authentication
  95       4.5.  Integrity and Confidentiality
  96       4.6.  Inter-process Context Transfer
  97       4.7.  The Use of Incomplete Contexts
  98     5.  Calling Conventions
  99       5.1.  Package Name
 100       5.2.  Provider Framework
 101       5.3.  Integer Types
 102       5.4.  Opaque Data Types
 103       5.5.  Strings
 104       5.6.  Object Identifiers
 105       5.7.  Object Identifier Sets
 106       5.8.  Credentials
 107       5.9.  Contexts
 108       5.10. Authentication Tokens
 109       5.11. Inter-Process Tokens
 110       5.12. Error Reporting
 111         5.12.1.  GSS Status Codes
 112         5.12.2.  Mechanism-Specific Status Codes
 113         5.12.3.  Supplementary Status Codes
 114       5.13. Names
 115       5.14. Channel Bindings
 116       5.15. Optional Parameters
 117     6.  Introduction to GSS-API Classes and Interfaces
 118       6.1.  GSSManager Class
 119       6.2.  GSSName Interface
 120       6.3.  GSSCredential Interface
 121       6.4.  GSSContext Interface
 122       6.5.  MessageProp Class
 123       6.6.  GSSException Class
 124       6.7.  Oid Class
 125       6.8.  ChannelBinding Class
 126     7.  Detailed GSS-API Class Description
 127       7.1.  public abstract class GSSManager
 128         7.1.1.  getInstance
 129         7.1.2.  getMechs
 130         7.1.3.  getNamesForMech
 131         7.1.4.  getMechsForName
 132         7.1.5.  createName
 133         7.1.6.  createName
 134         7.1.7.  createName
 135         7.1.8.  createName
 136         7.1.9.  createCredential
 137         7.1.10. createCredential
 138         7.1.11. createCredential
 139         7.1.12. createContext
 140         7.1.13. createContext
 141         7.1.14. createContext
 142         7.1.15. addProviderAtFront
 143           7.1.15.1.  addProviderAtFront Example Code
 144         7.1.16. addProviderAtEnd
 145           7.1.16.1.  addProviderAtEnd Example Code
 146         7.1.17. Example Code
 147       7.2.  public interface GSSName
 148         7.2.1.  Static Constants
 149         7.2.2.  equals
 150         7.2.3.  equals
 151         7.2.4.  canonicalize
 152         7.2.5.  export
 153         7.2.6.  toString
 154         7.2.7.  getStringNameType
 155         7.2.8.  isAnonymous
 156         7.2.9.  isMN
 157         7.2.10. Example Code
 158       7.3.  public interface GSSCredential implements Cloneable
 159         7.3.1.  Static Constants
 160         7.3.2.  dispose
 161         7.3.3.  getName
 162         7.3.4.  getName
 163         7.3.5.  getRemainingLifetime
 164         7.3.6.  getRemainingInitLifetime
 165         7.3.7.  getRemainingAcceptLifetime
 166         7.3.8.  getUsage
 167         7.3.9.  getUsage
 168         7.3.10. getMechs
 169         7.3.11. add
 170         7.3.12. equals
 171         7.3.13. Example Code
 172       7.4.  public interface GSSContext
 173         7.4.1.  Static Constants
 174         7.4.2.  initSecContext
 175         7.4.3.  acceptSecContext
 176         7.4.4.  isEstablished
 177         7.4.5.  dispose
 178         7.4.6.  getWrapSizeLimit
 179         7.4.7.  wrap
 180         7.4.8.  unwrap
 181         7.4.9.  getMIC
 182         7.4.10. verifyMIC
 183         7.4.11. export
 184         7.4.12. requestMutualAuth
 185         7.4.13. requestReplayDet
 186         7.4.14. requestSequenceDet
 187         7.4.15. requestCredDeleg
 188         7.4.16. requestAnonymity
 189         7.4.17. requestConf
 190         7.4.18. requestInteg
 191         7.4.19. requestLifetime
 192         7.4.20. setChannelBinding
 193         7.4.21. getCredDelegState
 194         7.4.22. getMutualAuthState
 195         7.4.23. getReplayDetState
 196         7.4.24. getSequenceDetState
 197         7.4.25. getAnonymityState
 198         7.4.26. isTransferable
 199         7.4.27. isProtReady
 200         7.4.28. getConfState
 201         7.4.29. getIntegState
 202         7.4.30. getLifetime
 203         7.4.31. getSrcName
 204         7.4.32. getTargName
 205         7.4.33. getMech
 206         7.4.34. getDelegCred
 207         7.4.35. isInitiator
 208         7.4.36. Example Code
 209       7.5.  public class MessageProp
 210         7.5.1.  Constructors
 211         7.5.2.  getQOP
 212         7.5.3.  getPrivacy
 213         7.5.4.  getMinorStatus
 214         7.5.5.  getMinorString
 215         7.5.6.  setQOP
 216         7.5.7.  setPrivacy
 217         7.5.8.  isDuplicateToken
 218         7.5.9.  isOldToken
 219         7.5.10. isUnseqToken
 220         7.5.11. isGapToken
 221         7.5.12. setSupplementaryStates
 222       7.6.  public class ChannelBinding
 223         7.6.1.  Constructors
 224         7.6.2.  getInitiatorAddress
 225         7.6.3.  getAcceptorAddress
 226         7.6.4.  getApplicationData
 227         7.6.5.  equals
 228       7.7.  public class Oid
 229         7.7.1.  Constructors
 230         7.7.2.  toString
 231         7.7.3.  equals
 232         7.7.4.  getDER
 233         7.7.5.  containedIn
 234       7.8.  public class GSSException extends Exception
 235         7.8.1.  Static Constants
 236         7.8.2.  Constructors
 237         7.8.3.  getMajor
 238         7.8.4.  getMinor
 239         7.8.5.  getMajorString
 240         7.8.6.  getMinorString
 241         7.8.7.  getOutputToken
 242         7.8.8.  setMinor
 243         7.8.9.  toString
 244         7.8.10. getMessage
 245     8.  Sample Applications
 246       8.1.  Simple GSS Context Initiator
 247       8.2.  Simple GSS Context Acceptor
 248     9.  Security Considerations
 249     10. IANA Considerations
 250     11. Acknowledgments
 251     12. Changes since RFC 5653
 252     13. Changes since RFC 2853
 253     14. References
 254       14.1.  Normative References
 255       14.2.  Informative References
 256     Authors' Addresses
 257  
 258  1.  Introduction
 259  
 260     This document specifies Java language bindings for the Generic
 261     Security Services Application Programming Interface version 2 (GSS-
 262     API).  GSS-API version 2 is described in a language-independent
 263     format in RFC 2743 [RFC2743].  The GSS-API allows a caller
 264     application to authenticate a principal identity, to delegate rights
 265     to a peer, and to apply security services such as confidentiality and
 266     integrity on a per-message basis.
 267  
 268     This document and its predecessor, RFC 2853 [RFC2853] and RFC 5653
 269     [RFC5653], leverage the work done by the working group (WG) in the
 270     area of RFC 2743 [RFC2743] and the C-bindings of RFC 2744 [RFC2744].
 271     Whenever appropriate, text has been used from the C-bindings document
 272     (RFC 2744) to explain generic concepts and provide direction to the
 273     implementors.
 274  
 275     The design goals of this API have been to satisfy all the
 276     functionality defined in RFC 2743 [RFC2743] and to provide these
 277     services in an object-oriented method.  The specification also aims
 278     to satisfy the needs of both types of Java application developers,
 279     those who would like access to a "system-wide" GSS-API
 280     implementation, as well as those who would want to provide their own
 281     "custom" implementation.
 282  
 283     A system-wide implementation is one that is available to all
 284     applications in the form of a library package.  It may be the
 285     standard package in the Java runtime environment (JRE) being used or
 286     it may be additionally installed and accessible to any application
 287     via the CLASSPATH.
 288  
 289     A custom implementation of the GSS-API, on the other hand, is one
 290     that would, in most cases, be bundled with the application during
 291     distribution.  It is expected that such an implementation would be
 292     meant to provide for some particular need of the application, such as
 293     support for some specific mechanism.
 294  
 295     The design of this API also aims to provide a flexible framework to
 296     add and manage GSS-API mechanisms.  GSS-API leverages the Java
 297     Cryptography Architecture (JCA) provider model to support the
 298     plugability of mechanisms.  Mechanisms can be added on a system-wide
 299     basis, where all users of the framework will have them available.
 300     The specification also allows for the addition of mechanisms per-
 301     instance of the GSS-API.
 302  
 303     Lastly, this specification presents an API that will naturally fit
 304     within the operation environment of the Java platform.  Readers are
 305     assumed to be familiar with both the GSS-API and the Java platform.
 306  
 307  2.  Notational Conventions
 308  
 309     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 310     "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
 311     "OPTIONAL" in this document are to be interpreted as described in BCP
 312     14 [RFC2119] [RFC8174] when, and only when, they appear in all
 313     capitals, as shown here.
 314  
 315  3.  GSS-API Operational Paradigm
 316  
 317     "Generic Security Service Application Programming Interface, Version
 318     2" [RFC2743] defines a generic security API to calling applications.
 319     It allows a communicating application to authenticate the user
 320     associated with another application, to delegate rights to another
 321     application, and to apply security services such as confidentiality
 322     and integrity on a per-message basis.
 323  
 324     There are four stages to using GSS-API:
 325  
 326     1) The application acquires a set of credentials with which it may
 327        prove its identity to other processes.  The application's
 328        credentials vouch for its global identity, which may or may not be
 329        related to any local username under which it may be running.
 330  
 331     2) A pair of communicating applications establish a joint security
 332        context using their credentials.  The security context
 333        encapsulates shared state information, which is required in order
 334        that per-message security services may be provided.  Examples of
 335        state information that might be shared between applications as
 336        part of a security context are cryptographic keys and message
 337        sequence numbers.  As part of the establishment of a security
 338        context, the context initiator is authenticated to the responder,
 339        and may require that the responder is authenticated back to the
 340        initiator.  The initiator may optionally give the responder the
 341        right to initiate further security contexts, acting as an agent or
 342        delegate of the initiator.  This transfer of rights is termed
 343        "delegation", and is achieved by creating a set of credentials,
 344        similar to those used by the initiating application, but which may
 345        be used by the responder.
 346  
 347        A GSSContext object is used to establish and maintain the shared
 348        information that makes up the security context.  Certain
 349        GSSContext methods will generate a token, which applications treat
 350        as cryptographically protected, opaque data.  The caller of such a
 351        GSSContext method is responsible for transferring the token to the
 352        peer application, encapsulated if necessary in an application-to-
 353        application protocol.  On receipt of such a token, the peer
 354        application should pass it to a corresponding GSSContext method
 355        which will decode the token and extract the information, updating
 356        the security context state information accordingly.
 357  
 358     3) Per-message services are invoked on a GSSContext object to apply
 359        either:
 360  
 361        integrity and data origin authentication, or
 362  
 363        confidentiality, integrity and data origin authentication
 364  
 365        to application data, which are treated by GSS-API as arbitrary
 366        octet-strings.  An application transmitting a message that it
 367        wishes to protect will call the appropriate GSSContext method
 368        (getMIC or wrap) to apply protection, and send the resulting token
 369        to the receiving application.  The receiver will pass the received
 370        token (and, in the case of data protected by getMIC, the
 371        accompanying message-data) to the corresponding decoding method of
 372        the GSSContext interface (verifyMIC or unwrap) to remove the
 373        protection and validate the data.
 374  
 375     4) At the completion of a communications session (which may extend
 376        across several transport connections), each application uses a
 377        GSSContext method to invalidate the security context and release
 378        any system or cryptographic resources held.  Multiple contexts may
 379        also be used (either successively or simultaneously) within a
 380        single communications association, at the discretion of the
 381        applications.
 382  
 383  4.  Additional Controls
 384  
 385     This section discusses the OPTIONAL services that a context initiator
 386     may request of the GSS-API before the context establishment.  Each of
 387     these services is requested by calling the appropriate mutator method
 388     in the GSSContext object before the first call to init is performed.
 389     Only the context initiator can request context flags.
 390  
 391     The OPTIONAL services defined are:
 392  
 393        Delegation: The (usually temporary) transfer of rights from
 394        initiator to acceptor, enabling the acceptor to authenticate
 395        itself as an agent of the initiator.
 396  
 397        Mutual Authentication: In addition to the initiator authenticating
 398        its identity to the context acceptor, the context acceptor SHOULD
 399        also authenticate itself to the initiator.
 400  
 401        Replay Detection: In addition to providing message integrity
 402        services, GSSContext per-message operations of getMIC and wrap
 403        SHOULD include message numbering information to enable verifyMIC
 404        and unwrap to detect if a message has been duplicated.
 405  
 406        Out-of-Sequence Detection: In addition to providing message
 407        integrity services, GSSContext per-message operations (getMIC and
 408        wrap) SHOULD include message sequencing information to enable
 409        verifyMIC and unwrap to detect if a message has been received out
 410        of sequence.
 411  
 412        Anonymous Authentication: The establishment of the security
 413        context SHOULD NOT reveal the initiator's identity to the context
 414        acceptor.
 415  
 416     Some mechanisms may not support all OPTIONAL services, and some
 417     mechanisms may only support some services in conjunction with others.
 418     The GSSContext interface offers query methods to allow the
 419     verification by the calling application of which services will be
 420     available from the context when the establishment phase is complete.
 421     In general, if the security mechanism is capable of providing a
 422     requested service, it SHOULD do so even if additional services must
 423     be enabled in order to provide the requested service.  If the
 424     mechanism is incapable of providing a requested service, it SHOULD
 425     proceed without the service leaving the application to abort the
 426     context establishment process if it considers the requested service
 427     to be mandatory.
 428  
 429     Some mechanisms MAY specify that support for some services is
 430     optional, and that implementors of the mechanism need not provide it.
 431     This is most commonly true of the confidentiality service, often
 432     because of legal restrictions on the use of data-encryption, but may
 433     apply to any of the services.  Such mechanisms are required to send
 434     at least one token from acceptor to initiator during context
 435     establishment when the initiator indicates a desire to use such a
 436     service, so that the initiating GSS-API can correctly indicate
 437     whether the service is supported by the acceptor's GSS-API.
 438  
 439  4.1.  Delegation
 440  
 441     The GSS-API allows delegation to be controlled by the initiating
 442     application via the requestCredDeleg method before the first call to
 443     init has been issued.  Some mechanisms do not support delegation, and
 444     for such mechanisms, attempts by an application to enable delegation
 445     are ignored.
 446  
 447     The acceptor of a security context, for which the initiator enabled
 448     delegation, can check if delegation was enabled by using the
 449     getCredDelegState method of the GSSContext interface.  In cases when
 450     it is enabled, the delegated credential object can be obtained by
 451     calling the getDelegCred method.  The obtained GSSCredential object
 452     may then be used to initiate subsequent GSS-API security contexts as
 453     an agent or delegate of the initiator.  If the original initiator's
 454     identity is "A" and the delegate's identity is "B", then, depending
 455     on the underlying mechanism, the identity embodied by the delegated
 456     credential may be either "A" or "B acting for A".
 457  
 458     For many mechanisms that support delegation, a simple boolean does
 459     not provide enough control.  Examples of additional aspects of
 460     delegation control that a mechanism might provide to an application
 461     are duration of delegation, network addresses from which delegation
 462     is valid, and constraints on the tasks that may be performed by a
 463     delegate.  Such controls are presently outside the scope of the GSS-
 464     API.  GSS-API implementations supporting mechanisms offering
 465     additional controls SHOULD provide extension routines that allow
 466     these controls to be exercised (perhaps by modifying the initiator's
 467     GSS-API credential object prior to its use in establishing a
 468     context).  However, the simple delegation control provided by GSS-API
 469     SHOULD always be able to override other mechanism-specific delegation
 470     controls.  If the application instructs the GSSContext object that
 471     delegation is not desired, then the implementation MUST NOT permit
 472     delegation to occur.  This is an exception to the general rule that a
 473     mechanism may enable services even if they are not requested --
 474     delegation may only be provided at the explicit request of the
 475     application.
 476  
 477  4.2.  Mutual Authentication
 478  
 479     Usually, a context acceptor will require that a context initiator
 480     authenticate itself so that the acceptor may make an access-control
 481     decision prior to performing a service for the initiator.  In some
 482     cases, the initiator may also request that the acceptor authenticate
 483     itself.  GSS-API allows the initiating application to request this
 484     mutual authentication service by calling the requestMutualAuth method
 485     of the GSSContext interface with a "true" parameter before making the
 486     first call to init.  The initiating application is informed as to
 487     whether or not the context acceptor has authenticated itself.  Note
 488     that some mechanisms may not support mutual authentication, and other
 489     mechanisms may always perform mutual authentication, whether or not
 490     the initiating application requests it.  In particular, mutual
 491     authentication may be required by some mechanisms in order to support
 492     replay or out-of-sequence message detection, and for such mechanisms,
 493     a request for either of these services will automatically enable
 494     mutual authentication.
 495  
 496  4.3.  Replay and Out-of-Sequence Detection
 497  
 498     The GSS-API MAY provide detection of mis-ordered messages once a
 499     security context has been established.  Protection MAY be applied to
 500     messages by either application, by calling either getMIC or wrap
 501     methods of the GSSContext interface, and verified by the peer
 502     application by calling verifyMIC or unwrap for the peer's GSSContext
 503     object.
 504  
 505     The getMIC method calculates a cryptographic checksum (authentication
 506     tag) of an application message, and returns that checksum in a token.
 507     The application SHOULD pass both the token and the message to the
 508     peer application, which presents them to the verifyMIC method of the
 509     peer's GSSContext object.
 510  
 511     The wrap method calculates a cryptographic checksum of an application
 512     message, and places both the checksum and the message inside a single
 513     token.  The application SHOULD pass the token to the peer
 514     application, which presents it to the unwrap method of the peer's
 515     GSSContext object to extract the message and verify the checksum.
 516  
 517     Either pair of routines may be capable of detecting out-of-sequence
 518     message delivery or the duplication of messages.  Details of such
 519     mis-ordered messages are indicated through supplementary query
 520     methods of the MessageProp object that is filled in by each of these
 521     routines.
 522  
 523     A mechanism need not maintain a list of all tokens that have been
 524     processed in order to support these status codes.  A typical
 525     mechanism might retain information about only the most recent "N"
 526     tokens processed, allowing it to distinguish duplicates and missing
 527     tokens within the most recent "N" messages; the receipt of a token
 528     older than the most recent "N" would result in the isOldToken method
 529     of the instance of MessageProp to return "true".
 530  
 531  4.4.  Anonymous Authentication
 532  
 533     In certain situations, an application may wish to initiate the
 534     authentication process to authenticate a peer, without revealing its
 535     own identity.  As an example, consider an application providing
 536     access to a database containing medical information and offering
 537     unrestricted access to the service.  A client of such a service might
 538     wish to authenticate the service (in order to establish trust in any
 539     information retrieved from it), but might not wish the service to be
 540     able to obtain the client's identity (perhaps due to privacy concerns
 541     about the specific inquiries, or perhaps simply to avoid being placed
 542     on mailing-lists).
 543  
 544     In normal use of the GSS-API, the initiator's identity is made
 545     available to the acceptor as a result of the context establishment
 546     process.  However, context initiators may request that their identity
 547     not be revealed to the context acceptor.  Many mechanisms do not
 548     support anonymous authentication, and for such mechanisms, the
 549     request will not be honored.  An authentication token will still be
 550     generated, but the application is always informed if a requested
 551     service is unavailable, and has the option to abort context
 552     establishment if anonymity is valued above the other security
 553     services that would require a context to be established.
 554  
 555     In addition to informing the application that a context is
 556     established anonymously (via the isAnonymous method of the GSSContext
 557     class), the getSrcName method of the acceptor's GSSContext object
 558     will, for such contexts, return a reserved internal-form name,
 559     defined by the implementation.
 560  
 561     The toString method for a GSSName object representing an anonymous
 562     entity will return a printable name.  The returned value will be
 563     syntactically distinguishable from any valid principal name supported
 564     by the implementation.  The associated name-type object identifier
 565     will be an oid representing the value of NT_ANONYMOUS.  This name-
 566     type oid will be defined as a public, static Oid object of the
 567     GSSName class.  The printable form of an anonymous name SHOULD be
 568     chosen such that it implies anonymity, since this name may appear in,
 569     for example, audit logs.  For example, the string "<anonymous>" might
 570     be a good choice, if no valid printable names supported by the
 571     implementation can begin with "<" and end with ">".
 572  
 573     When using the equal method of the GSSName interface, and one of the
 574     operands is a GSSName instance representing an anonymous entity, the
 575     method MUST return "false".
 576  
 577  4.5.  Integrity and Confidentiality
 578  
 579     If a GSSContext supports the integrity service, getMic method may be
 580     used to create message integrity check tokens on application
 581     messages.
 582  
 583     If a GSSContext supports the confidentiality service, wrap method may
 584     be used to encrypt application messages.  Messages are selectively
 585     encrypted, under the control of the setPrivacy method of the
 586     MessageProp object used in the wrap method.  Confidentiality will be
 587     applied if the privacy state is set to true.
 588  
 589  4.6.  Inter-process Context Transfer
 590  
 591     GSS-APIv2 provides functionality that allows a security context to be
 592     transferred between processes on a single machine.  These are
 593     implemented using the export method of GSSContext and a byte array
 594     constructor of the same class.  The most common use for such a
 595     feature is a client-server design where the server is implemented as
 596     a single process that accepts incoming security contexts, which then
 597     launches child processes to deal with the data on these contexts.  In
 598     such a design, the child processes must have access to the security
 599     context object created within the parent so that they can use per-
 600     message protection services and delete the security context when the
 601     communication session ends.
 602  
 603     Since the security context data structure is expected to contain
 604     sequencing information, it is impractical in general to share a
 605     context between processes.  Thus, the GSSContext interface provides
 606     an export method that the process, which currently owns the context,
 607     can call to declare that it has no intention to use the context
 608     subsequently, and to create an inter-process token containing
 609     information needed by the adopting process to successfully recreate
 610     the context.  After successful completion of export, the original
 611     security context is made inaccessible to the calling process by GSS-
 612     API, and any further usage of this object will result in failures.
 613     The originating process transfers the inter-process token to the
 614     adopting process, which creates a new GSSContext object using the
 615     byte array constructor.  The properties of the context are equivalent
 616     to that of the original context.
 617  
 618     The inter-process token MAY contain sensitive data from the original
 619     security context (including cryptographic keys).  Applications using
 620     inter-process tokens to transfer security contexts MUST take
 621     appropriate steps to protect these tokens in transit.
 622  
 623     Implementations are not required to support the inter-process
 624     transfer of security contexts.  Calling the isTransferable method of
 625     the GSSContext interface will indicate if the context object is
 626     transferable.
 627  
 628  4.7.  The Use of Incomplete Contexts
 629  
 630     Some mechanisms may allow the per-message services to be used before
 631     the context establishment process is complete.  For example, a
 632     mechanism may include sufficient information in its initial context-
 633     level tokens for the context acceptor to immediately decode messages
 634     protected with wrap or getMIC.  For such a mechanism, the initiating
 635     application need not wait until subsequent context-level tokens have
 636     been sent and received before invoking the per-message protection
 637     services.
 638  
 639     An application can invoke the isProtReady method of the GSSContext
 640     class to determine if the per-message services are available in
 641     advance of complete context establishment.  Applications wishing to
 642     use per-message protection services on partially established contexts
 643     SHOULD query this method before attempting to invoke wrap or getMIC.
 644  
 645  5.  Calling Conventions
 646  
 647     Java provides the implementors with not just a syntax for the
 648     language, but also an operational environment.  For example, memory
 649     is automatically managed and does not require application
 650     intervention.  These language features have allowed for a simpler API
 651     and have led to the elimination of certain GSS-API functions.
 652  
 653     Moreover, the JCA defines a provider model that allows for
 654     implementation-independent access to security services.  Using this
 655     model, applications can seamlessly switch between different
 656     implementations and dynamically add new services.  The GSS-API
 657     specification leverages these concepts by the usage of providers for
 658     the mechanism implementations.
 659  
 660  5.1.  Package Name
 661  
 662     The classes and interfaces defined in this document reside in the
 663     package called "org.ietf.jgss".  Applications that wish to make use
 664     of this API should import this package name as shown in section 8.
 665  
 666  5.2.  Provider Framework
 667  
 668     The Java security API's use a provider architecture that allows
 669     applications to be implementation independent and security API
 670     implementations to be modular and extensible.  The
 671     java.security.Provider class is an abstract class that a vendor
 672     extends.  This class maps various properties that represent different
 673     security services that are available to the names of the actual
 674     vendor classes that implement those services.  When requesting a
 675     service, an application simply specifies the desired provider and the
 676     API delegates the request to service classes available from that
 677     provider.
 678  
 679     Using the Java security provider model insulates applications from
 680     implementation details of the services they wish to use.
 681     Applications can switch between providers easily and new providers
 682     can be added as needed, even at runtime.
 683  
 684     The GSS-API may use providers to find components for specific
 685     underlying security mechanisms.  For instance, a particular provider
 686     might contain components that will allow the GSS-API to support the
 687     Kerberos v5 mechanism [RFC4121] and another might contain components
 688     to support the Simple Public-Key GSS-API Mechanism (SPKM) [RFC2025].
 689     By delegating mechanism-specific functionality to the components
 690     obtained from providers, the GSS-API can be extended to support an
 691     arbitrary list of mechanism.
 692  
 693     How the GSS-API locates and queries these providers is beyond the
 694     scope of this document and is being deferred to a Service Provider
 695     Interface (SPI) specification.  The availability of such an SPI
 696     specification is not mandatory for the adoption of this API
 697     specification nor is it mandatory to use providers in the
 698     implementation of a GSS-API framework.  However, by using the
 699     provider framework together with an SPI specification, one can create
 700     an extensible and implementation-independent GSS-API framework.
 701  
 702  5.3.  Integer Types
 703  
 704     All numeric values are declared as "int" primitive Java type.  The
 705     Java specification guarantees that this will be a 32-bit two's
 706     complement signed number.
 707  
 708     Throughout this API, the "boolean" primitive Java type is used
 709     wherever a boolean value is required or returned.
 710  
 711  5.4.  Opaque Data Types
 712  
 713     Java byte arrays are used to represent opaque data types that are
 714     consumed and produced by the GSS-API in the form of tokens.  Java
 715     arrays contain a length field that enables the users to easily
 716     determine their size.  The language has automatic garbage collection
 717     that alleviates the need by developers to release memory and
 718     simplifies buffer ownership issues.
 719  
 720  5.5.  Strings
 721  
 722     The String object will be used to represent all textual data.  The
 723     Java String object transparently treats all characters as two-byte
 724     Unicode characters, which allows support for many locals.  All
 725     routines returning or accepting textual data will use the String
 726     object.
 727  
 728  5.6.  Object Identifiers
 729  
 730     An Oid object will be used to represent Universal Object Identifiers
 731     (Oids).  Oids are ISO-defined, hierarchically globally interpretable
 732     identifiers used within the GSS-API framework to identify security
 733     mechanisms and name formats.  The Oid object can be created from a
 734     string representation of its dot notation (e.g., "1.3.6.1.5.6.2") as
 735     well as from its ASN.1 DER encoding.  Methods are also provided to
 736     test equality and provide the DER representation for the object.
 737  
 738     An important feature of the Oid class is that its instances are
 739     immutable -- i.e., there are no methods defined that allow one to
 740     change the contents of an Oid.  This property allows one to treat
 741     these objects as "statics" without the need to perform copies.
 742  
 743     Certain routines allow the usage of a default oid.  A "null" value
 744     can be used in those cases.
 745  
 746  5.7.  Object Identifier Sets
 747  
 748     The Java bindings represent object identifier sets as arrays of Oid
 749     objects.  All Java arrays contain a length field, which allows for
 750     easy manipulation and reference.
 751  
 752     In order to support the full functionality of RFC 2743 [RFC2743], the
 753     Oid class includes a method that checks for existence of an Oid
 754     object within a specified array.  This is equivalent in functionality
 755     to gss_test_oid_set_member.  The use of Java arrays and Java's
 756     automatic garbage collection has eliminated the need for the
 757     following routines: gss_create_empty_oid_set, gss_release_oid_set,
 758     and gss_add_oid_set_member.  Java GSS-API implementations will not
 759     contain them.  Java's automatic garbage collection and the immutable
 760     property of the Oid object eliminates the memory management issues of
 761     the C counterpart.
 762  
 763     Whenever a default value for an Object Identifier Set is required, a
 764     "null" value can be used.  Please consult the detailed method
 765     description for details.
 766  
 767  5.8.  Credentials
 768  
 769     GSS-API credentials are represented by the GSSCredential interface.
 770     The interface contains several constructs to allow for the creation
 771     of most common credential objects for the initiator and the acceptor.
 772     Comparisons are performed using the interface's "equals" method.  The
 773     following general description of GSS-API credentials is included from
 774     the C-bindings specification:
 775  
 776        GSS-API credentials can contain mechanism-specific principal
 777        authentication data for multiple mechanisms.  A GSS-API credential
 778        is composed of a set of credential-elements, each of which is
 779        applicable to a single mechanism.  A credential may contain at
 780        most one credential-element for each supported mechanism.  A
 781        credential-element identifies the data needed by a single
 782        mechanism to authenticate a single principal, and conceptually
 783        contains two credential-references that describe the actual
 784        mechanism-specific authentication data, one to be used by GSS-API
 785        for initiating contexts, and one to be used for accepting
 786        contexts.  For mechanisms that do not distinguish between acceptor
 787        and initiator credentials, both references would point to the same
 788        underlying mechanism-specific authentication data.
 789  
 790     Credentials describe a set of mechanism-specific principals, and give
 791     their holder the ability to act as any of those principals.  All
 792     principal identities asserted by a single GSS-API credential SHOULD
 793     belong to the same entity, although enforcement of this property is
 794     an implementation-specific matter.  A single GSSCredential object
 795     represents all the credential elements that have been acquired.
 796  
 797     The creation of an GSSContext object allows the value of "null" to be
 798     specified as the GSSCredential input parameter.  This will indicate a
 799     desire by the application to act as a default principal.  While
 800     individual GSS-API implementations are free to determine such default
 801     behavior as appropriate to the mechanism, the following default
 802     behavior by these routines is RECOMMENDED for portability:
 803  
 804     For the initiator side of the context:
 805  
 806     1) If there is only a single principal capable of initiating security
 807        contexts for the chosen mechanism that the application is
 808        authorized to act on behalf of, then that principal shall be used;
 809        otherwise,
 810  
 811     2) If the platform maintains a concept of a default network-identity
 812        for the chosen mechanism, and if the application is authorized to
 813        act on behalf of that identity for the purpose of initiating
 814        security contexts, then the principal corresponding to that
 815        identity shall be used; otherwise,
 816  
 817     3) If the platform maintains a concept of a default local identity,
 818        and provides a means to map local identities into network-
 819        identities for the chosen mechanism, and if the application is
 820        authorized to act on behalf of the network-identity image of the
 821        default local identity for the purpose of initiating security
 822        contexts using the chosen mechanism, then the principal
 823        corresponding to that identity shall be used; otherwise,
 824  
 825     4) A user-configurable default identity should be used.
 826  
 827     For the acceptor side of the context:
 828  
 829     1) If there is only a single authorized principal identity capable of
 830        accepting security contexts for the chosen mechanism, then that
 831        principal shall be used; otherwise,
 832  
 833     2) If the mechanism can determine the identity of the target
 834        principal by examining the context-establishment token processed
 835        during the accept method, and if the accepting application is
 836        authorized to act as that principal for the purpose of accepting
 837        security contexts using the chosen mechanism, then that principal
 838        identity shall be used; otherwise,
 839  
 840     3) If the mechanism supports context acceptance by any principal, and
 841        if mutual authentication was not requested, any principal that the
 842        application is authorized to accept security contexts under using
 843        the chosen mechanism may be used; otherwise,
 844  
 845     4) A user-configurable default identity shall be used.
 846  
 847     The purpose of the above rules is to allow security contexts to be
 848     established by both initiator and acceptor using the default behavior
 849     whenever possible.  Applications requesting default behavior are
 850     likely to be more portable across mechanisms and implementations than
 851     ones that instantiate an GSSCredential object representing a specific
 852     identity.
 853  
 854  5.9.  Contexts
 855  
 856     The GSSContext interface is used to represent one end of a GSS-API
 857     security context, storing state information appropriate to that end
 858     of the peer communication, including cryptographic state information.
 859     The instantiation of the context object is done differently by the
 860     initiator and the acceptor.  After the context has been instantiated,
 861     the initiator MAY choose to set various context options that will
 862     determine the characteristics of the desired security context.  When
 863     all the application-desired characteristics have been set, the
 864     initiator will call the initSecContext method, which will produce a
 865     token for consumption by the peer's acceptSecContext method.  It is
 866     the responsibility of the application to deliver the authentication
 867     token(s) between the peer applications for processing.  Upon
 868     completion of the context-establishment phase, context attributes can
 869     be retrieved, by both the initiator and acceptor, using the accessor
 870     methods.  These will reflect the actual attributes of the established
 871     context and might not match the initiator-requested values.  If any
 872     retrieved attribute does not match the desired value but it is
 873     necessary for the application protocol, the application SHOULD
 874     destroy the security context and not use it for application traffic.
 875     Otherwise, at this point, the context can be used by the application
 876     to apply cryptographic services to its data.
 877  
 878  5.10.  Authentication Tokens
 879  
 880     A token is a caller-opaque type that GSS-API uses to maintain
 881     synchronization between each end of the GSS-API security context.
 882     The token is a cryptographically protected octet-string, generated by
 883     the underlying mechanism at one end of a GSS-API security context for
 884     use by the peer mechanism at the other end.  Encapsulation (if
 885     required) within the application protocol and transfer of the token
 886     are the responsibility of the peer applications.
 887  
 888     Java GSS-API uses byte arrays to represent authentication tokens.
 889  
 890  5.11.  Inter-Process Tokens
 891  
 892     Certain GSS-API routines are intended to transfer data between
 893     processes in multi-process programs.  These routines use a caller-
 894     opaque octet-string, generated by the GSS-API in one process for use
 895     by the GSS-API in another process.  The calling application is
 896     responsible for transferring such tokens between processes.  Note
 897     that, while GSS-API implementors are encouraged to avoid placing
 898     sensitive information within inter-process tokens, or to
 899     cryptographically protect them, many implementations will be unable
 900     to avoid placing key material or other sensitive data within them.
 901     It is the application's responsibility to ensure that inter-process
 902     tokens are protected in transit, and transferred only to processes
 903     that are trustworthy.  An inter-process token is represented using a
 904     byte array emitted from the export method of the GSSContext
 905     interface.  The receiver of the inter-process token would initialize
 906     an GSSContext object with this token to create a new context.  Once a
 907     context has been exported, the GSSContext object is invalidated and
 908     is no longer available.
 909  
 910  5.12.  Error Reporting
 911  
 912     RFC 2743 [RFC2743] defined the usage of major and minor status values
 913     for the signaling of GSS-API errors.  The major code, also called GSS
 914     status code, is used to signal errors at the GSS-API level,
 915     independent of the underlying mechanism(s).  The minor status value
 916     or Mechanism status code, is a mechanism-defined error value
 917     indicating a mechanism-specific error code.
 918  
 919     Java GSS-API uses exceptions implemented by the GSSException class to
 920     signal both minor and major error values.  Both mechanism-specific
 921     errors and GSS-API level errors are signaled through instances of
 922     this class.  The usage of exceptions replaces the need for major and
 923     minor codes to be used within the API calls.  The GSSException class
 924     also contains methods to obtain textual representations for both the
 925     major and minor values, which is equivalent to the functionality of
 926     gss_display_status.  A GSSException object MAY also include an output
 927     token that SHOULD be sent to the peer.
 928  
 929     If an exception is thrown during context establishment, the context
 930     negotiation has failed and the GSSContext object MUST be abandoned.
 931     If it is thrown in a per-message call, the context MAY remain useful.
 932  
 933  5.12.1.  GSS Status Codes
 934  
 935     GSS status codes indicate errors that are independent of the
 936     underlying mechanism(s) used to provide the security service.  The
 937     errors that can be indicated via a GSS status code are generic API
 938     routine errors (errors that are defined in the GSS-API
 939     specification).  These bindings take advantage of the Java exceptions
 940     mechanism, thus, eliminating the need for calling errors.
 941  
 942     A GSS status code indicates a single fatal generic API error from the
 943     routine that has thrown the GSSException.  Using exceptions announces
 944     that a fatal error has occurred during the execution of the method.
 945     The GSS-API operational model also allows for the signaling of
 946     supplementary status information from the per-message calls.  These
 947     need to be handled as return values since using exceptions is not
 948     appropriate for informatory or warning-like information.  The methods
 949     that are capable of producing supplementary information are the two
 950     per-message methods GSSContext.verifyMIC() and GSSContext.unwrap().
 951     These methods fill the supplementary status codes in the MessageProp
 952     object that was passed in.
 953  
 954     A GSSException object, along with providing the functionality for
 955     setting of the various error codes and translating them into textual
 956     representation, also contains the definitions of all the numeric
 957     error values.  The following table lists the definitions of error
 958     codes:
 959  
 960     Table: GSS Status Codes
 961  
 962     +----------------------+-------+------------------------------------+
 963     | Name                 | Value | Meaning                            |
 964     +----------------------+-------+------------------------------------+
 965     | BAD_BINDINGS         | 1     | Incorrect channel bindings were    |
 966     |                      |       | supplied.                          |
 967     |                      |       |                                    |
 968     | BAD_MECH             | 2     | An unsupported mechanism was       |
 969     |                      |       | requested.                         |
 970     |                      |       |                                    |
 971     | BAD_NAME             | 3     | An invalid name was supplied.      |
 972     |                      |       |                                    |
 973     | BAD_NAMETYPE         | 4     | A supplied name was of an          |
 974     |                      |       | unsupported type.                  |
 975     |                      |       |                                    |
 976     | BAD_STATUS           | 5     | An invalid status code was         |
 977     |                      |       | supplied.                          |
 978     |                      |       |                                    |
 979     | BAD_MIC              | 6     | A token had an invalid MIC.        |
 980     |                      |       |                                    |
 981     | CONTEXT_EXPIRED      | 7     | The context has expired.           |
 982     |                      |       |                                    |
 983     | CREDENTIALS_EXPIRED  | 8     | The referenced credentials have    |
 984     |                      |       | expired.                           |
 985     |                      |       |                                    |
 986     | DEFECTIVE_CREDENTIAL | 9     | A supplied credential was invalid. |
 987     |                      |       |                                    |
 988     | DEFECTIVE_TOKEN      | 10    | A supplied token was invalid.      |
 989     |                      |       |                                    |
 990     | FAILURE              | 11    | Miscellaneous failure, unspecified |
 991     |                      |       | at the GSS-API level.              |
 992     |                      |       |                                    |
 993     | NO_CONTEXT           | 12    | Invalid context has been supplied. |
 994     |                      |       |                                    |
 995     | NO_CRED              | 13    | No credentials were supplied, or   |
 996     |                      |       | the credentials were unavailable   |
 997     |                      |       | or inaccessible.                   |
 998     |                      |       |                                    |
 999     | BAD_QOP              | 14    | The quality-of-protection (QOP)    |
1000     |                      |       | requested could not be provided.   |
1001     |                      |       |                                    |
1002     | UNAUTHORIZED         | 15    | The operation is forbidden by the  |
1003     |                      |       | local security policy.             |
1004     |                      |       |                                    |
1005     | UNAVAILABLE          | 16    | The operation or option is         |
1006     |                      |       | unavailable.                       |
1007     |                      |       |                                    |
1008     | DUPLICATE_ELEMENT    | 17    | The requested credential element   |
1009     |                      |       | already exists.                    |
1010     |                      |       |                                    |
1011     | NAME_NOT_MN          | 18    | The provided name was not a        |
1012     |                      |       | mechanism name.                    |
1013     +----------------------+-------+------------------------------------+
1014  
1015     The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN,
1016     UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException only if
1017     detected during context establishment, in which case it is a fatal
1018     error.  (During per-message calls, these values are indicated as
1019     supplementary information contained in the MessageProp object.)  They
1020     are:
1021  
1022     +-----------------+-------+-----------------------------------------+
1023     | Name            | Value | Meaning                                 |
1024     +-----------------+-------+-----------------------------------------+
1025     | DUPLICATE_TOKEN | 19    | The token was a duplicate of an earlier |
1026     |                 |       | version.                                |
1027     |                 |       |                                         |
1028     | OLD_TOKEN       | 20    | The token's validity period has         |
1029     |                 |       | expired.                                |
1030     |                 |       |                                         |
1031     | UNSEQ_TOKEN     | 21    | A later token has already been          |
1032     |                 |       | processed.                              |
1033     |                 |       |                                         |
1034     | GAP_TOKEN       | 22    | The expected token was not received.    |
1035     +-----------------+-------+-----------------------------------------+
1036  
1037     The GSS major status code of FAILURE is used to indicate that the
1038     underlying mechanism detected an error for which no specific GSS
1039     status code is defined.  The mechanism-specific status code can
1040     provide more details about the error.
1041  
1042     The different major status codes that can be contained in the
1043     GSSException object thrown by the methods in this specification are
1044     the same as the major status codes returned by the corresponding
1045     calls in RFC 2743 [RFC2743].
1046  
1047  5.12.2.  Mechanism-Specific Status Codes
1048  
1049     Mechanism-specific status codes are communicated in two ways, they
1050     are part of any GSSException thrown from the mechanism-specific layer
1051     to signal a fatal error, or they are part of the MessageProp object
1052     that the per-message calls use to signal non-fatal errors.
1053  
1054     A default value of 0 in either the GSSException object or the
1055     MessageProp object will be used to represent the absence of any
1056     mechanism-specific status code.
1057  
1058  5.12.3.  Supplementary Status Codes
1059  
1060     Supplementary status codes are confined to the per-message methods of
1061     the GSSContext interface.  Because of the informative nature of these
1062     errors it is not appropriate to use exceptions to signal them.
1063     Instead, the per-message operations of the GSSContext interface
1064     return these values in a MessageProp object.
1065  
1066     The MessageProp class defines query methods that return boolean
1067     values indicating the following supplementary states:
1068  
1069     Table: Supplementary Status Methods
1070  
1071     +------------------+------------------------------------------------+
1072     | Method Name      | Meaning when "true" is returned                |
1073     +------------------+------------------------------------------------+
1074     | isDuplicateToken | The token was a duplicate of an earlier token. |
1075     |                  |                                                |
1076     | isOldToken       | The token's validity period has expired.       |
1077     |                  |                                                |
1078     | isUnseqToken     | A later token has already been processed.      |
1079     |                  |                                                |
1080     | isGapToken       | An expected per-message token was not          |
1081     |                  | received.                                      |
1082     +------------------+------------------------------------------------+
1083  
1084     A "true" return value for any of the above methods indicates that the
1085     token exhibited the specified property.  The application MUST
1086     determine the appropriate course of action for these supplementary
1087     values.  They are not treated as errors by the GSS-API.
1088  
1089  5.13.  Names
1090  
1091     A name is used to identify a person or entity.  GSS-API authenticates
1092     the relationship between a name and the entity claiming the name.
1093  
1094     Since different authentication mechanisms may employ different
1095     namespaces for identifying their principals, GSS-API's naming support
1096     is necessarily complex in multi-mechanism environments (or even in
1097     some single-mechanism environments where the underlying mechanism
1098     supports multiple namespaces).
1099  
1100     Two distinct conceptual representations are defined for names:
1101  
1102     1) A GSS-API form represented by implementations of the GSSName
1103        interface: A single GSSName object MAY contain multiple names from
1104        different namespaces, but all names SHOULD refer to the same
1105        entity.  An example of such an internal name would be the name
1106        returned from a call to the getName method of the GSSCredential
1107        interface, when applied to a credential containing credential
1108        elements for multiple authentication mechanisms employing
1109        different namespaces.  This GSSName object will contain a distinct
1110        name for the entity for each authentication mechanism.
1111  
1112        For GSS-API implementations supporting multiple namespaces,
1113        GSSName implementations MUST contain sufficient information to
1114        determine the namespace to which each primitive name belongs.
1115  
1116     2) Mechanism-specific contiguous byte array and string forms:
1117        Different GSSName initialization methods are provided to handle
1118        both byte array and string formats and to accommodate various
1119        calling applications and name types.  These formats are capable of
1120        containing only a single name (from a single namespace).
1121        Contiguous string names are always accompanied by an object
1122        identifier specifying the namespace to which the name belongs, and
1123        their format is dependent on the authentication mechanism that
1124        employs that name.  The string name forms are assumed to be
1125        printable, and may therefore be used by GSS-API applications for
1126        communication with their users.  The byte array name formats are
1127        assumed to be in non-printable formats (e.g., the byte array
1128        returned from the export method of the GSSName interface).
1129  
1130     A GSSName object can be converted to a contiguous representation by
1131     using the toString method.  This will guarantee that the name will be
1132     converted to a printable format.  Different initialization methods in
1133     the GSSName interface are defined allowing support for multiple
1134     syntaxes for each supported namespace, and allowing users the freedom
1135     to choose a preferred name representation.  The toString method
1136     SHOULD use an implementation-chosen printable syntax for each
1137     supported name type.  To obtain the printable name type,
1138     getStringNameType method can be used.
1139  
1140     There is no guarantee that calling the toString method on the GSSName
1141     interface will produce the same string form as the original imported
1142     string name.  Furthermore, it is possible that the name was not even
1143     constructed from a string representation.  The same applies to
1144     namespace identifiers, which may not necessarily survive unchanged
1145     after a journey through the internal name form.  An example of this
1146     might be a mechanism that authenticates X.500 names, but provides an
1147     algorithmic mapping of Internet DNS names into X.500.  That
1148     mechanism's implementation of GSSName might, when presented with a
1149     DNS name, generate an internal name that contained both the original
1150     DNS name and the equivalent X.500 name.  Alternatively, it might only
1151     store the X.500 name.  In the latter case, the toString method of
1152     GSSName would most likely generate a printable X.500 name, rather
1153     than the original DNS name.
1154  
1155     The context acceptor can obtain a GSSName object representing the
1156     entity performing the context initiation (through the usage of
1157     getSrcName method).  Since this name has been authenticated by a
1158     single mechanism, it contains only a single name (even if the
1159     internal name presented by the context initiator to the GSSContext
1160     object had multiple components).  Such names are termed internal-
1161     mechanism names (or MNs), and the names emitted by GSSContext
1162     interface in the getSrcName and getTargName are always of this type.
1163     Since some applications may require MNs without wanting to incur the
1164     overhead of an authentication operation, creation methods are
1165     provided that take not only the name buffer and name type, but also
1166     the mechanism oid for which this name should be created.  When
1167     dealing with an existing GSSName object, the canonicalize method may
1168     be invoked to convert a general internal name into an MN.
1169  
1170     GSSName objects can be compared using their equal method, which
1171     returns "true" if the two names being compared refer to the same
1172     entity.  This is the preferred way to perform name comparisons
1173     instead of using the printable names that a given GSS-API
1174     implementation may support.  Since GSS-API assumes that all primitive
1175     names contained within a given internal name refer to the same
1176     entity, equal can return "true" if the two names have at least one
1177     primitive name in common.  If the implementation embodies knowledge
1178     of equivalence relationships between names taken from different
1179     namespaces, this knowledge may also allow successful comparisons of
1180     internal names containing no overlapping primitive elements.
1181     However, applications SHOULD note that to avoid surpising behavior,
1182     it is best to ensure that the names being compared are either both
1183     mechanism names for the same mechanism, or both internal names that
1184     are not mechanism names.  This holds whether the equals method is
1185     used directly, or the export method is used to generate byte strings
1186     that are then compared byte-by-byte.
1187  
1188     When used in large access control lists, the overhead of creating a
1189     GSSName object on each name and invoking the equal method on each
1190     name from the Access Control List (ACL) may be prohibitive.  As an
1191     alternative way of supporting this case, GSS-API defines a special
1192     form of the contiguous byte array name, which MAY be compared
1193     directly (byte by byte).  Contiguous names suitable for comparison
1194     are generated by the export method.  Exported names MAY be re-
1195     imported by using the byte array constructor and specifying the
1196     NT_EXPORT_NAME as the name type object identifier.  The resulting
1197     GSSName name will also be a MN.
1198  
1199     The GSSName interface defines public static Oid objects representing
1200     the standard name types.  Structurally, an exported name object
1201     consists of a header containing an OID identifying the mechanism that
1202     authenticated the name, and a trailer containing the name itself,
1203     where the syntax of the trailer is defined by the individual
1204     mechanism specification.  Detailed description of the format is
1205     specified in the language-independent GSS-API specification
1206     [RFC2743].
1207  
1208     Note that the results obtained by using the equals method will in
1209     general be different from those obtained by invoking canonicalize and
1210     export, and then comparing the byte array output.  The first series
1211     of operation determines whether two (unauthenticated) names identify
1212     the same principal; the second whether a particular mechanism would
1213     authenticate them as the same principal.  These two operations will
1214     in general give the same results only for MNs.
1215  
1216     It is important to note that the above are guidelines as to how
1217     GSSName implementations SHOULD behave, and are not intended to be
1218     specific requirements of how name objects must be implemented.  The
1219     mechanism designers are free to decide on the details of their
1220     implementations of the GSSName interface as long as the behavior
1221     satisfies the above guidelines.
1222  
1223  5.14.  Channel Bindings
1224  
1225     GSS-API supports the use of user-specified tags to identify a given
1226     context to the peer application.  These tags are intended to be used
1227     to identify the particular communications channel that carries the
1228     context.  Channel bindings are communicated to the GSS-API using the
1229     ChannelBinding object.  The application MAY use byte arrays to
1230     specify the application data to be used in the channel binding as
1231     well as using instances of the InetAddress.  The InetAddress for the
1232     initiator and/or acceptor can be used within an instance of a
1233     ChannelBinding.  ChannelBinding can be set for the GSSContext object
1234     using the setChannelBinding method before the first call to init or
1235     accept has been performed.  Unless the setChannelBinding method has
1236     been used to set the ChannelBinding for a GSSContext object, "null"
1237     ChannelBinding will be assumed.  InetAddress is currently the only
1238     address type defined within the Java platform and as such, it is the
1239     only one supported within the ChannelBinding class.  Applications
1240     that use other types of addresses can include them as part of the
1241     application-specific data.
1242  
1243     Conceptually, the GSS-API concatenates the initiator and acceptor
1244     address information, and the application-supplied byte array to form
1245     an octet-string.  The mechanism calculates a Message Integrity Code
1246     (MIC) over this octet-string and binds the MIC to the context
1247     establishment token emitted by the init method of the GSSContext
1248     interface.  The same bindings are set by the context acceptor for its
1249     GSSContext object and during processing of the accept method, a MIC
1250     is calculated in the same way.  The calculated MIC is compared with
1251     that found in the token, and if the MICs differ, accept will throw a
1252     GSSException with the major code set to BAD_BINDINGS, and the context
1253     will not be established.  Some mechanisms may include the actual
1254     channel binding data in the token (rather than just a MIC);
1255     applications SHOULD therefore not use confidential data as channel-
1256     binding components.
1257  
1258     Individual mechanisms may impose additional constraints on addresses
1259     that may appear in channel bindings.  For example, a mechanism may
1260     verify that the initiator address field of the channel binding
1261     contains the correct network address of the host system.  Portable
1262     applications SHOULD therefore ensure that they either provide correct
1263     information for the address fields, or omit the setting of the
1264     addressing information.
1265  
1266  5.15.  Optional Parameters
1267  
1268     Whenever the application wishes to omit an optional parameter the
1269     "null" value SHALL be used.  The detailed method descriptions
1270     indicate which parameters are optional.  Method overloading has also
1271     been used as a technique to indicate default parameters.
1272  
1273  6.  Introduction to GSS-API Classes and Interfaces
1274  
1275     This section presents a brief description of the classes and
1276     interfaces that constitute the GSS-API.  The implementations of these
1277     are obtained from the CLASSPATH defined by the application.  If Java
1278     GSS becomes part of the standard Java APIs, then these classes will
1279     be available by default on all systems as part of the JRE's system
1280     classes.
1281  
1282     This section also shows the corresponding RFC 2743 [RFC2743]
1283     functionality implemented by each of the classes.  Detailed
1284     description of these classes and their methods is presented in
1285     section 7
1286  
1287  6.1.  GSSManager Class
1288  
1289     This abstract class serves as a factory to instantiate
1290     implementations of the GSS-API interfaces and also provides methods
1291     to make queries about underlying security mechanisms.
1292  
1293     A default implementation can be obtained using the static method
1294     getInstance().  Applications that desire to provide their own
1295     implementation of the GSSManager class can simply extend the abstract
1296     class themselves.
1297  
1298     This class contains equivalents of the following RFC 2743 [RFC2743]
1299     routines:
1300  
1301     +----------------------------+-------------------------+------------+
1302     | RFC 2743 Routine           | Function                | Section(s) |
1303     +----------------------------+-------------------------+------------+
1304     | gss_import_name            | Create an internal name | 7.1.5 -    |
1305     |                            | from the supplied       | 7.1.8      |
1306     |                            | information.            |            |
1307     |                            |                         |            |
1308     | gss_acquire_cred           | Acquire credential for  | 7.1.9 -    |
1309     |                            | use.                    | 7.1.11     |
1310     |                            |                         |            |
1311     | gss_import_sec_context     | Create a previously     | 7.1.14     |
1312     |                            | exported context.       |            |
1313     |                            |                         |            |
1314     | gss_indicate_mechs         | List the mechanisms     | 7.1.2      |
1315     |                            | supported by this GSS-  |            |
1316     |                            | API implementation.     |            |
1317     |                            |                         |            |
1318     | gss_inquire_mechs_for_name | List the mechanisms     | 7.1.4      |
1319     |                            | supporting the          |            |
1320     |                            | specified name type.    |            |
1321     |                            |                         |            |
1322     | gss_inquire_names_for_mech | List the name types     | 7.1.3      |
1323     |                            | supported by the        |            |
1324     |                            | specified mechanism.    |            |
1325     +----------------------------+-------------------------+------------+
1326  
1327  6.2.  GSSName Interface
1328  
1329     GSS-API names are represented in the Java bindings through the
1330     GSSName interface.  Different name formats and their definitions are
1331     identified with Universal Object Identifiers (oids).  The format of
1332     the names can be derived based on the unique oid of each name type.
1333     The following GSS-API routines are provided by the GSSName interface:
1334  
1335     +-----------------------+------------------------------+------------+
1336     | RFC 2743 Routine      | Function                     | Section(s) |
1337     +-----------------------+------------------------------+------------+
1338     | gss_display_name      | Convert internal name        | 7.2.6      |
1339     |                       | representation to text       |            |
1340     |                       | format.                      |            |
1341     |                       |                              |            |
1342     | gss_compare_name      | Compare two internal names.  | 7.2.2,     |
1343     |                       |                              | 7.2.3      |
1344     |                       |                              |            |
1345     | gss_release_name      | Release resources associated | N/A        |
1346     |                       | with the internal name.      |            |
1347     |                       |                              |            |
1348     | gss_canonicalize_name | Convert an internal name to  | 7.2.4      |
1349     |                       | a mechanism name.            |            |
1350     |                       |                              |            |
1351     | gss_export_name       | Convert a mechanism name to  | 7.2.5      |
1352     |                       | export format.               |            |
1353     |                       |                              |            |
1354     | gss_duplicate_name    | Create a copy of the         | N/A        |
1355     |                       | internal name.               |            |
1356     +-----------------------+------------------------------+------------+
1357  
1358     The gss_release_name call is not provided as Java does its own
1359     garbage collection.  The gss_duplicate_name call is also redundant;
1360     the GSSName interface has no mutator methods that can change the
1361     state of the object so it is safe for sharing across threads.
1362  
1363  6.3.  GSSCredential Interface
1364  
1365     The GSSCredential interface is responsible for the encapsulation of
1366     GSS-API credentials.  Credentials identify a single entity and
1367     provide the necessary cryptographic information to enable the
1368     creation of a context on behalf of that entity.  A single credential
1369     may contain multiple mechanism-specific credentials, each referred to
1370     as a credential element.  The GSSCredential interface provides the
1371     functionality of the following GSS-API routines:
1372  
1373     +--------------------------+---------------------------+------------+
1374     | RFC 2743 Routine         | Function                  | Section(s) |
1375     +--------------------------+---------------------------+------------+
1376     | gss_add_cred             | Constructs credentials    | 7.3.11     |
1377     |                          | incrementally.            |            |
1378     |                          |                           |            |
1379     | gss_inquire_cred         | Obtain information about  | 7.3.3 -    |
1380     |                          | credential.               | 7.3.10     |
1381     |                          |                           |            |
1382     | gss_inquire_cred_by_mech | Obtain per-mechanism      | 7.3.4 -    |
1383     |                          | information about a       | 7.3.9      |
1384     |                          | credential.               |            |
1385     |                          |                           |            |
1386     | gss_release_cred         | Dispose of credentials    | 7.3.2      |
1387     |                          | after use.                |            |
1388     +--------------------------+---------------------------+------------+
1389  
1390  6.4.  GSSContext Interface
1391  
1392     This interface encapsulates the functionality of context-level calls
1393     required for security context establishment and management between
1394     peers as well as the per-message services offered to applications.  A
1395     context is established between a pair of peers and allows the usage
1396     of security services on a per-message basis on application data.  It
1397     is created over a single security mechanism.  The GSSContext
1398     interface provides the functionality of the following GSS-API
1399     routines:
1400  
1401     +------------------------+-----------------------------+------------+
1402     | RFC 2743 Routine       | Function                    | Section(s) |
1403     +------------------------+-----------------------------+------------+
1404     | gss_init_sec_context   | Initiate the creation of a  | 7.4.2      |
1405     |                        | security context with a     |            |
1406     |                        | peer.                       |            |
1407     |                        |                             |            |
1408     | gss_accept_sec_context | Accept a security context   | 7.4.3      |
1409     |                        | initiated by a peer.        |            |
1410     |                        |                             |            |
1411     | gss_delete_sec_context | Destroy a security context. | 7.4.5      |
1412     |                        |                             |            |
1413     | gss_context_time       | Obtain remaining context    | 7.4.30     |
1414     |                        | time.                       |            |
1415     |                        |                             |            |
1416     | gss_inquire_context    | Obtain context              | 7.4.21 -   |
1417     |                        | characteristics.            | 7.4.35     |
1418     |                        |                             |            |
1419     | gss_wrap_size_limit    | Determine token-size limit  | 7.4.6      |
1420     |                        | for gss_wrap.               |            |
1421     |                        |                             |            |
1422     | gss_export_sec_context | Transfer security context   | 7.4.11     |
1423     |                        | to another process.         |            |
1424     |                        |                             |            |
1425     | gss_get_mic            | Calculate a cryptographic   | 7.4.9      |
1426     |                        | Message Integrity Code      |            |
1427     |                        | (MIC) for a message.        |            |
1428     |                        |                             |            |
1429     | gss_verify_mic         | Verify integrity on a       | 7.4.10     |
1430     |                        | received message.           |            |
1431     |                        |                             |            |
1432     | gss_wrap               | Attach a MIC to a message   | 7.4.7      |
1433     |                        | and optionally encrypt the  |            |
1434     |                        | message content.            |            |
1435     |                        |                             |            |
1436     | gss_unwrap             | Obtain a previously wrapped | 7.4.8      |
1437     |                        | application message         |            |
1438     |                        | verifying its integrity and |            |
1439     |                        | optionally decrypting it.   |            |
1440     +------------------------+-----------------------------+------------+
1441  
1442     The functionality offered by the gss_process_context_token routine
1443     has not been included in the Java bindings specification.  The
1444     corresponding functionality of gss_delete_sec_context has also been
1445     modified to not return any peer tokens.  This has been proposed in
1446     accordance to the recommendations stated in RFC 2743 [RFC2743].
1447     GSSContext does offer the functionality of destroying the locally
1448     stored context information.
1449  
1450  6.5.  MessageProp Class
1451  
1452     This helper class is used in the per-message operations on the
1453     context.  An instance of this class is created by the application and
1454     then passed into the per-message calls.  In some cases, the
1455     application conveys information to the GSS-API implementation through
1456     this object and in other cases the GSS-API returns information to the
1457     application by setting it in this object.  See the description of the
1458     per-message operations wrap, unwrap, getMIC, and verifyMIC in the
1459     GSSContext interfaces for details.
1460  
1461  6.6.  GSSException Class
1462  
1463     Exceptions are used in the Java bindings to signal fatal errors to
1464     the calling applications.  This replaces the major and minor codes
1465     used in the C-bindings specification as a method of signaling
1466     failures.  The GSSException class handles both minor and major codes,
1467     as well as their translation into textual representation.  All GSS-
1468     API methods are declared as throwing this exception.
1469  
1470     +--------------------+----------------------------+-----------------+
1471     | RFC 2743 Routine   | Function                   | Section         |
1472     +--------------------+----------------------------+-----------------+
1473     | gss_display_status | Retrieve textual           | 7.8.5, 7.8.6,   |
1474     |                    | representation of error    | 7.8.9, 7.8.10   |
1475     |                    | codes.                     |                 |
1476     +--------------------+----------------------------+-----------------+
1477  
1478  6.7.  Oid Class
1479  
1480     This utility class is used to represent Universal Object Identifiers
1481     and their associated operations.  GSS-API uses object identifiers to
1482     distinguish between security mechanisms and name types.  This class,
1483     aside from being used whenever an object identifier is needed,
1484     implements the following GSS-API functionality:
1485  
1486     +-------------------------+-------------------------------+---------+
1487     | RFC 2743 Routine        | Function                      | Section |
1488     +-------------------------+-------------------------------+---------+
1489     | gss_test_oid_set_member | Determine if the specified    | 7.7.5   |
1490     |                         | oid is part of a set of oids. |         |
1491     +-------------------------+-------------------------------+---------+
1492  
1493  6.8.  ChannelBinding Class
1494  
1495     An instance of this class is used to specify channel binding
1496     information to the GSSContext object before the start of a security
1497     context establishment.  The application may use a byte array to
1498     specify application data to be used in the channel binding as well as
1499     to use instances of the InetAddress.  InetAddress is currently the
1500     only address type defined within the Java platform and as such, it is
1501     the only one supported within the ChannelBinding class.  Applications
1502     that use other types of addresses can include them as part of the
1503     application data.
1504  
1505  7.  Detailed GSS-API Class Description
1506  
1507     This section lists a detailed description of all the public methods
1508     that each of the GSS-API classes and interfaces MUST provide.
1509  
1510  7.1.  public abstract class GSSManager
1511  
1512     The GSSManager class is an abstract class that serves as a factory
1513     for three GSS interfaces: GSSName, GSSCredential, and GSSContext.  It
1514     also provides methods for applications to determine what mechanisms
1515     are available from the GSS implementation and what name types these
1516     mechanisms support.  An instance of the default GSSManager subclass
1517     MAY be obtained through the static method getInstance(), but
1518     applications are free to instantiate other subclasses of GSSManager.
1519  
1520     All but one method in this class are declared abstract.  This means
1521     that subclasses have to provide the complete implementation for those
1522     methods.  The only exception to this is the static method
1523     getInstance(), which will have platform-specific code to return an
1524     instance of the default subclass.
1525  
1526     Platform providers of GSS are REQUIRED not to add any constructors to
1527     this class, private, public, or protected.  This will ensure that all
1528     subclasses invoke only the default constructor provided to the base
1529     class by the compiler.
1530  
1531     A subclass extending the GSSManager abstract class MAY be implemented
1532     as a modular provider-based layer that utilizes some well-known
1533     service provider specification.  The GSSManager API provides the
1534     application with methods to set provider preferences on such an
1535     implementation.  These methods also allow the implementation to throw
1536     a well-defined exception in case provider-based configuration is not
1537     supported.  Applications that expect to be portable SHOULD be aware
1538     of this and recover cleanly by catching the exception.
1539  
1540     It is envisioned that there will be three most common ways in which
1541     providers will be used:
1542  
1543     1) The application does not care about what provider is used (the
1544        default case).
1545  
1546     2) The application wants a particular provider to be used
1547        preferentially, either for a particular mechanism or all the time,
1548        irrespective of the mechanism.
1549  
1550     3) The application wants to use the locally configured providers as
1551        far as possible, but if support is missing for one or more
1552        mechanisms, then it wants to fall back on its own provider.
1553  
1554     The GSSManager class has two methods that enable these modes of
1555     usage: addProviderAtFront() and addProviderAtEnd().  These methods
1556     have the effect of creating an ordered list of <provider, oid> pairs
1557     where each pair indicates a preference of provider for a given oid.
1558  
1559     The use of these methods does not require any knowledge of whatever
1560     service provider specification the GSSManager subclass follows.  It
1561     is hoped that these methods will serve the needs of most
1562     applications.  Additional methods MAY be added to an extended
1563     GSSManager that could be part of a service provider specification
1564     that is standardized later.
1565  
1566     When neither of the methods is called, the implementation SHOULD
1567     choose a default provider for each mechanism it supports.
1568  
1569  7.1.1.  getInstance
1570  
1571     public static GSSManager getInstance()
1572  
1573     Returns the default GSSManager implementation.
1574  
1575  7.1.2.  getMechs
1576  
1577     public abstract Oid[] getMechs()
1578  
1579     Returns an array of Oid objects indicating the mechanisms available
1580     to GSS-API callers.  A "null" value is returned when no mechanism are
1581     available (an example of this would be when mechanism are dynamically
1582     configured, and currently no mechanisms are installed).
1583  
1584  7.1.3.  getNamesForMech
1585  
1586     public abstract Oid[] getNamesForMech(Oid mech)
1587                           throws GSSException
1588  
1589     Returns name type Oid's supported by the specified mechanism.
1590  
1591     Parameters:
1592  
1593     mech                The Oid object for the mechanism to query.
1594  
1595  7.1.4.  getMechsForName
1596  
1597     public abstract Oid[] getMechsForName(Oid nameType)
1598  
1599     Returns an array of Oid objects corresponding to the mechanisms that
1600     support the specific name type. "null" is returned when no mechanisms
1601     are found to support the specified name type.
1602  
1603     Parameters:
1604  
1605     nameType            The Oid object for the name type.
1606  
1607  7.1.5.  createName
1608  
1609     public abstract GSSName createName(String nameStr, Oid nameType)
1610                     throws GSSException
1611  
1612     Factory method to convert a contiguous string name from the specified
1613     namespace to a GSSName object.  In general, the GSSName object
1614     created will not be an MN; two examples that are exceptions to this
1615     are when the namespace type parameter indicates NT_EXPORT_NAME or
1616     when the GSS-API implementation is not multi-mechanism.
1617  
1618     Parameters:
1619  
1620     nameStr             The string representing a printable form of the
1621                         name to create.
1622  
1623     nameType            The Oid specifying the namespace of the printable
1624                         name is supplied.  Note that nameType serves to
1625                         describe and qualify the interpretation of the
1626                         input nameStr, it does not necessarily imply a
1627                         type for the output GSSName implementation.  The
1628                         "null" value can be used to specify that a
1629                         mechanism-specific default printable syntax
1630                         SHOULD be assumed by each mechanism that examines
1631                         nameStr.
1632  
1633  7.1.6.  createName
1634  
1635     public abstract GSSName createName(byte[] name, Oid nameType)
1636                     throws GSSException
1637  
1638     Factory method to convert a contiguous byte array containing a name
1639     from the specified namespace to a GSSName object.  In general, the
1640     GSSName object created will not be an MN; two examples that are
1641     exceptions to this are when the namespace type parameter indicates
1642     NT_EXPORT_NAME or when the GSS-API implementation is not multi-
1643     mechanism.
1644  
1645     Parameters:
1646  
1647     name                The byte array containing the name to create.
1648  
1649     nameType            The Oid specifying the namespace of the name
1650                         supplied in the byte array.  Note that nameType
1651                         serves to describe and qualify the interpretation
1652                         of the input name byte array; it does not
1653                         necessarily imply a type for the output GSSName
1654                         implementation.  The "null" value can be used to
1655                         specify that a mechanism-specific default syntax
1656                         SHOULD be assumed by each mechanism that examines
1657                         the byte array.
1658  
1659  7.1.7.  createName
1660  
1661     public abstract GSSName createName(String nameStr, Oid nameType,
1662                     Oid mech) throws GSSException
1663  
1664     Factory method to convert a contiguous string name from the specified
1665     namespace to a GSSName object that is a mechanism name (MN).  In
1666     other words, this method is a utility that does the equivalent of two
1667     steps: the createName described in section 7.1.5, and then also the
1668     GSSName.canonicalize() described in section 7.2.4.
1669  
1670     Parameters:
1671  
1672     nameStr             The string representing a printable form of the
1673                         name to create.
1674  
1675     nameType            The Oid specifying the namespace of the printable
1676                         name supplied.  Note that nameType serves to
1677                         describe and qualify the interpretation of the
1678                         input nameStr; it does not necessarily imply a
1679                         type for the output GSSName implementation.  The
1680                         "null" value can be used to specify that a
1681                         mechanism-specific default printable syntax
1682                         SHOULD be assumed when the mechanism examines
1683                         nameStr.
1684  
1685     mech                Oid specifying the mechanism for which this name
1686                         should be created.
1687  
1688  7.1.8.  createName
1689  
1690     public abstract GSSName createName(byte[] name, Oid nameType,
1691                     Oid mech) throws GSSException
1692  
1693     Factory method to convert a contiguous byte array containing a name
1694     from the specified namespace to a GSSName object that is an MN.  In
1695     other words, this method is a utility that does the equivalent of two
1696     steps: the createName described in section 7.1.6, and then also the
1697     GSSName.canonicalize() described in section 7.2.4.
1698  
1699     Parameters:
1700  
1701     name                The byte array representing the name to create.
1702  
1703     nameType            The Oid specifying the namespace of the name
1704                         supplied in the byte array.  Note that nameType
1705                         serves to describe and qualify the interpretation
1706                         of the input name byte array, it does not
1707                         necessarily imply a type for the output GSSName
1708                         implementation.  The "null" value can be used to
1709                         specify that a mechanism-specific default syntax
1710                         SHOULD be assumed by each mechanism that examines
1711                         the byte array.
1712  
1713     mech                Oid specifying the mechanism for which this name
1714                         should be created.
1715  
1716  7.1.9.  createCredential
1717  
1718     public abstract GSSCredential createCredential(int usage)
1719                     throws GSSException
1720  
1721     Factory method for acquiring default credentials.  This will cause
1722     the GSS-API to use system-specific defaults for the set of
1723     mechanisms, name, and a DEFAULT lifetime.
1724  
1725     Parameters:
1726  
1727     usage               The intended usage for this credential object.
1728                         The value of this parameter MUST be one of:
1729  
1730                         GSSCredential.INITIATE_AND_ACCEPT(0),
1731                         GSSCredential.INITIATE_ONLY(1), or
1732                         GSSCredential.ACCEPT_ONLY(2)
1733  
1734  7.1.10.  createCredential
1735  
1736     public abstract GSSCredential createCredential(GSSName aName,
1737                     int lifetime, Oid mech, int usage)
1738                     throws GSSException
1739  
1740     Factory method for acquiring a single mechanism credential.
1741  
1742     Parameters:
1743  
1744     aName               Name of the principal for whom this credential is
1745                         to be acquired.  Use "null" to specify the
1746                         default principal.
1747  
1748     lifetime            The number of seconds that credentials should
1749                         remain valid.  Use
1750                         GSSCredential.INDEFINITE_LIFETIME to request that
1751                         the credentials have the maximum permitted
1752                         lifetime.  Use GSSCredential.DEFAULT_LIFETIME to
1753                         request default credential lifetime.
1754  
1755     mech                The oid of the desired mechanism.  Use "(Oid)
1756                         null" to request the default mechanism(s).
1757  
1758     usage               The intended usage for this credential object.
1759                         The value of this parameter MUST be one of:
1760  
1761                         GSSCredential.INITIATE_AND_ACCEPT(0),
1762                         GSSCredential.INITIATE_ONLY(1), or
1763                         GSSCredential.ACCEPT_ONLY(2)
1764  
1765  7.1.11.  createCredential
1766  
1767     public abstract GSSCredential createCredential(GSSName aName,
1768                     int lifetime, Oid[] mechs, int usage)
1769                     throws GSSException
1770  
1771     Factory method for acquiring credentials over a set of mechanisms.
1772     Acquires credentials for each of the mechanisms specified in the
1773     array called mechs.  To determine the list of mechanisms' for which
1774     the acquisition of credentials succeeded, the caller should use the
1775     GSSCredential.getMechs() method.
1776  
1777     Parameters:
1778  
1779     aName               Name of the principal for whom this credential is
1780                         to be acquired.  Use "null" to specify the
1781                         default principal.
1782  
1783     lifetime            The number of seconds that credentials should
1784                         remain valid.  Use
1785                         GSSCredential.INDEFINITE_LIFETIME to request that
1786                         the credentials have the maximum permitted
1787                         lifetime.  Use GSSCredential.DEFAULT_LIFETIME to
1788                         request default credential lifetime.
1789  
1790     mechs               The array of mechanisms over which the credential
1791                         is to be acquired.  Use "(Oid[]) null" for
1792                         requesting a system-specific default set of
1793                         mechanisms.
1794  
1795     usage               The intended usage for this credential object.
1796                         The value of this parameter MUST be one of:
1797  
1798                         GSSCredential.INITIATE_AND_ACCEPT(0),
1799                         GSSCredential.INITIATE_ONLY(1), or
1800                         GSSCredential.ACCEPT_ONLY(2)
1801  
1802  7.1.12.  createContext
1803  
1804     public abstract GSSContext createContext(GSSName peer, Oid mech,
1805                     GSSCredential myCred, int lifetime)
1806                     throws GSSException
1807  
1808     Factory method for creating a context on the initiator's side.
1809     Context flags may be modified through the mutator methods prior to
1810     calling GSSContext.initSecContext().
1811  
1812     Parameters:
1813  
1814     peer                Name of the target peer.
1815  
1816     mech                Oid of the desired mechanism.  Use "(Oid) null"
1817                         to request the default mechanism.
1818  
1819     myCred              Credentials of the initiator.  Use "null" to act
1820                         as a default initiator principal.
1821  
1822     lifetime            The request lifetime, in seconds, for the
1823                         context.  Use GSSContext.INDEFINITE_LIFETIME and
1824                         GSSContext.DEFAULT_LIFETIME to request indefinite
1825                         or default context lifetime.
1826  
1827  7.1.13.  createContext
1828  
1829     public abstract GSSContext createContext(GSSCredential myCred)
1830                     throws GSSException
1831  
1832     Factory method for creating a context on the acceptor' side.  The
1833     context's properties will be determined from the input token supplied
1834     to the accept method.
1835  
1836     Parameters:
1837  
1838     myCred              Credentials for the acceptor.  Use "null" to act
1839                         as a default acceptor principal.
1840  
1841  7.1.14.  createContext
1842  
1843     public abstract GSSContext createContext(byte[] interProcessToken)
1844                     throws GSSException
1845  
1846     Factory method for importing a previously exported context.  The
1847     context properties will be determined from the input token and can't
1848     be modified through the set methods.
1849  
1850     Parameters:
1851  
1852     interProcessToken   The token previously emitted from the export
1853                         method.
1854  
1855  7.1.15.  addProviderAtFront
1856  
1857     public abstract void addProviderAtFront(Provider p, Oid mech)
1858                     throws GSSException
1859  
1860     This method is used to indicate to the GSSManager that the
1861     application would like a particular provider to be used ahead of all
1862     others when support is desired for the given mechanism.  When a value
1863     of "null" is used instead of an Oid for the mechanism, the GSSManager
1864     MUST use the indicated provider ahead of all others no matter what
1865     the mechanism is.  Only when the indicated provider does not support
1866     the needed mechanism should the GSSManager move on to a different
1867     provider.
1868  
1869     Calling this method repeatedly preserves the older settings but
1870     lowers them in preference thus forming an ordered list of provider
1871     and Oid pairs that grows at the top.
1872  
1873     Calling addProviderAtFront with a null Oid will remove all previous
1874     preferences that were set for this provider in the GSSManager
1875     instance.  Calling addProviderAtFront with a non-null Oid will remove
1876     any previous preference that was set using this mechanism and this
1877     provider together.
1878  
1879     If the GSSManager implementation does not support an SPI with a
1880     pluggable provider architecture, it SHOULD throw a GSSException with
1881     the status code GSSException.UNAVAILABLE to indicate that the
1882     operation is unavailable.
1883  
1884     Parameters:
1885  
1886     p                   The provider instance that should be used
1887                         whenever support is needed for mech.
1888  
1889     mech                The mechanism for which the provider is being
1890                         set.
1891  
1892  7.1.15.1.  addProviderAtFront Example Code
1893  
1894     Suppose an application desired that the provider A always be checked
1895     first when any mechanism is needed, it would call:
1896  
1897     <CODE BEGINS>
1898     GSSManager mgr = GSSManager.getInstance();
1899     // mgr may at this point have its own pre-configured list
1900     // of provider preferences.  The following will prepend to
1901     // any such list:
1902  
1903     mgr.addProviderAtFront(A, null);
1904     <CODE ENDS>
1905  
1906     Now if it also desired that the mechanism of Oid m1 always be
1907     obtained from the provider B before the previously set A was checked,
1908     it would call:
1909  
1910     <CODE BEGINS>
1911     mgr.addProviderAtFront(B, m1);
1912     <CODE ENDS>
1913  
1914     The GSSManager would then first check with B if m1 was needed.  In
1915     case B did not provide support for m1, the GSSManager would continue
1916     on to check with A.  If any mechanism m2 is needed where m2 is
1917     different from m1, then the GSSManager would skip B and check with A
1918     directly.
1919  
1920     Suppose, at a later time, the following call is made to the same
1921     GSSManager instance:
1922  
1923     <CODE BEGINS>
1924     mgr.addProviderAtFront(B, null)
1925     <CODE ENDS>
1926  
1927     then the previous setting with the pair (B, m1) is subsumed by this
1928     and SHOULD be removed.  Effectively, the list of preferences now
1929     becomes {(B, null), (A, null), ... //followed by the pre-configured
1930     list}.
1931  
1932     Please note, however, that the following call:
1933  
1934     <CODE BEGINS>
1935     mgr.addProviderAtFront(A, m3)
1936     <CODE ENDS>
1937  
1938     does not subsume the previous setting of (A, null), and the list will
1939     effectively become {(A, m3), (B, null), (A, null), ...}
1940  
1941  7.1.16.  addProviderAtEnd
1942  
1943     public abstract void addProviderAtEnd(Provider p, Oid mech)
1944                     throws GSSException
1945  
1946     This method is used to indicate to the GSSManager that the
1947     application would like a particular provider to be used if no other
1948     provider can be found that supports the given mechanism.  When a
1949     value of "null" is used instead of an Oid for the mechanism, the
1950     GSSManager MUST use the indicated provider for any mechanism.
1951  
1952     Calling this method repeatedly preserves the older settings, but
1953     raises them above newer ones in preference thus forming an ordered
1954     list of providers and Oid pairs that grows at the bottom.  Thus, the
1955     older provider settings will be utilized first before this one is.
1956  
1957     If there are any previously existing preferences that conflict with
1958     the preference being set here, then the GSSManager SHOULD ignore this
1959     request.
1960  
1961     If the GSSManager implementation does not support an SPI with a
1962     pluggable provider architecture, it SHOULD throw a GSSException with
1963     the status code GSSException.UNAVAILABLE to indicate that the
1964     operation is unavailable.
1965  
1966     Parameters:
1967  
1968     p                   The provider instance that should be used
1969                         whenever support is needed for mech.
1970  
1971     mech                The mechanism for which the provider is being
1972                         set.
1973  
1974  7.1.16.1.  addProviderAtEnd Example Code
1975  
1976     Suppose an application desired that when a mechanism of Oid m1 is
1977     needed, the system default providers always be checked first, and
1978     only when they do not support m1 should a provider A be checked.  It
1979     would then make the call:
1980  
1981     <CODE BEGINS>
1982     GSSManager mgr = GSSManager.getInstance();
1983  
1984     mgr.addProviderAtEnd(A, m1);
1985     <CODE ENDS>
1986  
1987     Now, if it also desired that for all mechanisms the provider B be
1988     checked after all configured providers have been checked, it would
1989     then call:
1990  
1991     <CODE BEGINS>
1992     mgr.addProviderAtEnd(B, null);
1993     <CODE ENDS>
1994  
1995     Effectively, the list of preferences now becomes {..., (A, m1), (B,
1996     null)}.
1997  
1998     Suppose, at a later time, the following call is made to the same
1999     GSSManager instance:
2000  
2001     <CODE BEGINS>
2002     mgr.addProviderAtEnd(B, m2)
2003     <CODE ENDS>
2004  
2005     then the previous setting with the pair (B, null) subsumes this;
2006     therefore, this request SHOULD be ignored.  The same would happen if
2007     a request is made for the already existing pairs of (A, m1) or (B,
2008     null).
2009  
2010     Please note, however, that the following call:
2011  
2012     <CODE BEGINS>
2013     mgr.addProviderAtEnd(A, null)
2014     <CODE ENDS>
2015  
2016     is not subsumed by the previous setting of (A, m1) and the list will
2017     effectively become {..., (A, m1), (B, null), (A, null)}.
2018  
2019  7.1.17.  Example Code
2020  
2021     <CODE BEGINS>
2022     GSSManager mgr = GSSManager.getInstance();
2023  
2024     // What mechs are available to us?
2025  
2026     Oid[] supportedMechs = mgr.getMechs();
2027  
2028     // Set a preference for the provider to be used when support
2029     // is needed for the mechanisms:
2030     //  "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1".
2031  
2032     Oid krb = new Oid("1.2.840.113554.1.2.2");
2033     Oid spkm1 = new Oid("1.3.6.1.5.5.1.1");
2034  
2035     Provider p = (Provider) (new com.foo.security.Provider());
2036  
2037     mgr.addProviderAtFront(p, krb);
2038     mgr.addProviderAtFront(p, spkm1);
2039  
2040     // What name types does this spkm implementation support?
2041     Oid[] nameTypes = mgr.getNamesForMech(spkm1);
2042     <CODE ENDS>
2043  
2044  7.2.  public interface GSSName
2045  
2046     This interface encapsulates a single GSS-API principal entity.
2047     Different name formats and their definitions are identified with
2048     Universal Object Identifiers (Oids).  The format of the names can be
2049     derived based on the unique oid of its namespace type.
2050  
2051  7.2.1.  Static Constants
2052  
2053     public static final Oid NT_HOSTBASED_SERVICE
2054  
2055     Oid indicating a host-based service name form.  It is used to
2056     represent services associated with host computers.  This name form is
2057     constructed using two elements, "service" and "hostname", as follows:
2058  
2059        service@hostname
2060  
2061     Values for the "service" element are registered with the IANA.  It
2062     represents the following value: { iso(1) member-body(2) Unites
2063     States(840) mit(113554) infosys(1) gssapi(2) generic(1)
2064     service_name(4) }
2065  
2066     public static final Oid NT_USER_NAME
2067  
2068     Name type to indicate a named user on a local system.  It represents
2069     the following value: { iso(1) member-body(2) United States(840)
2070     mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) }
2071  
2072     public static final Oid NT_MACHINE_UID_NAME
2073  
2074     Name type to indicate a numeric user identifier corresponding to a
2075     user on a local system (e.g., Uid).  It represents the following
2076     value: { iso(1) member-body(2) United States(840) mit(113554)
2077     infosys(1) gssapi(2) generic(1) machine_uid_name(2) }
2078  
2079     public static final Oid NT_STRING_UID_NAME
2080  
2081     Name type to indicate a string of digits representing the numeric
2082     user identifier of a user on a local system.  It represents the
2083     following value: { iso(1) member-body(2) United States(840)
2084     mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) }
2085  
2086     public static final Oid NT_ANONYMOUS
2087  
2088     Name type for representing an anonymous entity.  It represents the
2089     following value: { iso(1), org(3), dod(6), internet(1), security(5),
2090     nametypes(6), gss-anonymous-name(3) }
2091  
2092     public static final Oid NT_EXPORT_NAME
2093  
2094     Name type used to indicate an exported name produced by the export
2095     method.  It represents the following value: { iso(1), org(3), dod(6),
2096     internet(1), security(5), nametypes(6), gss-api-exported-name(4) }
2097  
2098  7.2.2.  equals
2099  
2100     public boolean equals(GSSName another) throws GSSException
2101  
2102     Compares two GSSName objects to determine whether they refer to the
2103     same entity.  This method MAY throw a GSSException when the names
2104     cannot be compared.  If either of the names represents an anonymous
2105     entity, the method will return "false".
2106  
2107     Parameters:
2108  
2109     another             GSSName object with which to compare.
2110  
2111  7.2.3.  equals
2112  
2113     public boolean equals(Object another)
2114  
2115     A variation of the equals method, described in section 7.2.2, that is
2116     provided to override the Object.equals() method that the implementing
2117     class will inherit.  The behavior is exactly the same as that in
2118     section 7.2.2 except that no GSSException is thrown; instead, "false"
2119     will be returned in the situation where an error occurs.  (Note that
2120     the Java language specification requires that two objects that are
2121     equal according to the equals(Object) method MUST return the same
2122     integer result when the hashCode() method is called on them.)
2123  
2124     Parameters:
2125  
2126     another             GSSName object with which to compare.
2127  
2128  7.2.4.  canonicalize
2129  
2130     public GSSName canonicalize(Oid mech) throws GSSException
2131  
2132     Creates a mechanism name (MN) from an arbitrary internal name.  This
2133     is equivalent to using the factory methods described in sections
2134     7.1.7 or 7.1.8 that take the mechanism name as one of their
2135     parameters.
2136  
2137     Parameters:
2138  
2139     mech                The oid for the mechanism for which the canonical
2140                         form of the name is requested.
2141  
2142  7.2.5.  export
2143  
2144     public byte[] export() throws GSSException
2145  
2146     Returns a canonical contiguous byte representation of a mechanism
2147     name (MN), suitable for direct, byte-by-byte comparison by
2148     authorization functions.  If the name is not an MN, implementations
2149     MAY throw a GSSException with the NAME_NOT_MN status code.  If an
2150     implementation chooses not to throw an exception, it SHOULD use some
2151     system-specific default mechanism to canonicalize the name and then
2152     export it.  The format of the header of the output buffer is
2153     specified in RFC 2743 [RFC2743].
2154  
2155  7.2.6.  toString
2156  
2157     public String toString()
2158  
2159     Returns a textual representation of the GSSName object.  To retrieve
2160     the printed name format, which determines the syntax of the returned
2161     string, the getStringNameType method can be used.
2162  
2163  7.2.7.  getStringNameType
2164  
2165     public Oid getStringNameType() throws GSSException
2166  
2167     Returns the oid representing the type of name returned through the
2168     toString method.  Using this oid, the syntax of the printable name
2169     can be determined.
2170  
2171  7.2.8.  isAnonymous
2172  
2173     public boolean isAnonymous()
2174  
2175     Tests if this name object represents an anonymous entity.  Returns
2176     "true" if this is an anonymous name.
2177  
2178  7.2.9.  isMN
2179  
2180     public boolean isMN()
2181  
2182     Tests if this name object contains only one mechanism element and is
2183     thus a mechanism name as defined by RFC 2743 [RFC2743].
2184  
2185  7.2.10.  Example Code
2186  
2187     Included below are code examples utilizing the GSSName interface.
2188     The code below creates a GSSName, converts it to a mechanism name
2189     (MN), performs a comparison, obtains a printable representation of
2190     the name, exports it and then re-imports to obtain a new GSSName.
2191  
2192     <CODE BEGINS>
2193     GSSManager mgr = GSSManager.getInstance();
2194  
2195     // create a host-based service name
2196     GSSName name = mgr.createName("service@host",
2197                     GSSName.NT_HOSTBASED_SERVICE);
2198  
2199     Oid krb5 = new Oid("1.2.840.113554.1.2.2");
2200  
2201     GSSName mechName = name.canonicalize(krb5);
2202  
2203     // the above two steps are equivalent to the following
2204     GSSName mechName = mgr.createName("service@host",
2205                     GSSName.NT_HOSTBASED_SERVICE, krb5);
2206  
2207     // perform name comparison
2208     if (name.equals(mechName))
2209             print("Names are equals.");
2210  
2211     // obtain textual representation of name and its printable
2212     // name type
2213     print(mechName.toString() +
2214           mechName.getStringNameType().toString());
2215  
2216     // export the name
2217     byte[] exportName = mechName.export();
2218  
2219     // create a new name object from the exported buffer
2220     GSSName newName = mgr.createName(exportName,
2221                       GSSName.NT_EXPORT_NAME);
2222     <CODE ENDS>
2223  
2224  7.3.  public interface GSSCredential implements Cloneable
2225  
2226     This interface encapsulates the GSS-API credentials for an entity.  A
2227     credential contains all the necessary cryptographic information to
2228     enable the creation of a context on behalf of the entity that it
2229     represents.  It MAY contain multiple, distinct, mechanism-specific
2230     credential elements, each containing information for a specific
2231     security mechanism, but all referring to the same entity.
2232  
2233     A credential MAY be used to perform context initiation, acceptance,
2234     or both.
2235  
2236     GSS-API implementations MUST impose a local access-control policy on
2237     callers to prevent unauthorized callers from acquiring credentials to
2238     which they are not entitled.  GSS-API credential creation is not
2239     intended to provide a "login to the network" function, as such a
2240     function would involve the creation of new credentials rather than
2241     merely acquiring a handle to existing credentials.  Such functions,
2242     if required, SHOULD be defined in implementation-specific extensions
2243     to the API.
2244  
2245     If credential acquisition is time-consuming for a mechanism, the
2246     mechanism MAY choose to delay the actual acquisition until the
2247     credential is required (e.g., by GSSContext).  Such mechanism-
2248     specific implementation decisions SHOULD be invisible to the calling
2249     application; thus, the query methods immediately following the
2250     creation of a credential object MUST return valid credential data,
2251     and may therefore incur the overhead of a deferred credential
2252     acquisition.
2253  
2254     Applications will create a credential object passing the desired
2255     parameters.  The application can then use the query methods to obtain
2256     specific information about the instantiated credential object
2257     (equivalent to the gss_inquire routines).  When the credential is no
2258     longer needed, the application SHOULD call the dispose (equivalent to
2259     gss_release_cred) method to release any resources held by the
2260     credential object and to destroy any cryptographically sensitive
2261     information.
2262  
2263     Classes implementing this interface also implement the Cloneable
2264     interface.  This indicates that the class will support the clone()
2265     method that will allow the creation of duplicate credentials.  This
2266     is useful when called just before the add() call to retain a copy of
2267     the original credential.
2268  
2269  7.3.1.  Static Constants
2270  
2271     public static final int INITIATE_AND_ACCEPT
2272  
2273     Credential usage flag requesting that it be able to be used for both
2274     context initiation and acceptance.  The value of this constant is 0.
2275  
2276     public static final int INITIATE_ONLY
2277  
2278     Credential usage flag requesting that it be able to be used for
2279     context initiation only.  The value of this constant is 1.
2280  
2281     public static final int ACCEPT_ONLY
2282  
2283     Credential usage flag requesting that it be able to be used for
2284     context acceptance only.  The value of this constant is 2.
2285  
2286     public static final int DEFAULT_LIFETIME
2287  
2288     A lifetime constant representing the default credential lifetime.
2289     The value of this constant is 0.
2290  
2291     public static final int INDEFINITE_LIFETIME
2292  
2293     A lifetime constant representing indefinite credential lifetime.  The
2294     value of this constant is the maximum integer value in Java -
2295     Integer.MAX_VALUE.
2296  
2297  7.3.2.  dispose
2298  
2299     public void dispose() throws GSSException
2300  
2301     Releases any sensitive information that the GSSCredential object may
2302     be containing.  Applications SHOULD call this method as soon as the
2303     credential is no longer needed to minimize the time any sensitive
2304     information is maintained.
2305  
2306  7.3.3.  getName
2307  
2308     public GSSName getName() throws GSSException
2309  
2310     Retrieves the name of the entity that the credential asserts.
2311  
2312  7.3.4.  getName
2313  
2314     public GSSName getName(Oid mechOID) throws GSSException
2315  
2316     Retrieves a mechanism name of the entity that the credential asserts.
2317     Equivalent to calling canonicalize() on the name returned by section
2318     7.3.3.
2319  
2320     Parameters:
2321  
2322     mechOID             The mechanism for which information should be
2323                         returned.
2324  
2325  7.3.5.  getRemainingLifetime
2326  
2327     public int getRemainingLifetime() throws GSSException
2328  
2329     Returns the remaining lifetime in seconds for a credential.  The
2330     remaining lifetime is the minimum lifetime for any of the underlying
2331     credential mechanisms.  A return value of
2332     GSSCredential.INDEFINITE_LIFETIME indicates that the credential does
2333     not expire.  A return value of 0 indicates that the credential is
2334     already expired.
2335  
2336  7.3.6.  getRemainingInitLifetime
2337  
2338     public int getRemainingInitLifetime(Oid mech) throws GSSException
2339  
2340     Returns the remaining lifetime in seconds for the credential to
2341     remain capable of initiating security contexts under the specified
2342     mechanism.  A return value of GSSCredential.INDEFINITE_LIFETIME
2343     indicates that the credential does not expire for context initiation.
2344     A return value of 0 indicates that the credential is already expired.
2345  
2346     Parameters:
2347  
2348     mechOID             The mechanism for which information should be
2349                         returned.
2350  
2351  7.3.7.  getRemainingAcceptLifetime
2352  
2353     public int getRemainingAcceptLifetime(Oid mech) throws GSSException
2354  
2355     Returns the remaining lifetime in seconds for the credential to
2356     remain capable of accepting security contexts under the specified
2357     mechanism.  A return value of GSSCredential.INDEFINITE_LIFETIME
2358     indicates that the credential does not expire for context acceptance.
2359     A return value of 0 indicates that the credential is already expired.
2360  
2361     Parameters:
2362  
2363     mechOID             The mechanism for which information should be
2364                         returned.
2365  
2366  7.3.8.  getUsage
2367  
2368     public int getUsage() throws GSSException
2369  
2370     Returns the credential usage flag as a union over all mechanisms.
2371     The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0),
2372     GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2).
2373  
2374     Specifically, GSSCredential.INITIATE_AND_ACCEPT(0) SHOULD be returned
2375     as long as there exists one credential element allowing context
2376     initiation and one credential element allowing context acceptance.
2377     These two credential elements are not necessarily the same one, nor
2378     do they need to use the same mechanism(s).
2379  
2380  7.3.9.  getUsage
2381  
2382     public int getUsage(Oid mechOID) throws GSSException
2383  
2384     Returns the credential usage flag for the specified mechanism only.
2385     The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0),
2386     GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2).
2387  
2388     Parameters:
2389  
2390     mechOID             The mechanism for which information should be
2391                         returned.
2392  
2393  7.3.10.  getMechs
2394  
2395     public Oid[] getMechs() throws GSSException
2396  
2397     Returns an array of mechanisms supported by this credential.
2398  
2399  7.3.11.  add
2400  
2401     public void add(GSSName aName, int initLifetime, int acceptLifetime,
2402                     Oid mech, int usage) throws GSSException
2403  
2404     Adds a mechanism-specific credential-element to an existing
2405     credential.  This method allows the construction of credentials one
2406     mechanism at a time.
2407  
2408     This routine is envisioned to be used mainly by context acceptors
2409     during the creation of acceptance credentials, which are to be used
2410     with a variety of clients using different security mechanisms.
2411  
2412     This routine adds the new credential element "in-place".  To add the
2413     element in a new credential, first call clone() to obtain a copy of
2414     this credential, then call its add() method.
2415  
2416     Parameters:
2417  
2418     aName               Name of the principal for whom this credential is
2419                         to be acquired.  Use "null" to specify the
2420                         default principal.
2421  
2422     initLifetime        The number of seconds that credentials should
2423                         remain valid for initiating of security contexts.
2424                         Use GSSCredential.INDEFINITE_LIFETIME to request
2425                         that the credentials have the maximum permitted
2426                         lifetime.  Use GSSCredential.DEFAULT_LIFETIME to
2427                         request default credential lifetime.
2428  
2429     acceptLifetime      The number of seconds that credentials should
2430                         remain valid for accepting of security contexts.
2431  
2432                         Use GSSCredential.INDEFINITE_LIFETIME to request
2433                         that the credentials
2434                         have the maximum permitted lifetime.  Use
2435                         GSSCredential.DEFAULT_LIFETIME to request default
2436                         credential lifetime.
2437  
2438     mech                The mechanisms over which the credential is to be
2439                         acquired.
2440  
2441     usage               The intended usage for this credential object.
2442                         The value of this parameter MUST be one of:
2443  
2444                         GSSCredential.INITIATE_AND_ACCEPT(0),
2445                         GSSCredential.INITIATE_ONLY(1), or
2446                         GSSCredential.ACCEPT_ONLY(2)
2447  
2448  7.3.12.  equals
2449  
2450     public boolean equals(Object another)
2451  
2452     Tests if this GSSCredential refers to the same entity as the supplied
2453     object.  The two credentials MUST be acquired over the same
2454     mechanisms and MUST refer to the same principal.  Returns "true" if
2455     the two GSSCredentials refer to the same entity; "false" otherwise.
2456     (Note that the Java language specification [JLS] requires that two
2457     objects that are equal according to the equals(Object) method MUST
2458     return the same integer result when the hashCode() method is called
2459     on them.)
2460  
2461     Parameters:
2462  
2463     another             Another GSSCredential object for comparison.
2464  
2465  7.3.13.  Example Code
2466  
2467     This example code demonstrates the creation of a GSSCredential
2468     implementation for a specific entity, querying of its fields, and its
2469     release when it is no longer needed.
2470  
2471     <CODE BEGINS>
2472     GSSManager mgr = GSSManager.getInstance();
2473  
2474     // start by creating a name object for the entity
2475     GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME);
2476  
2477     // now acquire credentials for the entity
2478     GSSCredential cred = mgr.createCredential(name,
2479                          GSSCredential.ACCEPT_ONLY);
2480  
2481     // display credential information - name, remaining lifetime,
2482     // and the mechanisms it has been acquired over
2483     print(cred.getName().toString());
2484     print(cred.getRemainingLifetime());
2485  
2486     Oid[] mechs = cred.getMechs();
2487     if (mechs != null) {
2488        for (int i = 0; i < mechs.length; i++)
2489            print(mechs[i].toString());
2490     }
2491     // release system resources held by the credential
2492     cred.dispose();
2493     <CODE ENDS>
2494  
2495  7.4.  public interface GSSContext
2496  
2497     This interface encapsulates the GSS-API security context and provides
2498     the security services (wrap, unwrap, getMIC, verifyMIC) that are
2499     available over the context.  Security contexts are established
2500     between peers using locally acquired credentials.  Multiple contexts
2501     may exist simultaneously between a pair of peers, using the same or
2502     different set of credentials.  GSS-API functions in a manner
2503     independent of the underlying transport protocol and depends on its
2504     calling application to transport its tokens between peers.
2505  
2506     Before the context establishment phase is initiated, the context
2507     initiator may request specific characteristics desired of the
2508     established context.  These can be set using the set methods.  After
2509     the context is established, the caller can check the actual
2510     characteristic and services offered by the context using the query
2511     methods.
2512  
2513     The context establishment phase begins with the first call to the
2514     init method by the context initiator.  During this phase, the
2515     initSecContext and acceptSecContext methods will produce GSS-API
2516     authentication tokens, which the calling application needs to send to
2517     its peer.  If an error occurs at any point, an exception will get
2518     thrown and the code will start executing in a catch block where the
2519     exception may contain an output token that should be sent to the peer
2520     for debugging or informational purpose.  If not, the normal flow of
2521     code continues and the application can make a call to the
2522     isEstablished() method.  If this method returns "false" it indicates
2523     that a token is needed from its peer in order to continue the context
2524     establishment phase.  A return value of "true" signals that the local
2525     end of the context is established.  This may still require that a
2526     token be sent to the peer, if one is produced by GSS-API.  During the
2527     context establishment phase, the isProtReady() method may be called
2528     to determine if the context can be used for the per-message
2529     operations.  This allows applications to use per-message operations
2530     on contexts that aren't fully established.
2531  
2532     After the context has been established or the isProtReady() method
2533     returns "true", the query routines can be invoked to determine the
2534     actual characteristics and services of the established context.  The
2535     application can also start using the per-message methods of wrap and
2536     getMIC to obtain cryptographic operations on application supplied
2537     data.
2538  
2539     When the context is no longer needed, the application SHOULD call
2540     dispose to release any system resources the context may be using.
2541  
2542  7.4.1.  Static Constants
2543  
2544     public static final int DEFAULT_LIFETIME
2545  
2546     A lifetime constant representing the default context lifetime.  The
2547     value of this constant is 0.
2548  
2549     public static final int INDEFINITE_LIFETIME
2550  
2551     A lifetime constant representing indefinite context lifetime.  The
2552     value of this constant is the maximum integer value in Java -
2553     Integer.MAX_VALUE.
2554  
2555  7.4.2.  initSecContext
2556  
2557     public byte[] initSecContext(byte[] inputBuf, int offset, int len)
2558                   throws GSSException
2559  
2560     Called by the context initiator to start the context creation
2561     process.  This method MAY return an output token that the application
2562     will need to send to the peer for processing by the accept call.  The
2563     application can call isEstablished() to determine if the context
2564     establishment phase is complete for this peer.  A return value of
2565     "false" from isEstablished() indicates that more tokens are expected
2566     to be supplied to the initSecContext() method.  Note that it is
2567     possible that the initSecContext() method will return a token for the
2568     peer and isEstablished() will return "true" also.  This indicates
2569     that the token needs to be sent to the peer, but the local end of the
2570     context is now fully established.
2571  
2572     Upon completion of the context establishment, the available context
2573     options may be queried through the get methods.
2574  
2575     A GSSException will be thrown if the call fails.  Users SHOULD call
2576     its getOutputToken() method to find out if there is a token that can
2577     be sent to the acceptor to communicate the reason for the error.
2578  
2579     Parameters:
2580  
2581     inputBuf            Token generated by the peer.  This parameter is
2582                         ignored on the first call.
2583  
2584     offset              The offset within the inputBuf where the token
2585                         begins.
2586  
2587     len                 The length of the token within the inputBuf
2588                         (starting at the offset).
2589  
2590  7.4.3.  acceptSecContext
2591  
2592     public byte[] acceptSecContext(byte[] inTok, int offset, int len)
2593                throws GSSException
2594  
2595     Called by the context acceptor upon receiving a token from the peer.
2596  
2597     This method MAY return an output token that the application will need
2598     to send to the peer for further processing by the init call.
2599  
2600     The "null" return value indicates that no token needs to be sent to
2601     the peer.  The application can call isEstablished() to determine if
2602     the context establishment phase is complete for this peer.  A return
2603     value of "false" from isEstablished() indicates that more tokens are
2604     expected to be supplied to this method.
2605  
2606     Note that it is possible that acceptSecContext() will return a token
2607     for the peer and isEstablished() will return "true" also.  This
2608     indicates that the token needs to be sent to the peer, but the local
2609     end of the context is now fully established.
2610  
2611     Upon completion of the context establishment, the available context
2612     options may be queried through the get methods.
2613  
2614     A GSSException will be thrown if the call fails.  Users SHOULD call
2615     its getOutputToken() method to find out if there is a token that can
2616     be sent to the initiator to communicate the reason for the error.
2617  
2618     Parameters:
2619  
2620     inTok               Token generated by the peer.
2621  
2622     offset              The offset within the inTok where the token
2623                         begins.
2624  
2625     len                 The length of the token within the inTok
2626                         (starting at the offset).
2627  
2628  7.4.4.  isEstablished
2629  
2630     public boolean isEstablished()
2631  
2632     Used during context establishment to determine the state of the
2633     context.  Returns "true" if this is a fully established context on
2634     the caller's side and no more tokens are needed from the peer.
2635     Should be called after a call to initSecContext() or
2636     acceptSecContext() when no GSSException is thrown.
2637  
2638  7.4.5.  dispose
2639  
2640     public void dispose() throws GSSException
2641  
2642     Releases any system resources and cryptographic information stored in
2643     the context object.  This will invalidate the context.
2644  
2645  7.4.6.  getWrapSizeLimit
2646  
2647     public int getWrapSizeLimit(int qop, boolean confReq,
2648                int maxTokenSize) throws GSSException
2649  
2650     Returns the maximum message size that, if presented to the wrap
2651     method with the same confReq and qop parameters, will result in an
2652     output token containing no more than the maxTokenSize bytes.
2653  
2654     This call is intended for use by applications that communicate over
2655     protocols that impose a maximum message size.  It enables the
2656     application to fragment messages prior to applying protection.
2657  
2658     GSS-API implementations are RECOMMENDED but not required to detect
2659     invalid QOP values when getWrapSizeLimit is called.  This routine
2660     guarantees only a maximum message size, not the availability of
2661     specific QOP values for message protection.
2662  
2663     Successful completion of this call does not guarantee that wrap will
2664     be able to protect a message of the computed length, since this
2665     ability may depend on the availability of system resources at the
2666     time that wrap is called.  However, if the implementation itself
2667     imposes an upper limit on the length of messages that may be
2668     processed by wrap, the implementation SHOULD NOT return a value that
2669     is greater than this length.
2670  
2671     Parameters:
2672  
2673     qop                 Indicates the level of protection wrap will be
2674                         asked to provide.
2675  
2676     confReq             Indicates if wrap will be asked to provide
2677                         privacy service.
2678  
2679     maxTokenSize        The desired maximum size of the token emitted by
2680                         wrap.
2681  
2682  7.4.7.  wrap
2683  
2684     public byte[] wrap(byte[] inBuf, int offset, int len,
2685                        MessageProp msgProp) throws GSSException
2686  
2687     Applies per-message security services over the established security
2688     context.  The method will return a token with a cryptographic MIC and
2689     MAY optionally encrypt the specified inBuf.  The returned byte array
2690     will contain both the MIC and the message.
2691  
2692     The MessageProp object is instantiated by the application and used to
2693     specify a QOP value that selects cryptographic algorithms, and a
2694     privacy service to optionally encrypt the message.  The underlying
2695     mechanism that is used in the call may not be able to provide the
2696     privacy service.  It sets the actual privacy service that it does
2697     provide in this MessageProp object, which the caller SHOULD then
2698     query upon return.  If the mechanism is not able to provide the
2699     requested QOP, it throws a GSSException with the BAD_QOP code.
2700  
2701     Since some application-level protocols may wish to use tokens emitted
2702     by wrap to provide "secure framing", implementations SHOULD support
2703     the wrapping of zero-length messages.
2704  
2705     The application will be responsible for sending the token to the
2706     peer.
2707  
2708     Parameters:
2709  
2710     inBuf               Application data to be protected.
2711  
2712     offset              The offset within the inBuf where the data
2713                         begins.
2714  
2715     len                 The length of the data within the inBuf (starting
2716                         at the offset).
2717  
2718     msgProp             Instance of MessageProp that is used by the
2719                         application to set the desired QOP and privacy
2720                         state.  Set the desired QOP to 0 to request the
2721                         default QOP.  Upon return from this method, this
2722                         object will contain the actual privacy state that
2723                         was applied to the message by the underlying
2724                         mechanism.
2725  
2726  7.4.8.  unwrap
2727  
2728     public byte[] unwrap(byte[] inBuf, int offset, int len,
2729                          MessageProp msgProp) throws GSSException
2730  
2731     Used by the peer application to process tokens generated with the
2732     wrap call.  The method will return the message supplied in the peer
2733     application to the wrap call, verifying the embedded MIC.
2734  
2735     The MessageProp object is instantiated by the application and is used
2736     by the underlying mechanism to return information to the caller such
2737     as the QOP, whether confidentiality was applied to the message, and
2738     other supplementary message state information.
2739  
2740     Since some application-level protocols may wish to use tokens emitted
2741     by wrap to provide "secure framing", implementations SHOULD support
2742     the wrapping and unwrapping of zero-length messages.
2743  
2744     Parameters:
2745  
2746     inBuf               GSS-API wrap token received from peer.
2747  
2748     offset              The offset within the inBuf where the token
2749                         begins.
2750  
2751     len                 The length of the token within the inBuf
2752                         (starting at the offset).
2753  
2754     msgProp             Upon return from the method, this object will
2755                         contain the applied QOP, the privacy state of the
2756                         message, and supplementary information, described
2757                         in section 5.12.3, stating whether the token was
2758                         a duplicate, old, out of sequence, or arriving
2759                         after a gap.
2760  
2761  7.4.9.  getMIC
2762  
2763     public byte[] getMIC(byte[] inMsg, int offset, int len,
2764                          MessageProp msgProp) throws GSSException
2765  
2766     Returns a token containing a cryptographic MIC for the supplied
2767     message for transfer to the peer application.  Unlike wrap, which
2768     encapsulates the user message in the returned token, only the message
2769     MIC is returned in the output token.
2770  
2771     Note that privacy can only be applied through the wrap call.
2772  
2773     Since some application-level protocols may wish to use tokens emitted
2774     by getMIC to provide "secure framing", implementations SHOULD support
2775     derivation of MICs from zero-length messages.
2776  
2777     Parameters:
2778  
2779     inMsg               Message over which to generate MIC.
2780  
2781     offset              The offset within the inMsg where the token
2782                         begins.
2783  
2784     len                 The length of the token within the inMsg
2785                         (starting at the offset).
2786  
2787     msgProp             Instance of MessageProp that is used by the
2788                         application to set the desired QOP.  Set the
2789                         desired QOP to 0 in msgProp to request the
2790                         default QOP.  Alternatively, pass in "null" for
2791                         msgProp to request default QOP.
2792  
2793  7.4.10.  verifyMIC
2794  
2795     public void verifyMIC(byte[] inTok, int tokOffset, int tokLen,
2796                           byte[] inMsg, int msgOffset, int msgLen,
2797                           MessageProp msgProp) throws GSSException
2798  
2799     Verifies the cryptographic MIC, contained in the token parameter,
2800     over the supplied message.
2801  
2802     The MessageProp object is instantiated by the application and is used
2803     by the underlying mechanism to return information to the caller such
2804     as the QOP indicating the strength of protection that was applied to
2805     the message and other supplementary message state information.
2806  
2807     Since some application-level protocols may wish to use tokens emitted
2808     by getMIC to provide "secure framing", implementations SHOULD support
2809     the calculation and verification of MICs over zero-length messages.
2810  
2811     Parameters:
2812  
2813     inTok               Token generated by peer's getMIC method.
2814  
2815     tokOffset           The offset within the inTok where the token
2816                         begins.
2817  
2818     tokLen              The length of the token within the inTok
2819                         (starting at the offset).
2820  
2821     inMsg               Application message over which to verify the
2822                         cryptographic MIC.
2823  
2824     msgOffset           The offset within the inMsg where the message
2825                         begins.
2826  
2827     msgLen              The length of the message within the inMsg
2828                         (starting at the offset).
2829  
2830     msgProp             Upon return from the method, this object will
2831                         contain the applied QOP and supplementary
2832                         information, described in section 5.12.3, stating
2833                         whether the token was a duplicate, old, out of
2834                         sequence, or arriving after a gap.  The
2835                         confidentiality state will be set to "false".
2836  
2837  7.4.11.  export
2838  
2839     public byte[] export() throws GSSException
2840  
2841     Provided to support the sharing of work between multiple processes.
2842     This routine will typically be used by the context acceptor, in an
2843     application where a single process receives incoming connection
2844     requests and accepts security contexts over them, then passes the
2845     established context to one or more other processes for message
2846     exchange.
2847  
2848     This method deactivates the security context and creates an inter-
2849     process token which, when passed to the byte array constructor of the
2850     GSSContext interface in another process, will re-activate the context
2851     in the second process.  Only a single instantiation of a given
2852     context may be active at any one time; a subsequent attempt by a
2853     context exporter to access the exported security context will fail.
2854  
2855     The implementation MAY constrain the set of processes by which the
2856     inter-process token may be imported, either as a function of local
2857     security policy, or as a result of implementation decisions.  For
2858     example, some implementations may constrain contexts to be passed
2859     only between processes that run under the same account, or which are
2860     part of the same process group.
2861  
2862     The inter-process token MAY contain security-sensitive information
2863     (for example, cryptographic keys).  While mechanisms are encouraged
2864     to either avoid placing such sensitive information within inter-
2865     process tokens or to encrypt the token before returning it to the
2866     application, in a typical GSS-API implementation, this may not be
2867     possible.  Thus, the application MUST take care to protect the inter-
2868     process token, and ensure that any process to which the token is
2869     transferred is trustworthy.
2870  
2871  7.4.12.  requestMutualAuth
2872  
2873     public void requestMutualAuth(boolean state) throws GSSException
2874  
2875     Sets the request state of the mutual authentication flag for the
2876     context.  This method is only valid before the context creation
2877     process begins and only for the initiator.
2878  
2879     Parameters:
2880  
2881     state               Boolean representing if mutual authentication
2882                         should be requested during context establishment.
2883  
2884  7.4.13.  requestReplayDet
2885  
2886     public void requestReplayDet(boolean state) throws GSSException
2887  
2888     Sets the request state of the replay detection service for the
2889     context.  This method is only valid before the context creation
2890     process begins and only for the initiator.
2891  
2892     Parameters:
2893  
2894     state               Boolean representing if replay detection is
2895                         desired over the established context.
2896  
2897  7.4.14.  requestSequenceDet
2898  
2899     public void requestSequenceDet(boolean state) throws GSSException
2900  
2901     Sets the request state for the sequence checking service of the
2902     context.  This method is only valid before the context creation
2903     process begins and only for the initiator.
2904  
2905     Parameters:
2906  
2907     state               Boolean representing if sequence detection is
2908                         desired over the established context.
2909  
2910  7.4.15.  requestCredDeleg
2911  
2912     public void requestCredDeleg(boolean state) throws GSSException
2913  
2914     Sets the request state for the credential delegation flag for the
2915     context.  This method is only valid before the context creation
2916     process begins and only for the initiator.
2917  
2918     Parameters:
2919  
2920     state               Boolean representing if credential delegation is
2921                         desired.
2922  
2923  7.4.16.  requestAnonymity
2924  
2925     public void requestAnonymity(boolean state) throws GSSException
2926  
2927     Requests anonymous support over the context.  This method is only
2928     valid before the context creation process begins and only for the
2929     initiator.
2930  
2931     Parameters:
2932  
2933     state               Boolean representing if anonymity support is
2934                         requested.
2935  
2936  7.4.17.  requestConf
2937  
2938     public void requestConf(boolean state) throws GSSException
2939  
2940     Requests that confidentiality service be available over the context.
2941     This method is only valid before the context creation process begins
2942     and only for the initiator.
2943  
2944     Parameters:
2945  
2946     state               Boolean indicating if confidentiality services
2947                         are to be requested for the context.
2948  
2949  7.4.18.  requestInteg
2950  
2951     public void requestInteg(boolean state) throws GSSException
2952  
2953     Requests that integrity services be available over the context.  This
2954     method is only valid before the context creation process begins and
2955     only for the initiator.
2956  
2957     Parameters:
2958  
2959     state               Boolean indicating if integrity services are to
2960                         be requested for the context.
2961  
2962  7.4.19.  requestLifetime
2963  
2964     public void requestLifetime(int lifetime) throws GSSException
2965  
2966     Sets the desired lifetime for the context in seconds.  This method is
2967     only valid before the context creation process begins and only for
2968     the initiator.  Use GSSContext.INDEFINITE_LIFETIME and
2969     GSSContext.DEFAULT_LIFETIME to request indefinite or default context
2970     lifetime.
2971  
2972     Parameters:
2973  
2974     lifetime            The desired context lifetime in seconds.
2975  
2976  7.4.20.  setChannelBinding
2977  
2978     public void setChannelBinding(ChannelBinding cb) throws GSSException
2979  
2980     Sets the channel bindings to be used during context establishment.
2981     This method is only valid before the context creation process begins.
2982  
2983     Parameters:
2984  
2985     cb                  Channel bindings to be used.
2986  
2987  7.4.21.  getCredDelegState
2988  
2989     public boolean getCredDelegState()
2990  
2991     Returns the state of the delegated credentials for the context.  When
2992     issued before context establishment is completed or when the
2993     isProtReady method returns "false", it returns the desired state;
2994     otherwise, it will indicate the actual state over the established
2995     context.
2996  
2997  7.4.22.  getMutualAuthState
2998  
2999     public boolean getMutualAuthState()
3000  
3001     Returns the state of the mutual authentication option for the
3002     context.  When issued before context establishment completes or when
3003     the isProtReady method returns "false", it returns the desired state;
3004     otherwise, it will indicate the actual state over the established
3005     context.
3006  
3007  7.4.23.  getReplayDetState
3008  
3009     public boolean getReplayDetState()
3010  
3011     Returns the state of the replay detection option for the context.
3012     When issued before context establishment completes or when the
3013     isProtReady method returns "false", it returns the desired state;
3014     otherwise, it will indicate the actual state over the established
3015     context.
3016  
3017  7.4.24.  getSequenceDetState
3018  
3019     public boolean getSequenceDetState()
3020  
3021     Returns the state of the sequence detection option for the context.
3022     When issued before context establishment completes or when the
3023     isProtReady method returns "false", it returns the desired state;
3024     otherwise, it will indicate the actual state over the established
3025     context.
3026  
3027  7.4.25.  getAnonymityState
3028  
3029     public boolean getAnonymityState()
3030  
3031     Returns "true" if this is an anonymous context.  When issued before
3032     context establishment completes or when the isProtReady method
3033     returns "false", it returns the desired state; otherwise, it will
3034     indicate the actual state over the established context.
3035  
3036  7.4.26.  isTransferable
3037  
3038     public boolean isTransferable() throws GSSException
3039  
3040     Returns "true" if the context is transferable to other processes
3041     through the use of the export method.  This call is only valid on
3042     fully established contexts.
3043  
3044  7.4.27.  isProtReady
3045  
3046     public boolean isProtReady()
3047  
3048     Returns "true" if the per-message operations can be applied over the
3049     context.  Some mechanisms may allow the usage of per-message
3050     operations before the context is fully established.  This will also
3051     indicate that the get methods will return actual context state
3052     characteristics instead of the desired ones.
3053  
3054  7.4.28.  getConfState
3055  
3056     public boolean getConfState()
3057  
3058     Returns the confidentiality service state over the context.  When
3059     issued before context establishment completes or when the isProtReady
3060     method returns "false", it returns the desired state; otherwise, it
3061     will indicate the actual state over the established context.
3062  
3063  7.4.29.  getIntegState
3064  
3065     public boolean getIntegState()
3066  
3067     Returns the integrity service state over the context.  When issued
3068     before context establishment completes or when the isProtReady method
3069     returns "false", it returns the desired state; otherwise, it will
3070     indicate the actual state over the established context.
3071  
3072  7.4.30.  getLifetime
3073  
3074     public int getLifetime()
3075  
3076     Returns the context lifetime in seconds.  When issued before context
3077     establishment completes or when the isProtReady method returns
3078     "false", it returns the desired lifetime; otherwise, it will indicate
3079     the remaining lifetime for the context.
3080  
3081  7.4.31.  getSrcName
3082  
3083     public GSSName getSrcName() throws GSSException
3084  
3085     Returns the name of the context initiator.  This call is valid only
3086     after the context is fully established or the isProtReady method
3087     returns "true".  It is guaranteed to return an MN.
3088  
3089  7.4.32.  getTargName
3090  
3091     public GSSName getTargName() throws GSSException
3092  
3093     Returns the name of the context target (acceptor).  This call is
3094     valid only after the context is fully established or the isProtReady
3095     method returns "true".  It is guaranteed to return an MN.
3096  
3097  7.4.33.  getMech
3098  
3099     public Oid getMech() throws GSSException
3100  
3101     Returns the mechanism oid for this context.  This method MAY be
3102     called before the context is fully established, but the mechanism
3103     returned MAY change on successive calls in negotiated mechanism case.
3104  
3105  7.4.34.  getDelegCred
3106  
3107     public GSSCredential getDelegCred() throws GSSException
3108  
3109     Returns the delegated credential object on the acceptor's side.  To
3110     check for availability of delegated credentials call
3111     getDelegCredState.  This call is only valid on fully established
3112     contexts.
3113  
3114  7.4.35.  isInitiator
3115  
3116     public boolean isInitiator() throws GSSException
3117  
3118     Returns "true" if this is the initiator of the context.  This call is
3119     only valid after the context creation process has started.
3120  
3121  7.4.36.  Example Code
3122  
3123     The example code presented below demonstrates the usage of the
3124     GSSContext interface for the initiating peer.  Different operations
3125     on the GSSContext object are presented, including: object
3126     instantiation, setting of desired flags, context establishment, query
3127     of actual context flags, per-message operations on application data,
3128     and finally context deletion.
3129  
3130     <CODE BEGINS>
3131     GSSManager mgr = GSSManager.getInstance();
3132  
3133     // start by creating the name for a service entity
3134     GSSName targetName = mgr.createName("service@host",
3135                          GSSName.NT_HOSTBASED_SERVICE);
3136     // create a context using default credentials for the above entity
3137     // and the implementation-specific default mechanism
3138     GSSContext context = mgr.createContext(targetName,
3139                     null,   /* default mechanism */
3140                     null,   /* default credentials */
3141                     GSSContext.INDEFINITE_LIFETIME);
3142  
3143     // set desired context options - all others are "false" by default
3144     context.requestConf(true);
3145     context.requestMutualAuth(true);
3146     context.requestReplayDet(true);
3147     context.requestSequenceDet(true);
3148  
3149     // establish a context between peers - using byte arrays
3150     byte[]inTok = new byte[0];
3151  
3152     try {
3153         do {
3154             byte[] outTok = context.initSecContext(inTok, 0,
3155                                                   inTok.length);
3156  
3157             // send the token if present
3158             if (outTok != null)
3159                 sendToken(outTok);
3160  
3161             // check if we should expect more tokens
3162             if (context.isEstablished())
3163                 break;
3164  
3165             // another token expected from peer
3166             inTok = readToken();
3167  
3168         } while (true);
3169  
3170     } catch (GSSException e) {
3171         print("GSSAPI error: " + e.getMessage());
3172  
3173         // If the exception contains an output token,
3174         // it should be sent to the acceptor.
3175         byte[] outTok = e.getOutputToken();
3176         if (outTok != null) {
3177             sendToken(outTok);
3178         }
3179  
3180         return;
3181     }
3182  
3183     // display context information
3184     print("Remaining lifetime in seconds = " + context.getLifetime());
3185     print("Context mechanism = " + context.getMech().toString());
3186     print("Initiator = " + context.getSrcName().toString());
3187     print("Acceptor = " + context.getTargName().toString());
3188  
3189     if (context.getConfState())
3190         print("Confidentiality security service available");
3191  
3192     if (context.getIntegState())
3193         print("Integrity security service available");
3194  
3195     // perform wrap on an application-supplied message, appMsg,
3196     // using QOP = 0, and requesting privacy service
3197     byte[] appMsg ...
3198  
3199     MessageProp mProp = new MessageProp(0, true);
3200  
3201     byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp);
3202  
3203     if (mProp.getPrivacy())
3204         print("Message protected with privacy.");
3205  
3206     sendToken(tok);
3207  
3208     // release the local end of the context
3209     context.dispose();
3210     <CODE ENDS>
3211  
3212  7.5.  public class MessageProp
3213  
3214     This is a utility class used within the per-message GSSContext
3215     methods to convey per-message properties.
3216  
3217     When used with the GSSContext interface's wrap and getMIC methods, an
3218     instance of this class is used to indicate the desired QOP and to
3219     request if confidentiality services are to be applied to caller
3220     supplied data (wrap only).  To request default QOP, the value of 0
3221     should be used for QOP.  A QOP is an integer value defined by an
3222     mechanism.
3223  
3224     When used with the unwrap and verifyMIC methods of the GSSContext
3225     interface, an instance of this class will be used to indicate the
3226     applied QOP and confidentiality services over the supplied message.
3227     In the case of verifyMIC, the confidentiality state will always be
3228     "false".  Upon return from these methods, this object will also
3229     contain any supplementary status values applicable to the processed
3230     token.  The supplementary status values can indicate old tokens, out
3231     of sequence tokens, gap tokens, or duplicate tokens.
3232  
3233  7.5.1.  Constructors
3234  
3235     public MessageProp(boolean privState)
3236  
3237     Constructor that sets QOP to 0 indicating that the default QOP is
3238     requested.
3239  
3240     Parameters:
3241  
3242     privState           The desired privacy state. "true" for privacy and
3243                         "false" for integrity only.
3244  
3245     public MessageProp(int qop, boolean privState)
3246  
3247     Constructor that sets the values for the qop and privacy state.
3248  
3249     Parameters:
3250  
3251     qop                 The desired QOP.  Use 0 to request a default QOP.
3252  
3253     privState           The desired privacy state. "true" for privacy and
3254                         "false" for integrity only.
3255  
3256  7.5.2.  getQOP
3257  
3258     public int getQOP()
3259  
3260     Retrieves the QOP value.
3261  
3262  7.5.3.  getPrivacy
3263  
3264     public boolean getPrivacy()
3265  
3266     Retrieves the privacy state.
3267  
3268  7.5.4.  getMinorStatus
3269  
3270     public int getMinorStatus()
3271  
3272     Retrieves the minor status that the underlying mechanism might have
3273     set.
3274  
3275  7.5.5.  getMinorString
3276  
3277     public String getMinorString()
3278  
3279     Returns a string explaining the mechanism-specific error code. "null"
3280     will be returned when no mechanism error code has been set.
3281  
3282  7.5.6.  setQOP
3283  
3284     public void setQOP(int qopVal)
3285  
3286     Sets the QOP value.
3287  
3288     Parameters:
3289  
3290     qopVal              The QOP value to be set.  Use 0 to request a
3291                         default QOP value.
3292  
3293  7.5.7.  setPrivacy
3294  
3295     public void setPrivacy(boolean privState)
3296  
3297     Sets the privacy state.
3298  
3299     Parameters:
3300  
3301     privState           The privacy state to set.
3302  
3303  7.5.8.  isDuplicateToken
3304  
3305     public boolean isDuplicateToken()
3306  
3307     Returns "true" if this is a duplicate of an earlier token.
3308  
3309  7.5.9.  isOldToken
3310  
3311     public boolean isOldToken()
3312  
3313     Returns "true" if the token's validity period has expired.
3314  
3315  7.5.10.  isUnseqToken
3316  
3317     public boolean isUnseqToken()
3318  
3319     Returns "true" if a later token has already been processed.
3320  
3321  7.5.11.  isGapToken
3322  
3323     public boolean isGapToken()
3324  
3325     Returns "true" if an expected per-message token was not received.
3326  
3327  7.5.12.  setSupplementaryStates
3328  
3329     public void setSupplementaryStates(boolean duplicate,
3330                    boolean old, boolean unseq, boolean gap,
3331                    int minorStatus, String minorString)
3332  
3333     This method sets the state for the supplementary information flags
3334     and the minor status in MessageProp.  It is not used by the
3335     application but by the GSS implementation to return this information
3336     to the caller of a per-message context method.
3337  
3338     Parameters:
3339  
3340     duplicate           "true" if the token was a duplicate of an earlier
3341                         token; otherwise, "false".
3342  
3343     old                 "true" if the token's validity period has
3344                         expired; otherwise, "false".
3345  
3346     unseq               "true" if a later token has already been
3347                         processed; otherwise, "false".
3348  
3349     gap                 "true" if one or more predecessor tokens have not
3350                         yet been successfully processed; otherwise,
3351                         "false".
3352  
3353     minorStatus         The integer minor status code that the underlying
3354                         mechanism wants to set.
3355  
3356     minorString         The textual representation of the minorStatus
3357                         value.
3358  
3359  7.6.  public class ChannelBinding
3360  
3361     The GSS-API accommodates the concept of caller-provided channel
3362     binding information.  Channel bindings are used to strengthen the
3363     quality with which peer entity authentication is provided during
3364     context establishment.  They enable the GSS-API callers to bind the
3365     establishment of the security context to relevant characteristics
3366     like addresses or to application-specific data.
3367  
3368     The caller initiating the security context MUST determine the
3369     appropriate channel binding values to set in the GSSContext object.
3370     The acceptor MUST provide an identical binding in order to validate
3371     that received tokens possess correct channel-related characteristics.
3372  
3373     Use of channel bindings is OPTIONAL in GSS-API.  Since channel-
3374     binding information may be transmitted in context establishment
3375     tokens, applications SHOULD therefore not use confidential data as
3376     channel-binding components.
3377  
3378  7.6.1.  Constructors
3379  
3380     public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr,
3381                           byte[] appData)
3382  
3383     Create a ChannelBinding object with user-supplied address information
3384     and data. "null" values can be used for any fields that the
3385     application does not want to specify.
3386  
3387     Parameters:
3388  
3389     initAddr            The address of the context initiator. "null"
3390                         value can be supplied to indicate that the
3391                         application does not want to set this value.
3392  
3393     acceptAddr          The address of the context acceptor. "null" value
3394                         can be supplied to indicate that the application
3395                         does not want to set this value.
3396  
3397     appData             Application-supplied data to be used as part of
3398                         the channel bindings. "null" value can be
3399                         supplied to indicate that the application does
3400                         not want to set this value.
3401  
3402     public ChannelBinding(byte[] appData)
3403  
3404     Creates a ChannelBinding object without any addressing information.
3405  
3406     Parameters:
3407  
3408     appData             Application supplied data to be used as part of
3409                         the channel bindings.
3410  
3411  7.6.2.  getInitiatorAddress
3412  
3413     public InetAddress getInitiatorAddress()
3414  
3415     Returns the initiator's address for this channel binding. "null" is
3416     returned if the address has not been set.
3417  
3418  7.6.3.  getAcceptorAddress
3419  
3420     public InetAddress getAcceptorAddress()
3421  
3422     Returns the acceptor's address for this channel binding. "null" is
3423     returned if the address has not been set.
3424  
3425  7.6.4.  getApplicationData
3426  
3427     public byte[] getApplicationData()
3428  
3429     Returns application data being used as part of the ChannelBinding.
3430     "null" is returned if no application data has been specified for the
3431     channel binding.
3432  
3433  7.6.5.  equals
3434  
3435     public boolean equals(Object obj)
3436  
3437     Returns "true" if two channel bindings match.  (Note that the Java
3438     language specification requires that two objects that are equal
3439     according to the equals(Object) method MUST return the same integer
3440     result when the hashCode() method is called on them.)
3441  
3442     Parameters:
3443  
3444     obj                 Another channel binding with which to compare.
3445  
3446  7.7.  public class Oid
3447  
3448     This class represents Universal Object Identifiers (Oids) and their
3449     associated operations.
3450  
3451     Oids are hierarchically globally interpretable identifiers used
3452     within the GSS-API framework to identify mechanisms and name formats.
3453  
3454     The structure and encoding of Oids is defined in ISOIEC-8824 and
3455     ISOIEC-8825.  For example, the Oid representation of the Kerberos v5
3456     mechanism is "1.2.840.113554.1.2.2".
3457  
3458     The GSSName name class contains public static Oid objects
3459     representing the standard name types defined in GSS-API.
3460  
3461  7.7.1.  Constructors
3462  
3463     public Oid(String strOid) throws GSSException
3464  
3465     Creates an Oid object from a string representation of its integer
3466     components (e.g., "1.2.840.113554.1.2.2").
3467  
3468     Parameters:
3469  
3470     strOid              The string representation for the oid.
3471  
3472     public Oid(InputStream derOid) throws GSSException
3473  
3474     Creates an Oid object from its DER encoding.  This refers to the full
3475     encoding including tag and length.  The structure and encoding of
3476     Oids is defined in ISOIEC-8824 and ISOIEC-8825.  This method is
3477     identical in functionality to its byte array counterpart.
3478  
3479     Parameters:
3480  
3481     derOid              Stream containing the DER-encoded oid.
3482  
3483     public Oid(byte[] DEROid) throws GSSException
3484  
3485     Creates an Oid object from its DER encoding.  This refers to the full
3486     encoding including tag and length.  The structure and encoding of
3487     Oids is defined in ISOIEC-8824 and ISOIEC-8825.  This method is
3488     identical in functionality to its byte array counterpart.
3489  
3490     Parameters:
3491  
3492     derOid              Byte array storing a DER-encoded oid.
3493  
3494  7.7.2.  toString
3495  
3496     public String toString()
3497  
3498     Returns a string representation of the oid's integer components in
3499     dot separated notation (e.g., "1.2.840.113554.1.2.2").
3500  
3501  7.7.3.  equals
3502  
3503     public boolean equals(Object Obj)
3504  
3505     Returns "true" if the two Oid objects represent the same oid value.
3506     (Note that the Java language specification [JLS] requires that two
3507     objects that are equal according to the equals(Object) method MUST
3508     return the same integer result when the hashCode() method is called
3509     on them.)
3510  
3511     Parameters:
3512  
3513     obj                 Another Oid object with which to compare.
3514  
3515  7.7.4.  getDER
3516  
3517     public byte[] getDER()
3518  
3519     Returns the full ASN.1 DER encoding for this oid object, which
3520     includes the tag and length.
3521  
3522  7.7.5.  containedIn
3523  
3524     public boolean containedIn(Oid[] oids)
3525  
3526     A utility method to test if an Oid object is contained within the
3527     supplied Oid object array.
3528  
3529     Parameters:
3530  
3531     oids                An array of oids to search.
3532  
3533  7.8.  public class GSSException extends Exception
3534  
3535     This exception is thrown whenever a fatal GSS-API error occurs
3536     including mechanism-specific errors.  It MAY contain both, the major
3537     and minor, GSS-API status codes.  The mechanism implementors are
3538     responsible for setting appropriate minor status codes when throwing
3539     this exception.  Aside from delivering the numeric error code(s) to
3540     the caller, this class performs the mapping from their numeric values
3541     to textual representations.  This exception MAY also include an
3542     output token that SHOULD be sent to the peer.  For example, when an
3543     initSecContext call fails due to a fatal error, the mechanism MAY
3544     define an error token that SHOULD be sent to the peer for debugging
3545     or informational purpose.  All Java GSS-API methods are declared
3546     throwing this exception.
3547  
3548     All implementations are encouraged to use the Java
3549     internationalization techniques to provide local translations of the
3550     message strings.
3551  
3552  7.8.1.  Static Constants
3553  
3554     All valid major GSS-API error code values are declared as constants
3555     in this class.
3556  
3557     public static final int BAD_BINDINGS
3558  
3559     Channel bindings mismatch error.  The value of this constant is 1.
3560  
3561     public static final int BAD_MECH
3562  
3563     Unsupported mechanism requested error.  The value of this constant is
3564     2.
3565  
3566     public static final int BAD_NAME
3567  
3568     Invalid name provided error.  The value of this constant is 3.
3569  
3570     public static final int BAD_NAMETYPE
3571  
3572     Name of unsupported type provided error.  The value of this constant
3573     is 4.
3574  
3575     public static final int BAD_STATUS
3576  
3577     Invalid status code error - this is the default status value.  The
3578     value of this constant is 5.
3579  
3580     public static final int BAD_MIC
3581  
3582     Token had invalid integrity check error.  The value of this constant
3583     is 6.
3584  
3585     public static final int CONTEXT_EXPIRED
3586  
3587     Specified security context expired error.  The value of this constant
3588     is 7.
3589  
3590     public static final int CREDENTIALS_EXPIRED
3591  
3592     Expired credentials detected error.  The value of this constant is 8.
3593  
3594     public static final int DEFECTIVE_CREDENTIAL
3595  
3596     Defective credential error.  The value of this constant is 9.
3597  
3598     public static final int DEFECTIVE_TOKEN
3599  
3600     Defective token error.  The value of this constant is 10.
3601  
3602     public static final int FAILURE
3603  
3604     General failure, unspecified at GSS-API level.  The value of this
3605     constant is 11.
3606  
3607     public static final int NO_CONTEXT
3608  
3609     Invalid security context error.  The value of this constant is 12.
3610  
3611     public static final int NO_CRED
3612  
3613     Invalid credentials error.  The value of this constant is 13.
3614  
3615     public static final int BAD_QOP
3616  
3617     Unsupported QOP value error.  The value of this constant is 14.
3618  
3619     public static final int UNAUTHORIZED
3620  
3621     Operation unauthorized error.  The value of this constant is 15.
3622  
3623     public static final int UNAVAILABLE
3624  
3625     Operation unavailable error.  The value of this constant is 16.
3626  
3627     public static final int DUPLICATE_ELEMENT
3628  
3629     Duplicate credential element requested error.  The value of this
3630     constant is 17.
3631  
3632     public static final int NAME_NOT_MN
3633  
3634     Name contains multi-mechanism elements error.  The value of this
3635     constant is 18.
3636  
3637     public static final int DUPLICATE_TOKEN
3638  
3639     The token was a duplicate of an earlier token.  This is contained in
3640     an exception only when detected during context establishment, in
3641     which case it is considered a fatal error.  (Non-fatal supplementary
3642     codes are indicated via the MessageProp object.)  The value of this
3643     constant is 19.
3644  
3645     public static final int OLD_TOKEN
3646  
3647     The token's validity period has expired.  This is contained in an
3648     exception only when detected during context establishment, in which
3649     case it is considered a fatal error.  (Non-fatal supplementary codes
3650     are indicated via the MessageProp object.)  The value of this
3651     constant is 20.
3652  
3653     public static final int UNSEQ_TOKEN
3654  
3655     A later token has already been processed.  This is contained in an
3656     exception only when detected during context establishment, in which
3657     case it is considered a fatal error.  (Non-fatal supplementary codes
3658     are indicated via the MessageProp object.)  The value of this
3659     constant is 21.
3660  
3661     public static final int GAP_TOKEN
3662  
3663     An expected per-message token was not received.  This is contained in
3664     an exception only when detected during context establishment, in
3665     which case it is considered a fatal error.  (Non-fatal supplementary
3666     codes are indicated via the MessageProp object.)  The value of this
3667     constant is 22.
3668  
3669  7.8.2.  Constructors
3670  
3671     public GSSException(int majorCode)
3672  
3673     Creates a GSSException object with a specified major code.
3674  
3675     Calling this constructor is equivalent to calling
3676     GSSException(majorCode, null, 0, null, null).
3677  
3678     public GSSException(int majorCode, int minorCode, String minorString)
3679  
3680     Creates a GSSException object with the specified major code, minor
3681     code, and minor code textual explanation.  This constructor is to be
3682     used when the exception is originating from the security mechanism.
3683     It allows to specify the GSS code and the mechanism code.
3684  
3685     Calling this constructor is equivalent to calling
3686     GSSException(majorCode, null, minorCode, minorString, null).
3687  
3688     public GSSException(int majorCode, String majorString,
3689                         int minorCode, String minorString,
3690                         byte[] outputToken)
3691  
3692     Creates a GSSException object with the specified major code, major
3693     code textual explanation, minor code, minor code textual explanation,
3694     and an output token.  This is a general-purpose constructor that can
3695     be used to create any type of GSSException.
3696  
3697     Parameters:
3698  
3699     majorCode           The GSS error code causing this exception to be
3700                         thrown.
3701  
3702     majorString         The textual explanation of the GSS error code.
3703                         If null is provided, a default explanation that
3704                         matches the majorCode will be set.
3705  
3706     minorCode           The mechanism error code causing this exception
3707                         to be thrown.  Can be 0 if no mechanism error
3708                         code is available.
3709  
3710     minorString         The textual explanation of the mechanism error
3711                         code.  Can be null if no textual explanation is
3712                         available.
3713  
3714     outputToken         The output token that SHOULD be sent to the peer.
3715                         Can be null if no such token is available.  It
3716                         MUST NOT be an empty array.  When provided, the
3717                         array will be cloned to protect against
3718                         subsequent modifications.
3719  
3720  7.8.3.  getMajor
3721  
3722     public int getMajor()
3723  
3724     Returns the major code representing the GSS error code that caused
3725     this exception to be thrown.
3726  
3727  7.8.4.  getMinor
3728  
3729     public int getMinor()
3730  
3731     Returns the mechanism error code that caused this exception.  The
3732     minor code is set by the underlying mechanism.  Value of 0 indicates
3733     that mechanism error code is not set.
3734  
3735  7.8.5.  getMajorString
3736  
3737     public String getMajorString()
3738  
3739     Returns a string explaining the GSS major error code causing this
3740     exception to be thrown.
3741  
3742  7.8.6.  getMinorString
3743  
3744     public String getMinorString()
3745  
3746     Returns a string explaining the mechanism-specific error code. "null"
3747     will be returned when no string explaining the mechanism error code
3748     has been set.
3749  
3750  7.8.7.  getOutputToken
3751  
3752     public byte[] getOutputToken
3753  
3754     Returns the output token in a new byte array.
3755  
3756     If the method (For example, GSSContext#initSecContext) that throws
3757     this GSSException needs to generate an output token that SHOULD be
3758     sent to the peer, that token will be stored in this GSSException and
3759     can be retrieved with this method.
3760  
3761     The return value MUST be null if no such token is generated.  It MUST
3762     NOT be an empty byte array.
3763  
3764  7.8.8.  setMinor
3765  
3766     public void setMinor(int minorCode, String message)
3767  
3768     Used internally by the GSS-API implementation and the underlying
3769     mechanisms to set the minor code and its textual representation.
3770  
3771     Parameters:
3772  
3773     minorCode           The mechanism-specific error code.
3774  
3775     message             A textual explanation of the mechanism error
3776                         code.
3777  
3778  7.8.9.  toString
3779  
3780     public String toString()
3781  
3782     Returns a textual representation of both the major and minor status
3783     codes.
3784  
3785  7.8.10.  getMessage
3786  
3787     public String getMessage()
3788  
3789     Returns a detailed message of this exception.  Overrides
3790     Throwable.getMessage.  It is customary in Java to use this method to
3791     obtain exception information.
3792  
3793  8.  Sample Applications
3794  
3795  8.1.  Simple GSS Context Initiator
3796  
3797     <CODE BEGINS>
3798     import org.ietf.jgss.*;
3799  
3800     /**
3801      * This is a partial sketch for a simple client program that acts
3802      * as a GSS context initiator.  It illustrates how to use the Java
3803      * bindings for the GSS-API specified in
3804      * Generic Security Service API Version 2 : Java bindings
3805      *
3806      *
3807      * This code sketch assumes the existence of a GSS-API
3808      * implementation that supports the mechanism that it will need
3809      * and is present as a library package (org.ietf.jgss) either as
3810      * part of the standard JRE or in the CLASSPATH the application
3811      * specifies.
3812      */
3813  
3814      public class SimpleClient {
3815  
3816          private String serviceName; // name of peer (i.e., server)
3817          private GSSCredential clientCred = null;
3818          private GSSContext context = null;
3819          private Oid mech; // underlying mechanism to use
3820  
3821          private GSSManager mgr = GSSManager.getInstance();
3822  
3823          ...
3824          ...
3825  
3826          private void clientActions() {
3827             initializeGSS();
3828             establishContext();
3829             doCommunication();
3830          }
3831  
3832         /**
3833          * Acquire credentials for the client.
3834          */
3835         private void initializeGSS() {
3836  
3837             try {
3838  
3839                 clientCred = mgr.createCredential(null /*default princ*/,
3840                     GSSCredential.INDEFINITE_LIFETIME /* max lifetime */,
3841                     mech /* mechanism to use */,
3842                     GSSCredential.INITIATE_ONLY /* init context */);
3843  
3844                 print("GSSCredential created for " +
3845                         cred.getName().toString());
3846                 print("Credential lifetime (sec)=" +
3847                         cred.getRemainingLifetime());
3848             } catch (GSSException e) {
3849                 print("GSS-API error in credential acquisition: "
3850                       + e.getMessage());
3851                 ...
3852                 ...
3853             }
3854             ...
3855             ...
3856         }
3857  
3858         /**
3859          * Does the security context establishment with the
3860          * server.
3861          */
3862         private void establishContext() {
3863  
3864             byte[] inToken = new byte[0];
3865             byte[] outToken = null;
3866  
3867             try {
3868  
3869                 GSSName peer = mgr.createName(serviceName,
3870                                       GSSName.NT_HOSTBASED_SERVICE);
3871                 context = mgr.createContext(peer, mech, gssCred,
3872                        GSSContext.INDEFINITE_LIFETIME/*lifetime*/);
3873  
3874                 // Will need to support confidentiality
3875                 context.requestConf(true);
3876  
3877                 while (!context.isEstablished()) {
3878  
3879                     outToken = context.initSecContext(inToken, 0,
3880                                                     inToken.length);
3881  
3882                     if (outToken != null)
3883                         writeGSSToken(outToken);
3884  
3885                     if (!context.isEstablished())
3886                         inToken = readGSSToken();
3887                 }
3888  
3889                 GSSName peer = context.getSrcName();
3890                 print("Security context established with " + peer +
3891                       " using underlying mechanism " + mech.toString());
3892             } catch (GSSException e) {
3893                  print("GSS-API error during context establishment: "
3894                        + e.getMessage());
3895  
3896                  // If the exception contains an output token,
3897                  // it should be sent to the acceptor.
3898                  byte[] outTok = e.getOutputToken();
3899                  if (outTok != null) {
3900                      writeGSSToken(outTok);
3901                  }
3902                  ...
3903                  ...
3904             }
3905             ...
3906             ...
3907         }
3908  
3909         /**
3910          * Sends some data to the server and reads back the
3911          * response.
3912          */
3913         private void doCommunication()  {
3914             byte[] inToken = null;
3915             byte[] outToken = null;
3916             byte[] buffer;
3917  
3918             // Container for multiple input-output arguments to and
3919             // from the per-message routines (e.g., wrap/unwrap).
3920             MessageProp messgInfo = new MessageProp();
3921  
3922             try {
3923  
3924                 /*
3925                  * Now send some bytes to the server to be
3926                  * processed.  They will be integrity protected
3927                  * but not encrypted for privacy.
3928                  */
3929  
3930                 buffer = readFromFile();
3931  
3932                 // Set privacy to "false" and use the default QOP
3933                 messgInfo.setPrivacy(false);
3934  
3935                 outToken = context.wrap(buffer, 0, buffer.length,
3936                                         messgInfo);
3937  
3938                 writeGSSToken(outToken);
3939  
3940                 /*
3941                  * Now read the response from the server.
3942                  */
3943  
3944                 inToken = readGSSToken();
3945                 buffer = context.unwrap(inToken, 0,
3946                               inToken.length, messgInfo);
3947                 // All ok if no exception was thrown!
3948  
3949                 GSSName peer = context.getSrcName();
3950  
3951                 print("Message from "  + peer.toString()
3952                       + " arrived.");
3953                 print("Was it encrypted? "  +
3954                       messgInfo.getPrivacy());
3955                 print("Duplicate Token? "   +
3956                       messgInfo.isDuplicateToken());
3957                 print("Old Token? "         +
3958                       messgInfo.isOldToken());
3959                 print("Unsequenced Token? " +
3960                       messgInfo.isUnseqToken());
3961                 print("Gap Token? "         +
3962                       messgInfo.isGapToken());
3963                 ...
3964                 ...
3965             } catch (GSSException e) {
3966                 print("GSS-API error in per-message calls: "
3967                       + e.getMessage());
3968                 ...
3969                 ...
3970             }
3971             ...
3972             ...
3973         } // end of doCommunication method
3974  
3975         ...
3976         ...
3977  
3978     } // end of class SimpleClient
3979     <CODE ENDS>
3980  
3981  8.2.  Simple GSS Context Acceptor
3982  
3983     <CODE BEGINS>
3984     import org.ietf.jgss.*;
3985  
3986     /**
3987      * This is a partial sketch for a simple server program that acts
3988      * as a GSS context acceptor.  It illustrates how to use the Java
3989      * bindings for the GSS-API specified in
3990      * Generic Security Service API Version 2 : Java bindings.
3991      *
3992      * This code sketch assumes the existence of a GSS-API
3993      * implementation that supports the mechanisms that it will need
3994      * and is present as a library package (org.ietf.jgss) either as
3995      * part of the standard JRE or in the CLASSPATH the application
3996      * specifies.
3997      */
3998  
3999     import org.ietf.jgss.*;
4000  
4001     public class SimpleServer {
4002  
4003         private String serviceName;
4004         private GSSName name;
4005         private GSSCredential cred;
4006  
4007         private GSSManager mgr;
4008  
4009         ...
4010         ...
4011  
4012         /**
4013          * Wait for client connections, establish security contexts
4014          * and provide service.
4015          */
4016         private void loop() {
4017             ...
4018             ...
4019             mgr = GSSManager.getInstance();
4020  
4021             name = mgr.createName(serviceName,
4022                       GSSName.NT_HOSTBASED_SERVICE);
4023  
4024             cred = mgr.createCredential(name,
4025                       GSSCredential.INDEFINITE_LIFETIME,
4026                       null,
4027                       GSSCredential.ACCEPT_ONLY);
4028  
4029             // Loop infinitely
4030             while (true) {
4031                 Socket s = serverSock.accept();
4032  
4033                 // Start a new thread to serve this connection
4034                 Thread serverThread = new ServerThread(s);
4035                 serverThread.start();
4036             }
4037         }
4038  
4039         /**
4040          * Inner class ServerThread whose run() method provides the
4041          * secure service to a connection.
4042          */
4043  
4044         private class ServerThread extends Thread {
4045  
4046             ...
4047             ...
4048  
4049             /**
4050              * Deals with the connection from one client.  It also
4051              * handles all GSSException's thrown while talking to
4052              * this client.
4053              */
4054             public void run() {
4055  
4056                 byte[] inToken = null;
4057                 byte[] outToken = null;
4058                 byte[] buffer;
4059  
4060                 GSSName peer;
4061  
4062                 // Container for multiple input-output arguments to
4063                 // and from the per-message routines
4064                 // (i.e., wrap/unwrap).
4065                 MessageProp supplInfo = new MessageProp();
4066                 GSSContext secContext = null;
4067  
4068                 try {
4069                     // Now do the context establishment loop
4070                     GSSContext context = mgr.createContext(cred);
4071  
4072                     while (!context.isEstablished()) {
4073  
4074                         inToken = readGSSToken();
4075                         outToken = context.acceptSecContext(inToken,
4076                                                  0, inToken.length);
4077                         if (outToken != null)
4078                             writeGSSToken(outToken);
4079                     }
4080  
4081                     // SimpleServer wants confidentiality to be
4082                     // available.  Check for it.
4083                     if (!context.getConfState()){
4084                         ...
4085                         ...
4086                     }
4087  
4088                     GSSName peer = context.getSrcName();
4089                     Oid mech = context.getMech();
4090                     print("Security context established with " +
4091                            peer.toString() +
4092                           " using underlying mechanism " +
4093                           mech.toString() +
4094                           " from Provider " +
4095                           context.getProvider().getName());
4096  
4097                     // Now read the bytes sent by the client to be
4098                     // processed.
4099                     inToken = readGSSToken();
4100  
4101                     // Unwrap the message
4102                     buffer = context.unwrap(inToken, 0,
4103                                 inToken.length, supplInfo);
4104                     // All ok if no exception was thrown!
4105  
4106                     // Print other supplementary per-message status
4107                     // information.
4108  
4109                     print("Message from " +
4110                             peer.toString() + " arrived.");
4111                     print("Was it encrypted? " +
4112                             supplInfo.getPrivacy());
4113                     print("Duplicate Token? " +
4114                             supplInfo.isDuplicateToken());
4115                     print("Old Token? "  + supplInfo.isOldToken());
4116                     print("Unsequenced Token? " +
4117                             supplInfo.isUnseqToken());
4118                     print("Gap Token? "  + supplInfo.isGapToken());
4119  
4120                     /*
4121                      * Now process the bytes and send back an
4122                      * encrypted response.
4123                      */
4124  
4125                     buffer = serverProcess(buffer);
4126  
4127                     // Encipher it and send it across
4128  
4129                     supplInfo.setPrivacy(true); // privacy requested
4130                     supplInfo.setQOP(0); // default QOP
4131                     outToken = context.wrap(buffer, 0, buffer.length,
4132                                                supplInfo);
4133                     writeGSSToken(outToken);
4134  
4135                 } catch (GSSException e) {
4136                     print("GSS-API Error: " + e.getMessage());
4137                     // Alternatively, could call e.getMajorMessage()
4138                     // and e.getMinorMessage()
4139  
4140                     // If the exception contains an output token,
4141                     // it should be sent to the initiator.
4142                     byte[] outTok = e.getOutputToken();
4143                     if (outTok != null) {
4144                         writeGSSToken(outTok);
4145                     }
4146                     print("Abandoning security context.");
4147                     ...
4148                     ...
4149                 }
4150                 ...
4151                 ...
4152             } // end of run method in ServerThread
4153  
4154         } // end of inner class ServerThread
4155  
4156         ...
4157         ...
4158  
4159     } // end of class SimpleServer
4160     <CODE ENDS>
4161  
4162  9.  Security Considerations
4163  
4164     The Java language security model allows platform providers to have
4165     policy-based fine-grained access control over any resource that an
4166     application wants.  When using a Java security manager (such as, but
4167     not limited to, the case of applets running in browsers) the
4168     application code is in a sandbox by default.
4169  
4170     Administrators of the platform JRE determine what permissions, if
4171     any, are to be given to source from different codebases.  Thus, the
4172     administrator has to be aware of any special requirements that the
4173     GSS provider might have for system resources.  For instance, a
4174     Kerberos provider might wish to make a network connection to the Key
4175     Distribution Center (KDC) to obtain initial credentials.  This would
4176     not be allowed under the sandbox unless the administrator had granted
4177     permissions for this.  Also, note that this granting and checking of
4178     permissions happens transparently to the application and is outside
4179     the scope of this document.
4180  
4181     The Java language allows administrators to pre-configure a list of
4182     security service providers in the <JRE>/lib/security/java.security
4183     file.  At runtime, the system approaches these providers in order of
4184     preference when looking for security related services.  Applications
4185     have a means to modify this list through methods in the "Security"
4186     class in the "java.security" package.  However, since these
4187     modifications would be visible in the entire Java Virtual Machine
4188     (JVM) and thus affect all code executing in it, this operation is not
4189     available in the sandbox and requires special permissions to perform.
4190     Thus, when a GSS application has special needs that are met by a
4191     particular security provider, it has two choices:
4192  
4193     1) To install the provider on a JVM-wide basis using the
4194        java.security.Security class and then depend on the system to find
4195        the right provider automatically when the need arises.  (This
4196        would require the application to be granted a "insertProvider
4197        SecurityPermission".)
4198  
4199     2) To pass an instance of the provider to the local instance of
4200        GSSManager so that only factory calls going through that
4201        GSSManager use the desired provider.  (This would not require any
4202        permissions.)
4203  
4204  10.  IANA Considerations
4205  
4206     This document has no actions for IANA.
4207  
4208  11.  Acknowledgments
4209  
4210     This proposed API leverages earlier work performed by the IETF's CAT
4211     WG as outlined in both RFC 2743 [RFC2743] and RFC 2744 [RFC2744].
4212     Many conceptual definitions, implementation directions, and
4213     explanations have been included from these documents.
4214  
4215     We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael
4216     Saltz, and other members of Sun's development team for their helpful
4217     input, comments, and suggestions.
4218  
4219     We would also like to thank Joe Salowey, and Michael Smith for many
4220     insightful ideas and suggestions that have contributed to this
4221     document.
4222  
4223  12.  Changes since RFC 5653
4224  
4225     This document has following changes:
4226  
4227     1) New error token embedded in GSSException
4228  
4229        There is a design flaw in the initSecContext and acceptSecContext
4230        methods of the GSSContext class defined in Generic Security
4231        Service API Version 2: Java Bindings Update [RFC5653].
4232  
4233        The methods could either return a token (possibly null if no more
4234        tokens are needed) when the call succeeds or throw a GSSException
4235        if there is a failure, but NOT both.  On the other hand, the C
4236        bindings of GSS-API [RFC2744] can return both, that is to say, a
4237        call to the GSS_Init_sec_context() function can return a major
4238        status code, and at the same time, fill in the output_token
4239        argument if there is one.
4240  
4241        Without the ability to emit an error token when there is a
4242        failure, a Java application has no mechanism to tell the other
4243        side what the error is.  For example, a "reject" NegTokenResp
4244        token can never be transmitted for the SPNEGO mechanism [RFC4178].
4245  
4246        While a Java method can never return a value and throw an
4247        exception at the same time, we can embed the error token inside
4248        the exception so that the caller has a chance to retrieve it.
4249        This update adds a new GSSException constructor to include this
4250        token inside a GSSException object, and a getOutputToken() method
4251        to retrieve the token.  The specification for the initSecContext
4252        and acceptSecContext methods are updated to describe the new
4253        behavior.  Various examples are also updated.
4254  
4255        New JGSS programs SHOULD make use of this new feature but it is
4256        not mandatory.  A program that intends to run with both old and
4257        new GSS Java bindings can use reflection to check the availability
4258        of this new method and call it accordingly.
4259  
4260     2) Removing stream-based GSSContext methods
4261  
4262        The overloaded methods of GSSContext that use input and output
4263        streams as the means to convey authentication and per-message GSS-
4264        API tokens as described in Section 5.15 of RFC 5653 [RFC5653] are
4265        removed in this update as the wire protocol should be defined by
4266        an application and not a library.  It's also impossible to
4267        implement these methods correctly when the token has no self-
4268        framing (where the end cannot be determined) or the library has no
4269        knowledge of the token format (for example, as a bridge talking to
4270        another GSS library).  These methods include initSecContext
4271        (Section 7.4.5 of RFC 5653 [RFC5653]), acceptSecContext
4272        (Section 7.4.9 of RFC 5653 [RFC5653]), wrap (Section 7.4.15 of RFC
4273        5653 [RFC5653]), unwrap (Section 7.4.17 of RFC 5653 [RFC5653]),
4274        getMIC (Section 7.4.19 of RFC 5653 [RFC5653]), and verifyMIC
4275        (Section 7.4.21 of RFC 5653 [RFC5653]).
4276  
4277  13.  Changes since RFC 2853
4278  
4279     This document has following changes:
4280  
4281     1) Major GSS Status Code Constant Values
4282  
4283        RFC 2853 listed all the GSS status code values in two different
4284        sections: section 4.12.1 defined numeric values for them, and
4285        section 6.8.1 defined them as static constants in the GSSException
4286        class without assigning any values.  Due to an inconsistent
4287        ordering between these two sections, all of the GSS major status
4288        codes resulted in misalignment, and a subsequent disagreement
4289        between deployed implementations.
4290  
4291        This document defines the numeric values of the GSS status codes
4292        in both sections, while maintaining the original ordering from
4293        section 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status
4294        code values defined in section 4.12.1.  The relevant sections in
4295        this document are sections 5.12.1 and 7.8.1.
4296  
4297     2) GSS Credential Usage Constant Values
4298  
4299        RFC 2853 section 6.3.2 defines static constants for the
4300        GSSCredential usage flags.  However, the values of these constants
4301        were not defined anywhere in RFC 2853 [RFC2853].
4302  
4303        This document defines the credential usage values in section
4304        7.3.1.  The original ordering of these values from section 6.3.2
4305        of RFC 2853 [RFC2853] is maintained.
4306  
4307     3) GSS Host-Based Service Name
4308  
4309        RFC 2853 [RFC2853], section 6.2.2, defines the static constant for
4310        the GSS host-based service OID NT_HOSTBASED_SERVICE, using a
4311        deprecated OID value.
4312  
4313        This document updates the NT_HOSTBASED_SERVICE OID value in
4314        section 7.2.1 to be consistent with the C-bindings in RFC 2744
4315        [RFC2744].
4316  
4317  14.  References
4318  
4319  14.1.  Normative References
4320  
4321     [RFC2025]  Adams, C., "The Simple Public-Key GSS-API Mechanism
4322                (SPKM)", RFC 2025, DOI 10.17487/RFC2025, October 1996,
4323                <https://www.rfc-editor.org/info/rfc2025>.
4324  
4325     [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
4326                Requirement Levels", BCP 14, RFC 2119,
4327                DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
4328                editor.org/info/rfc2119>.
4329  
4330     [RFC2743]  Linn, J., "Generic Security Service Application Program
4331                Interface Version 2, Update 1", RFC 2743,
4332                DOI 10.17487/RFC2743, January 2000, <https://www.rfc-
4333                editor.org/info/rfc2743>.
4334  
4335     [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
4336                C-bindings", RFC 2744, DOI 10.17487/RFC2744, January 2000,
4337                <https://www.rfc-editor.org/info/rfc2744>.
4338  
4339     [RFC2853]  Kabat, J. and M. Upadhyay, "Generic Security Service API
4340                Version 2 : Java Bindings", RFC 2853,
4341                DOI 10.17487/RFC2853, June 2000, <https://www.rfc-
4342                editor.org/info/rfc2853>.
4343  
4344     [RFC4121]  Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
4345                Version 5 Generic Security Service Application Program
4346                Interface (GSS-API) Mechanism: Version 2", RFC 4121,
4347                DOI 10.17487/RFC4121, July 2005, <https://www.rfc-
4348                editor.org/info/rfc4121>.
4349  
4350     [RFC4178]  Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
4351                Simple and Protected Generic Security Service Application
4352                Program Interface (GSS-API) Negotiation Mechanism",
4353                RFC 4178, DOI 10.17487/RFC4178, October 2005,
4354                <https://www.rfc-editor.org/info/rfc4178>.
4355  
4356     [RFC5653]  Upadhyay, M. and S. Malkani, "Generic Security Service API
4357                Version 2: Java Bindings Update", RFC 5653,
4358                DOI 10.17487/RFC5653, August 2009, <https://www.rfc-
4359                editor.org/info/rfc5653>.
4360  
4361     [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
4362                2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
4363                May 2017, <https://www.rfc-editor.org/info/rfc8174>.
4364  
4365  14.2.  Informative References
4366  
4367     [JLS]      Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java
4368                Language Specification", Third Edition, 2005,
4369                <http://java.sun.com/docs/books/jls/>.
4370  
4371  Authors' Addresses
4372  
4373     Mayank D. Upadhyay
4374     Google Inc.
4375     1600 Amphitheatre Parkway
4376     Mountain View, CA  94043
4377     USA
4378  
4379     Email: m.d.upadhyay+ietf@gmail.com
4380  
4381  
4382     Seema Malkani
4383     ActivIdentity Corp.
4384     6623 Dumbarton Circle
4385     Fremont, California  94555
4386     USA
4387  
4388     Email: Seema.Malkani@gmail.com
4389  
4390  
4391     Wang Weijun
4392     Oracle
4393     Building No. 24, Zhongguancun Software Park
4394     Beijing  100193
4395     China
4396  
4397     Email: weijun.wang@oracle.com
4398