tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 5653

Proposed STD
Pages: 99
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: KITTEN

Generic Security Service API Version 2: Java Bindings Update

Part 1 of 5, p. 1 to 14
None       Next RFC Part

Obsoletes:    2853


Top       ToC       Page 1 
Network Working Group                                        M. Upadhyay
Request for Comments: 5653                                        Google
Obsoletes: 2853                                               S. Malkani
Category: Standards Track                                  ActivIdentity
                                                             August 2009


      Generic Security Service API Version 2: Java Bindings Update

Abstract

   The Generic Security Services Application Program Interface (GSS-API)
   offers application programmers uniform access to security services
   atop a variety of underlying cryptographic mechanisms.  This document
   updates the Java bindings for the GSS-API that are specified in
   "Generic Security Service API Version 2 : Java Bindings" (RFC 2853).
   This document obsoletes RFC 2853 by making specific and incremental
   clarifications and corrections to it in response to identification of
   transcription errors and implementation experience.

   The GSS-API is described at a language-independent conceptual level
   in "Generic Security Service Application Program Interface Version 2,
   Update 1" (RFC 2743).  The GSS-API allows a caller application to
   authenticate a principal identity, to delegate rights to a peer, and
   to apply security services such as confidentiality and integrity on a
   per-message basis.  Examples of security mechanisms defined for GSS-
   API are "The Simple Public-Key GSS-API Mechanism" (RFC 2025) and "The
   Kerberos Version 5 Generic Security Service Application Program
   Interface (GSS-API) Mechanism: Version 2" (RFC 4121).

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (c) 2009 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Page 2 
   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.

Table of Contents

   1. Introduction ....................................................6
   2. Conventions and Licenses ........................................7
   3. GSS-API Operational Paradigm ....................................8
   4. Additional Controls .............................................9
      4.1. Delegation ................................................10
      4.2. Mutual Authentication .....................................11
      4.3. Replay and Out-of-Sequence Detection ......................11
      4.4. Anonymous Authentication ..................................12
      4.5. Confidentiality ...........................................13
      4.6. Inter-process Context Transfer ............................13
      4.7. The Use of Incomplete Contexts ............................14
   5. Calling Conventions ............................................15
      5.1. Package Name ..............................................15
      5.2. Provider Framework ........................................15
      5.3. Integer Types .............................................16
      5.4. Opaque Data Types .........................................16
      5.5. Strings ...................................................16
      5.6. Object Identifiers ........................................16
      5.7. Object Identifier Sets ....................................17
      5.8. Credentials ...............................................17
      5.9. Contexts ..................................................19
      5.10. Authentication Tokens ....................................19
      5.11. Inter-Process Tokens .....................................20
      5.12. Error Reporting ..........................................20
           5.12.1. GSS Status Codes ..................................21
           5.12.2. Mechanism-Specific Status Codes ...................23
           5.12.3. Supplementary Status Codes ........................23
      5.13. Names ....................................................24
      5.14. Channel Bindings .........................................26
      5.15. Stream Objects ...........................................27
      5.16. Optional Parameters ......................................28
   6. Introduction to GSS-API Classes and Interfaces .................28
      6.1. GSSManager Class ..........................................28
      6.2. GSSName Interface .........................................29

Top      ToC       Page 3 
      6.3. GSSCredential Interface ...................................30
      6.4. GSSContext Interface ......................................30
      6.5. MessageProp Class .........................................31
      6.6. GSSException Class ........................................32
      6.7. Oid Class .................................................32
      6.8. ChannelBinding Class ......................................32
   7. Detailed GSS-API Class Description .............................33
      7.1. public abstract class GSSManager ..........................33
           7.1.1. Example Code .......................................34
           7.1.2. getInstance ........................................34
           7.1.3. getMechs ...........................................35
           7.1.4. getNamesForMech ....................................35
           7.1.5. getMechsForName ....................................35
           7.1.6. createName .........................................35
           7.1.7. createName .........................................36
           7.1.8. createName .........................................36
           7.1.9. createName .........................................37
           7.1.10. createCredential ..................................38
           7.1.11. createCredential ..................................38
           7.1.12. createCredential ..................................39
           7.1.13. createContext .....................................39
           7.1.14. createContext .....................................40
           7.1.15. createContext .....................................40
           7.1.16. addProviderAtFront ................................41
           7.1.17. Example Code ......................................41
           7.1.18. addProviderAtEnd ..................................42
           7.1.19. Example Code ......................................43
      7.2. public interface GSSName ..................................44
           7.2.1. Example Code .......................................44
           7.2.2. Static Constants ...................................45
           7.2.3. equals .............................................46
           7.2.4. equals .............................................46
           7.2.5. canonicalize .......................................46
           7.2.6. export .............................................47
           7.2.7. toString ...........................................47
           7.2.8. getStringNameType ..................................47
           7.2.9. isAnonymous ........................................47
           7.2.10. isMN ..............................................47
      7.3. public interface GSSCredential implements Cloneable .......47
           7.3.1. Example Code .......................................49
           7.3.2. Static Constants ...................................49
           7.3.3. dispose ............................................50
           7.3.4. getName ............................................50
           7.3.5. getName ............................................50
           7.3.6. getRemainingLifetime ...............................50
           7.3.7. getRemainingInitLifetime ...........................51
           7.3.8. getRemainingAcceptLifetime .........................51
           7.3.9. getUsage ...........................................51

