RFC 8353
Generic Security Service API Version 2: Java Bindings Update
Internet Engineering Task Force (IETF) M. Upadhyay Request for Comments: 8353 Google Obsoletes: 5653 S. Malkani Category: Standards Track ActivIdentity ISSN: 2070-1721 W. Wang Oracle May 2018 Generic Security Service API Version 2: Java Bindings UpdateAbstract
The Generic Security Services Application Programming 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 Update" (RFC 5653). This document obsoletes RFC 5653 by adding a new output token field to the GSSException class so that when the initSecContext or acceptSecContext methods of the GSSContext class fail, it has a chance to emit an error token that can be sent to the peer for debugging or informational purpose. The stream-based GSSContext methods are also removed in this version. 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 (SPKM)" (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 is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8353. Copyright Notice Copyright (c) 2018 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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. Notational Conventions . . . . . . . . . . . . . . . . . . . 7 3. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 7 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. Integrity and 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 . . . . . . . . . . . . . . . . . . 20 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 . . . . . . . . . . . . . . . . . . . . 27 5.15. Optional Parameters . . . . . . . . . . . . . . . . . . . 28 6. Introduction to GSS-API Classes and Interfaces . . . . . . . 28 6.1. GSSManager Class . . . . . . . . . . . . . . . . . . . . 28 6.2. GSSName Interface . . . . . . . . . . . . . . . . . . . . 29 6.3. GSSCredential Interface . . . . . . . . . . . . . . . . . 30 6.4. GSSContext Interface . . . . . . . . . . . . . . . . . . 31 6.5. MessageProp Class . . . . . . . . . . . . . . . . . . . . 32 6.6. GSSException Class . . . . . . . . . . . . . . . . . . . 32 6.7. Oid Class . . . . . . . . . . . . . . . . . . . . . . . . 32 6.8. ChannelBinding Class . . . . . . . . . . . . . . . . . . 33 7. Detailed GSS-API Class Description . . . . . . . . . . . . . 33 7.1. public abstract class GSSManager . . . . . . . . . . . . 33 7.1.1. getInstance . . . . . . . . . . . . . . . . . . . . . 34 7.1.2. getMechs . . . . . . . . . . . . . . . . . . . . . . 34 7.1.3. getNamesForMech . . . . . . . . . . . . . . . . . . . 35 7.1.4. getMechsForName . . . . . . . . . . . . . . . . . . . 35 7.1.5. createName . . . . . . . . . . . . . . . . . . . . . 35
7.1.6. createName . . . . . . . . . . . . . . . . . . . . . 36
7.1.7. createName . . . . . . . . . . . . . . . . . . . . . 36
7.1.8. createName . . . . . . . . . . . . . . . . . . . . . 37
7.1.9. createCredential . . . . . . . . . . . . . . . . . . 38
7.1.10. createCredential . . . . . . . . . . . . . . . . . . 38
7.1.11. createCredential . . . . . . . . . . . . . . . . . . 39
7.1.12. createContext . . . . . . . . . . . . . . . . . . . . 39
7.1.13. createContext . . . . . . . . . . . . . . . . . . . . 40
7.1.14. createContext . . . . . . . . . . . . . . . . . . . . 40
7.1.15. addProviderAtFront . . . . . . . . . . . . . . . . . 41
7.1.15.1. addProviderAtFront Example Code . . . . . . . . 42
7.1.16. addProviderAtEnd . . . . . . . . . . . . . . . . . . 43
7.1.16.1. addProviderAtEnd Example Code . . . . . . . . . 43
7.1.17. Example Code . . . . . . . . . . . . . . . . . . . . 44
7.2. public interface GSSName . . . . . . . . . . . . . . . . 45
7.2.1. Static Constants . . . . . . . . . . . . . . . . . . 45
7.2.2. equals . . . . . . . . . . . . . . . . . . . . . . . 46
7.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . 46
7.2.4. canonicalize . . . . . . . . . . . . . . . . . . . . 47
7.2.5. export . . . . . . . . . . . . . . . . . . . . . . . 47
7.2.6. toString . . . . . . . . . . . . . . . . . . . . . . 47
7.2.7. getStringNameType . . . . . . . . . . . . . . . . . . 47
7.2.8. isAnonymous . . . . . . . . . . . . . . . . . . . . . 47
7.2.9. isMN . . . . . . . . . . . . . . . . . . . . . . . . 48
7.2.10. Example Code . . . . . . . . . . . . . . . . . . . . 48
7.3. public interface GSSCredential implements Cloneable . . . 49
7.3.1. Static Constants . . . . . . . . . . . . . . . . . . 50
7.3.2. dispose . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.3. getName . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 51
7.3.5. getRemainingLifetime . . . . . . . . . . . . . . . . 51
7.3.6. getRemainingInitLifetime . . . . . . . . . . . . . . 51
7.3.7. getRemainingAcceptLifetime . . . . . . . . . . . . . 51
7.3.8. getUsage . . . . . . . . . . . . . . . . . . . . . . 52
7.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 52
7.3.10. getMechs . . . . . . . . . . . . . . . . . . . . . . 52
7.3.11. add . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.3.12. equals . . . . . . . . . . . . . . . . . . . . . . . 53
7.3.13. Example Code . . . . . . . . . . . . . . . . . . . . 54
7.4. public interface GSSContext . . . . . . . . . . . . . . . 54
7.4.1. Static Constants . . . . . . . . . . . . . . . . . . 55
7.4.2. initSecContext . . . . . . . . . . . . . . . . . . . 56
7.4.3. acceptSecContext . . . . . . . . . . . . . . . . . . 56
7.4.4. isEstablished . . . . . . . . . . . . . . . . . . . . 57
7.4.5. dispose . . . . . . . . . . . . . . . . . . . . . . . 57
7.4.6. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 58
7.4.7. wrap . . . . . . . . . . . . . . . . . . . . . . . . 58
7.4.8. unwrap . . . . . . . . . . . . . . . . . . . . . . . 59
7.4.9. getMIC . . . . . . . . . . . . . . . . . . . . . . . 60
7.4.10. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 61
7.4.11. export . . . . . . . . . . . . . . . . . . . . . . . 62
7.4.12. requestMutualAuth . . . . . . . . . . . . . . . . . . 62
7.4.13. requestReplayDet . . . . . . . . . . . . . . . . . . 63
7.4.14. requestSequenceDet . . . . . . . . . . . . . . . . . 63
7.4.15. requestCredDeleg . . . . . . . . . . . . . . . . . . 63
7.4.16. requestAnonymity . . . . . . . . . . . . . . . . . . 64
7.4.17. requestConf . . . . . . . . . . . . . . . . . . . . . 64
7.4.18. requestInteg . . . . . . . . . . . . . . . . . . . . 64
7.4.19. requestLifetime . . . . . . . . . . . . . . . . . . . 64
7.4.20. setChannelBinding . . . . . . . . . . . . . . . . . . 65
7.4.21. getCredDelegState . . . . . . . . . . . . . . . . . . 65
7.4.22. getMutualAuthState . . . . . . . . . . . . . . . . . 65
7.4.23. getReplayDetState . . . . . . . . . . . . . . . . . . 65
7.4.24. getSequenceDetState . . . . . . . . . . . . . . . . . 66
7.4.25. getAnonymityState . . . . . . . . . . . . . . . . . . 66
7.4.26. isTransferable . . . . . . . . . . . . . . . . . . . 66
7.4.27. isProtReady . . . . . . . . . . . . . . . . . . . . . 66
7.4.28. getConfState . . . . . . . . . . . . . . . . . . . . 66
7.4.29. getIntegState . . . . . . . . . . . . . . . . . . . . 67
7.4.30. getLifetime . . . . . . . . . . . . . . . . . . . . . 67
7.4.31. getSrcName . . . . . . . . . . . . . . . . . . . . . 67
7.4.32. getTargName . . . . . . . . . . . . . . . . . . . . . 67
7.4.33. getMech . . . . . . . . . . . . . . . . . . . . . . . 67
7.4.34. getDelegCred . . . . . . . . . . . . . . . . . . . . 68
7.4.35. isInitiator . . . . . . . . . . . . . . . . . . . . . 68
7.4.36. Example Code . . . . . . . . . . . . . . . . . . . . 68
7.5. public class MessageProp . . . . . . . . . . . . . . . . 70
7.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 70
7.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 71
7.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 71
7.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 71
7.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 71
7.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 71
7.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 72
7.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 72
7.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 72
7.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 72
7.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 72
7.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 72
7.6. public class ChannelBinding . . . . . . . . . . . . . . . 73
7.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 73
7.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 74
7.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 74
7.6.4. getApplicationData . . . . . . . . . . . . . . . . . 74
7.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 75
7.7. public class Oid . . . . . . . . . . . . . . . . . . . . 75
7.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 75
7.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 76
7.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 76
7.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 76
7.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 77
7.8. public class GSSException extends Exception . . . . . . . 77
7.8.1. Static Constants . . . . . . . . . . . . . . . . . . 77
7.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 80
7.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 81
7.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 81
7.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 81
7.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 81
7.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 82
7.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 82
7.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 82
7.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 82
8. Sample Applications . . . . . . . . . . . . . . . . . . . . . 83
8.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 83
8.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 87
9. Security Considerations . . . . . . . . . . . . . . . . . . . 90
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 91
11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 91
12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 93
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 94
13.1. Normative References . . . . . . . . . . . . . . . . . . 94
13.2. Informative References . . . . . . . . . . . . . . . . . 95
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 96
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 96
1. Introduction
This document specifies Java language bindings for the Generic
Security Services Application Programming Interface (GSS-API) version
2. GSS-API version 2 is described in a language-independent format
in RFC 2743 [RFC2743]. The GSS-API allows a caller application to
authenticate a principal identity, delegate rights to a peer, and
apply security services such as confidentiality and integrity on a
per-message basis.
This document and its predecessors, RFC 2853 [RFC2853] and RFC 5653
[RFC5653], leverage the work done by the working group (WG) in the
area of RFC 2743 [RFC2743] and the C-bindings of RFC 2744 [RFC2744].
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 [RFC2743] 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.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.3. GSS-API Operational Paradigm
"Generic Security Service Application Programming Interface, Version 2" [RFC2743] 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.
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 before sending 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.
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 it 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 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 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 (authentication tag) 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 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 (OID) 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. Integrity and Confidentiality
If a GSSContext supports the integrity service, the getMic method may be used to create message integrity check tokens on application messages. If a GSSContext supports the confidentiality service, the 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. Confidentiality will be applied if the privacy state is set to true.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. 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 page on part 2)
