draft-ietf-kitten-rfc5653bis-02.txt   draft-ietf-kitten-rfc5653bis-03.txt 
Network Working Group M. Upadhyay Network Working Group M. Upadhyay
Internet-Draft Google Internet-Draft Google
Obsoletes: 5653 (if approved) S. Malkani Obsoletes: 5653 (if approved) S. Malkani
Intended status: Standards Track ActivIdentity Intended status: Standards Track ActivIdentity
Expires: August 9, 2015 W. Wang Expires: October 7, 2016 W. Wang
Oracle Oracle
February 5, 2015 April 5, 2016
Generic Security Service API Version 2: Java Bindings Update Generic Security Service API Version 2: Java Bindings Update
draft-ietf-kitten-rfc5653bis-02 draft-ietf-kitten-rfc5653bis-03
Abstract Abstract
The Generic Security Services Application Program Interface (GSS-API) The Generic Security Services Application Program Interface (GSS-API)
offers application programmers uniform access to security services offers application programmers uniform access to security services
atop a variety of underlying cryptographic mechanisms. This document atop a variety of underlying cryptographic mechanisms. This document
updates the Java bindings for the GSS-API that are specified in updates the Java bindings for the GSS-API that are specified in
"Generic Security Service API Version 2 : Java Bindings Update" (RFC "Generic Security Service API Version 2 : Java Bindings Update" (RFC
5653). This document obsoletes RFC 5653 by adding a new output token 5653). This document obsoletes RFC 5653 by adding a new output token
field to the GSSException class so that when the initSecContext or field to the GSSException class so that when the initSecContext or
acceptSecContext methods of the GSSContext class fails it has a acceptSecContext methods of the GSSContext class fails it has a
chance to emit an error token which can be sent to the peer for chance to emit an error token which can be sent to the peer for
debugging or informational purpose. 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 The GSS-API is described at a language-independent conceptual level
in "Generic Security Service Application Program Interface Version 2, in "Generic Security Service Application Program Interface Version 2,
Update 1" (RFC 2743). The GSS-API allows a caller application to Update 1" (RFC 2743). The GSS-API allows a caller application to
authenticate a principal identity, to delegate rights to a peer, and authenticate a principal identity, to delegate rights to a peer, and
to apply security services such as confidentiality and integrity on a to apply security services such as confidentiality and integrity on a
per-message basis. Examples of security mechanisms defined for GSS- per-message basis. Examples of security mechanisms defined for GSS-
API are "The Simple Public-Key GSS-API Mechanism" (RFC 2025) and "The API are "The Simple Public-Key GSS-API Mechanism" (RFC 2025) and "The
Kerberos Version 5 Generic Security Service Application Program Kerberos Version 5 Generic Security Service Application Program
Interface (GSS-API) Mechanism: Version 2" (RFC 4121). Interface (GSS-API) Mechanism: Version 2" (RFC 4121).
skipping to change at page 2, line 7 skipping to change at page 2, line 7
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 9, 2015. This Internet-Draft will expire on October 7, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 40 skipping to change at page 2, line 40
the copyright in such materials, this document may not be modified the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 7 2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 7
3. Additional Controls . . . . . . . . . . . . . . . . . . . . . 9 3. Additional Controls . . . . . . . . . . . . . . . . . . . . . 8
3.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . 10
3.2. Mutual Authentication . . . . . . . . . . . . . . . . . . 11 3.2. Mutual Authentication . . . . . . . . . . . . . . . . . . 10
3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 11 3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 11
3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 12 3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 12
3.5. Confidentiality . . . . . . . . . . . . . . . . . . . . . 13 3.5. Confidentiality . . . . . . . . . . . . . . . . . . . . . 13
3.6. Inter-process Context Transfer . . . . . . . . . . . . . 13 3.6. Inter-process Context Transfer . . . . . . . . . . . . . 13
3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 14 3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 14
4. Calling Conventions . . . . . . . . . . . . . . . . . . . . . 14 4. Calling Conventions . . . . . . . . . . . . . . . . . . . . . 14
4.1. Package Name . . . . . . . . . . . . . . . . . . . . . . 14 4.1. Package Name . . . . . . . . . . . . . . . . . . . . . . 14
4.2. Provider Framework . . . . . . . . . . . . . . . . . . . 14 4.2. Provider Framework . . . . . . . . . . . . . . . . . . . 14
4.3. Integer Types . . . . . . . . . . . . . . . . . . . . . . 15 4.3. Integer Types . . . . . . . . . . . . . . . . . . . . . . 15
4.4. Opaque Data Types . . . . . . . . . . . . . . . . . . . . 15 4.4. Opaque Data Types . . . . . . . . . . . . . . . . . . . . 15
skipping to change at page 3, line 18 skipping to change at page 3, line 18
4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . . 17 4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . . 17
4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18 4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18
4.10. Authentication Tokens . . . . . . . . . . . . . . . . . . 19 4.10. Authentication Tokens . . . . . . . . . . . . . . . . . . 19
4.11. Inter-Process Tokens . . . . . . . . . . . . . . . . . . 19 4.11. Inter-Process Tokens . . . . . . . . . . . . . . . . . . 19
4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . . 20 4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . . 20
4.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . 20 4.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . 20
4.12.2. Mechanism-Specific Status Codes . . . . . . . . . . 22 4.12.2. Mechanism-Specific Status Codes . . . . . . . . . . 22
4.12.3. Supplementary Status Codes . . . . . . . . . . . . . 23 4.12.3. Supplementary Status Codes . . . . . . . . . . . . . 23
4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . . 26 4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . . 26
4.15. Stream Objects . . . . . . . . . . . . . . . . . . . . . 27 4.15. Optional Parameters . . . . . . . . . . . . . . . . . . . 27
4.16. Optional Parameters . . . . . . . . . . . . . . . . . . . 27
5. Introduction to GSS-API Classes and Interfaces . . . . . . . 27 5. Introduction to GSS-API Classes and Interfaces . . . . . . . 27
5.1. GSSManager Class . . . . . . . . . . . . . . . . . . . . 28 5.1. GSSManager Class . . . . . . . . . . . . . . . . . . . . 27
5.2. GSSName Interface . . . . . . . . . . . . . . . . . . . . 29 5.2. GSSName Interface . . . . . . . . . . . . . . . . . . . . 28
5.3. GSSCredential Interface . . . . . . . . . . . . . . . . . 29 5.3. GSSCredential Interface . . . . . . . . . . . . . . . . . 29
5.4. GSSContext Interface . . . . . . . . . . . . . . . . . . 30 5.4. GSSContext Interface . . . . . . . . . . . . . . . . . . 30
5.5. MessageProp Class . . . . . . . . . . . . . . . . . . . . 32 5.5. MessageProp Class . . . . . . . . . . . . . . . . . . . . 32
5.6. GSSException Class . . . . . . . . . . . . . . . . . . . 32 5.6. GSSException Class . . . . . . . . . . . . . . . . . . . 32
5.7. Oid Class . . . . . . . . . . . . . . . . . . . . . . . . 32 5.7. Oid Class . . . . . . . . . . . . . . . . . . . . . . . . 32
5.8. ChannelBinding Class . . . . . . . . . . . . . . . . . . 32 5.8. ChannelBinding Class . . . . . . . . . . . . . . . . . . 32
6. Detailed GSS-API Class Description . . . . . . . . . . . . . 33 6. Detailed GSS-API Class Description . . . . . . . . . . . . . 33
6.1. public abstract class GSSManager . . . . . . . . . . . . 33 6.1. public abstract class GSSManager . . . . . . . . . . . . 33
6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . 34 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . 34
6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 35 6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 35
skipping to change at page 4, line 31 skipping to change at page 4, line 30
6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . 51 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . 51
6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 52
6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 52
6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 52 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 52
6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 52 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 53 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 53
6.4. public interface GSSContext . . . . . . . . . . . . . . . 54 6.4. public interface GSSContext . . . . . . . . . . . . . . . 54
6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 55 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 55
6.4.2. Static Constants . . . . . . . . . . . . . . . . . . 56 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . 56
6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . 57 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . 57
6.4.4. Example Code . . . . . . . . . . . . . . . . . . . . 58 6.4.4. Example Code . . . . . . . . . . . . . . . . . . . . 57
6.4.5. initSecContext . . . . . . . . . . . . . . . . . . . 58 6.4.5. acceptSecContext . . . . . . . . . . . . . . . . . . 58
6.4.6. Example Code . . . . . . . . . . . . . . . . . . . . 59 6.4.6. Example Code . . . . . . . . . . . . . . . . . . . . 59
6.4.7. acceptSecContext . . . . . . . . . . . . . . . . . . 60 6.4.7. isEstablished . . . . . . . . . . . . . . . . . . . . 60
6.4.8. Example Code . . . . . . . . . . . . . . . . . . . . 61 6.4.8. dispose . . . . . . . . . . . . . . . . . . . . . . . 61
6.4.9. acceptSecContext . . . . . . . . . . . . . . . . . . 62 6.4.9. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 61
6.4.10. Example Code . . . . . . . . . . . . . . . . . . . . 63 6.4.10. wrap . . . . . . . . . . . . . . . . . . . . . . . . 62
6.4.11. isEstablished . . . . . . . . . . . . . . . . . . . . 64 6.4.11. unwrap . . . . . . . . . . . . . . . . . . . . . . . 63
6.4.12. dispose . . . . . . . . . . . . . . . . . . . . . . . 65 6.4.12. getMIC . . . . . . . . . . . . . . . . . . . . . . . 63
6.4.13. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 65 6.4.13. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 64
6.4.14. wrap . . . . . . . . . . . . . . . . . . . . . . . . 66 6.4.14. export . . . . . . . . . . . . . . . . . . . . . . . 65
6.4.15. wrap . . . . . . . . . . . . . . . . . . . . . . . . 67 6.4.15. requestMutualAuth . . . . . . . . . . . . . . . . . . 66
6.4.16. unwrap . . . . . . . . . . . . . . . . . . . . . . . 68 6.4.16. requestReplayDet . . . . . . . . . . . . . . . . . . 66
6.4.17. unwrap . . . . . . . . . . . . . . . . . . . . . . . 68 6.4.17. requestSequenceDet . . . . . . . . . . . . . . . . . 66
6.4.18. getMIC . . . . . . . . . . . . . . . . . . . . . . . 69 6.4.18. requestCredDeleg . . . . . . . . . . . . . . . . . . 66
6.4.19. getMIC . . . . . . . . . . . . . . . . . . . . . . . 70 6.4.19. requestAnonymity . . . . . . . . . . . . . . . . . . 67
6.4.20. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 70 6.4.20. requestConf . . . . . . . . . . . . . . . . . . . . . 67
6.4.21. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 71 6.4.21. requestInteg . . . . . . . . . . . . . . . . . . . . 67
6.4.22. export . . . . . . . . . . . . . . . . . . . . . . . 72 6.4.22. requestLifetime . . . . . . . . . . . . . . . . . . . 68
6.4.23. requestMutualAuth . . . . . . . . . . . . . . . . . . 73 6.4.23. setChannelBinding . . . . . . . . . . . . . . . . . . 68
6.4.24. requestReplayDet . . . . . . . . . . . . . . . . . . 73 6.4.24. getCredDelegState . . . . . . . . . . . . . . . . . . 68
6.4.25. requestSequenceDet . . . . . . . . . . . . . . . . . 73 6.4.25. getMutualAuthState . . . . . . . . . . . . . . . . . 68
6.4.26. requestCredDeleg . . . . . . . . . . . . . . . . . . 74 6.4.26. getReplayDetState . . . . . . . . . . . . . . . . . . 69
6.4.27. requestAnonymity . . . . . . . . . . . . . . . . . . 74 6.4.27. getSequenceDetState . . . . . . . . . . . . . . . . . 69
6.4.28. requestConf . . . . . . . . . . . . . . . . . . . . . 74 6.4.28. getAnonymityState . . . . . . . . . . . . . . . . . . 69
6.4.29. requestInteg . . . . . . . . . . . . . . . . . . . . 74 6.4.29. isTransferable . . . . . . . . . . . . . . . . . . . 69
6.4.30. requestLifetime . . . . . . . . . . . . . . . . . . . 75 6.4.30. isProtReady . . . . . . . . . . . . . . . . . . . . . 69
6.4.31. setChannelBinding . . . . . . . . . . . . . . . . . . 75 6.4.31. getConfState . . . . . . . . . . . . . . . . . . . . 70
6.4.32. getCredDelegState . . . . . . . . . . . . . . . . . . 75 6.4.32. getIntegState . . . . . . . . . . . . . . . . . . . . 70
6.4.33. getMutualAuthState . . . . . . . . . . . . . . . . . 75 6.4.33. getLifetime . . . . . . . . . . . . . . . . . . . . . 70
6.4.34. getReplayDetState . . . . . . . . . . . . . . . . . . 76 6.4.34. getSrcName . . . . . . . . . . . . . . . . . . . . . 70
6.4.35. getSequenceDetState . . . . . . . . . . . . . . . . . 76 6.4.35. getTargName . . . . . . . . . . . . . . . . . . . . . 70
6.4.36. getAnonymityState . . . . . . . . . . . . . . . . . . 76 6.4.36. getMech . . . . . . . . . . . . . . . . . . . . . . . 70
6.4.37. isTransferable . . . . . . . . . . . . . . . . . . . 76 6.4.37. getDelegCred . . . . . . . . . . . . . . . . . . . . 71
6.4.38. isProtReady . . . . . . . . . . . . . . . . . . . . . 76 6.4.38. isInitiator . . . . . . . . . . . . . . . . . . . . . 71
6.4.39. getConfState . . . . . . . . . . . . . . . . . . . . 77 6.5. public class MessageProp . . . . . . . . . . . . . . . . 71
6.4.40. getIntegState . . . . . . . . . . . . . . . . . . . . 77 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 71
6.4.41. getLifetime . . . . . . . . . . . . . . . . . . . . . 77 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 72
6.4.42. getSrcName . . . . . . . . . . . . . . . . . . . . . 77 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 72
6.4.43. getTargName . . . . . . . . . . . . . . . . . . . . . 77 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 72
6.4.44. getMech . . . . . . . . . . . . . . . . . . . . . . . 77 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 72
6.4.45. getDelegCred . . . . . . . . . . . . . . . . . . . . 78 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 72
6.4.46. isInitiator . . . . . . . . . . . . . . . . . . . . . 78 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 73
6.5. public class MessageProp . . . . . . . . . . . . . . . . 78 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 73
6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 78 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 73
6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 79 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 73
6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 79 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 73
6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 79 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 73
6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 79 6.6. public class ChannelBinding . . . . . . . . . . . . . . . 74
6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 79 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 74
6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 80 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 75
6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 80 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 75
6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 80 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . 75
6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 80 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 76
6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 80 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 76
6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 80 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 76
6.6. public class ChannelBinding . . . . . . . . . . . . . . . 81 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 77
6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 81 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 77
6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 82 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 77
6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 82 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 77
6.6.4. getApplicationData . . . . . . . . . . . . . . . . . 82 6.8. public class GSSException extends Exception . . . . . . . 78
6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 83 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . 78
6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 83 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 81
6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 83 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 82
6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 84 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 82
6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 84 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 82
6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 84 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 82
6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 84 6.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 82
6.8. public class GSSException extends Exception . . . . . . . 85 6.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 83
6.8.1. Static Constants . . . . . . . . . . . . . . . . . . 85 6.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 83
6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 88 6.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 83
6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 89 7. Sample Applications . . . . . . . . . . . . . . . . . . . . . 83
6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 89 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 83
6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 89 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 87
6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 89 8. Security Considerations . . . . . . . . . . . . . . . . . . . 91
6.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 89 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 92
6.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 90 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 92
6.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 90 11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 92
6.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 90 12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 93
7. Sample Applications . . . . . . . . . . . . . . . . . . . . . 90 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 90 13.1. Normative References . . . . . . . . . . . . . . . . . . 94
7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 94 13.2. Informative References . . . . . . . . . . . . . . . . . 95
8. Security Considerations . . . . . . . . . . . . . . . . . . . 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 95
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 99
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 99
11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 99
12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 100
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 101
13.1. Normative References . . . . . . . . . . . . . . . . . . 101
13.2. Informative References . . . . . . . . . . . . . . . . . 101
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 101
1. Introduction 1. Introduction
This document specifies Java language bindings for the Generic This document specifies Java language bindings for the Generic
Security Services Application Programming Interface version 2 (GSS- Security Services Application Programming Interface version 2 (GSS-
API). GSS-API version 2 is described in a language-independent API). GSS-API version 2 is described in a language-independent
format in RFC 2743 [RFC2743]. The GSS-API allows a caller format in RFC 2743 [RFC2743]. The GSS-API allows a caller
application to authenticate a principal identity, to delegate rights application to authenticate a principal identity, to delegate rights
to a peer, and to apply security services such as confidentiality and to a peer, and to apply security services such as confidentiality and
integrity on a per-message basis. integrity on a per-message basis.
This document and its predecessor, RFC 5653 [RFC5653], leverage the This document and its predecessor, RFC 2853 [RFC2853] and RFC 5653
work done by the working group (WG) in the area of RFC 2743 [RFC2743] [RFC5653], leverage the work done by the working group (WG) in the
and the C-bindings of RFC 2744 [RFC2744]. Whenever appropriate, text area of RFC 2743 [RFC2743] and the C-bindings of RFC 2744 [RFC2744].
has been used from the C-bindings document (RFC 2744) to explain Whenever appropriate, text has been used from the C-bindings document
generic concepts and provide direction to the implementors. (RFC 2744) to explain generic concepts and provide direction to the
implementors.
The design goals of this API have been to satisfy all the The design goals of this API have been to satisfy all the
functionality defined in RFC 2743 [RFC2743] and to provide these functionality defined in RFC 2743 [RFC2743] and to provide these
services in an object-oriented method. The specification also aims services in an object-oriented method. The specification also aims
to satisfy the needs of both types of Java application developers, to satisfy the needs of both types of Java application developers,
those who would like access to a "system-wide" GSS-API those who would like access to a "system-wide" GSS-API
implementation, as well as those who would want to provide their own implementation, as well as those who would want to provide their own
"custom" implementation. "custom" implementation.
A system-wide implementation is one that is available to all A system-wide implementation is one that is available to all
skipping to change at page 19, line 27 skipping to change at page 19, line 27
A token is a caller-opaque type that GSS-API uses to maintain A token is a caller-opaque type that GSS-API uses to maintain
synchronization between each end of the GSS-API security context. synchronization between each end of the GSS-API security context.
The token is a cryptographically protected octet-string, generated by The token is a cryptographically protected octet-string, generated by
the underlying mechanism at one end of a GSS-API security context for the underlying mechanism at one end of a GSS-API security context for
use by the peer mechanism at the other end. Encapsulation (if use by the peer mechanism at the other end. Encapsulation (if
required) within the application protocol and transfer of the token required) within the application protocol and transfer of the token
are the responsibility of the peer applications. are the responsibility of the peer applications.
Java GSS-API uses byte arrays to represent authentication tokens. Java GSS-API uses byte arrays to represent authentication tokens.
Overloaded methods exist that allow the caller to supply input and
output streams that will be used for the reading and writing of the
token data.
4.11. Inter-Process Tokens 4.11. Inter-Process Tokens
Certain GSS-API routines are intended to transfer data between Certain GSS-API routines are intended to transfer data between
processes in multi-process programs. These routines use a caller- processes in multi-process programs. These routines use a caller-
opaque octet-string, generated by the GSS-API in one process for use opaque octet-string, generated by the GSS-API in one process for use
by the GSS-API in another process. The calling application is by the GSS-API in another process. The calling application is
responsible for transferring such tokens between processes. Note responsible for transferring such tokens between processes. Note
that, while GSS-API implementors are encouraged to avoid placing that, while GSS-API implementors are encouraged to avoid placing
sensitive information within inter-process tokens, or to sensitive information within inter-process tokens, or to
skipping to change at page 20, line 21 skipping to change at page 20, line 21
or Mechanism status code, is a mechanism-defined error value or Mechanism status code, is a mechanism-defined error value
indicating a mechanism-specific error code. indicating a mechanism-specific error code.
Java GSS-API uses exceptions implemented by the GSSException class to Java GSS-API uses exceptions implemented by the GSSException class to
signal both minor and major error values. Both mechanism-specific signal both minor and major error values. Both mechanism-specific
errors and GSS-API level errors are signaled through instances of errors and GSS-API level errors are signaled through instances of
this class. The usage of exceptions replaces the need for major and this class. The usage of exceptions replaces the need for major and
minor codes to be used within the API calls. The GSSException class minor codes to be used within the API calls. The GSSException class
also contains methods to obtain textual representations for both the also contains methods to obtain textual representations for both the
major and minor values, which is equivalent to the functionality of major and minor values, which is equivalent to the functionality of
gss_display_status. gss_display_status. A GSSException object may also include an output
token that should be sent to the peer.
4.12.1. GSS Status Codes 4.12.1. GSS Status Codes
GSS status codes indicate errors that are independent of the GSS status codes indicate errors that are independent of the
underlying mechanism(s) used to provide the security service. The underlying mechanism(s) used to provide the security service. The
errors that can be indicated via a GSS status code are generic API errors that can be indicated via a GSS status code are generic API
routine errors (errors that are defined in the GSS-API routine errors (errors that are defined in the GSS-API
specification). These bindings take advantage of the Java exceptions specification). These bindings take advantage of the Java exceptions
mechanism, thus, eliminating the need for calling errors. mechanism, thus, eliminating the need for calling errors.
skipping to change at page 27, line 15 skipping to change at page 27, line 15
binding components. binding components.
Individual mechanisms may impose additional constraints on addresses Individual mechanisms may impose additional constraints on addresses
that may appear in channel bindings. For example, a mechanism may that may appear in channel bindings. For example, a mechanism may
verify that the initiator address field of the channel binding verify that the initiator address field of the channel binding
contains the correct network address of the host system. Portable contains the correct network address of the host system. Portable
applications should therefore ensure that they either provide correct applications should therefore ensure that they either provide correct
information for the address fields, or omit the setting of the information for the address fields, or omit the setting of the
addressing information. addressing information.
4.15. Stream Objects 4.15. Optional Parameters
The context object provides overloaded methods that use input and
output streams as the means to convey authentication and per-message
GSS-API tokens. It is important to note that the streams are
expected to contain the usual GSS-API tokens, which would otherwise
be handled through the usage of byte arrays. The tokens are expected
to have a definite start and an end. The callers are responsible for
ensuring that the supplied streams will not block, or expect to block
until a full token is processed by the GSS-API method. Only a single
GSS-API token will be processed per invocation of the stream-based
method.
The usage of streams allows the callers to have control and
management of the supplied buffers. Because streams are non-
primitive objects, the callers can make the streams as complicated or
as simple as desired simply by using the streams defined in the
java.io package or creating their own through the use of inheritance.
This will allow for the application's greatest flexibility.
4.16. Optional Parameters
Whenever the application wishes to omit an optional parameter the Whenever the application wishes to omit an optional parameter the
"null" value shall be used. The detailed method descriptions "null" value shall be used. The detailed method descriptions
indicate which parameters are optional. Method overloading has also indicate which parameters are optional. Method overloading has also
been used as a technique to indicate default parameters. been used as a technique to indicate default parameters.
5. Introduction to GSS-API Classes and Interfaces 5. Introduction to GSS-API Classes and Interfaces
This section presents a brief description of the classes and This section presents a brief description of the classes and
interfaces that constitute the GSS-API. The implementations of these interfaces that constitute the GSS-API. The implementations of these
skipping to change at page 28, line 27 skipping to change at page 28, line 8
getInstance(). Applications that desire to provide their own getInstance(). Applications that desire to provide their own
implementation of the GSSManager class can simply extend the abstract implementation of the GSSManager class can simply extend the abstract
class themselves. class themselves.
This class contains equivalents of the following RFC 2743 [RFC2743] This class contains equivalents of the following RFC 2743 [RFC2743]
routines: routines:
+----------------------------+-------------------------+------------+ +----------------------------+-------------------------+------------+
| RFC 2743 Routine | Function | Section(s) | | RFC 2743 Routine | Function | Section(s) |
+----------------------------+-------------------------+------------+ +----------------------------+-------------------------+------------+
| gss_import_name | Create an internal name | 6.1.6- | | gss_import_name | Create an internal name | 6.1.6 - |
| | from the supplied | 6.1.9 | | | from the supplied | 6.1.9 |
| | information. | | | | information. | |
| | | | | | | |
| gss_acquire_cred | Acquire credential for | 6.1.10- | | gss_acquire_cred | Acquire credential for | 6.1.10 - |
| | use. | 6.1.12 | | | use. | 6.1.12 |
| | | | | | | |
| gss_import_sec_context | Create a previously | 6.1.15 | | gss_import_sec_context | Create a previously | 6.1.15 |
| | exported context. | | | | exported context. | |
| | | | | | | |
| gss_indicate_mechs | List the mechanisms | 6.1.3 | | gss_indicate_mechs | List the mechanisms | 6.1.3 |
| | supported by this GSS- | | | | supported by this GSS- | |
| | API implementation. | | | | API implementation. | |
| | | | | | | |
| gss_inquire_mechs_for_name | List the mechanisms | 6.1.5 | | gss_inquire_mechs_for_name | List the mechanisms | 6.1.5 |
skipping to change at page 30, line 11 skipping to change at page 30, line 11
may contain multiple mechanism-specific credentials, each referred to may contain multiple mechanism-specific credentials, each referred to
as a credential element. The GSSCredential interface provides the as a credential element. The GSSCredential interface provides the
functionality of the following GSS-API routines: functionality of the following GSS-API routines:
+--------------------------+---------------------------+------------+ +--------------------------+---------------------------+------------+
| RFC 2743 Routine | Function | Section(s) | | RFC 2743 Routine | Function | Section(s) |
+--------------------------+---------------------------+------------+ +--------------------------+---------------------------+------------+
| gss_add_cred | Constructs credentials | 6.3.12 | | gss_add_cred | Constructs credentials | 6.3.12 |
| | incrementally. | | | | incrementally. | |
| | | | | | | |
| gss_inquire_cred | Obtain information about | 6.3.4- | | gss_inquire_cred | Obtain information about | 6.3.4 - |
| | credential. | 6.3.11 | | | credential. | 6.3.11 |
| | | | | | | |
| gss_inquire_cred_by_mech | Obtain per-mechanism | 6.3.5- | | gss_inquire_cred_by_mech | Obtain per-mechanism | 6.3.5 - |
| | information about a | 6.3.10 | | | information about a | 6.3.10 |
| | credential. | | | | credential. | |
| | | | | | | |
| gss_release_cred | Dispose of credentials | 6.3.3 | | gss_release_cred | Dispose of credentials | 6.3.3 |
| | after use. | | | | after use. | |
+--------------------------+---------------------------+------------+ +--------------------------+---------------------------+------------+
5.4. GSSContext Interface 5.4. GSSContext Interface
This interface encapsulates the functionality of context-level calls This interface encapsulates the functionality of context-level calls
skipping to change at page 31, line 8 skipping to change at page 31, line 8
peers as well as the per-message services offered to applications. A peers as well as the per-message services offered to applications. A
context is established between a pair of peers and allows the usage context is established between a pair of peers and allows the usage
of security services on a per-message basis on application data. It of security services on a per-message basis on application data. It
is created over a single security mechanism. The GSSContext is created over a single security mechanism. The GSSContext
interface provides the functionality of the following GSS-API interface provides the functionality of the following GSS-API
routines: routines:
+------------------------+-----------------------------+------------+ +------------------------+-----------------------------+------------+
| RFC 2743 Routine | Function | Section(s) | | RFC 2743 Routine | Function | Section(s) |
+------------------------+-----------------------------+------------+ +------------------------+-----------------------------+------------+
| gss_init_sec_context | Initiate the creation of a | 6.4.3- | | gss_init_sec_context | Initiate the creation of a | 6.4.3, |
| | security context with a | 6.4.6 | | | security context with a | 6.4.4 |
| | peer. | | | | peer. | |
| | | | | | | |
| gss_accept_sec_context | Accept a security context | 6.4.7- | | gss_accept_sec_context | Accept a security context | 6.4.5, |
| | initiated by a peer. | 6.4.10 | | | initiated by a peer. | 6.4.6 |
| | | | | | | |
| gss_delete_sec_context | Destroy a security context. | 6.4.12 | | gss_delete_sec_context | Destroy a security context. | 6.4.8 |
| | | | | | | |
| gss_context_time | Obtain remaining context | 6.4.41 | | gss_context_time | Obtain remaining context | 6.4.33 |
| | time. | | | | time. | |
| | | | | | | |
| gss_inquire_context | Obtain context | 6.4.32- | | gss_inquire_context | Obtain context | 6.4.24 - |
| | characteristics. | 6.4.46 | | | characteristics. | 6.4.38 |
| | | | | | | |
| gss_wrap_size_limit | Determine token-size limit | 6.4.13 | | gss_wrap_size_limit | Determine token-size limit | 6.4.9 |
| | for gss_wrap. | | | | for gss_wrap. | |
| | | | | | | |
| gss_export_sec_context | Transfer security context | 6.4.22 | | gss_export_sec_context | Transfer security context | 6.4.14 |
| | to another process. | | | | to another process. | |
| | | | | | | |
| gss_get_mic | Calculate a cryptographic | 6.4.18, | | gss_get_mic | Calculate a cryptographic | 6.4.12 |
| | Message Integrity Code | 6.4.19 | | | Message Integrity Code | |
| | (MIC) for a message. | | | | (MIC) for a message. | |
| | | | | | | |
| gss_verify_mic | Verify integrity on a | 6.4.20, | | gss_verify_mic | Verify integrity on a | 6.4.13 |
| | received message. | 6.4.21 | | | received message. | |
| | | | | | | |
| gss_wrap | Attach a MIC to a message | 6.4.14, | | gss_wrap | Attach a MIC to a message | 6.4.10 |
| | and optionally encrypt the | 6.4.15 | | | and optionally encrypt the | |
| | message content. | | | | message content. | |
| | | | | | | |
| gss_unwrap | Obtain a previously wrapped | 6.4.16, | | gss_unwrap | Obtain a previously wrapped | 6.4.11 |
| | application message | 6.4.17 | | | application message | |
| | verifying its integrity and | | | | verifying its integrity and | |
| | optionally decrypting it. | | | | optionally decrypting it. | |
+------------------------+-----------------------------+------------+ +------------------------+-----------------------------+------------+
The functionality offered by the gss_process_context_token routine The functionality offered by the gss_process_context_token routine
has not been included in the Java bindings specification. The has not been included in the Java bindings specification. The
corresponding functionality of gss_delete_sec_context has also been corresponding functionality of gss_delete_sec_context has also been
modified to not return any peer tokens. This has been proposed in modified to not return any peer tokens. This has been proposed in
accordance to the recommendations stated in RFC 2743 [RFC2743]. accordance to the recommendations stated in RFC 2743 [RFC2743].
GSSContext does offer the functionality of destroying the locally GSSContext does offer the functionality of destroying the locally
skipping to change at page 57, line 17 skipping to change at page 57, line 17
A lifetime constant representing indefinite context lifetime. The A lifetime constant representing indefinite context lifetime. The
value of this constant is the maximum integer value in Java - value of this constant is the maximum integer value in Java -
Integer.MAX_VALUE. Integer.MAX_VALUE.
6.4.3. initSecContext 6.4.3. initSecContext
public byte[] initSecContext(byte[] inputBuf, int offset, int len) public byte[] initSecContext(byte[] inputBuf, int offset, int len)
throws GSSException throws GSSException
Called by the context initiator to start the context creation Called by the context initiator to start the context creation
process. This is equivalent to the stream-based method except that process. This method may return an output token that the application
the token buffers are handled as byte arrays instead of using stream will need to send to the peer for processing by the accept call. The
objects. This method may return an output token that the application application can call isEstablished() to determine if the context
will need to send to the peer for processing by the accept call. establishment phase is complete for this peer. A return value of
Typically, the application would do so by calling the flush() method "false" from isEstablished() indicates that more tokens are expected
on an OutputStream that encapsulates the connection between the two to be supplied to the initSecContext() method. Note that it is
peers. The application can call isEstablished() to determine if the possible that the initSecContext() method will return a token for the
context establishment phase is complete for this peer. A return peer and isEstablished() will return "true" also. This indicates
value of "false" from isEstablished() indicates that more tokens are
expected to be supplied to the initSecContext() method. Note that it
is possible that the initSecContext() method will return a token for
the peer and isEstablished() will return "true" also. This indicates
that the token needs to be sent to the peer, but the local end of the that the token needs to be sent to the peer, but the local end of the
context is now fully established. context is now fully established.
Upon completion of the context establishment, the available context Upon completion of the context establishment, the available context
options may be queried through the get methods. options may be queried through the get methods.
A GSSException will be thrown if the call fails. Users should call A GSSException will be thrown if the call fails. Users should call
its getOutputToken() method to find out if there is a token that can its getOutputToken() method to find out if there is a token that can
be sent to the acceptor to communicate the reason for the error. be sent to the acceptor to communicate the reason for the error.
skipping to change at page 58, line 43 skipping to change at page 58, line 40
// If the exception contains an output token, // If the exception contains an output token,
// it should be sent to the acceptor. // it should be sent to the acceptor.
byte[] outTok = e.getOutputToken(); byte[] outTok = e.getOutputToken();
if (outTok != null) { if (outTok != null) {
sendToken(outTok); sendToken(outTok);
} }
} }
<CODE ENDS> <CODE ENDS>
6.4.5. initSecContext 6.4.5. acceptSecContext
public int initSecContext(InputStream inStream,
OutputStream outStream) throws GSSException
Called by the context initiator to start the context creation
process. This is equivalent to the byte-array-based method. This
method may write an output token to the outStream, which the
application will need to send to the peer for processing by the
accept call. Typically, the application would do so by calling the
flush() method on an OutputStream that encapsulates the connection
between the two peers. The application can call isEstablished() to
determine if the context establishment phase is complete for this
peer. A return value of "false" from isEstablished indicates that
more tokens are expected to be supplied to the initSecContext method.
Note that it is possible that the initSecContext() method will return
a token for the peer and isEstablished() will return "true" also.
This indicates that the token needs to be sent to the peer, but the
local end of the context is now fully established.
The GSS-API authentication tokens contain a definitive start and end.
This method will attempt to read one of these tokens per invocation,
and may block on the stream if only part of the token is available.
Upon completion of the context establishment, the available context
options may be queried through the get methods.
A GSSException will be thrown if the call fails. Users should call
its getOutputToken() method to find out if there is a token that can
be sent to the acceptor to communicate the reason for the error.
Parameters:
inStream Contains the token generated by the peer. This
parameter is ignored on the first call.
outStream Output stream where the output token will be
written. During the final stage of context
establishment, there may be no bytes written.
6.4.6. Example Code
This sample code merely demonstrates the token exchange during the
context establishment phase. It is expected that most Java
applications will use custom implementations of the Input and Output
streams that encapsulate the communication routines. For instance, a
simple read on the application InputStream, when called by the
Context, might cause a token to be read from the peer, and a simple
flush() on the application OutputStream might cause a previously
written token to be transmitted to the peer.
<CODE BEGINS>
// Create a new GSSContext implementation object.
// GSSContext wrapper implements interface GSSContext.
GSSContext context = mgr.createContext(...);
// use standard java.io stream objects
ByteArrayOutputStream os = new ByteArrayOutputStream();
ByteArrayInputStream is = null;
try {
do {
context.initSecContext(is, os);
// send token if present
if (os.size() > 0)
sendToken(os);
// check if we should expect more tokens
if (context.isEstablished())
break;
// another token expected from peer
is = recvToken();
} while (true);
} catch (GSSException e) {
print("GSSAPI error: " + e.getMessage());
// If the exception contains an output token,
// it should be sent to the acceptor.
byte[] outTok = e.getOutputToken();
if (outTok != null) {
sendToken(new ByteArrayOutputStream(outTok));
}
}
<CODE ENDS>
6.4.7. acceptSecContext
public byte[] acceptSecContext(byte[] inTok, int offset, int len) public byte[] acceptSecContext(byte[] inTok, int offset, int len)
throws GSSException throws GSSException
Called by the context acceptor upon receiving a token from the peer. Called by the context acceptor upon receiving a token from the peer.
This call is equivalent to the stream-based method except that the
token buffers are handled as byte arrays instead of using stream
objects.
This method may return an output token that the application will need This method may return an output token that the application will need
to send to the peer for further processing by the init call. to send to the peer for further processing by the init call.
The "null" return value indicates that no token needs to be sent to The "null" return value indicates that no token needs to be sent to
the peer. The application can call isEstablished() to determine if the peer. The application can call isEstablished() to determine if
the context establishment phase is complete for this peer. A return the context establishment phase is complete for this peer. A return
value of "false" from isEstablished() indicates that more tokens are value of "false" from isEstablished() indicates that more tokens are
expected to be supplied to this method. expected to be supplied to this method.
skipping to change at page 61, line 36 skipping to change at page 59, line 30
Parameters: Parameters:
inTok Token generated by the peer. inTok Token generated by the peer.
offset The offset within the inTok where the token offset The offset within the inTok where the token
begins. begins.
len The length of the token within the inTok len The length of the token within the inTok
(starting at the offset). (starting at the offset).
6.4.8. Example Code 6.4.6. Example Code
<CODE BEGINS> <CODE BEGINS>
// acquire server credentials // acquire server credentials
GSSCredential server = mgr.createCredential(...); GSSCredential server = mgr.createCredential(...);
// create acceptor GSS-API context from the default provider // create acceptor GSS-API context from the default provider
GSSContext context = mgr.createContext(server, null); GSSContext context = mgr.createContext(server, null);
try { try {
do { do {
byte[] inTok = readToken(); byte[] inTok = readToken();
skipping to change at page 62, line 39 skipping to change at page 60, line 39
// If the exception contains an output token, // If the exception contains an output token,
// it should be sent to the initiator. // it should be sent to the initiator.
byte[] outTok = e.getOutputToken(); byte[] outTok = e.getOutputToken();
if (outTok != null) { if (outTok != null) {
sendToken(outTok); sendToken(outTok);
} }
} }
<CODE ENDS> <CODE ENDS>
6.4.9. acceptSecContext 6.4.7. isEstablished
public void acceptSecContext(InputStream inStream,
OutputStream outStream) throws GSSException
Called by the context acceptor upon receiving a token from the peer.
This call is equivalent to the byte array method. It may write an
output token to the outStream, which the application will need to
send to the peer for processing by its initSecContext method.
Typically, the application would do so by calling the flush() method
on an OutputStream that encapsulates the connection between the two
peers. The application can call isEstablished() to determine if the
context establishment phase is complete for this peer. A return
value of "false" from isEstablished() indicates that more tokens are
expected to be supplied to this method.
Note that it is possible that acceptSecContext() will return a token
for the peer and isEstablished() will return "true" also. This
indicates that the token needs to be sent to the peer, but the local
end of the context is now fully established.
The GSS-API authentication tokens contain a definitive start and end.
This method will attempt to read one of these tokens per invocation,
and may block on the stream if only part of the token is available.
Upon completion of the context establishment, the available context
options may be queried through the get methods.
A GSSException will be thrown if the call fails. Users should call
its getOutputToken() method to find out if there is a token that can
be sent to the initiator to communicate the reason for the error.
Parameters:
inStream Contains the token generated by the peer.
outStream Output stream where the output token will be
written. During the final stage of context
establishment, there may be no bytes written.
6.4.10. Example Code
This sample code merely demonstrates the token exchange during the
context establishment phase. It is expected that most Java
applications will use custom implementations of the Input and Output
streams that encapsulate the communication routines. For instance, a
simple read on the application InputStream, when called by the
Context, might cause a token to be read from the peer, and a simple
flush() on the application OutputStream might cause a previously
written token to be transmitted to the peer.
<CODE BEGINS>
// acquire server credentials
GSSCredential server = mgr.createCredential(...);
// create acceptor GSS-API context from the default provider
GSSContext context = mgr.createContext(server, null);
// use standard java.io stream objects
ByteArrayOutputStream os = new ByteArrayOutputStream();
ByteArrayInputStream is = null;
try {
do {
is = recvToken();
context.acceptSecContext(is, os);
// possibly send token to peer
if (os.size() > 0)
sendToken(os);
// check if local context establishment is complete
if (context.isEstablished())
break;
} while (true);
} catch (GSSException e) {
print("GSS-API error: " + e.getMessage());
// If the exception contains an output token,
// it should be sent to the initiator.
byte[] outTok = e.getOutputToken();
if (outTok != null) {
sendToken(new ByteArrayOutputStream(outTok));
}
}
<CODE ENDS>
6.4.11. isEstablished
public boolean isEstablished() public boolean isEstablished()
Used during context establishment to determine the state of the Used during context establishment to determine the state of the
context. Returns "true" if this is a fully established context on context. Returns "true" if this is a fully established context on
the caller's side and no more tokens are needed from the peer. the caller's side and no more tokens are needed from the peer.
Should be called after a call to initSecContext() or Should be called after a call to initSecContext() or
acceptSecContext() when no GSSException is thrown. acceptSecContext() when no GSSException is thrown.
6.4.12. dispose 6.4.8. dispose
public void dispose() throws GSSException public void dispose() throws GSSException
Releases any system resources and cryptographic information stored in Releases any system resources and cryptographic information stored in
the context object. This will invalidate the context. the context object. This will invalidate the context.
6.4.13. getWrapSizeLimit 6.4.9. getWrapSizeLimit
public int getWrapSizeLimit(int qop, boolean confReq, public int getWrapSizeLimit(int qop, boolean confReq,
int maxTokenSize) throws GSSException int maxTokenSize) throws GSSException
Returns the maximum message size that, if presented to the wrap Returns the maximum message size that, if presented to the wrap
method with the same confReq and qop parameters, will result in an method with the same confReq and qop parameters, will result in an
output token containing no more than the maxTokenSize bytes. output token containing no more than the maxTokenSize bytes.
This call is intended for use by applications that communicate over This call is intended for use by applications that communicate over
protocols that impose a maximum message size. It enables the protocols that impose a maximum message size. It enables the
skipping to change at page 66, line 5 skipping to change at page 62, line 5
qop Indicates the level of protection wrap will be qop Indicates the level of protection wrap will be
asked to provide. asked to provide.
confReq Indicates if wrap will be asked to provide confReq Indicates if wrap will be asked to provide
privacy service. privacy service.
maxTokenSize The desired maximum size of the token emitted by maxTokenSize The desired maximum size of the token emitted by
wrap. wrap.
6.4.14. wrap 6.4.10. wrap
public byte[] wrap(byte[] inBuf, int offset, int len, public byte[] wrap(byte[] inBuf, int offset, int len,
MessageProp msgProp) throws GSSException MessageProp msgProp) throws GSSException
Applies per-message security services over the established security Applies per-message security services over the established security
context. The method will return a token with a cryptographic MIC and context. The method will return a token with a cryptographic MIC and
may optionally encrypt the specified inBuf. This method is may optionally encrypt the specified inBuf. The returned byte array
equivalent in functionality to its stream counterpart. The returned will contain both the MIC and the message.
byte array will contain both the MIC and the message.
The MessageProp object is instantiated by the application and used to The MessageProp object is instantiated by the application and used to
specify a QOP value that selects cryptographic algorithms, and a specify a QOP value that selects cryptographic algorithms, and a
privacy service to optionally encrypt the message. The underlying privacy service to optionally encrypt the message. The underlying
mechanism that is used in the call may not be able to provide the mechanism that is used in the call may not be able to provide the
privacy service. It sets the actual privacy service that it does privacy service. It sets the actual privacy service that it does
provide in this MessageProp object, which the caller should then provide in this MessageProp object, which the caller should then
query upon return. If the mechanism is not able to provide the query upon return. If the mechanism is not able to provide the
requested QOP, it throws a GSSException with the BAD_QOP code. requested QOP, it throws a GSSException with the BAD_QOP code.
skipping to change at page 67, line 5 skipping to change at page 63, line 5
at the offset). at the offset).
msgProp Instance of MessageProp that is used by the msgProp Instance of MessageProp that is used by the
application to set the desired QOP and privacy application to set the desired QOP and privacy
state. Set the desired QOP to 0 to request the state. Set the desired QOP to 0 to request the
default QOP. Upon return from this method, this default QOP. Upon return from this method, this
object will contain the actual privacy state that object will contain the actual privacy state that
was applied to the message by the underlying was applied to the message by the underlying
mechanism. mechanism.
6.4.15. wrap 6.4.11. unwrap
public void wrap(InputStream inStream, OutputStream outStream,
MessageProp msgProp) throws GSSException
Allows to apply per-message security services over the established
security context. The method will produce a token with a
cryptographic MIC and may optionally encrypt the message in inStream.
The outStream will contain both the MIC and the message.
The MessageProp object is instantiated by the application and used to
specify a QOP value that selects cryptographic algorithms, and a
privacy service to optionally encrypt the message. The underlying
mechanism that is used in the call may not be able to provide the
privacy service. It sets the actual privacy service that it does
provide in this MessageProp object, which the caller should then
query upon return. If the mechanism is not able to provide the
requested QOP, it throws a GSSException with the BAD_QOP code.
Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support
the wrapping of zero-length messages.
The application will be responsible for sending the token to the
peer.
Parameters:
inStream Input stream containing the application data to
be protected.
outStream The output stream to which to write the protected
message. The application is responsible for
sending this to the other peer for processing in
its unwrap method.
msgProp Instance of MessageProp that is used by the
application to set the desired QOP and privacy
state. Set the desired QOP to 0 to request the
default QOP. Upon return from this method, this
object will contain the actual privacy state that
was applied to the message by the underlying
mechanism.
6.4.16. unwrap
public byte[] unwrap(byte[] inBuf, int offset, int len, public byte[] unwrap(byte[] inBuf, int offset, int len,
MessageProp msgProp) throws GSSException MessageProp msgProp) throws GSSException
Used by the peer application to process tokens generated with the Used by the peer application to process tokens generated with the
wrap call. This call is equal in functionality to its stream wrap call. The method will return the message supplied in the peer
counterpart. The method will return the message supplied in the peer
application to the wrap call, verifying the embedded MIC. application to the wrap call, verifying the embedded MIC.
The MessageProp object is instantiated by the application and is used The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such by the underlying mechanism to return information to the caller such
as the QOP, whether confidentiality was applied to the message, and as the QOP, whether confidentiality was applied to the message, and
other supplementary message state information. other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support by wrap to provide "secure framing", implementations should support
the wrapping and unwrapping of zero-length messages. the wrapping and unwrapping of zero-length messages.
skipping to change at page 68, line 41 skipping to change at page 63, line 40
len The length of the token within the inBuf len The length of the token within the inBuf
(starting at the offset). (starting at the offset).
msgProp Upon return from the method, this object will msgProp Upon return from the method, this object will
contain the applied QOP, the privacy state of the contain the applied QOP, the privacy state of the
message, and supplementary information, described message, and supplementary information, described
in section 4.12.3, stating whether the token was in section 4.12.3, stating whether the token was
a duplicate, old, out of sequence, or arriving a duplicate, old, out of sequence, or arriving
after a gap. after a gap.
6.4.17. unwrap 6.4.12. getMIC
public void unwrap(InputStream inStream, OutputStream outStream,
MessageProp msgProp) throws GSSException
Used by the peer application to process tokens generated with the
wrap call. This call is equal in functionality to its byte array
counterpart. It will produce the message supplied in the peer
application to the wrap call, verifying the embedded MIC.
The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such
as the QOP, whether confidentiality was applied to the message, and
other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support
the wrapping and unwrapping of zero-length messages.
Parameters:
inStream Input stream containing the GSS-API wrap token
received from the peer.
outStream The output stream to which to write the
application message.
msgProp Upon return from the method, this object will
contain the applied QOP, the privacy state of the
message, and supplementary information, described
in section 4.12.3, stating whether the token was
a duplicate, old, out of sequence, or arriving
after a gap.
6.4.18. getMIC
public byte[] getMIC(byte[] inMsg, int offset, int len, public byte[] getMIC(byte[] inMsg, int offset, int len,
MessageProp msgProp) throws GSSException MessageProp msgProp) throws GSSException
Returns a token containing a cryptographic MIC for the supplied Returns a token containing a cryptographic MIC for the supplied
message for transfer to the peer application. Unlike wrap, which message for transfer to the peer application. Unlike wrap, which
encapsulates the user message in the returned token, only the message encapsulates the user message in the returned token, only the message
MIC is returned in the output token. This method is identical in MIC is returned in the output token.
functionality to its stream counterpart.
Note that privacy can only be applied through the wrap call. Note that privacy can only be applied through the wrap call.
Since some application-level protocols may wish to use tokens emitted Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support by getMIC to provide "secure framing", implementations should support
derivation of MICs from zero-length messages. derivation of MICs from zero-length messages.
Parameters: Parameters:
inMsg Message over which to generate MIC. inMsg Message over which to generate MIC.
skipping to change at page 70, line 11 skipping to change at page 64, line 25
len The length of the token within the inMsg len The length of the token within the inMsg
(starting at the offset). (starting at the offset).
msgProp Instance of MessageProp that is used by the msgProp Instance of MessageProp that is used by the
application to set the desired QOP. Set the application to set the desired QOP. Set the
desired QOP to 0 in msgProp to request the desired QOP to 0 in msgProp to request the
default QOP. Alternatively, pass in "null" for default QOP. Alternatively, pass in "null" for
msgProp to request default QOP. msgProp to request default QOP.
6.4.19. getMIC 6.4.13. verifyMIC
public void getMIC(InputStream inStream, OutputStream outStream,
MessageProp msgProp) throws GSSException
Produces a token containing a cryptographic MIC for the supplied
message, for transfer to the peer application. Unlike wrap, which
encapsulates the user message in the returned token, only the message
MIC is produced in the output token. This method is identical in
functionality to its byte array counterpart.
Note that privacy can only be applied through the wrap call.
Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support
derivation of MICs from zero-length messages.
Parameters:
inStream Input stream containing the message over which to
generate MIC.
outStream Output stream to which to write the GSS-API
output token.
msgProp Instance of MessageProp that is used by the
application to set the desired QOP. Set the
desired QOP to 0 in msgProp to request the
default QOP. Alternatively, pass in "null" for
msgProp to request default QOP.
6.4.20. verifyMIC
public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, public void verifyMIC(byte[] inTok, int tokOffset, int tokLen,
byte[] inMsg, int msgOffset, int msgLen, byte[] inMsg, int msgOffset, int msgLen,
MessageProp msgProp) throws GSSException MessageProp msgProp) throws GSSException
Verifies the cryptographic MIC, contained in the token parameter, Verifies the cryptographic MIC, contained in the token parameter,
over the supplied message. This method is equivalent in over the supplied message.
functionality to its stream counterpart.
The MessageProp object is instantiated by the application and is used The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such by the underlying mechanism to return information to the caller such
as the QOP indicating the strength of protection that was applied to as the QOP indicating the strength of protection that was applied to
the message and other supplementary message state information. the message and other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support by getMIC to provide "secure framing", implementations should support
the calculation and verification of MICs over zero-length messages. the calculation and verification of MICs over zero-length messages.
skipping to change at page 71, line 40 skipping to change at page 65, line 21
msgLen The length of the message within the inMsg msgLen The length of the message within the inMsg
(starting at the offset). (starting at the offset).
msgProp Upon return from the method, this object will msgProp Upon return from the method, this object will
contain the applied QOP and supplementary contain the applied QOP and supplementary
information, described in section 4.12.3, stating information, described in section 4.12.3, stating
whether the token was a duplicate, old, out of whether the token was a duplicate, old, out of
sequence, or arriving after a gap. The sequence, or arriving after a gap. The
confidentiality state will be set to "false". confidentiality state will be set to "false".
6.4.21. verifyMIC 6.4.14. export
public void verifyMIC(InputStream tokStream, InputStream msgStream,
MessageProp msgProp) throws GSSException
Verifies the cryptographic MIC, contained in the token parameter,
over the supplied message. This method is equivalent in
functionality to its byte array counterpart.
The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such
as the QOP indicating the strength of protection that was applied to
the message and other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support
the calculation and verification of MICs over zero-length messages.
Parameters:
tokStream Input stream containing the token generated by
the peer's getMIC method.
msgStream Input stream containing the application message
over which to verify the cryptographic MIC.
msgProp Upon return from the method, this object will
contain the applied QOP and supplementary
information, described in section 4.12.3, stating
whether the token was a duplicate, old, out of
sequence, or arriving after a gap. The
confidentiality state will be set to "false".
6.4.22. export
public byte[] export() throws GSSException public byte[] export() throws GSSException
Provided to support the sharing of work between multiple processes. Provided to support the sharing of work between multiple processes.
This routine will typically be used by the context acceptor, in an This routine will typically be used by the context acceptor, in an
application where a single process receives incoming connection application where a single process receives incoming connection
requests and accepts security contexts over them, then passes the requests and accepts security contexts over them, then passes the
established context to one or more other processes for message established context to one or more other processes for message
exchange. exchange.
skipping to change at page 73, line 9 skipping to change at page 66, line 7
The inter-process token may contain security-sensitive information The inter-process token may contain security-sensitive information
(for example, cryptographic keys). While mechanisms are encouraged (for example, cryptographic keys). While mechanisms are encouraged
to either avoid placing such sensitive information within inter- to either avoid placing such sensitive information within inter-
process tokens or to encrypt the token before returning it to the process tokens or to encrypt the token before returning it to the
application, in a typical GSS-API implementation, this may not be application, in a typical GSS-API implementation, this may not be
possible. Thus, the application must take care to protect the inter- possible. Thus, the application must take care to protect the inter-
process token, and ensure that any process to which the token is process token, and ensure that any process to which the token is
transferred is trustworthy. transferred is trustworthy.
6.4.23. requestMutualAuth 6.4.15. requestMutualAuth
public void requestMutualAuth(boolean state) throws GSSException public void requestMutualAuth(boolean state) throws GSSException
Sets the request state of the mutual authentication flag for the Sets the request state of the mutual authentication flag for the
context. This method is only valid before the context creation context. This method is only valid before the context creation
process begins and only for the initiator. process begins and only for the initiator.
Parameters: Parameters:
state Boolean representing if mutual authentication state Boolean representing if mutual authentication
should be requested during context establishment. should be requested during context establishment.
6.4.24. requestReplayDet 6.4.16. requestReplayDet
public void requestReplayDet(boolean state) throws GSSException public void requestReplayDet(boolean state) throws GSSException
Sets the request state of the replay detection service for the Sets the request state of the replay detection service for the
context. This method is only valid before the context creation context. This method is only valid before the context creation
process begins and only for the initiator. process begins and only for the initiator.
Parameters: Parameters:
state Boolean representing if replay detection is state Boolean representing if replay detection is
desired over the established context. desired over the established context.
6.4.25. requestSequenceDet 6.4.17. requestSequenceDet
public void requestSequenceDet(boolean state) throws GSSException public void requestSequenceDet(boolean state) throws GSSException
Sets the request state for the sequence checking service of the Sets the request state for the sequence checking service of the
context. This method is only valid before the context creation context. This method is only valid before the context creation
process begins and only for the initiator. process begins and only for the initiator.
Parameters: Parameters:
state Boolean representing if sequence detection is state Boolean representing if sequence detection is
desired over the established context. desired over the established context.
6.4.26. requestCredDeleg 6.4.18. requestCredDeleg
public void requestCredDeleg(boolean state) throws GSSException public void requestCredDeleg(boolean state) throws GSSException
Sets the request state for the credential delegation flag for the Sets the request state for the credential delegation flag for the
context. This method is only valid before the context creation context. This method is only valid before the context creation
process begins and only for the initiator. process begins and only for the initiator.
Parameters: Parameters:
state Boolean representing if credential delegation is state Boolean representing if credential delegation is
desired. desired.
6.4.27. requestAnonymity 6.4.19. requestAnonymity
public void requestAnonymity(boolean state) throws GSSException public void requestAnonymity(boolean state) throws GSSException
Requests anonymous support over the context. This method is only Requests anonymous support over the context. This method is only
valid before the context creation process begins and only for the valid before the context creation process begins and only for the
initiator. initiator.
Parameters: Parameters:
state Boolean representing if anonymity support is state Boolean representing if anonymity support is
requested. requested.
6.4.28. requestConf 6.4.20. requestConf
public void requestConf(boolean state) throws GSSException public void requestConf(boolean state) throws GSSException
Requests that confidentiality service be available over the context. Requests that confidentiality service be available over the context.
This method is only valid before the context creation process begins This method is only valid before the context creation process begins
and only for the initiator. and only for the initiator.
Parameters: Parameters:
state Boolean indicating if confidentiality services state Boolean indicating if confidentiality services
are to be requested for the context. are to be requested for the context.
6.4.29. requestInteg 6.4.21. requestInteg
public void requestInteg(boolean state) throws GSSException public void requestInteg(boolean state) throws GSSException
Requests that integrity services be available over the context. This Requests that integrity services be available over the context. This
method is only valid before the context creation process begins and method is only valid before the context creation process begins and
only for the initiator. only for the initiator.
Parameters: Parameters:
state Boolean indicating if integrity services are to state Boolean indicating if integrity services are to
be requested for the context. be requested for the context.
6.4.30. requestLifetime 6.4.22. requestLifetime
public void requestLifetime(int lifetime) throws GSSException public void requestLifetime(int lifetime) throws GSSException
Sets the desired lifetime for the context in seconds. This method is Sets the desired lifetime for the context in seconds. This method is
only valid before the context creation process begins and only for only valid before the context creation process begins and only for
the initiator. Use GSSContext.INDEFINITE_LIFETIME and the initiator. Use GSSContext.INDEFINITE_LIFETIME and
GSSContext.DEFAULT_LIFETIME to request indefinite or default context GSSContext.DEFAULT_LIFETIME to request indefinite or default context
lifetime. lifetime.
Parameters: Parameters:
lifetime The desired context lifetime in seconds. lifetime The desired context lifetime in seconds.
6.4.31. setChannelBinding 6.4.23. setChannelBinding
public void setChannelBinding(ChannelBinding cb) throws GSSException public void setChannelBinding(ChannelBinding cb) throws GSSException
Sets the channel bindings to be used during context establishment. Sets the channel bindings to be used during context establishment.
This method is only valid before the context creation process begins. This method is only valid before the context creation process begins.
Parameters: Parameters:
cb Channel bindings to be used. cb Channel bindings to be used.
6.4.32. getCredDelegState 6.4.24. getCredDelegState
public boolean getCredDelegState() public boolean getCredDelegState()
Returns the state of the delegated credentials for the context. When Returns the state of the delegated credentials for the context. When
issued before context establishment is completed or when the issued before context establishment is completed or when the
isProtReady method returns "false", it returns the desired state; isProtReady method returns "false", it returns the desired state;
otherwise, it will indicate the actual state over the established otherwise, it will indicate the actual state over the established
context. context.
6.4.33. getMutualAuthState 6.4.25. getMutualAuthState
public boolean getMutualAuthState() public boolean getMutualAuthState()
Returns the state of the mutual authentication option for the Returns the state of the mutual authentication option for the
context. When issued before context establishment completes or when context. When issued before context establishment completes or when
the isProtReady method returns "false", it returns the desired state; the isProtReady method returns "false", it returns the desired state;
otherwise, it will indicate the actual state over the established otherwise, it will indicate the actual state over the established
context. context.
6.4.34. getReplayDetState 6.4.26. getReplayDetState
public boolean getReplayDetState() public boolean getReplayDetState()
Returns the state of the replay detection option for the context. Returns the state of the replay detection option for the context.
When issued before context establishment completes or when the When issued before context establishment completes or when the
isProtReady method returns "false", it returns the desired state; isProtReady method returns "false", it returns the desired state;
otherwise, it will indicate the actual state over the established otherwise, it will indicate the actual state over the established
context. context.
6.4.35. getSequenceDetState 6.4.27. getSequenceDetState
public boolean getSequenceDetState() public boolean getSequenceDetState()
Returns the state of the sequence detection option for the context. Returns the state of the sequence detection option for the context.
When issued before context establishment completes or when the When issued before context establishment completes or when the
isProtReady method returns "false", it returns the desired state; isProtReady method returns "false", it returns the desired state;
otherwise, it will indicate the actual state over the established otherwise, it will indicate the actual state over the established
context. context.
6.4.36. getAnonymityState 6.4.28. getAnonymityState
public boolean getAnonymityState() public boolean getAnonymityState()
Returns "true" if this is an anonymous context. When issued before Returns "true" if this is an anonymous context. When issued before
context establishment completes or when the isProtReady method context establishment completes or when the isProtReady method
returns "false", it returns the desired state; otherwise, it will returns "false", it returns the desired state; otherwise, it will
indicate the actual state over the established context. indicate the actual state over the established context.
6.4.37. isTransferable 6.4.29. isTransferable
public boolean isTransferable() throws GSSException public boolean isTransferable() throws GSSException
Returns "true" if the context is transferable to other processes Returns "true" if the context is transferable to other processes
through the use of the export method. This call is only valid on through the use of the export method. This call is only valid on
fully established contexts. fully established contexts.
6.4.38. isProtReady 6.4.30. isProtReady
public boolean isProtReady() public boolean isProtReady()
Returns "true" if the per-message operations can be applied over the Returns "true" if the per-message operations can be applied over the
context. Some mechanisms may allow the usage of per-message context. Some mechanisms may allow the usage of per-message
operations before the context is fully established. This will also operations before the context is fully established. This will also
indicate that the get methods will return actual context state indicate that the get methods will return actual context state
characteristics instead of the desired ones. characteristics instead of the desired ones.
6.4.39. getConfState 6.4.31. getConfState
public boolean getConfState() public boolean getConfState()
Returns the confidentiality service state over the context. When Returns the confidentiality service state over the context. When
issued before context establishment completes or when the isProtReady issued before context establishment completes or when the isProtReady
method returns "false", it returns the desired state; otherwise, it method returns "false", it returns the desired state; otherwise, it
will indicate the actual state over the established context. will indicate the actual state over the established context.
6.4.40. getIntegState 6.4.32. getIntegState
public boolean getIntegState() public boolean getIntegState()
Returns the integrity service state over the context. When issued Returns the integrity service state over the context. When issued
before context establishment completes or when the isProtReady method before context establishment completes or when the isProtReady method
returns "false", it returns the desired state; otherwise, it will returns "false", it returns the desired state; otherwise, it will
indicate the actual state over the established context. indicate the actual state over the established context.
6.4.41. getLifetime 6.4.33. getLifetime
public int getLifetime() public int getLifetime()
Returns the context lifetime in seconds. When issued before context Returns the context lifetime in seconds. When issued before context
establishment completes or when the isProtReady method returns establishment completes or when the isProtReady method returns
"false", it returns the desired lifetime; otherwise, it will indicate "false", it returns the desired lifetime; otherwise, it will indicate
the remaining lifetime for the context. the remaining lifetime for the context.
6.4.42. getSrcName 6.4.34. getSrcName
public GSSName getSrcName() throws GSSException public GSSName getSrcName() throws GSSException
Returns the name of the context initiator. This call is valid only Returns the name of the context initiator. This call is valid only
after the context is fully established or the isProtReady method after the context is fully established or the isProtReady method
returns "true". It is guaranteed to return an MN. returns "true". It is guaranteed to return an MN.
6.4.43. getTargName 6.4.35. getTargName
public GSSName getTargName() throws GSSException public GSSName getTargName() throws GSSException
Returns the name of the context target (acceptor). This call is Returns the name of the context target (acceptor). This call is
valid only after the context is fully established or the isProtReady valid only after the context is fully established or the isProtReady
method returns "true". It is guaranteed to return an MN. method returns "true". It is guaranteed to return an MN.
6.4.44. getMech 6.4.36. getMech
public Oid getMech() throws GSSException public Oid getMech() throws GSSException
Returns the mechanism oid for this context. This method may be Returns the mechanism oid for this context. This method may be
called before the context is fully established, but the mechanism called before the context is fully established, but the mechanism
returned may change on successive calls in negotiated mechanism case. returned may change on successive calls in negotiated mechanism case.
6.4.45. getDelegCred 6.4.37. getDelegCred
public GSSCredential getDelegCred() throws GSSException public GSSCredential getDelegCred() throws GSSException
Returns the delegated credential object on the acceptor's side. To Returns the delegated credential object on the acceptor's side. To
check for availability of delegated credentials call check for availability of delegated credentials call
getDelegCredState. This call is only valid on fully established getDelegCredState. This call is only valid on fully established
contexts. contexts.
6.4.46. isInitiator 6.4.38. isInitiator
public boolean isInitiator() throws GSSException public boolean isInitiator() throws GSSException
Returns "true" if this is the initiator of the context. This call is Returns "true" if this is the initiator of the context. This call is
only valid after the context creation process has started. only valid after the context creation process has started.
6.5. public class MessageProp 6.5. public class MessageProp
This is a utility class used within the per-message GSSContext This is a utility class used within the per-message GSSContext
methods to convey per-message properties. methods to convey per-message properties.
skipping to change at page 88, line 12 skipping to change at page 81, line 12
codes are indicated via the MessageProp object.) The value of this codes are indicated via the MessageProp object.) The value of this
constant is 22. constant is 22.
6.8.2. Constructors 6.8.2. Constructors
public GSSException(int majorCode) public GSSException(int majorCode)
Creates a GSSException object with a specified major code. Creates a GSSException object with a specified major code.
Calling this constructor is equivalent to calling Calling this constructor is equivalent to calling
GSSException(majorCode, 0, null, null). GSSException(majorCode, null, 0, null, null).
public GSSException(int majorCode, int minorCode, String minorString) public GSSException(int majorCode, int minorCode, String minorString)
Creates a GSSException object with the specified major code, minor Creates a GSSException object with the specified major code, minor
code, and minor code textual explanation. This constructor is to be code, and minor code textual explanation. This constructor is to be
used when the exception is originating from the security mechanism. used when the exception is originating from the security mechanism.
It allows to specify the GSS code and the mechanism code. It allows to specify the GSS code and the mechanism code.
Calling this constructor is equivalent to calling Calling this constructor is equivalent to calling
GSSException(majorCode, minorCode, minorString, null). GSSException(majorCode, null, minorCode, minorString, null).
public GSSException(int majorCode, String majorString, public GSSException(int majorCode, String majorString,
int minorCode, String minorString, int minorCode, String minorString,
byte[] outputToken) byte[] outputToken)
Creates a GSSException object with the specified major code, major Creates a GSSException object with the specified major code, major
code textual explanation, minor code, minor code textual explanation, code textual explanation, minor code, minor code textual explanation,
and an output token. This is a general-purpose constructor that can and an output token. This is a general-purpose constructor that can
be used to create any type of GSSException. be used to create any type of GSSException.
skipping to change at page 99, line 33 skipping to change at page 92, line 33
We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael
Saltz, and other members of Sun's development team for their helpful Saltz, and other members of Sun's development team for their helpful
input, comments, and suggestions. input, comments, and suggestions.
We would also like to thank Joe Salowey, and Michael Smith for many We would also like to thank Joe Salowey, and Michael Smith for many
insightful ideas and suggestions that have contributed to this insightful ideas and suggestions that have contributed to this
document. document.
11. Changes since RFC 5653 11. Changes since RFC 5653
There is a design flaw in the initSecContext and acceptSecContext This document has following changes:
methods of the GSSContext class defined in Generic Security Service
API Version 2: Java Bindings Update [RFC5653].
The methods could either return a token (possibly null if no more 1) New error token embedded in GSSException
tokens are needed) when the call succeeds or throw a GSSException if
there is a failure, but NOT both. On the other hand, the C bindings
of GSS-API [RFC2744] can return both, that is to say, a call to the
GSS_Init_sec_context() function can return a major status code, and
at the same time, fill in the output_token argument if there is one.
Without the ability to emit an error token when there is a failure, a There is a design flaw in the initSecContext and acceptSecContext
Java application has no mechanism to tell the other side what the methods of the GSSContext class defined in Generic Security
error is. For example, a "reject" NegTokenResp token can never be Service API Version 2: Java Bindings Update [RFC5653].
transmitted for the SPNEGO mechanism [RFC4178].
While a Java method can never return a value and throw an exception The methods could either return a token (possibly null if no more
at the same time, we can embed the error token inside the exception tokens are needed) when the call succeeds or throw a GSSException
so that the caller has a chance to retrieve it. This update adds a if there is a failure, but NOT both. On the other hand, the C
new GSSException constructor to include this token inside a bindings of GSS-API [RFC2744] can return both, that is to say, a
GSSException object, and a getOutputToken() method to retrieve the call to the GSS_Init_sec_context() function can return a major
token. The specification for the initSecContext and acceptSecContext status code, and at the same time, fill in the output_token
methods are updated to describe the new behavior. Various examples argument if there is one.
are also updated.
This is a compatible change. New JGSS programs should make use of Without the ability to emit an error token when there is a
this new feature but it is not mandatory. failure, a Java application has no mechanism to tell the other
side what the error is. For example, a "reject" NegTokenResp
token can never be transmitted for the SPNEGO mechanism [RFC4178].
While a Java method can never return a value and throw an
exception at the same time, we can embed the error token inside
the exception so that the caller has a chance to retrieve it.
This update adds a new GSSException constructor to include this
token inside a GSSException object, and a getOutputToken() method
to retrieve the token. The specification for the initSecContext
and acceptSecContext methods are updated to describe the new
behavior. Various examples are also updated.
This is a compatible change. New JGSS programs should make use of
this new feature but it is not mandatory.
2) Removing stream-based GSSContext methods
The overloaded methods of GSSContext that use input and output
streams as the means to convey authentication and per-message GSS-
API tokens as described in Section 5.15 of RFC 5653 [RFC5653] are
removed in this update as the wire protocol should be defined by
an application and not a library. It's also impossible to
implement these methods correctly when the token has no self-
framing (where the end cannot be determined) or the library has no
knowledge of the token format (for example, as a bridge talking to
another GSS library). These methods include initSecContext
(Section 7.4.5 of RFC 5653 [RFC5653]), acceptSecContext
(Section 7.4.9 of RFC 5653 [RFC5653]), wrap (Section 7.4.15 of RFC
5653 [RFC5653]), unwrap (Section 7.4.17 of RFC 5653 [RFC5653]),
getMIC (Section 7.4.19 of RFC 5653 [RFC5653]), and verifyMIC
(Section 7.4.21 of RFC 5653 [RFC5653]).
12. Changes since RFC 2853 12. Changes since RFC 2853
This document has following changes: This document has following changes:
1) Major GSS Status Code Constant Values 1) Major GSS Status Code Constant Values
RFC 2853 listed all the GSS status code values in two different RFC 2853 listed all the GSS status code values in two different
sections: section 4.12.1 defined numeric values for them, and sections: section 4.12.1 defined numeric values for them, and
section 6.8.1 defined them as static constants in the GSSException section 6.8.1 defined them as static constants in the GSSException
skipping to change at page 101, line 10 skipping to change at page 94, line 33
This document updates the NT_HOSTBASED_SERVICE OID value in This document updates the NT_HOSTBASED_SERVICE OID value in
section 6.2.2 to be consistent with the C-bindings in RFC 2744 section 6.2.2 to be consistent with the C-bindings in RFC 2744
[RFC2744]. [RFC2744].
13. References 13. References
13.1. Normative References 13.1. Normative References
[RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
(SPKM)", RFC 2025, October 1996. (SPKM)", RFC 2025, DOI 10.17487/RFC2025, October 1996,
<http://www.rfc-editor.org/info/rfc2025>.
[RFC2743] Linn, J., "Generic Security Service Application Program [RFC2743] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", RFC 2743, January 2000. Interface Version 2, Update 1", RFC 2743,
DOI 10.17487/RFC2743, January 2000,
<http://www.rfc-editor.org/info/rfc2743>.
[RFC2744] Wray, J., "Generic Security Service API Version 2 : [RFC2744] Wray, J., "Generic Security Service API Version 2 :
C-bindings", RFC 2744, January 2000. C-bindings", RFC 2744, DOI 10.17487/RFC2744, January 2000,
<http://www.rfc-editor.org/info/rfc2744>.
[RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API
Version 2 : Java Bindings", RFC 2853, June 2000. Version 2 : Java Bindings", RFC 2853,
DOI 10.17487/RFC2853, June 2000,
<http://www.rfc-editor.org/info/rfc2853>.
[RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
Version 5 Generic Security Service Application Program Version 5 Generic Security Service Application Program
Interface (GSS-API) Mechanism: Version 2", RFC 4121, July Interface (GSS-API) Mechanism: Version 2", RFC 4121,
2005. DOI 10.17487/RFC4121, July 2005,
<http://www.rfc-editor.org/info/rfc4121>.
[RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
Simple and Protected Generic Security Service Application Simple and Protected Generic Security Service Application
Program Interface (GSS-API) Negotiation Mechanism", RFC Program Interface (GSS-API) Negotiation Mechanism",
4178, October 2005. RFC 4178, DOI 10.17487/RFC4178, October 2005,
<http://www.rfc-editor.org/info/rfc4178>.
[RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API [RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API
Version 2: Java Bindings Update", RFC 5653, August 2009. Version 2: Java Bindings Update", RFC 5653,
DOI 10.17487/RFC5653, August 2009,
<http://www.rfc-editor.org/info/rfc5653>.
13.2. Informative References 13.2. Informative References
[JLS] Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java [JLS] Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java
Language Specification", Third Edition, 2005, Language Specification", Third Edition, 2005,
<http://java.sun.com/docs/books/jls/>. <http://java.sun.com/docs/books/jls/>.
Authors' Addresses Authors' Addresses
Mayank D. Upadhyay Mayank D. Upadhyay
 End of changes. 86 change blocks. 
567 lines changed or deleted 238 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/