Top      ToC       Page 4 
           7.3.10. getUsage ..........................................51
           7.3.11. getMechs ..........................................52
           7.3.12. add ...............................................52
           7.3.13. equals ............................................53
      7.4. public interface GSSContext ...............................53
           7.4.1. Example Code .......................................54
           7.4.2. Static Constants ...................................56
           7.4.3. initSecContext .....................................56
           7.4.4. Example Code .......................................57
           7.4.5. initSecContext .....................................58
           7.4.6. Example Code .......................................58
           7.4.7. acceptSecContext ...................................59
           7.4.8. Example Code .......................................60
           7.4.9. acceptSecContext ...................................61
           7.4.10. Example Code ......................................61
           7.4.11. isEstablished .....................................62
           7.4.12. dispose ...........................................62
           7.4.13. getWrapSizeLimit ..................................63
           7.4.14. wrap ..............................................63
           7.4.15. wrap ..............................................64
           7.4.16. unwrap ............................................65
           7.4.17. unwrap ............................................66
           7.4.18. getMIC ............................................67
           7.4.19. getMIC ............................................68
           7.4.20. verifyMIC .........................................68
           7.4.21. verifyMIC .........................................69
           7.4.22. export ............................................70
           7.4.23. requestMutualAuth .................................71
           7.4.24. requestReplayDet ..................................71
           7.4.25. requestSequenceDet ................................71
           7.4.26. requestCredDeleg ..................................71
           7.4.27. requestAnonymity ..................................72
           7.4.28. requestConf .......................................72
           7.4.29. requestInteg ......................................72
           7.4.30. requestLifetime ...................................73
           7.4.31. setChannelBinding .................................73
           7.4.32. getCredDelegState .................................73
           7.4.33. getMutualAuthState ................................73
           7.4.34. getReplayDetState .................................74
           7.4.35. getSequenceDetState ...............................74
           7.4.36. getAnonymityState .................................74
           7.4.37. isTransferable ....................................74
           7.4.38. isProtReady .......................................74
           7.4.39. getConfState ......................................75
           7.4.40. getIntegState .....................................75
           7.4.41. getLifetime .......................................75
           7.4.42. getSrcName ........................................75
           7.4.43. getTargName .......................................75

Top      ToC       Page 5 
           7.4.44. getMech ...........................................76
           7.4.45. getDelegCred ......................................76
           7.4.46. isInitiator .......................................76
      7.5. public class MessageProp ..................................76
           7.5.1. Constructors .......................................77
           7.5.2. getQOP .............................................77
           7.5.3. getPrivacy .........................................77
           7.5.4. getMinorStatus .....................................77
           7.5.5. getMinorString .....................................77
           7.5.6. setQOP .............................................78
           7.5.7. setPrivacy .........................................78
           7.5.8. isDuplicateToken ...................................78
           7.5.9. isOldToken .........................................78
           7.5.10. isUnseqToken ......................................78
           7.5.11. isGapToken ........................................78
           7.5.12. setSupplementaryStates ............................79
      7.6. public class ChannelBinding ...............................79
           7.6.1. Constructors .......................................80
           7.6.2. getInitiatorAddress ................................80
           7.6.3. getAcceptorAddress .................................80
           7.6.4. getApplicationData .................................81
           7.6.5. equals .............................................81
      7.7. public class Oid ..........................................81
           7.7.1. Constructors .......................................81
           7.7.2. toString ...........................................82
           7.7.3. equals .............................................82
           7.7.4. getDER .............................................82
           7.7.5. containedIn ........................................83
      7.8. public class GSSException extends Exception ...............83
           7.8.1. Static Constants ...................................83
           7.8.2. Constructors .......................................86
           7.8.3. getMajor ...........................................86
           7.8.4. getMinor ...........................................86
           7.8.5. getMajorString .....................................87
           7.8.6. getMinorString .....................................87
           7.8.7. setMinor ...........................................87
           7.8.8. toString ...........................................87
           7.8.9. getMessage .........................................87
   8. Sample Applications ............................................88
      8.1. Simple GSS Context Initiator ..............................88
      8.2. Simple GSS Context Acceptor ...............................92
   9. Security Considerations ........................................96
   10. Acknowledgments ...............................................96
   11. Changes since RFC 2853 ........................................97
   12. References ....................................................98
      12.1. Normative References .....................................98
      12.2. Informative References ...................................98

