idnits 2.17.1 draft-ietf-kitten-rfc2853bis-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 4470. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4481. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4488. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4494. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. -- The abstract seems to indicate that this document obsoletes RFC2853, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 8, 2008) is 5769 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 4009 ** Obsolete normative reference: RFC 2853 (Obsoleted by RFC 5653) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Upadhyay 3 Internet-Draft Google 4 Intended status: Standards Track S. Malkani 5 Expires: January 9, 2009 Sun Microsystems 6 July 8, 2008 8 Generic Security Service API Version 2 : Java Bindings Update 9 draft-ietf-kitten-rfc2853bis-04.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on January 9, 2009. 36 Abstract 38 The Generic Security Services Application Program Interface (GSS-API) 39 offers application programmers uniform access to security services 40 atop a variety of underlying cryptographic mechanisms. This document 41 updates the Java bindings for the GSS-API that are specified in 42 "Generic Security Service API version 2 : Java Bindings" (RFC2853). 43 This document obsoletes RFC 2853 by making specific and incremental 44 clarifications and corrections to it in response to identification of 45 transcription errors and implementation experience. 47 The GSS-API is described at a language independent conceptual level 48 in "Generic Security Service Application Program Interface Version 2, 49 Update 1" (RFC2743). The GSS-API allows a caller application to 50 authenticate a principal identity, to delegate rights to a peer, and 51 to apply security services such as confidentiality and integrity on a 52 per-message basis. Examples of security mechanisms defined for GSS- 53 API are "The Simple Public-Key GSS-API Mechanism" (RFC2025) and "The 54 Kerberos Version 5 GSS-API Mechanism (RFC4121). 56 Table of Contents 58 1. Conventions Used in This Document . . . . . . . . . . 6 59 2. Introduction . . . . . . . . . . . . . . . . . . . . . 6 60 3. GSS-API Operational Paradigm . . . . . . . . . . . . . 7 61 4. Additional Controls . . . . . . . . . . . . . . . . . 8 62 4.1. Delegation . . . . . . . . . . . . . . . . . . . . . . 9 63 4.2. Mutual Authentication . . . . . . . . . . . . . . . . 10 64 4.3. Replay and Out-of-Sequence Detection . . . . . . . . . 10 65 4.4. Anonymous Authentication . . . . . . . . . . . . . . . 11 66 4.5. Confidentiality . . . . . . . . . . . . . . . . . . . 12 67 4.6. Inter-process Context Transfer . . . . . . . . . . . . 12 68 4.7. The Use of Incomplete Contexts . . . . . . . . . . . . 13 69 5. Calling Conventions . . . . . . . . . . . . . . . . . 13 70 5.1. Package Name . . . . . . . . . . . . . . . . . . . . . 14 71 5.2. Provider Framework . . . . . . . . . . . . . . . . . . 14 72 5.3. Integer Types . . . . . . . . . . . . . . . . . . . . 15 73 5.4. Opaque Data Types . . . . . . . . . . . . . . . . . . 15 74 5.5. Strings . . . . . . . . . . . . . . . . . . . . . . . 15 75 5.6. Object Identifiers . . . . . . . . . . . . . . . . . . 15 76 5.7. Object Identifier Sets . . . . . . . . . . . . . . . . 15 77 5.8. Credentials . . . . . . . . . . . . . . . . . . . . . 16 78 5.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . 18 79 5.10. Authentication Tokens . . . . . . . . . . . . . . . . 18 80 5.11. Interprocess Tokens . . . . . . . . . . . . . . . . . 18 81 5.12. Error Reporting . . . . . . . . . . . . . . . . . . . 19 82 5.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . . 19 83 5.12.2. Mechanism-Specific Status Codes . . . . . . . . . . . 22 84 5.12.3. Supplementary Status Codes . . . . . . . . . . . . . . 22 85 5.13. Names . . . . . . . . . . . . . . . . . . . . . . . . 22 86 5.14. Channel Bindings . . . . . . . . . . . . . . . . . . . 25 87 5.15. Stream Objects . . . . . . . . . . . . . . . . . . . . 26 88 5.16. Optional Parameters . . . . . . . . . . . . . . . . . 26 89 6. Introduction to GSS-API Classes and Interfaces . . . . 26 90 6.1. GSSManager class . . . . . . . . . . . . . . . . . . . 27 91 6.2. GSSName interface . . . . . . . . . . . . . . . . . . 28 92 6.3. GSSCredential interface . . . . . . . . . . . . . . . 28 93 6.4. GSSContext interface . . . . . . . . . . . . . . . . . 29 94 6.5. MessageProp class . . . . . . . . . . . . . . . . . . 30 95 6.6. GSSException class . . . . . . . . . . . . . . . . . . 30 96 6.7. Oid class . . . . . . . . . . . . . . . . . . . . . . 31 97 6.8. ChannelBinding class . . . . . . . . . . . . . . . . . 31 98 7. Detailed GSS-API Class Description . . . . . . . . . . 31 99 7.1. public abstract class GSSManager . . . . . . . . . . . 31 100 7.1.1. Example Code . . . . . . . . . . . . . . . . . . . . . 32 101 7.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 33 102 7.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . . 33 103 7.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 33 104 7.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 33 105 7.1.6. createName . . . . . . . . . . . . . . . . . . . . . . 34 106 7.1.7. createName . . . . . . . . . . . . . . . . . . . . . . 34 107 7.1.8. createName . . . . . . . . . . . . . . . . . . . . . . 35 108 7.1.9. createName . . . . . . . . . . . . . . . . . . . . . . 35 109 7.1.10. createCredential . . . . . . . . . . . . . . . . . . . 36 110 7.1.11. createCredential . . . . . . . . . . . . . . . . . . . 36 111 7.1.12. createCredential . . . . . . . . . . . . . . . . . . . 37 112 7.1.13. createContext . . . . . . . . . . . . . . . . . . . . 37 113 7.1.14. createContext . . . . . . . . . . . . . . . . . . . . 38 114 7.1.15. createContext . . . . . . . . . . . . . . . . . . . . 38 115 7.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . . 38 116 7.1.17. Example Code . . . . . . . . . . . . . . . . . . . . . 39 117 7.1.18. addProviderAtEnd . . . . . . . . . . . . . . . . . . . 40 118 7.1.19. Example Code . . . . . . . . . . . . . . . . . . . . . 41 119 7.2. public interface GSSName . . . . . . . . . . . . . . . 41 120 7.2.1. Example Code . . . . . . . . . . . . . . . . . . . . . 42 121 7.2.2. Static Constants . . . . . . . . . . . . . . . . . . . 42 122 7.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 43 123 7.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 44 124 7.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . . 44 125 7.2.6. export . . . . . . . . . . . . . . . . . . . . . . . . 44 126 7.2.7. toString . . . . . . . . . . . . . . . . . . . . . . . 44 127 7.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 45 128 7.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 45 129 7.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . . 45 130 7.3. public interface GSSCredential implements Cloneable . 45 131 7.3.1. Example Code . . . . . . . . . . . . . . . . . . . . . 46 132 7.3.2. Static Constants . . . . . . . . . . . . . . . . . . . 47 133 7.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 47 134 7.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 47 135 7.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 47 136 7.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . . 48 137 7.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . . 48 138 7.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . . 48 139 7.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . . 49 140 7.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . . 49 141 7.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . . 49 142 7.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 49 143 7.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . . 50 144 7.4. public interface GSSContext . . . . . . . . . . . . . 50 145 7.4.1. Example Code . . . . . . . . . . . . . . . . . . . . . 51 146 7.4.2. Static Constants . . . . . . . . . . . . . . . . . . . 53 147 7.4.3. initSecContext . . . . . . . . . . . . . . . . . . . . 53 148 7.4.4. Example Code . . . . . . . . . . . . . . . . . . . . . 54 149 7.4.5. initSecContext . . . . . . . . . . . . . . . . . . . . 54 150 7.4.6. Example Code . . . . . . . . . . . . . . . . . . . . . 55 151 7.4.7. acceptSecContext . . . . . . . . . . . . . . . . . . . 56 152 7.4.8. Example Code . . . . . . . . . . . . . . . . . . . . . 57 153 7.4.9. acceptSecContext . . . . . . . . . . . . . . . . . . . 57 154 7.4.10. Example Code . . . . . . . . . . . . . . . . . . . . . 58 155 7.4.11. isEstablished . . . . . . . . . . . . . . . . . . . . 59 156 7.4.12. dispose . . . . . . . . . . . . . . . . . . . . . . . 59 157 7.4.13. getWrapSizeLimit . . . . . . . . . . . . . . . . . . . 59 158 7.4.14. wrap . . . . . . . . . . . . . . . . . . . . . . . . . 60 159 7.4.15. wrap . . . . . . . . . . . . . . . . . . . . . . . . . 61 160 7.4.16. unwrap . . . . . . . . . . . . . . . . . . . . . . . . 62 161 7.4.17. unwrap . . . . . . . . . . . . . . . . . . . . . . . . 62 162 7.4.18. getMIC . . . . . . . . . . . . . . . . . . . . . . . . 63 163 7.4.19. getMIC . . . . . . . . . . . . . . . . . . . . . . . . 64 164 7.4.20. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 64 165 7.4.21. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 65 166 7.4.22. export . . . . . . . . . . . . . . . . . . . . . . . . 66 167 7.4.23. requestMutualAuth . . . . . . . . . . . . . . . . . . 67 168 7.4.24. requestReplayDet . . . . . . . . . . . . . . . . . . . 67 169 7.4.25. requestSequenceDet . . . . . . . . . . . . . . . . . . 67 170 7.4.26. requestCredDeleg . . . . . . . . . . . . . . . . . . . 67 171 7.4.27. requestAnonymity . . . . . . . . . . . . . . . . . . . 68 172 7.4.28. requestConf . . . . . . . . . . . . . . . . . . . . . 68 173 7.4.29. requestInteg . . . . . . . . . . . . . . . . . . . . . 68 174 7.4.30. requestLifetime . . . . . . . . . . . . . . . . . . . 68 175 7.4.31. setChannelBinding . . . . . . . . . . . . . . . . . . 69 176 7.4.32. getCredDelegState . . . . . . . . . . . . . . . . . . 69 177 7.4.33. getMutualAuthState . . . . . . . . . . . . . . . . . . 69 178 7.4.34. getReplayDetState . . . . . . . . . . . . . . . . . . 69 179 7.4.35. getSequenceDetState . . . . . . . . . . . . . . . . . 70 180 7.4.36. getAnonymityState . . . . . . . . . . . . . . . . . . 70 181 7.4.37. isTransferable . . . . . . . . . . . . . . . . . . . . 70 182 7.4.38. isProtReady . . . . . . . . . . . . . . . . . . . . . 70 183 7.4.39. getConfState . . . . . . . . . . . . . . . . . . . . . 70 184 7.4.40. getIntegState . . . . . . . . . . . . . . . . . . . . 71 185 7.4.41. getLifetime . . . . . . . . . . . . . . . . . . . . . 71 186 7.4.42. getSrcName . . . . . . . . . . . . . . . . . . . . . . 71 187 7.4.43. getTargName . . . . . . . . . . . . . . . . . . . . . 71 188 7.4.44. getMech . . . . . . . . . . . . . . . . . . . . . . . 71 189 7.4.45. getDelegCred . . . . . . . . . . . . . . . . . . . . . 71 190 7.4.46. isInitiator . . . . . . . . . . . . . . . . . . . . . 72 191 7.5. public class MessageProp . . . . . . . . . . . . . . . 72 192 7.5.1. Constructors . . . . . . . . . . . . . . . . . . . . . 72 193 7.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . . 73 194 7.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . . 73 195 7.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . . 73 196 7.5.5. getMinorString . . . . . . . . . . . . . . . . . . . . 73 197 7.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . . 73 198 7.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . . 73 199 7.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . . 74 200 7.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . . 74 201 7.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . . 74 202 7.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . . 74 203 7.5.12. setSupplementaryStates . . . . . . . . . . . . . . . . 74 204 7.6. public class ChannelBinding . . . . . . . . . . . . . 75 205 7.6.1. Constructors . . . . . . . . . . . . . . . . . . . . . 75 206 7.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 76 207 7.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . . 76 208 7.6.4. getApplicationData . . . . . . . . . . . . . . . . . . 76 209 7.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 76 210 7.7. public class Oid . . . . . . . . . . . . . . . . . . . 77 211 7.7.1. Constructors . . . . . . . . . . . . . . . . . . . . . 77 212 7.7.2. toString . . . . . . . . . . . . . . . . . . . . . . . 78 213 7.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 78 214 7.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . . 78 215 7.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 78 216 7.8. public class GSSException extends Exception . . . . . 78 217 7.8.1. Static Constants . . . . . . . . . . . . . . . . . . . 79 218 7.8.2. Constructors . . . . . . . . . . . . . . . . . . . . . 81 219 7.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . . 82 220 7.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . . 82 221 7.8.5. getMajorString . . . . . . . . . . . . . . . . . . . . 82 222 7.8.6. getMinorString . . . . . . . . . . . . . . . . . . . . 82 223 7.8.7. setMinor . . . . . . . . . . . . . . . . . . . . . . . 82 224 7.8.8. toString . . . . . . . . . . . . . . . . . . . . . . . 83 225 7.8.9. getMessage . . . . . . . . . . . . . . . . . . . . . . 83 226 8. Sample Applications . . . . . . . . . . . . . . . . . 83 227 8.1. Simple GSS Context Initiator . . . . . . . . . . . . . 83 228 8.2. Simple GSS Context Acceptor . . . . . . . . . . . . . 87 229 9. Security Considerations . . . . . . . . . . . . . . . 91 230 10. IANA Considerations . . . . . . . . . . . . . . . . . 91 231 11. Acknowledgments . . . . . . . . . . . . . . . . . . . 92 232 Appendix A. Changes since RFC 2853 . . . . . . . . . . . . . . . . 92 233 12. References . . . . . . . . . . . . . . . . . . . . . . 93 234 12.1. Normative References . . . . . . . . . . . . . . . . . 93 235 12.2. Informative References . . . . . . . . . . . . . . . . 93 236 Authors' Addresses . . . . . . . . . . . . . . . . . . 93 237 Intellectual Property and Copyright Statements . . . . 95 239 1. Conventions Used in This Document 241 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 242 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 243 document are to be interpreted as described in [RFC2119]. 245 2. Introduction 247 This document specifies Java language bindings for the Generic 248 Security Services Application Programming Interface Version 2 (GSS- 249 API). GSS-API Version 2 is described in a language independent 250 format in RFC 2743 [GSSAPIv2-UPDATE]. The GSS-API allows a caller 251 application to authenticate a principal identity, to delegate rights 252 to a peer, and to apply security services such as confidentiality and 253 integrity on a per-message basis. 255 This document and its predecessor RFC 2853 [RFC2853] leverage the 256 work done by the WG in the area of RFC 2743 [GSSAPIv2-UPDATE] and the 257 C-bindings RFC 2744 [GSSAPI-Cbind]. Whenever appropriate, text has 258 been used from the C-bindings RFC 2744 to explain generic concepts 259 and provide direction to the implementors. 261 The design goals of this API have been to satisfy all the 262 functionality defined in RFC 2743 [GSSAPIv2-UPDATE] and to provide 263 these services in an object oriented method. The specification also 264 aims to satisfy the needs of both types of Java application 265 developers, those who would like access to a "system-wide" GSS-API 266 implementation, as well as those who would want to provide their own 267 "custom" implementation. 269 A "system-wide" implementation is one that is available to all 270 applications in the form of a library package. It may be the 271 standard package in the Java runtime environment (JRE) being used or 272 it may be additionally installed and accessible to any application 273 via the CLASSPATH. 275 A "custom" implementation of the GSS-API, on the other hand, is one 276 that would, in most cases, be bundled with the application during 277 distribution. It is expected that such an implementation would be 278 meant to provide for some particular need of the application, such as 279 support for some specific mechanism. 281 The design of this API also aims to provide a flexible framework to 282 add and manage GSS-API mechanisms. GSS-API leverages the Java 283 Cryptography Architecture (JCA) provider model to support the 284 plugability of mechanisms. Mechanisms can be added on a "system- 285 wide" basis, where all users of the framework will have them 286 available. The specification also allows for the addition of 287 mechanisms per-instance of the GSS-API. 289 Lastly, this specification presents an API that will naturally fit 290 within the operation environment of the Java platform. Readers are 291 assumed to be familiar with both the GSS-API and the Java platform. 293 3. GSS-API Operational Paradigm 295 The Generic Security Service Application Programming Interface 296 Version 2 [GSSAPIv2-UPDATE] defines a generic security API to calling 297 applications. It allows a communicating application to authenticate 298 the user associated with another application, to delegate rights to 299 another application, and to apply security services such as 300 confidentiality and integrity on a per-message basis. 302 There are four stages to using GSS-API: 304 1) The application acquires a set of credentials with which it may 305 prove its identity to other processes. The application's credentials 306 vouch for its global identity, which may or may not be related to any 307 local username under which it may be running. 309 2) A pair of communicating applications establish a joint security 310 context using their credentials. The security context encapsulates 311 shared state information, which is required in order that per-message 312 security services may be provided. Examples of state information 313 that might be shared between applications as part of a security 314 context are cryptographic keys, and message sequence numbers. As 315 part of the establishment of a security context, the context 316 initiator is authenticated to the responder, and may require that the 317 responder is authenticated back to the initiator. The initiator may 318 optionally give the responder the right to initiate further security 319 contexts, acting as an agent or delegate of the initiator. This 320 transfer of rights is termed "delegation", and is achieved by 321 creating a set of credentials, similar to those used by the 322 initiating application, but which may be used by the responder. 324 A GSSContext object is used to establish and maintain the shared 325 information that makes up the security context. Certain GSSContext 326 methods will generate a token, which applications treat as 327 cryptographically protected, opaque data. The caller of such 328 GSSContext method is responsible for transferring the token to the 329 peer application, encapsulated if necessary in an application-to- 330 application protocol. On receipt of such a token, the peer 331 application should pass it to a corresponding GSSContext method which 332 will decode the token and extract the information, updating the 333 security context state information accordingly. 335 3) Per-message services are invoked on a GSSContext object to apply 336 either: 338 integrity and data origin authentication, or 340 confidentiality, integrity and data origin authentication 342 to application data, which are treated by GSS-API as arbitrary octet- 343 strings. An application transmitting a message that it wishes to 344 protect will call the appropriate GSSContext method (getMIC or wrap) 345 to apply protection, and send the resulting token to the receiving 346 application. The receiver will pass the received token (and, in the 347 case of data protected by getMIC, the accompanying message-data) to 348 the corresponding decoding method of the GSSContext interface 349 (verifyMIC or unwrap) to remove the protection and validate the data. 351 4) At the completion of a communications session (which may extend 352 across several transport connections), each application uses a 353 GSSContext method to invalidate the security context and release any 354 system or cryptographic resources held. Multiple contexts may also 355 be used (either successively or simultaneously) within a single 356 communications association, at the discretion of the applications. 358 4. Additional Controls 360 This section discusses the optional services that a context initiator 361 may request of the GSS-API before the context establishment. Each of 362 these services is requested by calling the appropriate mutator method 363 in the GSSContext object before the first call to init is performed. 364 Only the context initiator can request context flags. 366 The optional services defined are: 368 Delegation The (usually temporary) transfer of rights from 369 initiator to acceptor, enabling the acceptor to authenticate 370 itself as an agent of the initiator. 372 Mutual Authentication In addition to the initiator authenticating 373 its identity to the context acceptor, the context acceptor should 374 also authenticate itself to the initiator. 376 Replay Detection In addition to providing message integrity 377 services, GSSContext per-message operations of getMIC and wrap 378 should include message numbering information to enable verifyMIC 379 and unwrap to detect if a message has been duplicated. 381 Out-of-Sequence Detection In addition to providing message 382 integrity services, GSSContext per-message operations (getMIC and 383 wrap) should include message sequencing information to enable 384 verifyMIC and unwrap to detect if a message has been received out 385 of sequence. 387 Anonymous Authentication The establishment of the security context 388 should not reveal the initiator's identity to the context 389 acceptor. 391 Some mechanisms may not support all optional services, and some 392 mechanisms may only support some services in conjunction with others. 393 The GSSContext interface offers query methods to allow the 394 verification by the calling application of which services will be 395 available from the context when the establishment phase is complete. 396 In general, if the security mechanism is capable of providing a 397 requested service, it should do so even if additional services must 398 be enabled in order to provide the requested service. If the 399 mechanism is incapable of providing a requested service, it should 400 proceed without the service leaving the application to abort the 401 context establishment process if it considers the requested service 402 to be mandatory. 404 Some mechanisms may specify that support for some services is 405 optional, and that implementors of the mechanism need not provide it. 406 This is most commonly true of the confidentiality service, often 407 because of legal restrictions on the use of data-encryption, but may 408 apply to any of the services. Such mechanisms are required to send 409 at least one token from acceptor to initiator during context 410 establishment when the initiator indicates a desire to use such a 411 service, so that the initiating GSS-API can correctly indicate 412 whether the service is supported by the acceptor's GSS-API. 414 4.1. Delegation 416 The GSS-API allows delegation to be controlled by the initiating 417 application via the requestCredDeleg method before the first call to 418 init has been issued. Some mechanisms do not support delegation, and 419 for such mechanisms attempts by an application to enable delegation 420 are ignored. 422 The acceptor of a security context, for which the initiator enabled 423 delegation, can check if delegation was enabled by using the 424 getCredDelegState method of the GSSContext interface. In cases when 425 it is, the delegated credential object can be obtained by calling the 426 getDelegCred method. The obtained GSSCredential object may then be 427 used to initiate subsequent GSS-API security contexts as an agent or 428 delegate of the initiator. If the original initiator's identity is 429 "A" and the delegate's identity is "B", then, depending on the 430 underlying mechanism, the identity embodied by the delegated 431 credential may be either "A" or "B acting for A". 433 For many mechanisms that support delegation, a simple boolean does 434 not provide enough control. Examples of additional aspects of 435 delegation control that a mechanism might provide to an application 436 are duration of delegation, network addresses from which delegation 437 is valid, and constraints on the tasks that may be performed by a 438 delegate. Such controls are presently outside the scope of the GSS- 439 API. GSS-API implementations supporting mechanisms offering 440 additional controls should provide extension routines that allow 441 these controls to be exercised (perhaps by modifying the initiator's 442 GSS-API credential object prior to its use in establishing a 443 context). However, the simple delegation control provided by GSS-API 444 should always be able to over-ride other mechanism-specific 445 delegation controls. If the application instructs the GSSContext 446 object that delegation is not desired, then the implementation must 447 not permit delegation to occur. This is an exception to the general 448 rule that a mechanism may enable services even if they are not 449 requested - delegation may only be provided at the explicit request 450 of the application. 452 4.2. Mutual Authentication 454 Usually, a context acceptor will require that a context initiator 455 authenticate itself so that the acceptor may make an access-control 456 decision prior to performing a service for the initiator. In some 457 cases, the initiator may also request that the acceptor authenticate 458 itself. GSS-API allows the initiating application to request this 459 mutual authentication service by calling the requestMutualAuth method 460 of the GSSContext interface with a "true" parameter before making the 461 first call to init. The initiating application is informed as to 462 whether or not the context acceptor has authenticated itself. Note 463 that some mechanisms may not support mutual authentication, and other 464 mechanisms may always perform mutual authentication, whether or not 465 the initiating application requests it. In particular, mutual 466 authentication may be required by some mechanisms in order to support 467 replay or out-of-sequence message detection, and for such mechanisms 468 a request for either of these services will automatically enable 469 mutual authentication. 471 4.3. Replay and Out-of-Sequence Detection 473 The GSS-API may provide detection of mis-ordered messages once a 474 security context has been established. Protection may be applied to 475 messages by either application, by calling either getMIC or wrap 476 methods of the GSSContext interface, and verified by the peer 477 application by calling verifyMIC or unwrap for the peer's GSSContext 478 object. 480 The getMIC method calculates a cryptographic checksum of an 481 application message, and returns that checksum in a token. The 482 application should pass both the token and the message to the peer 483 application, which presents them to the verifyMIC method of the 484 peer's GSSContext object. 486 The wrap method calculates a cryptographic checksum of an application 487 message, and places both the checksum and the message inside a single 488 token. The application should pass the token to the peer 489 application, which presents it to the unwrap method of the peer's 490 GSSContext object to extract the message and verify the checksum. 492 Either pair of routines may be capable of detecting out-of-sequence 493 message delivery, or duplication of messages. Details of such mis- 494 ordered messages are indicated through supplementary query methods of 495 the MessageProp object that is filled in by each of these routines. 497 A mechanism need not maintain a list of all tokens that have been 498 processed in order to support these status codes. A typical 499 mechanism might retain information about only the most recent "N" 500 tokens processed, allowing it to distinguish duplicates and missing 501 tokens within the most recent "N" messages; the receipt of a token 502 older than the most recent "N" would result in the isOldToken method 503 of the instance of MessageProp to return "true". 505 4.4. Anonymous Authentication 507 In certain situations, an application may wish to initiate the 508 authentication process to authenticate a peer, without revealing its 509 own identity. As an example, consider an application providing 510 access to a database containing medical information, and offering 511 unrestricted access to the service. A client of such a service might 512 wish to authenticate the service (in order to establish trust in any 513 information retrieved from it), but might not wish the service to be 514 able to obtain the client's identity (perhaps due to privacy concerns 515 about the specific inquiries, or perhaps simply to avoid being placed 516 on mailing-lists). 518 In normal use of the GSS-API, the initiator's identity is made 519 available to the acceptor as a result of the context establishment 520 process. However, context initiators may request that their identity 521 not be revealed to the context acceptor. Many mechanisms do not 522 support anonymous authentication, and for such mechanisms the request 523 will not be honored. An authentication token will still be 524 generated, but the application is always informed if a requested 525 service is unavailable, and has the option to abort context 526 establishment if anonymity is valued above the other security 527 services that would require a context to be established. 529 In addition to informing the application that a context is 530 established anonymously (via the isAnonymous method of the GSSContext 531 class), the getSrcName method of the acceptor's GSSContext object 532 will, for such contexts, return a reserved internal-form name, 533 defined by the implementation. 535 The toString method for a GSSName object representing an anonymous 536 entity will return a printable name. The returned value will be 537 syntactically distinguishable from any valid principal name supported 538 by the implementation. The associated name-type object identifier 539 will be an oid representing the value of NT_ANONYMOUS. This name- 540 type oid will be defined as a public, static Oid object of the 541 GSSName class. The printable form of an anonymous name should be 542 chosen such that it implies anonymity, since this name may appear in, 543 for example, audit logs. For example, the string "" might 544 be a good choice, if no valid printable names supported by the 545 implementation can begin with "<" and end with ">". 547 When using the equal method of the GSSName interface, and one of the 548 operands is a GSSName instance representing an anonymous entity, the 549 method must return "false". 551 4.5. Confidentiality 553 If a GSSContext supports the confidentiality service, wrap method may 554 be used to encrypt application messages. Messages are selectively 555 encrypted, under the control of the setPrivacy method of the 556 MessageProp object used in the wrap method. 558 4.6. Inter-process Context Transfer 560 GSS-API V2 provides functionality which allows a security context to 561 be transferred between processes on a single machine. These are 562 implemented using the export method of GSSContext and a byte array 563 constructor of the same class. The most common use for such a 564 feature is a client-server design where the server is implemented as 565 a single process that accepts incoming security contexts, which then 566 launches child processes to deal with the data on these contexts. In 567 such a design, the child processes must have access to the security 568 context object created within the parent so that they can use per- 569 message protection services and delete the security context when the 570 communication session ends. 572 Since the security context data structure is expected to contain 573 sequencing information, it is impractical in general to share a 574 context between processes. Thus GSSContext interface provides an 575 export method that the process, which currently owns the context, can 576 call to declare that it has no intention to use the context 577 subsequently, and to create an inter-process token containing 578 information needed by the adopting process to successfully re-create 579 the context. After successful completion of export, the original 580 security context is made inaccessible to the calling process by GSS- 581 API and any further usage of this object will result in failures. 582 The originating process transfers the inter-process token to the 583 adopting process, which creates a new GSSContext object using the 584 byte array constructor. The properties of the context are equivalent 585 to that of the original context. 587 The inter-process token may contain sensitive data from the original 588 security context (including cryptographic keys). Applications using 589 inter-process tokens to transfer security contexts must take 590 appropriate steps to protect these tokens in transit. 592 Implementations are not required to support the inter-process 593 transfer of security contexts. Calling the isTransferable method of 594 the GSSContext interface will indicate if the context object is 595 transferable. 597 4.7. The Use of Incomplete Contexts 599 Some mechanisms may allow the per-message services to be used before 600 the context establishment process is complete. For example, a 601 mechanism may include sufficient information in its initial context- 602 level tokens for the context acceptor to immediately decode messages 603 protected with wrap or getMIC. For such a mechanism, the initiating 604 application need not wait until subsequent context-level tokens have 605 been sent and received before invoking the per-message protection 606 services. 608 An application can invoke the isProtReady method of the GSSContext 609 class to determine if the per-message services are available in 610 advance of complete context establishment. Applications wishing to 611 use per-message protection services on partially-established contexts 612 should query this method before attempting to invoke wrap or getMIC. 614 5. Calling Conventions 616 Java provides the implementors with not just a syntax for the 617 language, but also an operational environment. For example, memory 618 is automatically managed and does not require application 619 intervention. These language features have allowed for a simpler API 620 and have led to the elimination of certain GSS-API functions. 622 Moreover, the JCA defines a provider model which allows for 623 implementation independent access to security services. Using this 624 model, applications can seamlessly switch between different 625 implementations and dynamically add new services. The GSS-API 626 specification leverages these concepts by the usage of providers for 627 the mechanism implementations. 629 5.1. Package Name 631 The classes and interfaces defined in this document reside in the 632 package called "org.ietf.jgss". Applications that wish to make use 633 of this API should import this package name as shown in section 8. 635 5.2. Provider Framework 637 The Java security API's use a provider architecture that allows 638 applications to be implementation independent and security API 639 implementations to be modular and extensible. The 640 java.security.Provider class is an abstract class that a vendor 641 extends. This class maps various properties that represent different 642 security services that are available to the names of the actual 643 vendor classes that implement those services. When requesting a 644 service, an application simply specifies the desired provider and the 645 API delegates the request to service classes available from that 646 provider. 648 Using the Java security provider model insulates applications from 649 implementation details of the services they wish to use. 650 Applications can switch between providers easily and new providers 651 can be added as needed, even at runtime. 653 The GSS-API may use providers to find components for specific 654 underlying security mechanisms. For instance, a particular provider 655 might contain components that will allow the GSS-API to support the 656 Kerberos v5 mechanism [RFC4121] and another might contain components 657 to support the SPKM [RFC2025] mechanism. By delegating mechanism 658 specific functionality to the components obtained from providers, the 659 GSS-API can be extended to support an arbitrary list of mechanism. 661 How the GSS-API locates and queries these providers is beyond the 662 scope of this document and is being deferred to a Service Provider 663 Interface (SPI) specification. The availability of such a SPI 664 specification is not mandatory for the adoption of this API 665 specification nor is it mandatory to use providers in the 666 implementation of a GSS-API framework. However, by using the 667 provider framework together with an SPI specification one can create 668 an extensible and implementation independent GSS-API framework. 670 5.3. Integer Types 672 All numeric values are declared as "int" primitive Java type. The 673 Java specification guarantees that this will be a 32 bit two's 674 complement signed number. 676 Throughout this API, the "boolean" primitive Java type is used 677 wherever a boolean value is required or returned. 679 5.4. Opaque Data Types 681 Java byte arrays are used to represent opaque data types which are 682 consumed and produced by the GSS-API in the forms of tokens. Java 683 arrays contain a length field which enables the users to easily 684 determine their size. The language has automatic garbage collection 685 which alleviates the need by developers to release memory and 686 simplifies buffer ownership issues. 688 5.5. Strings 690 The String object will be used to represent all textual data. The 691 Java String object, transparently treats all characters as two-byte 692 Unicode characters which allows support for many locals. All 693 routines returning or accepting textual data will use the String 694 object. 696 5.6. Object Identifiers 698 An Oid object will be used to represent Universal Object Identifiers 699 (Oids). Oids are ISO-defined, hierarchically globally-interpretable 700 identifiers used within the GSS-API framework to identify security 701 mechanisms and name formats. The Oid object can be created from a 702 string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as 703 well as from its ASN.1 DER encoding. Methods are also provided to 704 test equality and provide the DER representation for the object. 706 An important feature of the Oid class is that its instances are 707 immutable - i.e. there are no methods defined that allow one to 708 change the contents of an Oid. This property allows one to treat 709 these objects as "statics" without the need to perform copies. 711 Certain routines allow the usage of a default oid. A "null" value 712 can be used in those cases. 714 5.7. Object Identifier Sets 715 The Java bindings represents object identifiers sets as arrays of Oid 716 objects. All Java arrays contain a length field which allows for 717 easy manipulation and reference. 719 In order to support the full functionality of RFC 2743 720 [GSSAPIv2-UPDATE], the Oid class includes a method which checks for 721 existence of an Oid object within a specified array. This is 722 equivalent in functionality to gss_test_oid_set_member. The use of 723 Java arrays and Java's automatic garbage collection has eliminated 724 the need for the following routines: gss_create_empty_oid_set, 725 gss_release_oid_set, and gss_add_oid_set_member. Java GSS-API 726 implementations will not contain them. Java's automatic garbage 727 collection and the immutable property of the Oid object eliminates 728 the memory management issues of the C counterpart. 730 When ever a default value for an Object Identifier Set is required, a 731 "null" value can be used. Please consult the detailed method 732 description for details. 734 5.8. Credentials 736 GSS-API credentials are represented by the GSSCredential interface. 737 The interface contains several constructs to allow for the creation 738 of most common credential objects for the initiator and the acceptor. 739 Comparisons are performed using the interface's "equals" method. The 740 following general description of GSS-API credentials is included from 741 the C-bindings specification: 743 GSS-API credentials can contain mechanism-specific principal 744 authentication data for multiple mechanisms. A GSS-API credential is 745 composed of a set of credential-elements, each of which is applicable 746 to a single mechanism. A credential may contain at most one 747 credential-element for each supported mechanism. A credential- 748 element identifies the data needed by a single mechanism to 749 authenticate a single principal, and conceptually contains two 750 credential-references that describe the actual mechanism-specific 751 authentication data, one to be used by GSS-API for initiating 752 contexts, and one to be used for accepting contexts. For mechanisms 753 that do not distinguish between acceptor and initiator credentials, 754 both references would point to the same underlying mechanism-specific 755 authentication data. 757 Credentials describe a set of mechanism-specific principals, and give 758 their holder the ability to act as any of those principals. All 759 principal identities asserted by a single GSS-API credential should 760 belong to the same entity, although enforcement of this property is 761 an implementation-specific matter. A single GSSCredential object 762 represents all the credential elements that have been acquired. 764 The creation's of an GSSContext object allows the value of "null" to 765 be specified as the GSSCredential input parameter. This will 766 indicate a desire by the application to act as a default principal. 767 While individual GSS-API implementations are free to determine such 768 default behavior as appropriate to the mechanism, the following 769 default behavior by these routines is recommended for portability: 771 For the initiator side of the context: 773 1) If there is only a single principal capable of initiating security 774 contexts for the chosen mechanism that the application is authorized 775 to act on behalf of, then that principal shall be used, otherwise 777 2) If the platform maintains a concept of a default network- identity 778 for the chosen mechanism, and if the application is authorized to act 779 on behalf of that identity for the purpose of initiating security 780 contexts, then the principal corresponding to that identity shall be 781 used, otherwise 783 3) If the platform maintains a concept of a default local identity, 784 and provides a means to map local identities into network-identities 785 for the chosen mechanism, and if the application is authorized to act 786 on behalf of the network- identity image of the default local 787 identity for the purpose of initiating security contexts using the 788 chosen mechanism, then the principal corresponding to that identity 789 shall be used, otherwise 791 4) A user-configurable default identity should be used. 793 and for the acceptor side of the context 795 1) If there is only a single authorized principal identity capable of 796 accepting security contexts for the chosen mechanism, then that 797 principal shall be used, otherwise 799 2) If the mechanism can determine the identity of the target 800 principal by examining the context-establishment token processed 801 during the accept method, and if the accepting application is 802 authorized to act as that principal for the purpose of accepting 803 security contexts using the chosen mechanism, then that principal 804 identity shall be used, otherwise 806 3) If the mechanism supports context acceptance by any principal, and 807 if mutual authentication was not requested, any principal that the 808 application is authorized to accept security contexts under using the 809 chosen mechanism may be used, otherwise 811 4) A user-configurable default identity shall be used. 813 The purpose of the above rules is to allow security contexts to be 814 established by both initiator and acceptor using the default behavior 815 whenever possible. Applications requesting default behavior are 816 likely to be more portable across mechanisms and implementations than 817 ones that instantiate an GSSCredential object representing a specific 818 identity. 820 5.9. Contexts 822 The GSSContext interface is used to represent one end of a GSS-API 823 security context, storing state information appropriate to that end 824 of the peer communication, including cryptographic state information. 825 The instantiation of the context object is done differently by the 826 initiator and the acceptor. After the context has been instantiated, 827 the initiator may choose to set various context options which will 828 determine the characteristics of the desired security context. When 829 all the application desired characteristics have been set, the 830 initiator will call the initSecContext method which will produce a 831 token for consumption by the peer's acceptSecContext method. It is 832 the responsibility of the application to deliver the authentication 833 token(s) between the peer applications for processing. Upon 834 completion of the context establishment phase, context attributes can 835 be retrieved, by both the initiator and acceptor, using the accessor 836 methods. These will reflect the actual attributes of the established 837 context. At this point the context can be used by the application to 838 apply cryptographic services to its data. 840 5.10. Authentication Tokens 842 A token is a caller-opaque type that GSS-API uses to maintain 843 synchronization between each end of the GSS-API security context. 844 The token is a cryptographically protected octet-string, generated by 845 the underlying mechanism at one end of a GSS-API security context for 846 use by the peer mechanism at the other end. Encapsulation (if 847 required) within the application protocol and transfer of the token 848 are the responsibility of the peer applications. 850 Java GSS-API uses byte arrays to represent authentication tokens. 851 Overloaded methods exist which allow the caller to supply input and 852 output streams which will be used for the reading and writing of the 853 token data. 855 5.11. Interprocess Tokens 857 Certain GSS-API routines are intended to transfer data between 858 processes in multi-process programs. These routines use a caller- 859 opaque octet-string, generated by the GSS-API in one process for use 860 by the GSS-API in another process. The calling application is 861 responsible for transferring such tokens between processes. Note 862 that, while GSS-API implementors are encouraged to avoid placing 863 sensitive information within interprocess tokens, or to 864 cryptographically protect them, many implementations will be unable 865 to avoid placing key material or other sensitive data within them. 866 It is the application's responsibility to ensure that interprocess 867 tokens are protected in transit, and transferred only to processes 868 that are trustworthy. An interprocess token is represented using a 869 byte array emitted from the export method of the GSSContext 870 interface. The receiver of the interprocess token would initialize 871 an GSSContext object with this token to create a new context. Once a 872 context has been exported, the GSSContext object is invalidated and 873 is no longer available. 875 5.12. Error Reporting 877 RFC 2743 [GSSAPIv2-UPDATE] defined the usage of major and minor 878 status values for signaling of GSS-API errors. The major code, also 879 called GSS status code, is used to signal errors at the GSS-API level 880 independent of the underlying mechanism(s). The minor status value 881 or Mechanism status code, is a mechanism defined error value 882 indicating a mechanism specific error code. 884 Java GSS-API uses exceptions implemented by the GSSException class to 885 signal both minor and major error values. Both mechanism specific 886 errors and GSS-API level errors are signaled through instances of 887 this class. The usage of exceptions replaces the need for major and 888 minor codes to be used within the API calls. GSSException class also 889 contains methods to obtain textual representations for both the major 890 and minor values, which is equivalent to the functionality of 891 gss_display_status. 893 5.12.1. GSS Status Codes 895 GSS status codes indicate errors that are independent of the 896 underlying mechanism(s) used to provide the security service. The 897 errors that can be indicated via a GSS status code are generic API 898 routine errors (errors that are defined in the GSS-API 899 specification). These bindings take advantage of the Java exceptions 900 mechanism, thus eliminating the need for calling errors. 902 A GSS status code indicates a single fatal generic API error from the 903 routine that has thrown the GSSException. Using exceptions announces 904 that a fatal error has occurred during the execution of the method. 905 The GSS-API operational model also allows for the signaling of 906 supplementary status information from the per-message calls. These 907 need to be handled as return values since using exceptions is not 908 appropriate for informatory or warning-like information. The methods 909 that are capable of producing supplementary information are the two 910 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 911 These methods fill the supplementary status codes in the MessageProp 912 object that was passed in. 914 A GSSException object, along with providing the functionality for 915 setting of the various error codes and translating them into textual 916 representation, also contains the definitions of all the numeric 917 error values. The following table lists the definitions of error 918 codes: 920 Table: GSS Status Codes 922 Name Value Meaning 924 BAD_BINDINGS 1 Incorrect channel bindings were 925 supplied. 927 BAD_MECH 2 An unsupported mechanism 928 was requested. 930 BAD_NAME 3 An invalid name was supplied. 932 BAD_NAMETYPE 4 A supplied name was of an 933 unsupported type. 935 BAD_STATUS 5 An invalid status code was 936 supplied. 938 BAD_MIC 6 A token had an invalid MIC. 940 CONTEXT_EXPIRED 7 The context has expired. 942 CREDENTIALS_EXPIRED 8 The referenced credentials 943 have expired. 945 DEFECTIVE_CREDENTIAL 9 A supplied credential was 946 invalid. 948 DEFECTIVE_TOKEN 10 A supplied token was invalid. 950 FAILURE 11 Miscellaneous failure, 951 unspecified at the GSS-API 952 level. 954 NO_CONTEXT 12 Invalid context has been 955 supplied. 957 NO_CRED 13 No credentials were supplied, or 958 the credentials were unavailable 959 or inaccessible. 961 BAD_QOP 14 The quality-of-protection 962 requested could not be provided. 964 UNAUTHORIZED 15 The operation is forbidden by 965 the local security policy. 967 UNAVAILABLE 16 The operation or option is 968 unavailable. 970 DUPLICATE_ELEMENT 17 The requested credential 971 element already exists. 973 NAME_NOT_MN 18 The provided name was not a 974 mechanism name. 976 The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN, 977 UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException 978 only if detected during context establishment, in which case it 979 is a fatal error. (During per-message calls, these values are 980 indicated as supplementary information contained in the 981 MessageProp object.) They are: 983 DUPLICATE_TOKEN 19 The token was a duplicate of an 984 earlier version. 986 OLD_TOKEN 20 The token's validity period has 987 expired. 989 UNSEQ_TOKEN 21 A later token has already been 990 processed. 992 GAP_TOKEN 22 The expected token was not 993 received. 995 The GSS major status code of FAILURE is used to indicate that the 996 underlying mechanism detected an error for which no specific GSS 997 status code is defined. The mechanism-specific status code can 998 provide more details about the error. 1000 The different major status codes that can be contained in the 1001 GSSException object thrown by the methods in this specification are 1002 the same as the major status codes returned by the corresponding 1003 calls in RFC 2743 [GSSAPIv2-UPDATE]. 1005 5.12.2. Mechanism-Specific Status Codes 1007 Mechanism-specific status codes are communicated in two ways, they 1008 are part of any GSSException thrown from the mechanism specific layer 1009 to signal a fatal error, or they are part of the MessageProp object 1010 that the per-message calls use to signal non-fatal errors. 1012 A default value of 0 in either the GSSException object or the 1013 MessageProp object will be used to represent the absence of any 1014 mechanism specific status code. 1016 5.12.3. Supplementary Status Codes 1018 Supplementary status codes are confined to the per-message methods of 1019 the GSSContext interface. Because of the informative nature of these 1020 errors it is not appropriate to use exceptions to signal them. 1021 Instead, the per-message operations of the GSSContext interface 1022 return these values in a MessageProp object. 1024 The MessageProp class defines query methods which return boolean 1025 values indicating the following supplementary states: 1027 Table: Supplementary Status Methods 1029 Method Name Meaning when "true" is returned 1031 isDuplicateToken The token was a duplicate of an 1032 earlier token. 1034 isOldToken The token's validity period has 1035 expired. 1037 isUnseqToken A later token has already been 1038 processed. 1040 isGapToken An expected per-message token was 1041 not received. 1043 "true" return value for any of the above methods indicates that the 1044 token exhibited the specified property. The application must 1045 determine the appropriate course of action for these supplementary 1046 values. They are not treated as errors by the GSS-API. 1048 5.13. Names 1050 A name is used to identify a person or entity. GSS-API authenticates 1051 the relationship between a name and the entity claiming the name. 1053 Since different authentication mechanisms may employ different 1054 namespaces for identifying their principals, GSS-API's naming support 1055 is necessarily complex in multi-mechanism environments (or even in 1056 some single-mechanism environments where the underlying mechanism 1057 supports multiple namespaces). 1059 Two distinct conceptual representations are defined for names: 1061 1) A GSS-API form represented by implementations of the GSSName 1062 interface: A single GSSName object may contain multiple names from 1063 different namespaces, but all names should refer to the same entity. 1064 An example of such an internal name would be the name returned from a 1065 call to the getName method of the GSSCredential interface, when 1066 applied to a credential containing credential elements for multiple 1067 authentication mechanisms employing different namespaces. This 1068 GSSName object will contain a distinct name for the entity for each 1069 authentication mechanism. 1071 For GSS-API implementations supporting multiple namespaces, GSSName 1072 implementations must contain sufficient information to determine the 1073 namespace to which each primitive name belongs. 1075 2) Mechanism-specific contiguous byte array and string forms: 1076 Different GSSName initialization methods are provided to handle both 1077 byte array and string formats and to accommodate various calling 1078 applications and name types. These formats are capable of containing 1079 only a single name (from a single namespace). Contiguous string 1080 names are always accompanied by an object identifier specifying the 1081 namespace to which the name belongs, and their format is dependent on 1082 the authentication mechanism that employs that name. The string name 1083 forms are assumed to be printable, and may therefore be used by GSS- 1084 API applications for communication with their users. The byte array 1085 name formats are assumed to be in non-printable formats (e.g. the 1086 byte array returned from the export method of the GSSName interface). 1088 A GSSName object can be converted to a contiguous representation by 1089 using the toString method. This will guarantee that the name will be 1090 converted to a printable format. Different initialization methods in 1091 the GSSName interface are defined allowing support for multiple 1092 syntaxes for each supported namespace, and allowing users the freedom 1093 to choose a preferred name representation. The toString method 1094 should use an implementation-chosen printable syntax for each 1095 supported name-type. To obtain the printable name type, 1096 getStringNameType method can be used. 1098 There is no guarantee that calling the toString method on the GSSName 1099 interface will produce the same string form as the original imported 1100 string name. Furthermore, it is possible that the name was not even 1101 constructed from a string representation. The same applies to name- 1102 space identifiers which may not necessarily survive unchanged after a 1103 journey through the internal name-form. An example of this might be 1104 a mechanism that authenticates X.500 names, but provides an 1105 algorithmic mapping of Internet DNS names into X.500. That 1106 mechanism's implementation of GSSName might, when presented with a 1107 DNS name, generate an internal name that contained both the original 1108 DNS name and the equivalent X.500 name. Alternatively, it might only 1109 store the X.500 name. In the latter case, the toString method of 1110 GSSName would most likely generate a printable X.500 name, rather 1111 than the original DNS name. 1113 The context acceptor can obtain a GSSName object representing the 1114 entity performing the context initiation (through the usage of 1115 getSrcName method). Since this name has been authenticated by a 1116 single mechanism, it contains only a single name (even if the 1117 internal name presented by the context initiator to the GSSContext 1118 object had multiple components). Such names are termed internal 1119 mechanism names, or "MN"s and the names emitted by GSSContext 1120 interface in the getSrcName and getTargName are always of this type. 1121 Since some applications may require MNs without wanting to incur the 1122 overhead of an authentication operation, creation methods are 1123 provided that take not only the name buffer and name type, but also 1124 the mechanism oid for which this name should be created. When 1125 dealing with an existing GSSName object, the canonicalize method may 1126 be invoked to convert a general internal name into an MN. 1128 GSSName objects can be compared using their equal method, which 1129 returns "true" if the two names being compared refer to the same 1130 entity. This is the preferred way to perform name comparisons 1131 instead of using the printable names that a given GSS-API 1132 implementation may support. Since GSS-API assumes that all primitive 1133 names contained within a given internal name refer to the same 1134 entity, equal can return "true" if the two names have at least one 1135 primitive name in common. If the implementation embodies knowledge 1136 of equivalence relationships between names taken from different 1137 namespaces, this knowledge may also allow successful comparisons of 1138 internal names containing no overlapping primitive elements. 1140 When used in large access control lists, the overhead of creating an 1141 GSSName object on each name and invoking the equal method on each 1142 name from the ACL may be prohibitive. As an alternative way of 1143 supporting this case, GSS-API defines a special form of the 1144 contiguous byte array name which may be compared directly (byte by 1145 byte). Contiguous names suitable for comparison are generated by the 1146 export method. Exported names may be re-imported by using the byte 1147 array constructor and specifying the NT_EXPORT_NAME as the name type 1148 object identifier. The resulting GSSName name will also be a MN. 1150 The GSSName interface defines public static Oid objects representing 1151 the standard name types. Structurally, an exported name object 1152 consists of a header containing an OID identifying the mechanism that 1153 authenticated the name, and a trailer containing the name itself, 1154 where the syntax of the trailer is defined by the individual 1155 mechanism specification. Detailed description of the format is 1156 specified in the language-independent GSS-API specification 1157 [GSSAPIv2-UPDATE]. 1159 Note that the results obtained by using the equals method will in 1160 general be different from those obtained by invoking canonicalize and 1161 export, and then comparing the byte array output. The first series 1162 of operation determines whether two (unauthenticated) names identify 1163 the same principal; the second whether a particular mechanism would 1164 authenticate them as the same principal. These two operations will 1165 in general give the same results only for MNs. 1167 It is important to note that the above are guidelines as how GSSName 1168 implementations should behave, and are not intended to be specific 1169 requirements of how names objects must be implemented. The mechanism 1170 designers are free to decide on the details of their implementations 1171 of the GSSName interface as long as the behavior satisfies the above 1172 guidelines. 1174 5.14. Channel Bindings 1176 GSS-API supports the use of user-specified tags to identify a given 1177 context to the peer application. These tags are intended to be used 1178 to identify the particular communications channel that carries the 1179 context. Channel bindings are communicated to the GSS-API using the 1180 ChannelBinding object. The application may use byte arrays to 1181 specify the application data to be used in the channel binding as 1182 well as using instances of the InetAddress. The InetAddress for the 1183 initiator and/or acceptor can be used within an instance of a 1184 ChannelBinding. ChannelBinding can be set for the GSSContext object 1185 using the setChannelBinding method before the first call to init or 1186 accept has been performed. Unless the setChannelBinding method has 1187 been used to set the ChannelBinding for a GSSContext object, "null" 1188 ChannelBinding will be assumed. InetAddress is currently the only 1189 address type defined within the Java platform and as such, it is the 1190 only one supported within the ChannelBinding class. Applications 1191 that use other types of addresses can include them as part of the 1192 application specific data. 1194 Conceptually, the GSS-API concatenates the initiator and acceptor 1195 address information, and the application supplied byte array to form 1196 an octet string. The mechanism calculates a MIC over this octet 1197 string and binds the MIC to the context establishment token emitted 1198 by init method of the GSSContext interface. The same bindings are 1199 set by the context acceptor for its GSSContext object and during 1200 processing of the accept method a MIC is calculated in the same way. 1201 The calculated MIC is compared with that found in the token, and if 1202 the MICs differ, accept will throw a GSSException with the major code 1203 set to BAD_BINDINGS, and the context will not be established. Some 1204 mechanisms may include the actual channel binding data in the token 1205 (rather than just a MIC); applications should therefore not use 1206 confidential data as channel-binding components. 1208 Individual mechanisms may impose additional constraints on addresses 1209 that may appear in channel bindings. For example, a mechanism may 1210 verify that the initiator address field of the channel binding 1211 contains the correct network address of the host system. Portable 1212 applications should therefore ensure that they either provide correct 1213 information for the address fields, or omit setting of the addressing 1214 information. 1216 5.15. Stream Objects 1218 The context object provides overloaded methods which use input and 1219 output streams as the means to convey authentication and per-message 1220 GSS-API tokens. It is important to note that the streams are 1221 expected to contain the usual GSS-API tokens which would otherwise be 1222 handled through the usage of byte arrays. The tokens are expected to 1223 have a definite start and an end. The callers are responsible for 1224 ensuring that the supplied streams will not block, or expect to block 1225 until a full token is processed by the GSS-API method. Only a single 1226 GSS-API token will be processed per invocation of the stream based 1227 method. 1229 The usage of streams allows the callers to have control and 1230 management of the supplied buffers. Because streams are non- 1231 primitive objects, the callers can make the streams as complicated or 1232 as simple as desired simply by using the streams defined in the 1233 java.io package or creating their own through the use of inheritance. 1234 This will allow for the application's greatest flexibility. 1236 5.16. Optional Parameters 1238 Whenever the application wishes to omit an optional parameter the 1239 "null" value shall be used. The detailed method descriptions 1240 indicate which parameters are optional. Methods overloading has also 1241 been used as a technique to indicate default parameters. 1243 6. Introduction to GSS-API Classes and Interfaces 1244 This section presents a brief description of the classes and 1245 interfaces that constitute the GSS-API. The implementations of these 1246 are obtained from the CLASSPATH defined by the application. If Java 1247 GSS becomes part of the standard Java API's then these classes will 1248 be available by default on all systems as part of the JRE's system 1249 classes. 1251 This section also shows the corresponding RFC 2743 [GSSAPIv2-UPDATE] 1252 functionality implemented by each of the classes. Detailed 1253 description of these classes and their methods is presented in 1254 section 7. 1256 6.1. GSSManager class 1258 This abstract class serves as a factory to instantiate 1259 implementations of the GSS-API interfaces and also provides methods 1260 to make queries about underlying security mechanisms. 1262 A default implementation can be obtained using the static method 1263 getInstance(). Applications that desire to provide their own 1264 implementation of the GSSManager class can simply extend the abstract 1265 class themselves. 1267 This class contains equivalents of the following RFC 2743 1268 [GSSAPIv2-UPDATE] routines: 1270 gss_import_name Create an internal name from 7.1.6- 1271 the supplied information. 7.1.9 1273 gss_acquire_cred Acquire credential 7.1.10- 1274 for use. 7.1.12 1276 gss_import_sec_context Create a previously exported 7.1.15 1277 context. 1279 gss_indicate_mechs List the mechanisms 7.1.3 1280 supported by this GSS-API 1281 implementation. 1283 gss_inquire_mechs_for_name List the mechanisms 7.1.5 1284 supporting the 1285 specified name type. 1287 gss_inquire_names_for_mech List the name types 7.1.4 1288 supported by the 1289 specified mechanism. 1291 6.2. GSSName interface 1293 GSS-API names are represented in the Java bindings through the 1294 GSSName interface. Different name formats and their definitions are 1295 identified with universal Object Identifiers (oids). The format of 1296 the names can be derived based on the unique oid of each name type. 1297 The following GSS-API routines are provided by the GSSName interface: 1299 RFC 2743 Routine Function Section(s) 1301 gss_display_name Covert internal name 7.2.7 1302 representation to text format. 1304 gss_compare_name Compare two internal names. 7.2.3, 1305 7.2.4 1307 gss_release_name Release resources associated N/A 1308 with the internal name. 1310 gss_canonicalize_name Convert an internal name to a 7.2.5 1311 mechanism name. 1313 gss_export_name Convert a mechanism name to 7.2.6 1314 export format. 1316 gss_duplicate_name Create a copy of the internal N/A 1317 name. 1319 The gss_release_name call is not provided as Java does its own 1320 garbage collection. The gss_duplicate_name call is also redundant; 1321 the GSSName interface has no mutator methods that can change the 1322 state of the object so it is safe for sharing across threads. 1324 6.3. GSSCredential interface 1326 The GSSCredential interface is responsible for the encapsulation of 1327 GSS-API credentials. Credentials identify a single entity and 1328 provide the necessary cryptographic information to enable the 1329 creation of a context on behalf of that entity. A single credential 1330 may contain multiple mechanism specific credentials, each referred to 1331 as a credential element. The GSSCredential interface provides the 1332 functionality of the following GSS-API routines: 1334 RFC 2743 Routine Function Section(s) 1336 gss_add_cred Constructs credentials 7.3.12 1337 incrementally. 1339 gss_inquire_cred Obtain information about 7.3.4- 1340 credential. 7.3.11 1342 gss_inquire_cred_by_mech Obtain per-mechanism 7.3.5- 1343 information about 7.3.10 1344 a credential. 1346 gss_release_cred Disposes of credentials 7.3.3 1347 after use. 1349 6.4. GSSContext interface 1351 This interface encapsulates the functionality of context-level calls 1352 required for security context establishment and management between 1353 peers as well as the per-message services offered to applications. A 1354 context is established between a pair of peers and allows the usage 1355 of security services on a per-message basis on application data. It 1356 is created over a single security mechanism. The GSSContext 1357 interface provides the functionality of the following GSS-API 1358 routines: 1360 RFC 2743 Routine Function Section(s) 1362 gss_init_sec_context Initiate the creation of a 7.4.3- 1363 security context with a peer. 7.4.6 1365 gss_accept_sec_context Accept a security context 7.4.7- 1366 initiated by a peer. 7.4.10 1368 gss_delete_sec_context Destroy a security context. 7.4.12 1370 gss_context_time Obtain remaining context 7.4.41 1371 time. 1373 gss_inquire_context Obtain context 7.4.32- 1374 characteristics. 7.3.46 1376 gss_wrap_size_limit Determine token-size limit 7.4.13 1377 for gss_wrap. 1379 gss_export_sec_context Transfer security context 7.4.22 1380 to another process. 1382 gss_get_mic Calculate a cryptographic 7.4.18, 1383 Message Integrity Code (MIC) 7.4.19 1384 for a message. 1386 gss_verify_mic Verify integrity on a received 7.4.20, 1387 message. 7.4.21 1389 gss_wrap Attach a MIC to a message and 7.4.14, 1390 optionally encrypt the message 7.4.15 1391 content. 1393 gss_unwrap Obtain a previously wrapped 7.4.16, 1394 application message verifying 7.4.17 1395 its integrity and optionally 1396 decrypting it. 1398 The functionality offered by the gss_process_context_token routine 1399 has not been included in the Java bindings specification. The 1400 corresponding functionality of gss_delete_sec_context has also been 1401 modified to not return any peer tokens. This has been proposed in 1402 accordance to the recommendations stated in RFC 2743 1403 [GSSAPIv2-UPDATE]. GSSContext does offer the functionality of 1404 destroying the locally-stored context information. 1406 6.5. MessageProp class 1408 This helper class is used in the per-message operations on the 1409 context. An instance of this class is created by the application and 1410 then passed into the per-message calls. In some cases, the 1411 application conveys information to the GSS-API implementation through 1412 this object and in other cases the GSS-API returns information to the 1413 application by setting it in this object. See the description of the 1414 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1415 GSSContext interfaces for details. 1417 6.6. GSSException class 1419 Exceptions are used in the Java bindings to signal fatal errors to 1420 the calling applications. This replaces the major and minor codes 1421 used in the C-bindings specification as a method of signaling 1422 failures. The GSSException class handles both minor and major codes, 1423 as well as their translation into textual representation. All GSS- 1424 API methods are declared as throwing this exception. 1426 RFC 2743 Routine Function Section 1428 gss_display_status Retrieve textual 7.8.5, 7.8.6, 1429 representation of error 7.8.8, 7.8.9 1430 codes. 1432 6.7. Oid class 1434 This utility class is used to represent Universal Object Identifiers 1435 and their associated operations. GSS-API uses object identifiers to 1436 distinguish between security mechanisms and name types. This class, 1437 aside from being used whenever an object identifier is needed, 1438 implements the following GSS-API functionality: 1440 RFC 2743 Routine Function Section 1442 gss_test_oid_set_member Determine if the specified oid 7.7.5 1443 is part of a set of oids. 1445 6.8. ChannelBinding class 1447 An instance of this class is used to specify channel binding 1448 information to the GSSContext object before the start of a security 1449 context establishment. The application may use a byte array to 1450 specify application data to be used in the channel binding as well as 1451 use instances of the InetAddress. InetAddress is currently the only 1452 address type defined within the Java platform and as such, it is the 1453 only one supported within the ChannelBinding class. Applications 1454 that use other types of addresses can include them as part of the 1455 application data. 1457 7. Detailed GSS-API Class Description 1459 This section lists a detailed description of all the public methods 1460 that each of the GSS-API classes and interfaces must provide. 1462 7.1. public abstract class GSSManager 1464 The GSSManager class is an abstract class that serves as a factory 1465 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1466 also provides methods for applications to determine what mechanisms 1467 are available from the GSS implementation and what nametypes these 1468 mechanisms support. An instance of the default GSSManager subclass 1469 may be obtained through the static method getInstance(), but 1470 applications are free to instantiate other subclasses of GSSManager. 1472 All but one method in this class are declared abstract. This means 1473 that subclasses have to provide the complete implementation for those 1474 methods. The only exception to this is the static method 1475 getInstance() which will have platform specific code to return an 1476 instance of the default subclass. 1478 Platform providers of GSS are required not to add any constructors to 1479 this class, private, public, or protected. This will ensure that all 1480 subclasses invoke only the default constructor provided to the base 1481 class by the compiler. 1483 A subclass extending the GSSManager abstract class may be implemented 1484 as a modular provider based layer that utilizes some well known 1485 service provider specification. The GSSManager API provides the 1486 application with methods to set provider preferences on such an 1487 implementation. These methods also allow the implementation to throw 1488 a well-defined exception in case provider based configuration is not 1489 supported. Applications that expect to be portable should be aware 1490 of this and recover cleanly by catching the exception. 1492 It is envisioned that there will be three most common ways in which 1493 providers will be used: 1495 1) The application does not care about what provider is used (the 1496 default case). 1498 2) The application wants a particular provider to be used 1499 preferentially, either for a particular mechanism or all the time, 1500 irrespective of mechanism. 1502 3) The application wants to use the locally configured providers as 1503 far as possible but if support is missing for one or more mechanisms 1504 then it wants to fall back on its own provider. 1506 The GSSManager class has two methods that enable these modes of 1507 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1508 have the effect of creating an ordered list of pairs 1509 where each pair indicates a preference of provider for a given oid. 1511 The use of these methods does not require any knowledge of whatever 1512 service provider specification the GSSManager subclass follows. It 1513 is hoped that these methods will serve the needs of most 1514 applications. Additional methods may be added to an extended 1515 GSSManager that could be part of a service provider specification 1516 that is standardized later. 1518 7.1.1. Example Code 1520 GSSManager mgr = GSSManager.getInstance(); 1522 // What mechs are available to us? 1523 Oid[] supportedMechs = mgr.getMechs(); 1525 // Set a preference for the provider to be used when support 1526 // is needed for the mechanisms: 1527 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1529 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1530 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1532 Provider p = (Provider) (new com.foo.security.Provider()); 1534 mgr.addProviderAtFront(p, krb); 1535 mgr.addProviderAtFront(p, spkm1); 1537 // What name types does this spkm implementation support? 1538 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1540 7.1.2. getInstance 1542 public static GSSManager getInstance() 1544 Returns the default GSSManager implementation. 1546 7.1.3. getMechs 1548 public abstract Oid[] getMechs() 1550 Returns an array of Oid objects indicating the mechanisms available 1551 to GSS-API callers. A "null" value is returned when no mechanism are 1552 available (an example of this would be when mechanism are dynamically 1553 configured, and currently no mechanisms are installed). 1555 7.1.4. getNamesForMech 1557 public abstract Oid[] getNamesForMech(Oid mech) 1558 throws GSSException 1560 Returns name type Oid's supported by the specified mechanism. 1562 Parameters: 1564 mech The Oid object for the mechanism to query. 1566 7.1.5. getMechsForName 1568 public abstract Oid[] getMechsForName(Oid nameType) 1570 Returns an array of Oid objects corresponding to the mechanisms that 1571 support the specific name type. "null" is returned when no mechanisms 1572 are found to support the specified name type. 1574 Parameters: 1576 nameType The Oid object for the name type. 1578 7.1.6. createName 1580 public abstract GSSName createName(String nameStr, Oid nameType) 1581 throws GSSException 1583 Factory method to convert a contiguous string name from the specified 1584 namespace to a GSSName object. In general, the GSSName object 1585 created will not be an MN; two examples that are exceptions to this 1586 are when the namespace type parameter indicates NT_EXPORT_NAME or 1587 when the GSS-API implementation is not multi-mechanism. 1589 Parameters: 1591 nameStr The string representing a printable form of the name to 1592 create. 1594 nameType The Oid specifying the namespace of the printable name 1595 supplied. Note that nameType serves to describe and qualify the 1596 interpretation of the input nameStr, it does not necessarily imply 1597 a type for the output GSSName implementation. "null" value can be 1598 used to specify that a mechanism specific default printable syntax 1599 should be assumed by each mechanism that examines nameStr. 1601 7.1.7. createName 1603 public abstract GSSName createName(byte[] name, Oid nameType) 1604 throws GSSException 1606 Factory method to convert a contiguous byte array containing a name 1607 from the specified namespace to a GSSName object. In general, the 1608 GSSName object created will not be an MN; two examples that are 1609 exceptions to this are when the namespace type parameter indicates 1610 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1611 mechanism. 1613 Parameters: 1615 name The byte array containing the name to create. 1617 nameType The Oid specifying the namespace of the name supplied in 1618 the byte array. Note that nameType serves to describe and qualify 1619 the interpretation of the input name byte array, it does not 1620 necessarily imply a type for the output GSSName implementation. 1621 "null" value can be used to specify that a mechanism specific 1622 default syntax should be assumed by each mechanism that examines 1623 the byte array. 1625 7.1.8. createName 1627 public abstract GSSName createName(String nameStr, Oid nameType, 1628 Oid mech) throws GSSException 1630 Factory method to convert a contiguous string name from the specified 1631 namespace to an GSSName object that is a mechanism name (MN). In 1632 other words, this method is a utility that does the equivalent of two 1633 steps: the createName described in 7.1.6 and then also the 1634 GSSName.canonicalize() described in 7.2.5. 1636 Parameters: 1638 nameStr The string representing a printable form of the name to 1639 create. 1641 nameType The Oid specifying the namespace of the printable name 1642 supplied. Note that nameType serves to describe and qualify the 1643 interpretation of the input nameStr, it does not necessarily imply 1644 a type for the output GSSName implementation. "null" value can be 1645 used to specify that a mechanism specific default printable syntax 1646 should be assumed when the mechanism examines nameStr. 1648 mech Oid specifying the mechanism for which this name should be 1649 created. 1651 7.1.9. createName 1653 public abstract GSSName createName(byte[] name, Oid nameType, 1654 Oid mech) throws GSSException 1656 Factory method to convert a contiguous byte array containing a name 1657 from the specified namespace to a GSSName object that is an MN. In 1658 other words, this method is a utility that does the equivalent of two 1659 steps: the createName described in 7.1.7 and then also the 1660 GSSName.canonicalize() described in 7.2.5. 1662 Parameters: 1664 name The byte array representing the name to create. 1666 nameType The Oid specifying the namespace of the name supplied in 1667 the byte array. Note that nameType serves to describe and qualify 1668 the interpretation of the input name byte array, it does not 1669 necessarily imply a type for the output GSSName implementation. 1670 "null" value can be used to specify that a mechanism specific 1671 default syntax should be assumed by each mechanism that examines 1672 the byte array. 1674 mech Oid specifying the mechanism for which this name should be 1675 created. 1677 7.1.10. createCredential 1679 public abstract GSSCredential createCredential(int usage) 1680 throws GSSException 1682 Factory method for acquiring default credentials. This will cause 1683 the GSS-API to use system specific defaults for the set of 1684 mechanisms, name, and a DEFAULT lifetime. 1686 Parameters: 1688 usage The intended usage for this credential object.The value of 1689 this parameter must be one of: 1690 GSSCredential.INITIATE_AND_ACCEPT(0), 1691 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1693 7.1.11. createCredential 1695 public abstract GSSCredential createCredential(GSSName aName, 1696 int lifetime, Oid mech, int usage) 1697 throws GSSException 1699 Factory method for acquiring a single mechanism credential. 1701 Parameters: 1703 aName Name of the principal for whom this credential is to be 1704 acquired. Use "null" to specify the default principal. 1706 lifetime The number of seconds that credentials should remain 1707 valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the 1708 credentials have the maximum permitted lifetime. Use 1709 GSSCredential.DEFAULT_LIFETIME to request default credential 1710 lifetime. 1712 mech The oid of the desired mechanism. Use "(Oid) null" to 1713 request the default mechanism(s). 1715 usage The intended usage for this credential object. The value of 1716 this parameter must be one of: 1717 GSSCredential.INITIATE_AND_ACCEPT(0), 1718 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1720 7.1.12. createCredential 1722 public abstract GSSCredential createCredential(GSSName aName, 1723 int lifetime, Oid[] mechs, int usage) 1724 throws GSSException 1726 Factory method for acquiring credentials over a set of mechanisms. 1727 Acquires credentials for each of the mechanisms specified in the 1728 array called mechs. To determine the list of mechanisms' for which 1729 the acquisition of credentials succeeded, the caller should use the 1730 GSSCredential.getMechs() method. 1732 Parameters: 1734 aName Name of the principal for whom this credential is to be 1735 acquired. Use "null" to specify the default principal. 1737 lifetime The number of seconds that credentials should remain 1738 valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the 1739 credentials have the maximum permitted lifetime. Use 1740 GSSCredential.DEFAULT_LIFETIME to request default credential 1741 lifetime. 1743 mechs The array of mechanisms over which the credential is to be 1744 acquired. Use "(Oid[]) null" for requesting a system specific 1745 default set of mechanisms. 1747 usage The intended usage for this credential object. The value of 1748 this parameter must be one of: 1749 GSSCredential.INITIATE_AND_ACCEPT(0), 1750 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1752 7.1.13. createContext 1754 public abstract GSSContext createContext(GSSName peer, Oid mech, 1755 GSSCredential myCred, int lifetime) 1756 throws GSSException 1758 Factory method for creating a context on the initiator's side. 1759 Context flags may be modified through the mutator methods prior to 1760 calling GSSContext.initSecContext(). 1762 Parameters: 1764 peer Name of the target peer. 1766 mech Oid of the desired mechanism. Use "(Oid) null" to request 1767 the default mechanism. 1769 myCred Credentials of the initiator. Use "null" to act as a 1770 default initiator principal. 1772 lifetime The request lifetime, in seconds, for the context. Use 1773 GSSContext.INDEFINITE_LIFETIME and GSSContext.DEFAULT_LIFETIME to 1774 request indefinite or default context lifetime. 1776 7.1.14. createContext 1778 public abstract GSSContext createContext(GSSCredential myCred) 1779 throws GSSException 1781 Factory method for creating a context on the acceptor' side. The 1782 context's properties will be determined from the input token supplied 1783 to the accept method. 1785 Parameters: 1787 myCred Credentials for the acceptor. Use "null" to act as a 1788 default acceptor principal. 1790 7.1.15. createContext 1792 public abstract GSSContext createContext(byte[] interProcessToken) 1793 throws GSSException 1795 Factory method for creating a previously exported context. The 1796 context properties will be determined from the input token and can't 1797 be modified through the set methods. 1799 Parameters: 1801 interProcessToken The token previously emitted from the export 1802 method. 1804 7.1.16. addProviderAtFront 1806 public abstract void addProviderAtFront(Provider p, Oid mech) 1807 throws GSSException 1809 This method is used to indicate to the GSSManager that the 1810 application would like a particular provider to be used ahead of all 1811 others when support is desired for the given mechanism. When a value 1812 of null is used instead of an Oid for the mechanism, the GSSManager 1813 must use the indicated provider ahead of all others no matter what 1814 the mechanism is. Only when the indicated provider does not support 1815 the needed mechanism should the GSSManager move on to a different 1816 provider. 1818 Calling this method repeatedly preserves the older settings but 1819 lowers them in preference thus forming an ordered list of provider 1820 and Oid pairs that grows at the top. 1822 Calling addProviderAtFront with a null Oid will remove all previous 1823 preferences that were set for this provider in the GSSManager 1824 instance. Calling addProviderAtFront with a non-null Oid will remove 1825 any previous preference that was set using this mechanism and this 1826 provider together. 1828 If the GSSManager implementation does not support an SPI with a 1829 pluggable provider architecture it should throw a GSSException with 1830 the status code GSSException.UNAVAILABLE to indicate that the 1831 operation is unavailable. 1833 Parameters: 1835 p The provider instance that should be used whenever support is 1836 needed for mech. 1838 mech The mechanism for which the provider is being set 1840 7.1.17. Example Code 1842 Suppose an application desired that the provider A always be checked 1843 first when any mechanism is needed, it would call: 1845 GSSManager mgr = GSSManager.getInstance(); 1846 // mgr may at this point have its own pre-configured list 1847 // of provider preferences. The following will prepend to 1848 // any such list: 1850 mgr.addProviderAtFront(A, null); 1852 Now if it also desired that the mechanism of Oid m1 always be 1853 obtained from the provider B before the previously set A was checked, 1854 it would call: 1856 mgr.addProviderAtFront(B, m1); 1858 The GSSManager would then first check with B if m1 was needed. In 1859 case B did not provide support for m1, the GSSManager would continue 1860 on to check with A. If any mechanism m2 is needed where m2 is 1861 different from m1 then the GSSManager would skip B and check with A 1862 directly. 1864 Suppose at a later time the following call is made to the same 1865 GSSManager instance: 1867 mgr.addProviderAtFront(B, null) 1869 then the previous setting with the pair (B, m1) is subsumed by this 1870 and should be removed. Effectively the list of preferences now 1871 becomes {(B, null), (A, null), ... //followed by the pre-configured 1872 list. 1874 Please note, however, that the following call: 1876 mgr.addProviderAtFront(A, m3) 1878 does not subsume the previous setting of (A, null) and the list will 1879 effectively become {(A, m3), (B, null), (A, null), ...} 1881 7.1.18. addProviderAtEnd 1883 public abstract void addProviderAtEnd(Provider p, Oid mech) 1884 throws GSSException 1886 This method is used to indicate to the GSSManager that the 1887 application would like a particular provider to be used if no other 1888 provider can be found that supports the given mechanism. When a 1889 value of null is used instead of an Oid for the mechanism, the 1890 GSSManager must use the indicated provider for any mechanism. 1892 Calling this method repeatedly preserves the older settings but 1893 raises them above newer ones in preference thus forming an ordered 1894 list of providers and Oid pairs that grows at the bottom. Thus the 1895 older provider settings will be utilized first before this one is. 1897 If there are any previously existing preferences that conflict with 1898 the preference being set here, then the GSSManager should ignore this 1899 request. 1901 If the GSSManager implementation does not support an SPI with a 1902 pluggable provider architecture it should throw a GSSException with 1903 the status code GSSException.UNAVAILABLE to indicate that the 1904 operation is unavailable. 1906 Parameters: 1908 p The provider instance that should be used whenever support is 1909 needed for mech. 1911 mech The mechanism for which the provider is being set 1913 7.1.19. Example Code 1915 Suppose an application desired that when a mechanism of Oid m1 is 1916 needed the system default providers always be checked first, and only 1917 when they do not support m1 should a provider A be checked. It would 1918 then make the call: 1920 GSSManager mgr = GSSManager.getInstance(); 1922 mgr.addProviderAtEnd(A, m1); 1924 Now, if it also desired that for all mechanisms the provider B be 1925 checked after all configured providers have been checked, it would 1926 then call: 1928 mgr.addProviderAtEnd(B, null); 1930 Effectively the list of preferences now becomes {..., (A, m1), (B, 1931 null)}. 1933 Suppose at a later time the following call is made to the same 1934 GSSManager instance: 1936 mgr.addProviderAtEnd(B, m2) 1938 then the previous setting with the pair (B, null) subsumes this and 1939 therefore this request should be ignored. The same would happen if a 1940 request is made for the already existing pairs of (A, m1) or (B, 1941 null). 1943 Please note, however, that the following call: 1945 mgr.addProviderAtEnd(A, null) 1947 is not subsumed by the previous setting of (A, m1) and the list will 1948 effectively become {..., (A, m1), (B, null), (A, null)} 1950 7.2. public interface GSSName 1952 This interface encapsulates a single GSS-API principal entity. 1953 Different name formats and their definitions are identified with 1954 universal Object Identifiers (Oids). The format of the names can be 1955 derived based on the unique oid of its namespace type. 1957 7.2.1. Example Code 1959 Included below are code examples utilizing the GSSName interface. 1960 The code below creates a GSSName, converts it to a mechanism name 1961 (MN), performs a comparison, obtains a printable representation of 1962 the name, exports it and then re-imports to obtain a new GSSName. 1964 GSSManager mgr = GSSManager.getInstance(); 1966 // create a host based service name 1967 GSSName name = mgr.createName("service@host", 1968 GSSName.NT_HOSTBASED_SERVICE); 1970 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 1972 GSSName mechName = name.canonicalize(krb5); 1974 // the above two steps are equivalent to the following 1975 GSSName mechName = mgr.createName("service@host", 1976 GSSName.NT_HOSTBASED_SERVICE, krb5); 1978 // perform name comparison 1979 if (name.equals(mechName)) 1980 print("Names are equals."); 1982 // obtain textual representation of name and its printable 1983 // name type 1984 print(mechName.toString() + 1985 mechName.getStringNameType().toString()); 1987 // export and re-import the name 1988 byte[] exportName = mechName.export(); 1990 // create a new name object from the exported buffer 1991 GSSName newName = mgr.createName(exportName, 1992 GSSName.NT_EXPORT_NAME); 1994 7.2.2. Static Constants 1996 public static final Oid NT_HOSTBASED_SERVICE 1998 Oid indicating a host-based service name form. It is used to 1999 represent services associated with host computers. This name form is 2000 constructed using two elements, "service" and "hostname", as follows: 2002 service@hostname 2004 Values for the "service" element are registered with the IANA. It 2005 represents the following value: { iso(1) member-body(2) Unites 2006 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2007 service_name(4) } 2009 public static final Oid NT_USER_NAME 2011 Name type to indicate a named user on a local system. It represents 2012 the following value: { iso(1) member-body(2) United States(840) 2013 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2015 public static final Oid NT_MACHINE_UID_NAME 2017 Name type to indicate a numeric user identifier corresponding to a 2018 user on a local system. (e.g. Uid). It represents the following 2019 value: { iso(1) member-body(2) United States(840) mit(113554) 2020 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2022 public static final Oid NT_STRING_UID_NAME 2024 Name type to indicate a string of digits representing the numeric 2025 user identifier of a user on a local system. It represents the 2026 following value: { iso(1) member-body(2) United States(840) 2027 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2029 public static final Oid NT_ANONYMOUS 2031 Name type for representing an anonymous entity. It represents the 2032 following value: { iso(1), org(3), dod(6), internet(1), security(5), 2033 nametypes(6), gss-anonymous-name(3) } 2035 public static final Oid NT_EXPORT_NAME 2037 Name type used to indicate an exported name produced by the export 2038 method. It represents the following value: { iso(1), org(3), dod(6), 2039 internet(1), security(5), nametypes(6), gss-api-exported-name(4) } 2041 7.2.3. equals 2043 public boolean equals(GSSName another) throws GSSException 2045 Compares two GSSName objects to determine whether they refer to the 2046 same entity. This method may throw a GSSException when the names 2047 cannot be compared. If either of the names represents an anonymous 2048 entity, the method will return "false". 2050 Parameters: 2052 another GSSName object to compare with. 2054 7.2.4. equals 2056 public boolean equals(Object another) 2058 A variation of the equals method described in 7.2.3 that is provided 2059 to override the Object.equals() method that the implementing class 2060 will inherit. The behavior is exactly the same as that in 7.2.3 2061 except that no GSSException is thrown; instead, false will be 2062 returned in the situation where an error occurs. (Note that the Java 2063 language specification requires that two objects that are equal 2064 according to the equals(Object) method must return the same integer 2065 result when the hashCode() method is called on them.) 2067 Parameters: 2069 another GSSName object to compare with. 2071 7.2.5. canonicalize 2073 public GSSName canonicalize(Oid mech) throws GSSException 2075 Creates a mechanism name (MN) from an arbitrary internal name. This 2076 is equivalent to using the factory methods described in 7.1.8 or 2077 7.1.9 that take the mechanism name as one of their parameters. 2079 Parameters: 2081 mech The oid for the mechanism for which the canonical form of the 2082 name is requested. 2084 7.2.6. export 2086 public byte[] export() throws GSSException 2088 Returns a canonical contiguous byte representation of a mechanism 2089 name (MN), suitable for direct, byte by byte comparison by 2090 authorization functions. If the name is not an MN, implementations 2091 may throw a GSSException with the NAME_NOT_MN status code. If an 2092 implementation chooses not to throw an exception, it should use some 2093 system specific default mechanism to canonicalize the name and then 2094 export it. The format of the header of the output buffer is 2095 specified in RFC 2743 [GSSAPIv2-UPDATE]. 2097 7.2.7. toString 2099 public String toString() 2101 Returns a textual representation of the GSSName object. To retrieve 2102 the printed name format, which determines the syntax of the returned 2103 string, the getStringNameType method can be used. 2105 7.2.8. getStringNameType 2107 public Oid getStringNameType() throws GSSException 2109 Returns the oid representing the type of name returned through the 2110 toString method. Using this oid, the syntax of the printable name 2111 can be determined. 2113 7.2.9. isAnonymous 2115 public boolean isAnonymous() 2117 Tests if this name object represents an anonymous entity. Returns 2118 "true" if this is an anonymous name. 2120 7.2.10. isMN 2122 public boolean isMN() 2124 Tests if this name object contains only one mechanism element and is 2125 thus a mechanism name as defined by RFC 2743 [GSSAPIv2-UPDATE]. 2127 7.3. public interface GSSCredential implements Cloneable 2129 This interface encapsulates the GSS-API credentials for an entity. A 2130 credential contains all the necessary cryptographic information to 2131 enable the creation of a context on behalf of the entity that it 2132 represents. It may contain multiple, distinct, mechanism specific 2133 credential elements, each containing information for a specific 2134 security mechanism, but all referring to the same entity. 2136 A credential may be used to perform context initiation, acceptance, 2137 or both. 2139 GSS-API implementations must impose a local access-control policy on 2140 callers to prevent unauthorized callers from acquiring credentials to 2141 which they are not entitled. GSS-API credential creation is not 2142 intended to provide a "login to the network" function, as such a 2143 function would involve the creation of new credentials rather than 2144 merely acquiring a handle to existing credentials. Such functions, 2145 if required, should be defined in implementation-specific extensions 2146 to the API. 2148 If credential acquisition is time-consuming for a mechanism, the 2149 mechanism may choose to delay the actual acquisition until the 2150 credential is required (e.g. by GSSContext). Such mechanism- 2151 specific implementation decisions should be invisible to the calling 2152 application; thus the query methods immediately following the 2153 creation of a credential object must return valid credential data, 2154 and may therefore incur the overhead of a deferred credential 2155 acquisition. 2157 Applications will create a credential object passing the desired 2158 parameters. The application can then use the query methods to obtain 2159 specific information about the instantiated credential object 2160 (equivalent to the gss_inquire routines). When the credential is no 2161 longer needed, the application should call the dispose (equivalent to 2162 gss_release_cred) method to release any resources held by the 2163 credential object and to destroy any cryptographically sensitive 2164 information. 2166 Classes implementing this interface also implement the Cloneable 2167 interface. This indicates the the class will support the clone() 2168 method that will allow the creation of duplicate credentials. This 2169 is useful when called just before the add() call to retain a copy of 2170 the original credential. 2172 7.3.1. Example Code 2174 This example code demonstrates the creation of a GSSCredential 2175 implementation for a specific entity, querying of its fields, and its 2176 release when it is no longer needed. 2178 GSSManager mgr = GSSManager.getInstance(); 2180 // start by creating a name object for the entity 2181 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2183 // now acquire credentials for the entity 2184 GSSCredential cred = mgr.createCredential(name, 2185 GSSCredential.ACCEPT_ONLY); 2187 // display credential information - name, remaining lifetime, 2188 // and the mechanisms it has been acquired over 2189 print(cred.getName().toString()); 2190 print(cred.getRemainingLifetime()); 2192 Oid[] mechs = cred.getMechs(); 2193 if (mechs != null) { 2194 for (int i = 0; i < mechs.length; i++) 2195 print(mechs[i].toString()); 2196 } 2197 // release system resources held by the credential 2198 cred.dispose(); 2200 7.3.2. Static Constants 2202 public static final int INITIATE_AND_ACCEPT 2204 Credential usage flag requesting that it be able to be used for both 2205 context initiation and acceptance. The value of this constant is 0. 2207 public static final int INITIATE_ONLY 2209 Credential usage flag requesting that it be able to be used for 2210 context initiation only. The value of this constant is 1. 2212 public static final int ACCEPT_ONLY 2214 Credential usage flag requesting that it be able to be used for 2215 context acceptance only. The value of this constant is 2. 2217 public static final int DEFAULT_LIFETIME 2219 A lifetime constant representing the default credential lifetime. 2220 The value of this constant is 0. 2222 public static final int INDEFINITE_LIFETIME 2224 A lifetime constant representing indefinite credential lifetime. The 2225 value of this constant is the maximum integer value in Java - 2226 Integer.MAX_VALUE. 2228 7.3.3. dispose 2230 public void dispose() throws GSSException 2232 Releases any sensitive information that the GSSCredential object may 2233 be containing. Applications should call this method as soon as the 2234 credential is no longer needed to minimize the time any sensitive 2235 information is maintained. 2237 7.3.4. getName 2239 public GSSName getName() throws GSSException 2241 Retrieves the name of the entity that the credential asserts. 2243 7.3.5. getName 2244 public GSSName getName(Oid mechOID) throws GSSException 2246 Retrieves a mechanism name of the entity that the credential asserts. 2247 Equivalent to calling canonicalize() on the name returned by 7.3.4. 2249 Parameters: 2251 mechOID The mechanism for which information should be returned. 2253 7.3.6. getRemainingLifetime 2255 public int getRemainingLifetime() throws GSSException 2257 Returns the remaining lifetime in seconds for a credential. The 2258 remaining lifetime is the minimum lifetime for any of the underlying 2259 credential mechanisms. A return value of 2260 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2261 not expire. A return value of 0 indicates that the credential is 2262 already expired. 2264 7.3.7. getRemainingInitLifetime 2266 public int getRemainingInitLifetime(Oid mech) throws GSSException 2268 Returns the remaining lifetime is seconds for the credential to 2269 remain capable of initiating security contexts under the specified 2270 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2271 indicates that the credential does not expire for context initiation. 2272 A return value of 0 indicates that the credential is already expired. 2274 Parameters: 2276 mechOID The mechanism for which information should be returned. 2278 7.3.8. getRemainingAcceptLifetime 2280 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2282 Returns the remaining lifetime is seconds for the credential to 2283 remain capable of accepting security contexts under the specified 2284 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2285 indicates that the credential does not expire for context acceptance. 2286 A return value of 0 indicates that the credential is already expired. 2288 Parameters: 2290 mechOID The mechanism for which information should be returned. 2292 7.3.9. getUsage 2294 public int getUsage() throws GSSException 2296 Returns the credential usage flag as a union over all mechanisms. 2297 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2298 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2300 7.3.10. getUsage 2302 public int getUsage(Oid mechOID) throws GSSException 2304 Returns the credential usage flag for the specified mechanism only. 2305 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2306 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2308 Parameters: 2310 mechOID The mechanism for which information should be returned. 2312 7.3.11. getMechs 2314 public Oid[] getMechs() throws GSSException 2316 Returns an array of mechanisms supported by this credential. 2318 7.3.12. add 2320 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2321 Oid mech, int usage) throws GSSException 2323 Adds a mechanism specific credential-element to an existing 2324 credential. This method allows the construction of credentials one 2325 mechanism at a time. 2327 This routine is envisioned to be used mainly by context acceptors 2328 during the creation of acceptance credentials which are to be used 2329 with a variety of clients using different security mechanisms. 2331 This routine adds the new credential element "in-place". To add the 2332 element in a new credential, first call clone() to obtain a copy of 2333 this credential, then call its add() method. 2335 Parameters: 2337 aName Name of the principal for whom this credential is to be 2338 acquired. Use "null" to specify the default principal. 2340 initLifetime The number of seconds that credentials should remain 2341 valid for initiating of security contexts. Use 2342 GSSCredential.INDEFINITE_LIFETIME to request that the credentials 2343 have the maximum permitted lifetime. Use 2344 GSSCredential.DEFAULT_LIFETIME to request default credential 2345 lifetime. 2347 acceptLifetime The number of seconds that credentials should 2348 remain valid for accepting of security contexts. Use 2349 GSSCredential.INDEFINITE_LIFETIME to request that the credentials 2350 have the maximum permitted lifetime. Use 2351 GSSCredential.DEFAULT_LIFETIME to request default credential 2352 lifetime. 2354 mech The mechanisms over which the credential is to be acquired. 2356 usage The intended usage for this credential object. The value of 2357 this parameter must be one of: 2358 GSSCredential.INITIATE_AND_ACCEPT(0), 2359 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 2361 7.3.13. equals 2363 public boolean equals(Object another) 2365 Tests if this GSSCredential refers to the same entity as the supplied 2366 object. The two credentials must be acquired over the same 2367 mechanisms and must refer to the same principal. Returns "true" if 2368 the two GSSCredentials refer to the same entity; "false" otherwise. 2369 (Note that the Java language specification [JLS] requires that two 2370 objects that are equal according to the equals(Object) method must 2371 return the same integer result when the hashCode() method is called 2372 on them.) 2374 Parameters: 2376 another Another GSSCredential object for comparison. 2378 7.4. public interface GSSContext 2380 This interface encapsulates the GSS-API security context and provides 2381 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2382 available over the context. Security contexts are established 2383 between peers using locally acquired credentials. Multiple contexts 2384 may exist simultaneously between a pair of peers, using the same or 2385 different set of credentials. GSS-API functions in a manner 2386 independent of the underlying transport protocol and depends on its 2387 calling application to transport its tokens between peers. 2389 Before the context establishment phase is initiated, the context 2390 initiator may request specific characteristics desired of the 2391 established context. These can be set using the set methods. After 2392 the context is established, the caller can check the actual 2393 characteristic and services offered by the context using the query 2394 methods. 2396 The context establishment phase begins with the first call to the 2397 init method by the context initiator. During this phase the 2398 initSecContext and acceptSecContext methods will produce GSS-API 2399 authentication tokens which the calling application needs to send to 2400 its peer. If an error occurs at any point, an exception will get 2401 thrown and the code will start executing in a catch block. If not, 2402 the normal flow of code continues and the application can make a call 2403 to the isEstablished() method. If this method returns false it 2404 indicates that a token is needed from its peer in order to continue 2405 the context establishment phase. A return value of true signals that 2406 the local end of the context is established. This may still require 2407 that a token be sent to the peer, if one is produced by GSS-API. 2408 During the context establishment phase, the isProtReady() method may 2409 be called to determine if the context can be used for the per-message 2410 operations. This allows applications to use per-message operations 2411 on contexts which aren't fully established. 2413 After the context has been established or the isProtReady() method 2414 returns "true", the query routines can be invoked to determine the 2415 actual characteristics and services of the established context. The 2416 application can also start using the per-message methods of wrap and 2417 getMIC to obtain cryptographic operations on application supplied 2418 data. 2420 When the context is no longer needed, the application should call 2421 dispose to release any system resources the context may be using. 2423 7.4.1. Example Code 2425 The example code presented below demonstrates the usage of the 2426 GSSContext interface for the initiating peer. Different operations 2427 on the GSSContext object are presented, including: object 2428 instantiation, setting of desired flags, context establishment, query 2429 of actual context flags, per-message operations on application data, 2430 and finally context deletion. 2432 GSSManager mgr = GSSManager.getInstance(); 2434 // start by creating the name for a service entity 2435 GSSName targetName = mgr.createName("service@host", 2436 GSSName.NT_HOSTBASED_SERVICE); 2438 // create a context using default credentials for the above entity 2439 // and the implementation specific default mechanism 2440 GSSContext context = mgr.createContext(targetName, 2441 null, /* default mechanism */ 2442 null, /* default credentials */ 2443 GSSContext.INDEFINITE_LIFETIME); 2445 // set desired context options - all others are false by default 2446 context.requestConf(true); 2447 context.requestMutualAuth(true); 2448 context.requestReplayDet(true); 2449 context.requestSequenceDet(true); 2451 // establish a context between peers - using byte arrays 2452 byte[]inTok = new byte[0]; 2454 try { 2455 do { 2456 byte[] outTok = context.initSecContext(inTok, 0, 2457 inTok.length); 2459 // send the token if present 2460 if (outTok != null) 2461 sendToken(outTok); 2463 // check if we should expect more tokens 2464 if (context.isEstablished()) 2465 break; 2467 // another token expected from peer 2468 inTok = readToken(); 2470 } while (true); 2472 } catch (GSSException e) { 2473 print("GSSAPI error: " + e.getMessage()); 2474 } 2476 // display context information 2477 print("Remaining lifetime in seconds = " + context.getLifetime()); 2478 print("Context mechanism = " + context.getMech().toString()); 2479 print("Initiator = " + context.getSrcName().toString()); 2480 print("Acceptor = " + context.getTargName().toString()); 2482 if (context.getConfState()) 2483 print("Confidentiality security service available"); 2485 if (context.getIntegState()) 2486 print("Integrity security service available"); 2488 // perform wrap on an application supplied message, appMsg, 2489 // using QOP = 0, and requesting privacy service 2490 byte[] appMsg ... 2492 MessageProp mProp = new MessageProp(0, true); 2494 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2496 if (mProp.getPrivacy()) 2497 print("Message protected with privacy."); 2499 sendToken(tok); 2501 // release the local-end of the context 2502 context.dispose(); 2504 7.4.2. Static Constants 2506 public static final int DEFAULT_LIFETIME 2508 A lifetime constant representing the default context lifetime. The 2509 value of this constant is 0. 2511 public static final int INDEFINITE_LIFETIME 2513 A lifetime constant representing indefinite context lifetime. The 2514 value of this constant is the maximum integer value in Java - 2515 Integer.MAX_VALUE. 2517 7.4.3. initSecContext 2519 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2520 throws GSSException 2522 Called by the context initiator to start the context creation 2523 process. This is equivalent to the stream based method except that 2524 the token buffers are handled as byte arrays instead of using stream 2525 objects. This method may return an output token which the 2526 application will need to send to the peer for processing by the 2527 accept call. Typically, the application would do so by calling the 2528 flush() method on an OutputStream that encapsulates the connection 2529 between the two peers. The application can call isEstablished() to 2530 determine if the context establishment phase is complete for this 2531 peer. A return value of "false" from isEstablished() indicates that 2532 more tokens are expected to be supplied to the initSecContext() 2533 method. Note that it is possible that the initSecContext() method 2534 return a token for the peer, and isEstablished() return "true" also. 2535 This indicates that the token needs to be sent to the peer, but the 2536 local end of the context is now fully established. 2538 Upon completion of the context establishment, the available context 2539 options may be queried through the get methods. 2541 Parameters: 2543 inputBuf Token generated by the peer. This parameter is ignored 2544 on the first call. 2546 offset The offset within the inputBuf where the token begins. 2548 len The length of the token within the inputBuf (starting at the 2549 offset). 2551 7.4.4. Example Code 2553 // Create a new GSSContext implementation object. 2554 // GSSContext wrapper implements interface GSSContext. 2555 GSSContext context = mgr.createContext(...); 2557 byte[] inTok = new byte[0]; 2559 try { 2560 do { 2561 byte[] outTok = context.initSecContext(inTok, 0, 2562 inTok.length); 2564 // send the token if present 2565 if (outTok != null) 2566 sendToken(outTok); 2568 // check if we should expect more tokens 2569 if (context.isEstablished()) 2570 break; 2572 // another token expected from peer 2573 inTok = readToken(); 2574 } while (true); 2576 } catch (GSSException e) { 2577 print("GSSAPI error: " + e.getMessage()); 2578 } 2580 7.4.5. initSecContext 2581 public int initSecContext(InputStream inStream, 2582 OutputStream outStream) throws GSSException 2584 Called by the context initiator to start the context creation 2585 process. This is equivalent to the byte array based method. This 2586 method may write an output token to the outStream, which the 2587 application will need to send to the peer for processing by the 2588 accept call. Typically, the application would do so by calling the 2589 flush() method on an OutputStream that encapsulates the connection 2590 between the two peers. The application can call isEstablished() to 2591 determine if the context establishment phase is complete for this 2592 peer. A return value of "false" from isEstablished indicates that 2593 more tokens are expected to be supplied to the initSecContext method. 2594 Note that it is possible that the initSecContext() method return a 2595 token for the peer, and isEstablished() return "true" also. This 2596 indicates that the token needs to be sent to the peer, but the local 2597 end of the context is now fully established. 2599 The GSS-API authentication tokens contain a definitive start and end. 2600 This method will attempt to read one of these tokens per invocation, 2601 and may block on the stream if only part of the token is available. 2603 Upon completion of the context establishment, the available context 2604 options may be queried through the get methods. 2606 Parameters: 2608 inStream Contains the token generated by the peer. This parameter 2609 is ignored on the first call. 2611 outStream Output stream where the output token will be written. 2612 During the final stage of context establishment, there may be no 2613 bytes written. 2615 7.4.6. Example Code 2617 This sample code merely demonstrates the token exchange during the 2618 context establishment phase. It is expected that most Java 2619 applications will use custom implementations of the Input and Output 2620 streams that encapsulate the communication routines. For instance, a 2621 simple read on the application InputStream, when called by the 2622 Context, might cause a token to be read from the peer, and a simple 2623 flush() on the application OutputStream might cause a previously 2624 written token to be transmitted to the peer. 2626 // Create a new GSSContext implementation object. 2627 // GSSContext wrapper implements interface GSSContext. 2628 GSSContext context = mgr.createContext(...); 2629 // use standard java.io stream objects 2630 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2631 ByteArrayInputStream is = null; 2633 try { 2634 do { 2635 context.initSecContext(is, os); 2637 // send token if present 2638 if (os.size() > 0) 2639 sendToken(os); 2641 // check if we should expect more tokens 2642 if (context.isEstablished()) 2643 break; 2645 // another token expected from peer 2646 is = recvToken(); 2648 } while (true); 2650 } catch (GSSException e) { 2651 print("GSSAPI error: " + e.getMessage()); 2652 } 2654 7.4.7. acceptSecContext 2656 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2657 throws GSSException 2659 Called by the context acceptor upon receiving a token from the peer. 2660 This call is equivalent to the stream based method except that the 2661 token buffers are handled as byte arrays instead of using stream 2662 objects. 2664 This method may return an output token which the application will 2665 need to send to the peer for further processing by the init call. 2667 "null" return value indicates that no token needs to be sent to the 2668 peer. The application can call isEstablished() to determine if the 2669 context establishment phase is complete for this peer. A return 2670 value of "false" from isEstablished() indicates that more tokens are 2671 expected to be supplied to this method. 2673 Note that it is possible that acceptSecContext() return a token for 2674 the peer, and isEstablished() return "true" also. This indicates 2675 that the token needs to be sent to the peer, but the local end of the 2676 context is now fully established. 2678 Upon completion of the context establishment, the available context 2679 options may be queried through the get methods. 2681 Parameters: 2683 inTok Token generated by the peer. 2685 offset The offset within the inTok where the token begins. 2687 len The length of the token within the inTok (starting at the 2688 offset). 2690 7.4.8. Example Code 2692 // acquire server credentials 2693 GSSCredential server = mgr.createCredential(...); 2695 // create acceptor GSS-API context from the default provider 2696 GSSContext context = mgr.createContext(server, null); 2698 try { 2699 do { 2700 byte[] inTok = readToken(); 2702 byte[] outTok = context.acceptSecContext(inTok, 0, 2703 inTok.length); 2705 // possibly send token to peer 2706 if (outTok != null) 2707 sendToken(outTok); 2709 // check if local context establishment is complete 2710 if (context.isEstablished()) 2711 break; 2712 } while (true); 2714 } catch (GSSException e) { 2715 print("GSS-API error: " + e.getMessage()); 2716 } 2718 7.4.9. acceptSecContext 2720 public void acceptSecContext(InputStream inStream, 2721 OutputStream outStream) throws GSSException 2723 Called by the context acceptor upon receiving a token from the peer. 2724 This call is equivalent to the byte array method. It may write an 2725 output token to the outStream, which the application will need to 2726 send to the peer for processing by its initSecContext method. 2727 Typically, the application would do so by calling the flush() method 2728 on an OutputStream that encapsulates the connection between the two 2729 peers. The application can call isEstablished() to determine if the 2730 context establishment phase is complete for this peer. A return 2731 value of "false" from isEstablished() indicates that more tokens are 2732 expected to be supplied to this method. 2734 Note that it is possible that acceptSecContext() return a token for 2735 the peer, and isEstablished() return "true" also. This indicates 2736 that the token needs to be sent to the peer, but the local end of the 2737 context is now fully established. 2739 The GSS-API authentication tokens contain a definitive start and end. 2740 This method will attempt to read one of these tokens per invocation, 2741 and may block on the stream if only part of the token is available. 2743 Upon completion of the context establishment, the available context 2744 options may be queried through the get methods. 2746 Parameters: 2748 inStream Contains the token generated by the peer. 2750 outStream Output stream where the output token will be written. 2751 During the final stage of context establishment, there may be no 2752 bytes written. 2754 7.4.10. Example Code 2756 This sample code merely demonstrates the token exchange during the 2757 context establishment phase. It is expected that most Java 2758 applications will use custom implementations of the Input and Output 2759 streams that encapsulate the communication routines. For instance, a 2760 simple read on the application InputStream, when called by the 2761 Context, might cause a token to be read from the peer, and a simple 2762 flush() on the application OutputStream might cause a previously 2763 written token to be transmitted to the peer. 2765 // acquire server credentials 2766 GSSCredential server = mgr.createCredential(...); 2768 // create acceptor GSS-API context from the default provider 2769 GSSContext context = mgr.createContext(server, null); 2771 // use standard java.io stream objects 2772 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2773 ByteArrayInputStream is = null; 2774 try { 2775 do { 2777 is = recvToken(); 2779 context.acceptSecContext(is, os); 2781 // possibly send token to peer 2782 if (os.size() > 0) 2783 sendToken(os); 2785 // check if local context establishment is complete 2786 if (context.isEstablished()) 2787 break; 2788 } while (true); 2790 } catch (GSSException e) { 2791 print("GSS-API error: " + e.getMessage()); 2792 } 2794 7.4.11. isEstablished 2796 public boolean isEstablished() 2798 Used during context establishment to determine the state of the 2799 context. Returns "true" if this is a fully established context on 2800 the caller's side and no more tokens are needed from the peer. 2801 Should be called after a call to initSecContext() or 2802 acceptSecContext() when no GSSException is thrown. 2804 7.4.12. dispose 2806 public void dispose() throws GSSException 2808 Releases any system resources and cryptographic information stored in 2809 the context object. This will invalidate the context. 2811 7.4.13. getWrapSizeLimit 2813 public int getWrapSizeLimit(int qop, boolean confReq, 2814 int maxTokenSize) throws GSSException 2816 Returns the maximum message size that, if presented to the wrap 2817 method with the same confReq and qop parameters, will result in an 2818 output token containing no more than the maxTokenSize bytes. 2820 This call is intended for use by applications that communicate over 2821 protocols that impose a maximum message size. It enables the 2822 application to fragment messages prior to applying protection. 2824 GSS-API implementations are recommended but not required to detect 2825 invalid QOP values when getWrapSizeLimit is called. This routine 2826 guarantees only a maximum message size, not the availability of 2827 specific QOP values for message protection. 2829 Successful completion of this call does not guarantee that wrap will 2830 be able to protect a message of the computed length, since this 2831 ability may depend on the availability of system resources at the 2832 time that wrap is called. However, if the implementation itself 2833 imposes an upper limit on the length of messages that may be 2834 processed by wrap, the implementation should not return a value that 2835 is greater than this length. 2837 Parameters: 2839 qop Indicates the level of protection wrap will be asked to 2840 provide. 2842 confReq Indicates if wrap will be asked to provide privacy 2843 service. 2845 maxTokenSize The desired maximum size of the token emitted by 2846 wrap. 2848 7.4.14. wrap 2850 public byte[] wrap(byte[] inBuf, int offset, int len, 2851 MessageProp msgProp) throws GSSException 2853 Applies per-message security services over the established security 2854 context. The method will return a token with a cryptographic MIC and 2855 may optionally encrypt the specified inBuf. This method is 2856 equivalent in functionality to its stream counterpart. The returned 2857 byte array will contain both the MIC and the message. 2859 The MessageProp object is instantiated by the application and used to 2860 specify a QOP value which selects cryptographic algorithms, and a 2861 privacy service to optionally encrypt the message. The underlying 2862 mechanism that is used in the call may not be able to provide the 2863 privacy service. It sets the actual privacy service that it does 2864 provide in this MessageProp object which the caller should then query 2865 upon return. If the mechanism is not able to provide the requested 2866 QOP, it throws a GSSException with the BAD_QOP code. 2868 Since some application-level protocols may wish to use tokens emitted 2869 by wrap to provide "secure framing", implementations should support 2870 the wrapping of zero-length messages. 2872 The application will be responsible for sending the token to the 2873 peer. 2875 Parameters: 2877 inBuf Application data to be protected. 2879 offset The offset within the inBuf where the data begins. 2881 len The length of the data within the inBuf (starting at the 2882 offset). 2884 msgProp Instance of MessageProp that is used by the application to 2885 set the desired QOP and privacy state. Set the desired QOP to 0 2886 to request the default QOP. Upon return from this method, this 2887 object will contain the the actual privacy state that was applied 2888 to the message by the underlying mechanism. 2890 7.4.15. wrap 2892 public void wrap(InputStream inStream, OutputStream outStream, 2893 MessageProp msgProp) throws GSSException 2895 Allows to apply per-message security services over the established 2896 security context. The method will produce a token with a 2897 cryptographic MIC and may optionally encrypt the message in inStream. 2898 The outStream will contain both the MIC and the message. 2900 The MessageProp object is instantiated by the application and used to 2901 specify a QOP value which selects cryptographic algorithms, and a 2902 privacy service to optionally encrypt the message. The underlying 2903 mechanism that is used in the call may not be able to provide the 2904 privacy service. It sets the actual privacy service that it does 2905 provide in this MessageProp object which the caller should then query 2906 upon return. If the mechanism is not able to provide the requested 2907 QOP, it throws a GSSException with the BAD_QOP code. 2909 Since some application-level protocols may wish to use tokens emitted 2910 by wrap to provide "secure framing", implementations should support 2911 the wrapping of zero-length messages. 2913 The application will be responsible for sending the token to the 2914 peer. 2916 Parameters: 2918 inStream Input stream containing the application data to be 2919 protected. 2921 outStream The output stream to write the protected message to. 2922 The application is responsible for sending this to the other peer 2923 for processing in its unwrap method. 2925 msgProp Instance of MessageProp that is used by the application to 2926 set the desired QOP and privacy state. Set the desired QOP to 0 2927 to request the default QOP. Upon return from this method, this 2928 object will contain the the actual privacy state that was applied 2929 to the message by the underlying mechanism. 2931 7.4.16. unwrap 2933 public byte[] unwrap(byte[] inBuf, int offset, int len, 2934 MessageProp msgProp) throws GSSException 2936 Used by the peer application to process tokens generated with the 2937 wrap call. This call is equal in functionality to its stream 2938 counterpart. The method will return the message supplied in the peer 2939 application to the wrap call, verifying the embedded MIC. 2941 The MessageProp object is instantiated by the application and is used 2942 by the underlying mechanism to return information to the caller such 2943 as the QOP, whether confidentiality was applied to the message, and 2944 other supplementary message state information. 2946 Since some application-level protocols may wish to use tokens emitted 2947 by wrap to provide "secure framing", implementations should support 2948 the wrapping and unwrapping of zero-length messages. 2950 Parameters: 2952 inBuf GSS-API wrap token received from peer. 2954 offset The offset within the inBuf where the token begins. 2956 len The length of the token within the inBuf (starting at the 2957 offset). 2959 msgProp Upon return from the method, this object will contain the 2960 applied QOP, the privacy state of the message, and supplementary 2961 information described in 5.12.3 stating whether the token was a 2962 duplicate, old, out of sequence or arriving after a gap. 2964 7.4.17. unwrap 2965 public void unwrap(InputStream inStream, OutputStream outStream, 2966 MessageProp msgProp) throws GSSException 2968 Used by the peer application to process tokens generated with the 2969 wrap call. This call is equal in functionality to its byte array 2970 counterpart. It will produce the message supplied in the peer 2971 application to the wrap call, verifying the embedded MIC. 2973 The MessageProp object is instantiated by the application and is used 2974 by the underlying mechanism to return information to the caller such 2975 as the QOP, whether confidentiality was applied to the message, and 2976 other supplementary message state information. 2978 Since some application-level protocols may wish to use tokens emitted 2979 by wrap to provide "secure framing", implementations should support 2980 the wrapping and unwrapping of zero-length messages. 2982 Parameters: 2984 inStream Input stream containing the GSS-API wrap token received 2985 from the peer. 2987 outStream The output stream to write the application message to. 2989 msgProp Upon return from the method, this object will contain the 2990 applied QOP, the privacy state of the message, and supplementary 2991 information described in 5.12.3 stating whether the token was a 2992 duplicate, old, out of sequence or arriving after a gap. 2994 7.4.18. getMIC 2996 public byte[] getMIC(byte[] inMsg, int offset, int len, 2997 MessageProp msgProp) throws GSSException 2999 Returns a token containing a cryptographic MIC for the supplied 3000 message, for transfer to the peer application. Unlike wrap, which 3001 encapsulates the user message in the returned token, only the message 3002 MIC is returned in the output token. This method is identical in 3003 functionality to its stream counterpart. 3005 Note that privacy can only be applied through the wrap call. 3007 Since some application-level protocols may wish to use tokens emitted 3008 by getMIC to provide "secure framing", implementations should support 3009 derivation of MICs from zero-length messages. 3011 Parameters: 3013 inMsg Message to generate MIC over. 3015 offset The offset within the inMsg where the token begins. 3017 len The length of the token within the inMsg (starting at the 3018 offset). 3020 msgProp Instance of MessageProp that is used by the application to 3021 set the desired QOP. Set the desired QOP to 0 in msgProp to 3022 request the default QOP. Alternatively pass in "null" for msgProp 3023 to request default QOP. 3025 7.4.19. getMIC 3027 public void getMIC(InputStream inStream, OutputStream outStream, 3028 MessageProp msgProp) throws GSSException 3030 Produces a token containing a cryptographic MIC for the supplied 3031 message, for transfer to the peer application. Unlike wrap, which 3032 encapsulates the user message in the returned token, only the message 3033 MIC is produced in the output token. This method is identical in 3034 functionality to its byte array counterpart. 3036 Note that privacy can only be applied through the wrap call. 3038 Since some application-level protocols may wish to use tokens emitted 3039 by getMIC to provide "secure framing", implementations should support 3040 derivation of MICs from zero-length messages. 3042 Parameters: 3044 inStream Input stream containing the message to generate MIC over. 3046 outStream Output stream to write the GSS-API output token to. 3048 msgProp Instance of MessageProp that is used by the application to 3049 set the desired QOP. Set the desired QOP to 0 in msgProp to 3050 request the default QOP. Alternatively pass in "null" for msgProp 3051 to request default QOP. 3053 7.4.20. verifyMIC 3055 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 3056 byte[] inMsg, int msgOffset, int msgLen, 3057 MessageProp msgProp) throws GSSException 3059 Verifies the cryptographic MIC, contained in the token parameter, 3060 over the supplied message. This method is equivalent in 3061 functionality to its stream counterpart. 3063 The MessageProp object is instantiated by the application and is used 3064 by the underlying mechanism to return information to the caller such 3065 as the QOP indicating the strength of protection that was applied to 3066 the message and other supplementary message state information. 3068 Since some application-level protocols may wish to use tokens emitted 3069 by getMIC to provide "secure framing", implementations should support 3070 the calculation and verification of MICs over zero-length messages. 3072 Parameters: 3074 inTok Token generated by peer's getMIC method. 3076 tokOffset The offset within the inTok where the token begins. 3078 tokLen The length of the token within the inTok (starting at the 3079 offset). 3081 inMsg Application message to verify the cryptographic MIC over. 3083 msgOffset The offset within the inMsg where the message begins. 3085 msgLen The length of the message within the inMsg (starting at the 3086 offset). 3088 msgProp Upon return from the method, this object will contain the 3089 applied QOP and supplementary information described in 5.12.3 3090 stating whether the token was a duplicate, old, out of sequence or 3091 arriving after a gap. The confidentiality state will be set to 3092 "false". 3094 7.4.21. verifyMIC 3096 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3097 MessageProp msgProp) throws GSSException 3099 Verifies the cryptographic MIC, contained in the token parameter, 3100 over the supplied message. This method is equivalent in 3101 functionality to its byte array counterpart. 3103 The MessageProp object is instantiated by the application and is used 3104 by the underlying mechanism to return information to the caller such 3105 as the QOP indicating the strength of protection that was applied to 3106 the message and other supplementary message state information. 3108 Since some application-level protocols may wish to use tokens emitted 3109 by getMIC to provide "secure framing", implementations should support 3110 the calculation and verification of MICs over zero-length messages. 3112 Parameters: 3114 tokStream Input stream containing the token generated by peer's 3115 getMIC method. 3117 msgStream Input stream containing the application message to 3118 verify the cryptographic MIC over. 3120 msgProp Upon return from the method, this object will contain the 3121 applied QOP and supplementary information described in 5.12.3 3122 stating whether the token was a duplicate, old, out of sequence or 3123 arriving after a gap. The confidentiality state will be set to 3124 "false". 3126 7.4.22. export 3128 public byte[] export() throws GSSException 3130 Provided to support the sharing of work between multiple processes. 3131 This routine will typically be used by the context-acceptor, in an 3132 application where a single process receives incoming connection 3133 requests and accepts security contexts over them, then passes the 3134 established context to one or more other processes for message 3135 exchange. 3137 This method deactivates the security context and creates an 3138 interprocess token which, when passed to the byte array constructor 3139 of the GSSContext interface in another process, will re-activate the 3140 context in the second process. Only a single instantiation of a 3141 given context may be active at any one time; a subsequent attempt by 3142 a context exporter to access the exported security context will fail. 3144 The implementation may constrain the set of processes by which the 3145 interprocess token may be imported, either as a function of local 3146 security policy, or as a result of implementation decisions. For 3147 example, some implementations may constrain contexts to be passed 3148 only between processes that run under the same account, or which are 3149 part of the same process group. 3151 The interprocess token may contain security-sensitive information 3152 (for example cryptographic keys). While mechanisms are encouraged to 3153 either avoid placing such sensitive information within interprocess 3154 tokens, or to encrypt the token before returning it to the 3155 application, in a typical GSS-API implementation this may not be 3156 possible. Thus the application must take care to protect the 3157 interprocess token, and ensure that any process to which the token is 3158 transferred is trustworthy. 3160 7.4.23. requestMutualAuth 3162 public void requestMutualAuth(boolean state) throws GSSException 3164 Sets the request state of the mutual authentication flag for the 3165 context. This method is only valid before the context creation 3166 process begins and only for the initiator. 3168 Parameters: 3170 state Boolean representing if mutual authentication should be 3171 requested during context establishment. 3173 7.4.24. requestReplayDet 3175 public void requestReplayDet(boolean state) throws GSSException 3177 Sets the request state of the replay detection service for the 3178 context. This method is only valid before the context creation 3179 process begins and only for the initiator. 3181 Parameters: 3183 state Boolean representing if replay detection is desired over the 3184 established context. 3186 7.4.25. requestSequenceDet 3188 public void requestSequenceDet(boolean state) throws GSSException 3190 Sets the request state for the sequence checking service of the 3191 context. This method is only valid before the context creation 3192 process begins and only for the initiator. 3194 Parameters: 3196 state Boolean representing if sequence detection is desired over 3197 the established context. 3199 7.4.26. requestCredDeleg 3201 public void requestCredDeleg(boolean state) throws GSSException 3203 Sets the request state for the credential delegation flag for the 3204 context. This method is only valid before the context creation 3205 process begins and only for the initiator. 3207 Parameters: 3209 state Boolean representing if credential delegation is desired. 3211 7.4.27. requestAnonymity 3213 public void requestAnonymity(boolean state) throws GSSException 3215 Requests anonymous support over the context. This method is only 3216 valid before the context creation process begins and only for the 3217 initiator. 3219 Parameters: 3221 state Boolean representing if anonymity support is requested. 3223 7.4.28. requestConf 3225 public void requestConf(boolean state) throws GSSException 3227 Requests that confidentiality service be available over the context. 3228 This method is only valid before the context creation process begins 3229 and only for the initiator. 3231 Parameters: 3233 state Boolean indicating if confidentiality services are to be 3234 requested for the context. 3236 7.4.29. requestInteg 3238 public void requestInteg(boolean state) throws GSSException 3240 Requests that integrity services be available over the context. This 3241 method is only valid before the context creation process begins and 3242 only for the initiator. 3244 Parameters: 3246 state Boolean indicating if integrity services are to be requested 3247 for the context. 3249 7.4.30. requestLifetime 3251 public void requestLifetime(int lifetime) throws GSSException 3252 Sets the desired lifetime for the context in seconds. This method is 3253 only valid before the context creation process begins and only for 3254 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 3255 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 3256 lifetime. 3258 Parameters: 3260 lifetime The desired context lifetime in seconds. 3262 7.4.31. setChannelBinding 3264 public void setChannelBinding(ChannelBinding cb) throws GSSException 3266 Sets the channel bindings to be used during context establishment. 3267 This method is only valid before the context creation process begins. 3269 Parameters: 3271 cb Channel bindings to be used. 3273 7.4.32. getCredDelegState 3275 public boolean getCredDelegState() 3277 Returns the state of the delegated credentials for the context. When 3278 issued before context establishment is completed or when the 3279 isProtReady method returns "false", it returns the desired state, 3280 otherwise it will indicate the actual state over the established 3281 context. 3283 7.4.33. getMutualAuthState 3285 public boolean getMutualAuthState() 3287 Returns the state of the mutual authentication option for the 3288 context. When issued before context establishment completes or when 3289 the isProtReady method returns "false", it returns the desired state, 3290 otherwise it will indicate the actual state over the established 3291 context. 3293 7.4.34. getReplayDetState 3295 public boolean getReplayDetState() 3297 Returns the state of the replay detection option for the context. 3298 When issued before context establishment completes or when the 3299 isProtReady method returns "false", it returns the desired state, 3300 otherwise it will indicate the actual state over the established 3301 context. 3303 7.4.35. getSequenceDetState 3305 public boolean getSequenceDetState() 3307 Returns the state of the sequence detection option for the context. 3308 When issued before context establishment completes or when the 3309 isProtReady method returns "false", it returns the desired state, 3310 otherwise it will indicate the actual state over the established 3311 context. 3313 7.4.36. getAnonymityState 3315 public boolean getAnonymityState() 3317 Returns "true" if this is an anonymous context. When issued before 3318 context establishment completes or when the isProtReady method 3319 returns "false", it returns the desired state, otherwise it will 3320 indicate the actual state over the established context. 3322 7.4.37. isTransferable 3324 public boolean isTransferable() throws GSSException 3326 Returns "true" if the context is transferable to other processes 3327 through the use of the export method. This call is only valid on 3328 fully established contexts. 3330 7.4.38. isProtReady 3332 public boolean isProtReady() 3334 Returns "true" if the per message operations can be applied over the 3335 context. Some mechanisms may allow the usage of per-message 3336 operations before the context is fully established. This will also 3337 indicate that the get methods will return actual context state 3338 characteristics instead of the desired ones. 3340 7.4.39. getConfState 3342 public boolean getConfState() 3344 Returns the confidentiality service state over the context. When 3345 issued before context establishment completes or when the isProtReady 3346 method returns "false", it returns the desired state, otherwise it 3347 will indicate the actual state over the established context. 3349 7.4.40. getIntegState 3351 public boolean getIntegState() 3353 Returns the integrity service state over the context. When issued 3354 before context establishment completes or when the isProtReady method 3355 returns "false", it returns the desired state, otherwise it will 3356 indicate the actual state over the established context. 3358 7.4.41. getLifetime 3360 public int getLifetime() 3362 Returns the context lifetime in seconds. When issued before context 3363 establishment completes or when the isProtReady method returns 3364 "false", it returns the desired lifetime, otherwise it will indicate 3365 the remaining lifetime for the context. 3367 7.4.42. getSrcName 3369 public GSSName getSrcName() throws GSSException 3371 Returns the name of the context initiator. This call is valid only 3372 after the context is fully established or the isProtReady method 3373 returns "true". It is guaranteed to return an MN. 3375 7.4.43. getTargName 3377 public GSSName getTargName() throws GSSException 3379 Returns the name of the context target (acceptor). This call is 3380 valid only after the context is fully established or the isProtReady 3381 method returns "true". It is guaranteed to return an MN. 3383 7.4.44. getMech 3385 public Oid getMech() throws GSSException 3387 Returns the mechanism oid for this context. This method may be 3388 called before the context is fully established, but the mechanism 3389 returned may change on successive calls in negotiated mechanism case. 3391 7.4.45. getDelegCred 3393 public GSSCredential getDelegCred() throws GSSException 3395 Returns the delegated credential object on the acceptor's side. To 3396 check for availability of delegated credentials call 3397 getDelegCredState. This call is only valid on fully established 3398 contexts. 3400 7.4.46. isInitiator 3402 public boolean isInitiator() throws GSSException 3404 Returns "true" if this is the initiator of the context. This call is 3405 only valid after the context creation process has started. 3407 7.5. public class MessageProp 3409 This is a utility class used within the per-message GSSContext 3410 methods to convey per-message properties. 3412 When used with the GSSContext interface's wrap and getMIC methods, an 3413 instance of this class is used to indicate the desired QOP and to 3414 request if confidentiality services are to be applied to caller 3415 supplied data (wrap only). To request default QOP, the value of 0 3416 should be used for QOP. 3418 When used with the unwrap and verifyMIC methods of the GSSContext 3419 interface, an instance of this class will be used to indicate the 3420 applied QOP and confidentiality services over the supplied message. 3421 In the case of verifyMIC, the confidentiality state will always be 3422 "false". Upon return from these methods, this object will also 3423 contain any supplementary status values applicable to the processed 3424 token. The supplementary status values can indicate old tokens, out 3425 of sequence tokens, gap tokens or duplicate tokens. 3427 7.5.1. Constructors 3429 public MessageProp(boolean privState) 3431 Constructor which sets QOP to 0 indicating that the default QOP is 3432 requested. 3434 Parameters: 3436 privState The desired privacy state. "true" for privacy and 3437 "false" for integrity only. 3439 public MessageProp(int qop, boolean privState) 3441 Constructor which sets the values for the qop and privacy state. 3443 Parameters: 3445 qop The desired QOP. Use 0 to request a default QOP. 3447 privState The desired privacy state. "true" for privacy and 3448 "false" for integrity only. 3450 7.5.2. getQOP 3452 public int getQOP() 3454 Retrieves the QOP value. 3456 7.5.3. getPrivacy 3458 public boolean getPrivacy() 3460 Retrieves the privacy state. 3462 7.5.4. getMinorStatus 3464 public int getMinorStatus() 3466 Retrieves the minor status that the underlying mechanism might have 3467 set. 3469 7.5.5. getMinorString 3471 public String getMinorString() 3473 Returns a string explaining the mechanism specific error code. null 3474 will be returned when no mechanism error code has been set. 3476 7.5.6. setQOP 3478 public void setQOP(int qopVal) 3480 Sets the QOP value. 3482 Parameters: 3484 qopVal The QOP value to be set. Use 0 to request a default QOP 3485 value. 3487 7.5.7. setPrivacy 3489 public void setPrivacy(boolean privState) 3491 Sets the privacy state. 3493 Parameters: 3495 privState The privacy state to set. 3497 7.5.8. isDuplicateToken 3499 public boolean isDuplicateToken() 3501 Returns "true" if this is a duplicate of an earlier token. 3503 7.5.9. isOldToken 3505 public boolean isOldToken() 3507 Returns "true" if the token's validity period has expired. 3509 7.5.10. isUnseqToken 3511 public boolean isUnseqToken() 3513 Returns "true" if a later token has already been processed. 3515 7.5.11. isGapToken 3517 public boolean isGapToken() 3519 Returns "true" if an expected per-message token was not received. 3521 7.5.12. setSupplementaryStates 3523 public void setSupplementaryStates(boolean duplicate, 3524 boolean old, boolean unseq, boolean gap, 3525 int minorStatus, String minorString) 3527 This method sets the state for the supplementary information flags 3528 and the minor status in MessageProp. It is not used by the 3529 application but by the GSS implementation to return this information 3530 to the caller of a per-message context method. 3532 Parameters: 3534 duplicate true if the token was a duplicate of an earlier token, 3535 false otherwise 3537 old true if the token's validity period has expired, false 3538 otherwise 3540 unseq true if a later token has already been processed, false 3541 otherwise 3543 gap true if one or more predecessor tokens have not yet been 3544 successfully processed, false otherwise 3546 minorStatus the integer minor status code that the underlying 3547 mechanism wants to set 3549 minorString the textual representation of the minorStatus value 3551 7.6. public class ChannelBinding 3553 The GSS-API accommodates the concept of caller-provided channel 3554 binding information. Channel bindings are used to strengthen the 3555 quality with which peer entity authentication is provided during 3556 context establishment. They enable the GSS-API callers to bind the 3557 establishment of the security context to relevant characteristics 3558 like addresses or to application specific data. 3560 The caller initiating the security context must determine the 3561 appropriate channel binding values to set in the GSSContext object. 3562 The acceptor must provide an identical binding in order to validate 3563 that received tokens possess correct channel-related characteristics. 3565 Use of channel bindings is optional in GSS-API. Since channel- 3566 binding information may be transmitted in context establishment 3567 tokens, applications should therefore not use confidential data as 3568 channel-binding components. 3570 7.6.1. Constructors 3572 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3573 byte[] appData) 3575 Create a ChannelBinding object with user supplied address information 3576 and data. "null" values can be used for any fields which the 3577 application does not want to specify. 3579 Parameters: 3581 initAddr The address of the context initiator. "null" value can be 3582 supplied to indicate that the application does not want to set 3583 this value. 3585 acceptAddr The address of the context acceptor. "null" value can 3586 be supplied to indicate that the application does not want to set 3587 this value. 3589 appData Application supplied data to be used as part of the 3590 channel bindings. "null" value can be supplied to indicate that 3591 the application does not want to set this value. 3593 public ChannelBinding(byte[] appData) 3595 Creates a ChannelBinding object without any addressing information. 3597 Parameters: 3599 appData Application supplied data to be used as part of the 3600 channel bindings. 3602 7.6.2. getInitiatorAddress 3604 public InetAddress getInitiatorAddress() 3606 Returns the initiator's address for this channel binding. "null" is 3607 returned if the address has not been set. 3609 7.6.3. getAcceptorAddress 3611 public InetAddress getAcceptorAddress() 3613 Returns the acceptor's address for this channel binding. "null" is 3614 returned if the address has not been set. 3616 7.6.4. getApplicationData 3618 public byte[] getApplicationData() 3620 Returns application data being used as part of the ChannelBinding. 3621 "null" is returned if no application data has been specified for the 3622 channel binding. 3624 7.6.5. equals 3626 public boolean equals(Object obj) 3628 Returns "true" if two channel bindings match. (Note that the Java 3629 language specification requires that two objects that are equal 3630 according to the equals(Object) method must return the same integer 3631 result when the hashCode() method is called on them.) 3633 Parameters: 3635 obj Another channel binding to compare with. 3637 7.7. public class Oid 3639 This class represents Universal Object Identifiers (Oids) and their 3640 associated operations. 3642 Oids are hierarchically globally-interpretable identifiers used 3643 within the GSS-API framework to identify mechanisms and name formats. 3645 The structure and encoding of Oids is defined in ISOIEC-8824 and 3646 ISOIEC-8825. For example the Oid representation of Kerberos V5 3647 mechanism is "1.2.840.113554.1.2.2" 3649 The GSSName name class contains public static Oid objects 3650 representing the standard name types defined in GSS-API. 3652 7.7.1. Constructors 3654 public Oid(String strOid) throws GSSException 3656 Creates an Oid object from a string representation of its integer 3657 components (e.g. "1.2.840.113554.1.2.2"). 3659 Parameters: 3661 strOid The string representation for the oid. 3663 public Oid(InputStream derOid) throws GSSException 3665 Creates an Oid object from its DER encoding. This refers to the full 3666 encoding including tag and length. The structure and encoding of 3667 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3668 identical in functionality to its byte array counterpart. 3670 Parameters: 3672 derOid Stream containing the DER encoded oid. 3674 public Oid(byte[] DEROid) throws GSSException 3676 Creates an Oid object from its DER encoding. This refers to the full 3677 encoding including tag and length. The structure and encoding of 3678 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3679 identical in functionality to its byte array counterpart. 3681 Parameters: 3683 derOid Byte array storing a DER encoded oid. 3685 7.7.2. toString 3687 public String toString() 3689 Returns a string representation of the oid's integer components in 3690 dot separated notation (e.g. "1.2.840.113554.1.2.2"). 3692 7.7.3. equals 3694 public boolean equals(Object Obj) 3696 Returns "true" if the two Oid objects represent the same oid value. 3697 (Note that the Java language specification [JLS] requires that two 3698 objects that are equal according to the equals(Object) method must 3699 return the same integer result when the hashCode() method is called 3700 on them.) 3702 Parameters: 3704 obj Another Oid object to compare with. 3706 7.7.4. getDER 3708 public byte[] getDER() 3710 Returns the full ASN.1 DER encoding for this oid object, which 3711 includes the tag and length. 3713 7.7.5. containedIn 3715 public boolean containedIn(Oid[] oids) 3717 A utility method to test if an Oid object is contained within the 3718 supplied Oid object array. 3720 Parameters: 3722 oids An array of oids to search. 3724 7.8. public class GSSException extends Exception 3726 This exception is thrown whenever a fatal GSS-API error occurs 3727 including mechanism specific errors. It may contain both, the major 3728 and minor, GSS-API status codes. The mechanism implementers are 3729 responsible for setting appropriate minor status codes when throwing 3730 this exception. Aside from delivering the numeric error code(s) to 3731 the caller, this class performs the mapping from their numeric values 3732 to textual representations. All Java GSS-API methods are declared 3733 throwing this exception. 3735 All implementations are encouraged to use the Java 3736 internationalization techniques to provide local translations of the 3737 message strings. 3739 7.8.1. Static Constants 3741 All valid major GSS-API error code values are declared as constants 3742 in this class. 3744 public static final int BAD_BINDINGS 3746 Channel bindings mismatch error. The value of this constant is 1. 3748 public static final int BAD_MECH 3750 Unsupported mechanism requested error. The value of this constant is 3751 2 3753 public static final int BAD_NAME 3755 Invalid name provided error. The value of this constant is 3. 3757 public static final int BAD_NAMETYPE 3759 Name of unsupported type provided error. The value of this constant 3760 is 4. 3762 public static final int BAD_STATUS 3764 Invalid status code error - this is the default status value. The 3765 value of this constant is 5. 3767 public static final int BAD_MIC 3769 Token had invalid integrity check error. The value of this constant 3770 is 6. 3772 public static final int CONTEXT_EXPIRED 3774 Specified security context expired error. The value of this constant 3775 is 7. 3777 public static final int CREDENTIALS_EXPIRED 3779 Expired credentials detected error. The value of this constant is 8. 3781 public static final int DEFECTIVE_CREDENTIAL 3783 Defective credential error. The value of this constant is 9. 3785 public static final int DEFECTIVE_TOKEN 3787 Defective token error. The value of this constant is 10. 3789 public static final int FAILURE 3791 General failure, unspecified at GSS-API level. The value of this 3792 constant is 11. 3794 public static final int NO_CONTEXT 3796 Invalid security context error. The value of this constant is 12. 3798 public static final int NO_CRED 3800 Invalid credentials error. The value of this constant is 13. 3802 public static final int BAD_QOP 3804 Unsupported QOP value error. The value of this constant is 14. 3806 public static final int UNAUTHORIZED 3808 Operation unauthorized error. The value of this constant is 15. 3810 public static final int UNAVAILABLE 3812 Operation unavailable error. The value of this constant is 16. 3814 public static final int DUPLICATE_ELEMENT 3816 Duplicate credential element requested error. The value of this 3817 constant is 17. 3819 public static final int NAME_NOT_MN 3821 Name contains multi-mechanism elements error. The value of this 3822 constant is 18. 3824 public static final int DUPLICATE_TOKEN 3826 The token was a duplicate of an earlier token. This is contained in 3827 an exception only when detected during context establishment, in 3828 which case it is considered a fatal error. (Non-fatal supplementary 3829 codes are indicated via the MessageProp object.) The value of this 3830 constant is 19. 3832 public static final int OLD_TOKEN 3834 The token's validity period has expired. This is contained in an 3835 exception only when detected during context establishment, in which 3836 case it is considered a fatal error. (Non-fatal supplementary codes 3837 are indicated via the MessageProp object.) The value of this 3838 constant is 20. 3840 public static final int UNSEQ_TOKEN 3842 A later token has already been processed. This is contained in an 3843 exception only when detected during context establishment, in which 3844 case it is considered a fatal error. (Non-fatal supplementary codes 3845 are indicated via the MessageProp object.) The value of this 3846 constant is 21. 3848 public static final int GAP_TOKEN 3850 An expected per-message token was not received. This is contained in 3851 an exception only when detected during context establishment, in 3852 which case it is considered a fatal error. (Non-fatal supplementary 3853 codes are indicated via the MessageProp object.) The value of this 3854 constant is 22. 3856 7.8.2. Constructors 3858 public GSSException(int majorCode) 3860 Creates a GSSException object with a specified major code. 3862 Parameters: 3864 majorCode The GSS error code causing this exception to be thrown. 3866 public GSSException(int majorCode, int minorCode, String minorString) 3868 Creates a GSSException object with the specified major code, minor 3869 code, and minor code textual explanation. This constructor is to be 3870 used when the exception is originating from the security mechanism. 3871 It allows to specify the GSS code and the mechanism code. 3873 Parameters: 3875 majorCode The GSS error code causing this exception to be thrown. 3877 minorCode The mechanism error code causing this exception to be 3878 thrown. 3880 minorString The textual explanation of the mechanism error code. 3882 7.8.3. getMajor 3884 public int getMajor() 3886 Returns the major code representing the GSS error code that caused 3887 this exception to be thrown. 3889 7.8.4. getMinor 3891 public int getMinor() 3893 Returns the mechanism error code that caused this exception. The 3894 minor code is set by the underlying mechanism. Value of 0 indicates 3895 that mechanism error code is not set. 3897 7.8.5. getMajorString 3899 public String getMajorString() 3901 Returns a string explaining the GSS major error code causing this 3902 exception to be thrown. 3904 7.8.6. getMinorString 3906 public String getMinorString() 3908 Returns a string explaining the mechanism specific error code. null 3909 will be returned when no mechanism error code has been set. 3911 7.8.7. setMinor 3913 public void setMinor(int minorCode, String message) 3915 Used internally by the GSS-API implementation and the underlying 3916 mechanisms to set the minor code and its textual representation. 3918 Parameters: 3920 minorCode The mechanism specific error code. 3922 message A textual explanation of the mechanism error code. 3924 7.8.8. toString 3925 public String toString() 3927 Returns a textual representation of both the major and minor status 3928 codes. 3930 7.8.9. getMessage 3932 public String getMessage() 3934 Returns a detailed message of this exception. Overrides 3935 Throwable.getMessage. It is customary in Java to use this method to 3936 obtain exception information. 3938 8. Sample Applications 3940 8.1. Simple GSS Context Initiator 3942 import org.ietf.jgss.*; 3944 /** 3945 * This is a partial sketch for a simple client program that acts 3946 * as a GSS context initiator. It illustrates how to use the Java 3947 * bindings for the GSS-API specified in 3948 * Generic Security Service API Version 2 : Java bindings 3949 * 3950 * 3951 * This code sketch assumes the existence of a GSS-API 3952 * implementation that supports the mechanism that it will need 3953 * and is present as a library package (org.ietf.jgss) either as 3954 * part of the standard JRE or in the CLASSPATH the application 3955 * specifies. 3956 */ 3958 public class SimpleClient { 3960 private String serviceName; // name of peer (ie. server) 3961 private GSSCredential clientCred = null; 3962 private GSSContext context = null; 3963 private Oid mech; // underlying mechanism to use 3965 private GSSManager mgr = GSSManager.getInstance(); 3967 ... 3968 ... 3970 private void clientActions() { 3971 initializeGSS(); 3972 establishContext(); 3973 doCommunication(); 3974 } 3976 /** 3977 * Acquire credentials for the client. 3978 */ 3979 private void initializeGSS() { 3981 try { 3983 clientCred = mgr.createCredential(null /*default princ*/, 3984 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 3985 mech /* mechanism to use */, 3986 GSSCredential.INITIATE_ONLY /* init context */); 3988 print("GSSCredential created for " + 3989 cred.getName().toString()); 3990 print("Credential lifetime (sec)=" + 3991 cred.getRemainingLifetime()); 3992 } catch (GSSException e) { 3993 print("GSS-API error in credential acquisition: " 3994 + e.getMessage()); 3995 ... 3996 ... 3997 } 3999 ... 4000 ... 4001 } 4003 /** 4004 * Does the security context establishment with the 4005 * server. 4006 */ 4007 private void establishContext() { 4009 byte[] inToken = new byte[0]; 4010 byte[] outToken = null; 4012 try { 4014 GSSName peer = mgr.createName(serviceName, 4015 GSSName.NT_HOSTBASED_SERVICE); 4016 context = mgr.createContext(peer, mech, gssCred, 4017 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 4019 // Will need to support confidentiality 4020 context.requestConf(true); 4022 while (!context.isEstablished()) { 4024 outToken = context.initSecContext(inToken, 0, 4025 inToken.length); 4027 if (outToken != null) 4028 writeGSSToken(outToken); 4030 if (!context.isEstablished()) 4031 inToken = readGSSToken(); 4032 } 4034 GSSName peer = context.getSrcName(); 4035 print("Security context established with " + peer + 4036 " using underlying mechanism " + mech.toString()); 4037 } catch (GSSException e) { 4038 print("GSS-API error during context establishment: " 4039 + e.getMessage()); 4040 ... 4041 ... 4042 } 4044 ... 4045 ... 4046 } 4048 /** 4049 * Sends some data to the server and reads back the 4050 * response. 4051 */ 4052 private void doCommunication() { 4053 byte[] inToken = null; 4054 byte[] outToken = null; 4055 byte[] buffer; 4057 // Container for multiple input-output arguments to and 4058 // from the per-message routines (e.g., wrap/unwrap). 4059 MessageProp messgInfo = new MessageProp(); 4061 try { 4063 /* 4064 * Now send some bytes to the server to be 4065 * processed. They will be integrity protected but 4066 * not encrypted for privacy. 4067 */ 4069 buffer = readFromFile(); 4071 // Set privacy to false and use the default QOP 4072 messgInfo.setPrivacy(false); 4074 outToken = context.wrap(buffer, 0, buffer.length, 4075 messgInfo); 4077 writeGSSToken(outToken); 4079 /* 4080 * Now read the response from the server. 4081 */ 4083 inToken = readGSSToken(); 4084 buffer = context.unwrap(inToken, 0, 4085 inToken.length, messgInfo); 4086 // All ok if no exception was thrown! 4088 GSSName peer = context.getSrcName(); 4090 print("Message from " + peer.toString() 4091 + " arrived."); 4092 print("Was it encrypted? " + 4093 messgInfo.getPrivacy()); 4094 print("Duplicate Token? " + 4095 messgInfo.isDuplicateToken()); 4096 print("Old Token? " + 4097 messgInfo.isOldToken()); 4098 print("Unsequenced Token? " + 4099 messgInfo.isUnseqToken()); 4100 print("Gap Token? " + 4101 messgInfo.isGapToken()); 4103 ... 4104 ... 4106 } catch (GSSException e) { 4107 print("GSS-API error in per-message calls: " 4108 + e.getMessage()); 4109 ... 4110 ... 4112 } 4114 ... 4116 ... 4118 } // end of doCommunication method 4120 ... 4121 ... 4123 } // end of class SimpleClient 4125 8.2. Simple GSS Context Acceptor 4127 import org.ietf.jgss.*; 4129 /** 4130 * This is a partial sketch for a simple server program that acts 4131 * as a GSS context acceptor. It illustrates how to use the Java 4132 * bindings for the GSS-API specified in 4133 * Generic Security Service API Version 2 : Java bindings 4134 * 4135 * This code sketch assumes the existence of a GSS-API 4136 * implementation that supports the mechanisms that it will need 4137 * and is present as a library package (org.ietf.jgss) either as 4138 * part of the standard JRE or in the CLASSPATH the application 4139 * specifies. 4140 */ 4142 import org.ietf.jgss.*; 4144 public class SimpleServer { 4146 private String serviceName; 4147 private GSSName name; 4148 private GSSCredential cred; 4150 private GSSManager mgr; 4152 ... 4153 ... 4155 /** 4156 * Wait for client connections, establish security contexts 4157 * and provide service. 4158 */ 4159 private void loop() { 4161 ... 4162 ... 4164 mgr = GSSManager.getInstance(); 4165 name = mgr.createName(serviceName, 4166 GSSName.NT_HOSTBASED_SERVICE); 4168 cred = mgr.createCredential(name, 4169 GSSCredential.INDEFINITE_LIFETIME, 4170 null, 4171 GSSCredential.ACCEPT_ONLY); 4173 // Loop infinitely 4174 while (true) { 4176 Socket s = serverSock.accept(); 4178 // Start a new thread to serve this connection 4179 Thread serverThread = new ServerThread(s); 4180 serverThread.start(); 4182 } 4183 } 4185 /** 4186 * Inner class ServerThread whose run() method provides the 4187 * secure service to a connection. 4188 */ 4190 private class ServerThread extends Thread { 4192 ... 4193 ... 4195 /** 4196 * Deals with the connection from one client. It also 4197 * handles all GSSException's thrown while talking to 4198 * this client. 4199 */ 4200 public void run() { 4202 byte[] inToken = null; 4203 byte[] outToken = null; 4204 byte[] buffer; 4206 GSSName peer; 4208 // Container for multiple input-output arguments to 4209 // and from the per-message routines 4210 // (i.e. wrap/unwrap). 4211 MessageProp supplInfo = new MessageProp(); 4212 GSSContext secContext = null; 4214 try { 4216 // Now do the context establishment loop 4218 GSSContext context = mgr.createContext(cred); 4220 while (!context.isEstablished()) { 4222 inToken = readGSSToken(); 4224 outToken = context.acceptSecContext(inToken, 4225 0, inToken.length); 4227 if (outToken != null) 4228 writeGSSToken(outToken); 4230 } 4232 // SimpleServer wants confidentiality to be 4233 // available. Check for it. 4234 if (!context.getConfState()){ 4235 ... 4236 ... 4237 } 4239 GSSName peer = context.getSrcName(); 4240 Oid mech = context.getMech(); 4241 print("Security context established with " + 4242 peer.toString() + 4243 " using underlying mechanism " + 4244 mech.toString() + 4245 " from Provider " + 4246 context.getProvider().getName()); 4248 // Now read the bytes sent by the client to be 4249 // processed. 4250 inToken = readGSSToken(); 4252 // Unwrap the message 4253 buffer = context.unwrap(inToken, 0, 4254 inToken.length, supplInfo); 4255 // All ok if no exception was thrown! 4257 // Print other supplementary per-message status 4258 // information 4260 print("Message from " + 4261 peer.toString() + " arrived."); 4262 print("Was it encrypted? " + 4263 supplInfo.getPrivacy()); 4264 print("Duplicate Token? " + 4265 supplInfo.isDuplicateToken()); 4266 print("Old Token? " + supplInfo.isOldToken()); 4267 print("Unsequenced Token? " + 4268 supplInfo.isUnseqToken()); 4269 print("Gap Token? " + supplInfo.isGapToken()); 4271 /* 4272 * Now process the bytes and send back an 4273 * encrypted response. 4274 */ 4276 buffer = serverProcess(buffer); 4278 // Encipher it and send it across 4280 supplInfo.setPrivacy(true); // privacy requested 4281 supplInfo.setQOP(0); // default QOP 4282 outToken = context.wrap(buffer, 0, buffer.length, 4283 supplInfo); 4284 writeGSSToken(outToken); 4286 } catch (GSSException e) { 4287 print("GSS-API Error: " + e.getMessage()); 4288 // Alternatively, could call e.getMajorMessage() 4289 // and e.getMinorMessage() 4290 print("Abandoning security context."); 4292 ... 4293 ... 4295 } 4297 ... 4298 ... 4300 } // end of run method in ServerThread 4302 } // end of inner class ServerThread 4304 ... 4305 ... 4307 } // end of class SimpleServer 4309 9. Security Considerations 4311 The Java language security model allows platform providers to have 4312 policy based fine-grained access control over any resource that an 4313 application wants. When using a Java security manager (such as, but 4314 not limited to, the case of applets running in browsers) the 4315 application code is in a sandbox by default. 4317 Administrators of the platform JRE determine what permissions, if 4318 any, are to be given to source from different codebases. Thus the 4319 administrator has to be aware of any special requirements that the 4320 GSS provider might have for system resources. For instance, a 4321 Kerberos provider might wish to make a network connection to the KDC 4322 to obtain initial credentials. This would not be allowed under the 4323 sandbox unless the administrator had granted permissions for this. 4324 Also note that this granting and checking of permissions happens 4325 transparently to the application and is outside the scope of this 4326 document. 4328 The Java language allows administrators to pre-configure a list of 4329 security service providers in the /lib/security/java.security 4330 file. At runtime, the system approaches these providers in order of 4331 preference when looking for security related services. Applications 4332 have a means to modify this list through methods in the "Security" 4333 class in the "java.security" package. However, since these 4334 modifications would be visible in the entire JVM and thus affect all 4335 code executing in it, this operation is not available in the sandbox 4336 and requires special permissions to perform. Thus when a GSS 4337 application has special needs that are met by a particular security 4338 provider, it has two choices: 4340 1) To install the provider on a JVM wide basis using the 4341 java.security.Security class and then depend on the system to find 4342 the right provider automatically when the need arises. (This would 4343 require the application to be granted a "insertProvider 4344 SecurityPermission".) 4346 2) To pass an instance of the provider to the local instance of 4347 GSSManager so that only factory calls going through that GSSManager 4348 use the desired provider. (This would not require any permissions.) 4350 10. IANA Considerations 4352 This document has no IANA considerations currently. 4354 11. Acknowledgments 4356 This proposed API leverages earlier work performed by the IETF's CAT 4357 WG as outlined in both RFC 2743 [GSSAPIv2-UPDATE] and RFC 2744 4358 [GSSAPI-Cbind]. Many conceptual definitions, implementation 4359 directions, and explanations have been included from these documents. 4361 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4362 Saltz and other members of Sun's development team for their helpful 4363 input, comments and suggestions. 4365 We would also like to thank Joe Salowey, and Michael Smith for many 4366 insightful ideas and suggestions that have contributed to this 4367 document. 4369 Appendix A. Changes since RFC 2853 4371 This document has following changes: 4373 1) Major GSS Status Code Constant Values 4375 RFC 2853 listed all the GSS status code values in two different 4376 sections: section 4.12.1 defined numeric values for them, and section 4377 6.8.1 defined them as static constants in the GSSException class 4378 without assigning any values. Due to an inconsistent ordering 4379 between these two sections, all of the GSS major status codes 4380 resulted in misalignment, and a subsequent disagreement between 4381 deployed implementations. 4383 This document defines the numeric values of the GSS status codes in 4384 both sections, while maintaining the original ordering from section 4385 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status code values 4386 defined in 4.12.1. The relevant sections in this document are 4387 sections 5.12.1 and 7.8.1. 4389 2) GSS Credential Usage Constant Values 4391 RFC 2853 section 6.3.2 defines static constants for the GSSCredential 4392 usage flags. However, the values of these constants were not defined 4393 anywhere in RFC 2853 [RFC2853]. 4395 This document defines the credential usage values in section 7.3.2. 4396 The original ordering of these values from section 6.3.2 of RFC 2853 4397 [RFC2853] is maintained. 4399 3) GSS Host-Based Service Name 4400 RFC 2853 [RFC2853] section 6.2.2 defines the static constant for the 4401 GSS host-based service OID NT_HOSTBASED_SERVICE, using a deprecated 4402 OID value. 4404 This document updates the NT_HOSTBASED_SERVICE OID value in section 4405 7.2.2 to be consistent with the C-bindings in RFC 2744 4406 [GSSAPI-Cbind]. 4408 12. References 4410 12.1. Normative References 4412 [GSSAPI-Cbind] 4413 Wray, J., "Generic Security Service API Version 2 : 4414 C-bindings", RFC 2744, January 2000. 4416 [GSSAPIv2-UPDATE] 4417 Linn, J., "Generic Security Service Application Program 4418 Interface, Version 2, Update 1", RFC 2743, January 2000. 4420 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism", 4421 RFC 2025, October 1996. 4423 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4424 Requirement Levels", BCP 14, RFC 2119, March 1997. 4426 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service 4427 Application Program Interface : Java Bindings", RFC 2853, 4428 June 2000. 4430 [RFC4121] Zhu, L. and S. Hartman, "The Kerberos Version 5 Generic 4431 Security Service Application Program Interface (GSS-API) 4432 Mechanism: Version 2", RFC 4121, July 2005. 4434 12.2. Informative References 4436 [JLS] Gosling, J., "The Java Language Specification", 4437 JLS langspec. 4439 Authors' Addresses 4441 Mayank D. Upadhyay 4442 Google Inc. 4443 1600 Amphitheatre Parkway 4444 Mountain View, CA 94043 4445 USA 4446 Email: mayank+ietf-2853@google.com 4448 Seema Malkani 4449 Sun Microsystems, Inc. 4450 4140 Network Circle 4451 Santa Clara, CA 95054 4452 USA 4454 Email: Seema.Malkani@sun.com 4456 Full Copyright Statement 4458 Copyright (C) The IETF Trust (2008). 4460 This document is subject to the rights, licenses and restrictions 4461 contained in BCP 78, and except as set forth therein, the authors 4462 retain all their rights. 4464 This document and the information contained herein are provided on an 4465 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4466 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4467 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4468 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4469 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4470 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4472 Intellectual Property 4474 The IETF takes no position regarding the validity or scope of any 4475 Intellectual Property Rights or other rights that might be claimed to 4476 pertain to the implementation or use of the technology described in 4477 this document or the extent to which any license under such rights 4478 might or might not be available; nor does it represent that it has 4479 made any independent effort to identify any such rights. Information 4480 on the procedures with respect to rights in RFC documents can be 4481 found in BCP 78 and BCP 79. 4483 Copies of IPR disclosures made to the IETF Secretariat and any 4484 assurances of licenses to be made available, or the result of an 4485 attempt made to obtain a general license or permission for the use of 4486 such proprietary rights by implementers or users of this 4487 specification can be obtained from the IETF on-line IPR repository at 4488 http://www.ietf.org/ipr. 4490 The IETF invites any interested party to bring to its attention any 4491 copyrights, patents or patent applications, or other proprietary 4492 rights that may cover technology that may be required to implement 4493 this standard. Please address the information to the IETF at 4494 ietf-ipr@ietf.org.