Top      ToC       Page 6 
1.  Introduction

   This document specifies Java language bindings for the Generic
   Security Services Application Programming Interface version 2 (GSS-
   API).  GSS-API version 2 is described in a language-independent
   format in RFC 2743 [GSSAPIv2-UPDATE].  The GSS-API allows a caller
   application to authenticate a principal identity, to delegate rights
   to a peer, and to apply security services such as confidentiality and
   integrity on a per-message basis.

   This document and its predecessor, RFC 2853 [RFC2853], leverage the
   work done by the working group (WG) in the area of RFC 2743
   [GSSAPIv2-UPDATE] and the C-bindings of RFC 2744 [GSSAPI-Cbind].
   Whenever appropriate, text has been used from the C-bindings document
   (RFC 2744) to explain generic concepts and provide direction to the
   implementors.

   The design goals of this API have been to satisfy all the
   functionality defined in RFC 2743 [GSSAPIv2-UPDATE] and to provide
   these services in an object-oriented method.  The specification also
   aims to satisfy the needs of both types of Java application
   developers, those who would like access to a "system-wide" GSS-API
   implementation, as well as those who would want to provide their own
   "custom" implementation.

   A system-wide implementation is one that is available to all
   applications in the form of a library package.  It may be the
   standard package in the Java runtime environment (JRE) being used or
   it may be additionally installed and accessible to any application
   via the CLASSPATH.

   A custom implementation of the GSS-API, on the other hand, is one
   that would, in most cases, be bundled with the application during
   distribution.  It is expected that such an implementation would be
   meant to provide for some particular need of the application, such as
   support for some specific mechanism.

   The design of this API also aims to provide a flexible framework to
   add and manage GSS-API mechanisms.  GSS-API leverages the Java
   Cryptography Architecture (JCA) provider model to support the
   plugability of mechanisms.  Mechanisms can be added on a system-wide
   basis, where all users of the framework will have them available.
   The specification also allows for the addition of mechanisms per-
   instance of the GSS-API.

   Lastly, this specification presents an API that will naturally fit
   within the operation environment of the Java platform.  Readers are
   assumed to be familiar with both the GSS-API and the Java platform.

Top      ToC       Page 7 
2.  Conventions and Licenses

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   The following license applies to all code segments included in this
   specification.  If code is extracted from this specification, please
   include the following text in the code:

/*
--   Copyright (c) 2009 IETF Trust and the persons identified as
--   authors of the code.  All rights reserved.
--
--   Redistribution and use in source and binary forms, with or without
--   modification, are permitted provided that the following conditions
--   are met:
--
--   - Redistributions of source code must retain the above copyright
--     notice, this list of conditions and the following disclaimer.
--
--   - Redistributions in binary form must reproduce the above copyright
--     notice, this list of conditions and the following disclaimer in
--     the documentation and/or other materials provided with the
--     distribution.
--
--   - Neither the name of Internet Society, IETF or IETF Trust, nor the
--     names of specific contributors, may be used to endorse or promote
--     products derived from this software without specific prior
--     written permission.
--
--   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
--   CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES,
--   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
--   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
--   DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
--   BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
--   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
--   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
--   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
--   ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
--   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
--   OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
--   POSSIBILITY OF SUCH DAMAGE.
--
--   This code is part of RFC 5653; see the RFC itself for full legal
--   notices.
*/

Top      ToC       Page 8 
3.  GSS-API Operational Paradigm

   "Generic Security Service Application Programming Interface, Version
   2" [GSSAPIv2-UPDATE] defines a generic security API to calling
   applications.  It allows a communicating application to authenticate
   the user associated with another application, to delegate rights to
   another application, and to apply security services such as
   confidentiality and integrity on a per-message basis.

   There are four stages to using GSS-API:

   1) The application acquires a set of credentials with which it may
      prove its identity to other processes.  The application's
      credentials vouch for its global identity, which may or may not be
      related to any local username under which it may be running.

   2) A pair of communicating applications establish a joint security
      context using their credentials.  The security context
      encapsulates shared state information, which is required in order
      that per-message security services may be provided.  Examples of
      state information that might be shared between applications as
      part of a security context are cryptographic keys and message
      sequence numbers.  As part of the establishment of a security
      context, the context initiator is authenticated to the responder,
      and may require that the responder is authenticated back to the
      initiator.  The initiator may optionally give the responder the
      right to initiate further security contexts, acting as an agent or
      delegate of the initiator.  This transfer of rights is termed
      "delegation", and is achieved by creating a set of credentials,
      similar to those used by the initiating application, but which may
      be used by the responder.

      A GSSContext object is used to establish and maintain the shared
      information that makes up the security context.  Certain
      GSSContext methods will generate a token, which applications treat
      as cryptographically protected, opaque data.  The caller of such a
      GSSContext method is responsible for transferring the token to the
      peer application, encapsulated if necessary in an application-to-
      application protocol.  On receipt of such a token, the peer
      application should pass it to a corresponding GSSContext method
      which will decode the token and extract the information, updating
      the security context state information accordingly.

Top      ToC       Page 9 
   3) Per-message services are invoked on a GSSContext object to apply
      either:

      integrity and data origin authentication, or

      confidentiality, integrity and data origin authentication

      to application data, which are treated by GSS-API as arbitrary
      octet-strings.  An application transmitting a message that it
      wishes to protect will call the appropriate GSSContext method
      (getMIC or wrap) to apply protection, and send the resulting token
      to the receiving application.  The receiver will pass the received
      token (and, in the case of data protected by getMIC, the
      accompanying message-data) to the corresponding decoding method of
      the GSSContext interface (verifyMIC or unwrap) to remove the
      protection and validate the data.

   4) At the completion of a communications session (which may extend
      across several transport connections), each application uses a
      GSSContext method to invalidate the security context and release
      any system or cryptographic resources held.  Multiple contexts may
      also be used (either successively or simultaneously) within a
      single communications association, at the discretion of the
      applications.

4.  Additional Controls

   This section discusses the optional services that a context initiator
   may request of the GSS-API before the context establishment.  Each of
   these services is requested by calling the appropriate mutator method
   in the GSSContext object before the first call to init is performed.
   Only the context initiator can request context flags.

   The optional services defined are:

      Delegation: The (usually temporary) transfer of rights from
      initiator to acceptor, enabling the acceptor to authenticate
      itself as an agent of the initiator.

      Mutual Authentication: In addition to the initiator authenticating
      its identity to the context acceptor, the context acceptor should
      also authenticate itself to the initiator.

      Replay Detection: In addition to providing message integrity
      services, GSSContext per-message operations of getMIC and wrap
      should include message numbering information to enable verifyMIC
      and unwrap to detect if a message has been duplicated.

Top      ToC       Page 10 
      Out-of-Sequence Detection: In addition to providing message
      integrity services, GSSContext per-message operations (getMIC and
      wrap) should include message sequencing information to enable
      verifyMIC and unwrap to detect if a message has been received out
      of sequence.

      Anonymous Authentication: The establishment of the security
      context should not reveal the initiator's identity to the context
      acceptor.

   Some mechanisms may not support all optional services, and some
   mechanisms may only support some services in conjunction with others.
   The GSSContext interface offers query methods to allow the
   verification by the calling application of which services will be
   available from the context when the establishment phase is complete.
   In general, if the security mechanism is capable of providing a
   requested service, it should do so even if additional services must
   be enabled in order to provide the requested service.  If the
   mechanism is incapable of providing a requested service, it should
   proceed without the service leaving the application to abort the
   context establishment process if it considers the requested service
   to be mandatory.

   Some mechanisms may specify that support for some services is
   optional, and that implementors of the mechanism need not provide it.
   This is most commonly true of the confidentiality service, often
   because of legal restrictions on the use of data-encryption, but may
   apply to any of the services.  Such mechanisms are required to send
   at least one token from acceptor to initiator during context
   establishment when the initiator indicates a desire to use such a
   service, so that the initiating GSS-API can correctly indicate
   whether the service is supported by the acceptor's GSS-API.

4.1.  Delegation

   The GSS-API allows delegation to be controlled by the initiating
   application via the requestCredDeleg method before the first call to
   init has been issued.  Some mechanisms do not support delegation, and
   for such mechanisms, attempts by an application to enable delegation
   are ignored.

   The acceptor of a security context, for which the initiator enabled
   delegation, can check if delegation was enabled by using the
   getCredDelegState method of the GSSContext interface.  In cases when
   it is enabled, the delegated credential object can be obtained by
   calling the getDelegCred method.  The obtained GSSCredential object
   may then be used to initiate subsequent GSS-API security contexts as
   an agent or delegate of the initiator.  If the original initiator's

Top      ToC       Page 11 
   identity is "A" and the delegate's identity is "B", then, depending
   on the underlying mechanism, the identity embodied by the delegated
   credential may be either "A" or "B acting for A".

   For many mechanisms that support delegation, a simple boolean does
   not provide enough control.  Examples of additional aspects of
   delegation control that a mechanism might provide to an application
   are duration of delegation, network addresses from which delegation
   is valid, and constraints on the tasks that may be performed by a
   delegate.  Such controls are presently outside the scope of the GSS-
   API.  GSS-API implementations supporting mechanisms offering
   additional controls should provide extension routines that allow
   these controls to be exercised (perhaps by modifying the initiator's
   GSS-API credential object prior to its use in establishing a
   context).  However, the simple delegation control provided by GSS-API
   should always be able to override other mechanism-specific delegation
   controls.  If the application instructs the GSSContext object that
   delegation is not desired, then the implementation must not permit
   delegation to occur.  This is an exception to the general rule that a
   mechanism may enable services even if they are not requested --
   delegation may only be provided at the explicit request of the
   application.

4.2.  Mutual Authentication

   Usually, a context acceptor will require that a context initiator
   authenticate itself so that the acceptor may make an access-control
   decision prior to performing a service for the initiator.  In some
   cases, the initiator may also request that the acceptor authenticate
   itself.  GSS-API allows the initiating application to request this
   mutual authentication service by calling the requestMutualAuth method
   of the GSSContext interface with a "true" parameter before making the
   first call to init.  The initiating application is informed as to
   whether or not the context acceptor has authenticated itself.  Note
   that some mechanisms may not support mutual authentication, and other
   mechanisms may always perform mutual authentication, whether or not
   the initiating application requests it.  In particular, mutual
   authentication may be required by some mechanisms in order to support
   replay or out-of-sequence message detection, and for such mechanisms,
   a request for either of these services will automatically enable
   mutual authentication.

4.3.  Replay and Out-of-Sequence Detection

   The GSS-API may provide detection of mis-ordered messages once a
   security context has been established.  Protection may be applied to
   messages by either application, by calling either getMIC or wrap

Top      ToC       Page 12 
   methods of the GSSContext interface, and verified by the peer
   application by calling verifyMIC or unwrap for the peer's GSSContext
   object.

   The getMIC method calculates a cryptographic checksum of an
   application message, and returns that checksum in a token.  The
   application should pass both the token and the message to the peer
   application, which presents them to the verifyMIC method of the
   peer's GSSContext object.

   The wrap method calculates a cryptographic checksum of an application
   message, and places both the checksum and the message inside a single
   token.  The application should pass the token to the peer
   application, which presents it to the unwrap method of the peer's
   GSSContext object to extract the message and verify the checksum.

   Either pair of routines may be capable of detecting out-of-sequence
   message delivery or the duplication of messages.  Details of such
   mis-ordered messages are indicated through supplementary query
   methods of the MessageProp object that is filled in by each of these
   routines.

   A mechanism need not maintain a list of all tokens that have been
   processed in order to support these status codes.  A typical
   mechanism might retain information about only the most recent "N"
   tokens processed, allowing it to distinguish duplicates and missing
   tokens within the most recent "N" messages; the receipt of a token
   older than the most recent "N" would result in the isOldToken method
   of the instance of MessageProp to return "true".

4.4.  Anonymous Authentication

   In certain situations, an application may wish to initiate the
   authentication process to authenticate a peer, without revealing its
   own identity.  As an example, consider an application providing
   access to a database containing medical information and offering
   unrestricted access to the service.  A client of such a service might
   wish to authenticate the service (in order to establish trust in any
   information retrieved from it), but might not wish the service to be
   able to obtain the client's identity (perhaps due to privacy concerns
   about the specific inquiries, or perhaps simply to avoid being placed
   on mailing-lists).

   In normal use of the GSS-API, the initiator's identity is made
   available to the acceptor as a result of the context establishment
   process.  However, context initiators may request that their identity
   not be revealed to the context acceptor.  Many mechanisms do not
   support anonymous authentication, and for such mechanisms, the

Top      ToC       Page 13 
   request will not be honored.  An authentication token will still be
   generated, but the application is always informed if a requested
   service is unavailable, and has the option to abort context
   establishment if anonymity is valued above the other security
   services that would require a context to be established.

   In addition to informing the application that a context is
   established anonymously (via the isAnonymous method of the GSSContext
   class), the getSrcName method of the acceptor's GSSContext object
   will, for such contexts, return a reserved internal-form name,
   defined by the implementation.

   The toString method for a GSSName object representing an anonymous
   entity will return a printable name.  The returned value will be
   syntactically distinguishable from any valid principal name supported
   by the implementation.  The associated name-type object identifier
   will be an oid representing the value of NT_ANONYMOUS.  This name-
   type oid will be defined as a public, static Oid object of the
   GSSName class.  The printable form of an anonymous name should be
   chosen such that it implies anonymity, since this name may appear in,
   for example, audit logs.  For example, the string "<anonymous>" might
   be a good choice, if no valid printable names supported by the
   implementation can begin with "<" and end with ">".

   When using the equal method of the GSSName interface, and one of the
   operands is a GSSName instance representing an anonymous entity, the
   method must return "false".

4.5.  Confidentiality

   If a GSSContext supports the confidentiality service, wrap method may
   be used to encrypt application messages.  Messages are selectively
   encrypted, under the control of the setPrivacy method of the
   MessageProp object used in the wrap method.

4.6.  Inter-process Context Transfer

   GSS-APIv2 provides functionality that allows a security context to be
   transferred between processes on a single machine.  These are
   implemented using the export method of GSSContext and a byte array
   constructor of the same class.  The most common use for such a
   feature is a client-server design where the server is implemented as
   a single process that accepts incoming security contexts, which then
   launches child processes to deal with the data on these contexts.  In
   such a design, the child processes must have access to the security
   context object created within the parent so that they can use per-
   message protection services and delete the security context when the
   communication session ends.

Top      ToC       Page 14 
   Since the security context data structure is expected to contain
   sequencing information, it is impractical in general to share a
   context between processes.  Thus, the GSSContext interface provides
   an export method that the process, which currently owns the context,
   can call to declare that it has no intention to use the context
   subsequently, and to create an inter-process token containing
   information needed by the adopting process to successfully recreate
   the context.  After successful completion of export, the original
   security context is made inaccessible to the calling process by GSS-
   API, and any further usage of this object will result in failures.
   The originating process transfers the inter-process token to the
   adopting process, which creates a new GSSContext object using the
   byte array constructor.  The properties of the context are equivalent
   to that of the original context.

   The inter-process token may contain sensitive data from the original
   security context (including cryptographic keys).  Applications using
   inter-process tokens to transfer security contexts must take
   appropriate steps to protect these tokens in transit.

   Implementations are not required to support the inter-process
   transfer of security contexts.  Calling the isTransferable method of
   the GSSContext interface will indicate if the context object is
   transferable.

4.7.  The Use of Incomplete Contexts

   Some mechanisms may allow the per-message services to be used before
   the context establishment process is complete.  For example, a
   mechanism may include sufficient information in its initial context-
   level tokens for the context acceptor to immediately decode messages
   protected with wrap or getMIC.  For such a mechanism, the initiating
   application need not wait until subsequent context-level tokens have
   been sent and received before invoking the per-message protection
   services.

   An application can invoke the isProtReady method of the GSSContext
   class to determine if the per-message services are available in
   advance of complete context establishment.  Applications wishing to
   use per-message protection services on partially established contexts
   should query this method before attempting to invoke wrap or getMIC.


Next RFC Part